Examples

Complete, working Lost Cities content. Every file here is a whole file, not a fragment, so you can copy one wholesale and edit from a known-good starting point.

Targets Lost Cities 7.4.12 / Minecraft 1.20.1 (Forge). code review

first-city

The datapack built step by step in Your First Custom City. A glass-and-concrete tower that replaces most buildings in a city, in its own mycity namespace so it collides with nothing.

File	What it is code review
pack.mcmeta	Makes the folder a datapack
palettes/tower.json	Five characters, one damaged mapping
parts/tower_floor.json	16×16×6, the repeating storey
parts/tower_top.json	16×16×6, the roof
buildings/tower.json	Stacks the parts, sets filler
citystyles/mycity.json	Inherits citystyle_common, adds the tower
worldstyles/mycity.json	Points at that city style
profile/mycity.json	Config, not datapack. See below

Full tree, as it sits in the repo:

docs/examples/first-city/
  pack.mcmeta
  data/mycity/lostcities/
    palettes/tower.json
    parts/tower_floor.json
    parts/tower_top.json
    buildings/tower.json
    citystyles/mycity.json
    worldstyles/mycity.json
  profile/mycity.json

profile/mycity.json does not go in the datapack

Profiles are config, not content. That file belongs in config/lostcities/profiles/. Everything under data/ is the datapack. It sits inside this folder only to keep the example together.

Using it

1. Copy first-city/ into <world>/datapacks/, minus the profile/ folder.
2. Put profile/mycity.json into config/lostcities/profiles/.
3. Add "lostcities:lostcity=mycity" to dimensionsWithProfiles in config/lostcities/common.toml.
4. Restart, load the world, and run /lostcities locate mycity:tower.

The tutorial explains why each step is there and what breaks if you skip one.

Notes on how it is built

• The parts were generated by a script, not typed. Row lengths and layer counts are the two things nothing in the mod validates and the two things easiest to get wrong by hand.
• Palette characters are Greek (α β γ δ ε) rather than ASCII, because the mod already claims most printable ASCII and collisions overwrite silently. See What counts as a valid character.
• The building keeps one part reference with no conditions, which is what prevents the most common failure.

every-key, the reference fixture

every-key/ uses every key the mod's codecs declare, 209 of them across all thirteen top-level asset types, in a pack that loads and generates. game test

It answers the question a key table cannot: what does this actually look like in a file? palette on a building and palette on a part share a name and are different keys, and the fixture shows both. So are parts on a building and parts on a world style. game test

A reference, not a tutorial

Nothing in this pack is a sensible city. It exists to be read one key at a time, and copying it wholesale gives you a building with thirteen competing part references and a world style overriding every highway part with its own default. Start from first-city instead.

It ships two profiles. ekdemo sets the nine keys the tests need. ekfull sets all 155 profile keys the mod declares, each at its own documented default, so it demonstrates every key's name and section while generating exactly the same world as the minimal one. The five client-only keys, fog and horizon, are absent because a server cannot show them. game test

Coverage is enforced rather than claimed. key-coverage.py fails if any declared key is missing from an example, checks each top-level type against its own folder so two keys sharing a name are counted separately, and counts profile keys too: game test game test

python docs/examples/key-coverage.py

Building it corrected several things on this site. An embedded palette is a whole palette asset and nests, which no page said; a part of a single slice drew nothing at all; and the key export itself was missing three codec types worth 37 keys, because those types register their fields through a helper rather than through fieldOf. code review game test

Regenerate it after editing generate.py:

python docs/examples/every-key/generate.py

validate.py

validate.py checks a datapack against the rules this wiki documents.

python docs/examples/validate.py docs/examples/first-city

What it catches in a datapack, and where each rule is documented:

Check	Documented at code review
char is one UTF-16 code unit, and a longer string is truncated to its first	Palette
Exactly one of block/variant/blocks/frompalette per entry	Palette
Weighted lists reach 128, and no entry sits past the fill point	Palette
loot and mob name a Condition, not a loot table or an entity	Palette
Parts are 16×16, every row exactly xsize UTF-16 units long	Part
meta, not metadata	Part
Buildings have filler	Building
Every level from -cellars to maxfloors matches a part	Building
range parses as two integers	Condition
inpart and belowpart are not used in a building's parts	Condition
Floor and cellar bounds inside their windows	Building
filler and rubble resolve in the building's palette	Building
Stuff maxcount > mincount, maxheight > minheight	Stuff Object
Part characters are defined somewhere	Palette

And in a profile, if the pack ships one:

Check	Documented at code review
Every key exists, and sits in the section the mod registered it under	Profile
worldStyle names a world style the pack defines	Error Messages
The file name is lowercase letters only	Profile

It also gates the wiki itself. Reference tables are checked against mod-keys.json, the keys the mod's codecs declare, so a key the wiki documents that the mod does not have fails the build. If validate.py and the mod disagree, one of them is wrong. code review

The bundle above passes with zero errors and zero warnings.

Ready-made test packs

json5-test/ holds three datapacks and two profiles, generated from one definition so they cannot drift apart. All three build the same three towers, so any difference between them is a fault. game test

Pack	Every asset is	Needs
j5-pure-json	.json	nothing but Lost Cities 7.4.12
j5-pure-json5	.json5	The Lost Cities - DevTool
j5-fighting	both, with the .json twin wrong wherever a wrong answer shows in blocks	the DevTool

j5-pure-json is the control. It proves the towers are correct with no extension handling in play, which is what makes the other two mean anything.

Each pack pins a predefined city in both minecraft:overworld and lostcities:lostcity, so the same pack works whether the profile is chosen on the world creation screen or wired up through dimensionsWithProfiles. Getting that wrong is the most common reason a pinned city appears not to generate at all. game test

Instructions, coordinates and what each wrong colour means are in the pack's README.

behaviour: features that place themselves

behaviour/ covers the features a pinned grid cannot reach, because the generator decides where they go: cellars, preferslonely, highways, railways and city spheres. game test

Every one is a pair. One profile turns the feature on, a second differs from it by a single key and turns it off, and both count the same marker block over the same boxes. A count on its own would prove nothing here, because "found some" could be luck and "found none" could be a broken pack. The off run is what makes the on run readable. game test

Pair	The single key that differs	On	Off
Cellars	buildingMaxCellars	17515	2352, and 0 once the city level is pinned game test
preferslonely	the key itself, 0.0 against 1.0	18028	4560, not 0 game test
Highways	highwayDistanceMask	49152	0 game test
Railways	railwaysEnabled, then railwayStationsEnabled	24320	13792, then 0 game test
City spheres	citySphereChance	20835	0 game test

Two of those five off runs are not zero, and neither was expected. Both are documented on the pages the keys belong to. game test game test

Monorails are the one feature in this pack that was attempted and never placed. What has already been ruled out is recorded so a later attempt does not repeat it. unverified

python docs/examples/behaviour/generate.py

matcher-test: does a biome matcher actually gate anything

matcher-test/ is three city styles that are identical apart from the block they build from, reached through three citystyles entries that are identical apart from the matcher on each: if_any, if_all and excluding, all naming the void biome. game test

The void biome cannot occur in an overworld, so the expected result is the same on every version and every seed. It ships with a control whose entry carries no matcher at all, and the excluding run builds exactly the control's number. game test

python docs/examples/matcher-test/generate.py

wiki-test10: what a bad namespace does

wiki-test10/ is four towers that differ only in how their references are spelled. One spells every namespace in full and generates. The other three each drop nstest: from a different reference, and each fails differently: one silently, one across a 40-chunk area, one by taking the server down. game test

Profile	What it changes	Outcome game test
wtten	nothing	Three of four towers behave as the register records
wttenbare	the profile's worldStyle loses its namespace	The server crashes on the first chunk

Read the results in the claim register.

Three packs for features nobody had generated

Each of these exists because a page was documenting something from the code alone. Each one turns a random feature into something a fixed probe can find.

Pack	Covers	The trick that makes it measurable
wiki-test11/	Building fronts and stuff objects	Overriding the three shipped front parts, so the draw cannot pick one of them instead of yours
wiki-test12/	Scattered structures	areasize: 1, chance: 1.0, weightnone: 0, so every chunk is an area that must place one
wiki-test13/	A predefined sphere	onlyPredefined on and citySphereChance at 0.0, so the pinned dome is the only one
file-era-test/	The file-asset era, before datapacks	One userassets.json holding seven assets, for Lost Cities 1.0.1 through 5.0.4
game test

Results in the claim register. All three found something the pages had wrong. game test

It does not check everything

Nothing here can verify that a block ID exists, or that files are in the right folder. Those need the game. It catches the mechanical mistakes, not the wiring ones.