Settings

Three ways to set them

Pick the level of control you want.

1. Just play

The defaults are tuned already. Pick a world type (cityworld:city, or a style preset like cityworld:apocalypse) and go. Nothing below is required.

2. Customize screen

Single-player, easiest. On the create-world screen, choose CityWorld as the world type and hit Customize. Every setting is there with a widget, grouped the same way as below. Locked settings for your chosen style grey out with a tooltip explaining why.

3. Hand-edit a datapack

Servers, or version-controlled configs. On first run, a full example is written to config/cityworld/settings-example/. Copy it into <world>/datapacks/, edit default.json, and start (or /reload) the world. Every field is optional - a file of just {} is a stock world.

▸

Tip: the fastest workflow is to shape a world you like in single-player via Customize, then run /cityexport <name> to bottle its exact settings into a datapack you can hand to a server.

When changes apply: settings are read when the world loads, and only affect new chunks - existing chunks never regenerate. Spawn odds, names, treasure odds and decay bite as you explore into fresh land; terrain-shaping knobs (seas, mountains, caves, radius) want a brand-new world to be seen properly.

Naming several profiles: default.json overrides the built-in cityworld:default, which every CityWorld world preset and the /cityworld dimension reference - so editing it changes that world. To keep several named profiles instead, rename the file (e.g. ruined.json) and point a dimension's generator at it with "settings": "cityworld:ruined".

For modpacks: config/cityworld-startup.toml locks the create-world screen on each player's own client. lockedWorldPreset fixes every new single-player world to one preset, such as "cityworld:apocalypse"; ruinedNether and cityworldEnd lock the Nether and End to "cityworld" or "vanilla"; and with a preset locked, lockCustomize = true removes the Customize button so every world gets the preset's settings exactly as the pack ships them. A server sets its world type in server.properties instead.

Recipes

A few common asks, as complete default.json files.

A gentler apocalypse

Ruined buildings and roads, but no fire, on a normal green world.

{
  "terrain": {
    "includeDecayedRoads": true,
    "includeDecayedBuildings": true,
    "includeDecayedNature": false
  },
  "decay": {
    "buildingIntensity": 0.5,
    "roadIntensity": 0.4,
    "oddsOfDecayFire": 0.0,
    "oddsOfPristineRoad": 0.3
  }
}

Cities far apart, tiled on a grid

SPARSE-style, in a normal-style world.

{
  "radius": {
    "minInbetweenChunkDistanceOfCities": 100
  }
}

Your own villager names

Sprinkled in among the built-in hundreds.

{
  "naming": {
    "append": true,
    "villagerGivenNames": ["Sablednah", "Darren"]
  }
}

A tougher, more hostile sewer system

{
  "mobs": {
    "sewers": ["minecraft:zombie", "minecraft:zombie", "minecraft:drowned", "minecraft:cave_spider"]
  }
}

Skyscraper city

Taller buildings than the MODERN default.

{
  "world": {
    "maxBuildingFloors": 60
  }
}

Villages in the city

Or any other vanilla or mod structure set - see the guide below.

{
  "structures": {
    "allow": ["minecraft:villages"]
  }
}

Cities in a vanilla world

Vanilla's land, with a CityWorld city every so often, like a village.

{
  "cities": {
    "vanillaTerrain": true,
    "spacing": 3072,
    "districts": 4
  }
}

Turn off caves' winding tunnels

Back to the classic noise-blob caves, on a MODERN world.

{
  "terrain": {
    "windingCaves": false
  }
}

Villages - and any other vanilla or mod structure

"Why are there no villages?" Because CityWorld builds its own cities, it places only the structures that are switched on - by default strongholds (so the End is reachable), trial chambers, ancient cities, and the Nether's and End's own. Turning more on takes one of three routes.

The easy way: the Structures page. Pick a CityWorld world type, press Customize, then Vanilla & mod structures. Every structure set the install has is listed, grouped by mod, with an on/off each. Switch on Villages and create the world.

For a server or a pack: the structures settings group - two lists in the world settings, the same thing the Structures page writes:

{ "structures": { "allow": ["minecraft:villages"] } }

The datapack way works on any version, and sets the default for every world: data/cityworld/tags/worldgen/structure_set/allowed.json in a world datapack. One set covers all five village variants.

{
  "replace": false,
  "values": [ "minecraft:villages" ]
}

▸

"replace": false is the one thing not to get wrong. With true your file replaces CityWorld's list instead of adding to it, which drops strongholds - and no stronghold means no End portal. For another mod's sets, write each entry as { "id": "themod:their_set", "required": false }: one unknown required entry discards the whole tag, silently.

The other vanilla sets you can name the same way: pillager_outposts, woodland_mansions, mineshafts, ocean_monuments, desert_pyramids, swamp_huts, igloos, jungle_temples, shipwrecks, ocean_ruins, buried_treasures, ruined_portals, trail_ruins and nether_fossils, each with the minecraft: prefix.

An allowed structure is not dropped on top of the city. Ground is reserved so streets plan around it, and the terrain under each piece is bent to fit - on a fixed seed, 745 of 745 columns seated exactly, none buried, easing back to natural ground a chunk past the footprint.

Telling whether it worked: /cwlocate structure minecraft:village_plains only finds what is switched on for that world, so "not found" means the choice has not taken. Nothing retro-fits into chunks that already exist, so test in a new world or in land nobody has visited.

Full settings reference

Every knob, grouped.

This mirrors settings-reference.txt, generated alongside the example datapack on first run - if the two ever disagree, the file in your config/ folder is the authority for the version you're running.

`cities` - cities in a vanilla world

Customize calls it Land - Vanilla, cities apart: vanilla's terrain, caves, ores, biomes and villages, with a CityWorld city every so often, each on its own level and eased into the hills. Rivers run through the cities untouched, crossed by bridges, with quays along the banks. Works with the Modern, Apocalypse, Classic, Destroyed and Sparse styles; settings vanilla's world decides instead are greyed out while it is on. Baked in at creation like everything here - change these under an existing world and its cities move beneath chunks already built.

Setting	Default	What it does
vanillaTerrain	false	Turn it on.
spacing	2048	One city per this many blocks, 1024-16384.
districts	3	How many districts across a city is, 1-8.
districtsVariance	1	Give or take this many, 0-3.
levelRange	40	How far above sea level a city may stand, 0-120. Higher ground gets no city.
maxWater	0.35	Datapack only: the share of a candidate site that may be under the sea.
minNear	0.75	Datapack only: the share of a candidate site that must already lie within sixteen blocks of its level.
rivers	false*	Rivers on CityWorld's own land: springs on the high ground running down to the sea in gullies and waterfalls, with quays and harbours where they meet a city. *Customize calls it Land - Rivers; on for new worlds of the Modern, Classic, Apocalypse, Destroyed and Sparse presets, and off for any world saved before rivers existed, so an old world never grows one that stops dead at the chunks it already has.

`features` - what the planner is allowed to build

Setting	Default	What it does
includeRoads	true	Road network. Off = no streets (and no sewers).
includeRoundabouts	true	Roundabouts at some intersections.
includeSewers	true	Sewers beneath the roads.
includeCisterns	true	Water cisterns under some buildings.
includeBasements	true	Building basements.
includeMines	true	Abandoned mine networks underground.
includeBunkers	true	Buried bunkers under midlands/highlands and factories.
includeBuildings	true	Buildings at all. Off = roads/nature only.
includeHouses	true	Houses in neighborhoods (a subset of buildings).
includeFarms	true	Farm districts.
includeMunicipalities	true	Civic district (town halls, libraries, museums, ...).
includeIndustrialSectors	true	Factories, warehouses, storage yards.
includeAirborneStructures	true	Balloons/blimps over the fields.
includeBuildingInteriors	true	Furnish building interiors. Off = empty shells (faster).
includeSchematics	false	Drop the bundled classic building schematics into cities.
includeNamedRoads	true	Street-name signs.

`terrain` - the land, its fluids, and decay

Setting	Default	What it does
includeCaves	true	Carve caves.
windingCaves	false*	Winding "noodle" cave tunnels that wander and branch (vanilla-like) instead of the classic noise blobs. *On by default for MODERN/APOCALYPSE; a free toggle for any style. Needs includeCaves. Never style-locked.
includeLavaFields	true	Underground lava fields (basalt-lined pools in MODERN/APOCALYPSE).
includeSeas	true	Oceans/lakes. Off = a dry, land-only world.
includeMountains	true	Mountainous terrain. Off = flatter.
includeOres	true	Ore deposits in the strata.
includeBones	true	Fossils/bone deposits.
includeFires	true	Lit campfires/fire pits, and burning demolition debris.
includeAbovegroundFluids	true	Surface water/lava placement.
includeUndergroundFluids	true	Underground water/lava placement.
includeWorkingLights	true	Lights burn. Off puts out every light CityWorld draws: glowstone, sea lanterns and froglights become unpowered redstone lamps, lanterns the chain they hung from, torches burnt-out ones, and anything with a lit state - candles, campfires, copper bulbs, most mods' lights - is placed unlit. Natural light (lava, glow lichen, amethyst) and decay fires stay. FLOODED, SAND DUNES and SNOW DUNES ship with it off; the APOCALYPSE vault keeps its own power. A pack says what any block becomes with the cityworld:unlit block data map.
includeDecayedRoads	false	Break roads up with rubble.
includeDecayedBuildings	false	Chew ruin-holes into buildings - the "apocalypse" switch.
includeDecayedNature	false	Drain the seas + desert the world (whole-world ruin mood). Leave false for ruins on a normal wet, green world.
largeCaverns	false*	Rare, big rooms astride the deepslate line, roughly y -50 to +25, terraced and rough inside rather than a blob, with room for a cave biome to be something. *On by default for MODERN/APOCALYPSE; a free toggle for any style.
oddsOfPristineBuilding	0.0001	When decay is on, the chance a building/schematic is spared and stays intact. A schematic's .yml can override this per-building with PristineChance: 0..1 (Decayable: false = never decays).

`caves` - the underground's own biomes

Empty means the shipped defaults. Which biomes are in the pool at all is the tag #cityworld:cave_pool, so a modded cave biome can join it from a datapack - this group only shapes how the pool is placed.

Setting	Default	What it does
structureCarveHalo	10	How far, horizontally, terrain is cleared past a structure like an ancient city - too small reads as a row of boxes, right reads as one roomy cavern.
structureCarveHaloUp	6	The same, upward. Deliberately smaller - headroom, not a chimney.
surfaceMargin	8	How far below the terrain surface a cave patch begins, so a patch can't bleed into a hillside's surface.
patches	[]	Per-biome patch shaping: biome, cell (patch size in blocks, default 96), percent (roughly what share of cells, out of 100, default 5), minY/maxY (default -60/20). Listing any entry replaces the shipped set. Order matters - the first entry whose cell matches owns the column, so list the rarest and deepest first.

`overgrowth` - nature reclaiming the built world (runs after decay)

Setting	Default	What it does
enabled	false	Drape buildings/roads in moss, vines, leaf litter, azalea and small reclaim trees, plus dripstone in mines and basements. Works with or without decay.
intensity	1.0	Density multiplier: 1.0 = default, 2-3 = heavy (more/denser vines and plants).
capVines	false	Finish each outer wall-vine string with a glow lichen tip, so live vine growth can't lengthen it over time.

`decay` - fine control of demolition (pairs with the includeDecayed* toggles above)

Setting	Default	What it does
buildingIntensity	1.0	How ruined a decayed building is - scales both the number and size of collapse holes. Below 1 = light weathering, above 1 = heavy rubble. APOCALYPSE uses 0.5, DESTROYED 1.1.
roadIntensity	1.0	The same, for decayed roads. APOCALYPSE 0.4, DESTROYED 1.1.
oddsOfDecayFire	0.20	Fraction of collapse rubble that catches fire. Only bites when includeFires and includeDecayedFires are both on. DESTROYED uses 0.07.
oddsOfPristineRoad	0.0	Chance a road chunk is spared and stays intact, so a ruined grid keeps walkable stretches. APOCALYPSE uses 0.3.

`shops` - themed retail with villager job blocks (MODERN dressing)

Setting	Default	What it does
enabled	false	Villager job-site blocks so a store/farm reads as its trade (cartography table = map seller, fletching table = fletcher, smoker = butcher, ...), a composter at farm edges, and a rare fish-pond farm. The shop classification itself is always computed for /cityinfo; this only governs block placement.
malls	true	Shopping malls (MODERN and APOCALYPSE): rare, at the edge of town, two or three storeys round a glass-roofed atrium, built in wings, with dozens of named shops - each with its own loot table - and car parks out to the road. Announced as the landmark kind mall. Independent of enabled.

`structures` - which vanilla and mod structures this world places

Two lists of structure-set ids laid over CityWorld's defaults - what the Structures page of the Customize screen writes. An id whose mod is not installed is ignored, a structure still only appears where its biomes exist, and the Nether and End follow the overworld's lists.

Setting	Default	What it does
allow	[]	Structure sets to place as well: ["minecraft:villages", "minecraft:woodland_mansions"].
deny	[]	Structure sets to stop placing: ["minecraft:trial_chambers"].

`subways` - a metro under the city (MODERN and APOCALYPSE)

Setting	Default	What it does
enabled	true	A station in every urban district - a ticket hall beside a road, stairs down to twin-track platforms 24 blocks under the street - and tunnels to stations up to six districts away. East-west lines run on the upper level and north-south lines eight blocks lower; a station on both is an interchange. Powered rails, so a cart runs the line. Stations announce as the landmark kind subway (off by default).
spawners	true	In a ruined (APOCALYPSE) world, sewer-mob spawners in niches in the tunnel walls.

`spawns` - who turns up, and how often (odds 0.0-1.0)

Setting	Default	What it does
spawnBeings	0.5	Villagers/witches appearing in populated spots.
spawnBaddies	0.0476	Hostile mobs at the surface. Raise for a rougher world.
spawnAnimals	0.667	Farm/wild animals.
spawnVagrants	0.2	Wanderers in Customize: strays out of town, on wild land and dirt roads - hostile on a Baddies roll, or always in a ruined world. The key keeps its old name.
nameVillagers	true	Give villagers generated names (see naming).
showVillagersNames	true	Show those names as floating nametags.

`treasures` - chests and spawners

Setting	Default	What it does
treasuresInMines / spawnersInMines	true	Loot chests / mob spawners in mines.
treasuresInBunkers / spawnersInBunkers	true	Loot chests / mob spawners in bunkers.
treasuresInSewers / spawnersInSewers	true	Loot chests / mob spawners in sewers.
treasuresInBuildings	true	Loot chests in buildings.
oddsOfTreasureInMines/Bunkers/Sewers/Buildings	0.5	Chance a given spot gets a chest.
oddsOfAlcoveInMines	0.5	Chance a mine tunnel opens into a side alcove.

`world` - trees, biomes and climate, wild decoration, landmarks

Setting	Default	What it does
treeStyle	"NORMAL"	Tree family: NORMAL, SPOOKY, CRYSTAL.
spawnTrees	0.5	How densely trees grow.
subSurfaceStyle	"LAND"	What fills space under a FLOATING world's land: NONE, LAND, CLOUD, LAVA. Only the FLOATING style reads this.
ruralnessLevel	0.0	Skews the world more rural (more nature, fewer cities) - up toward 1.0.
maxBuildingFloors	20	Tallest a building may rise, in floors (4 blocks each) above street level. 20 = the classic 1.8 look; MODERN ships taller. Sensible range 8-60.
biomeScale	1.5	How large biome regions are, as a multiplier. 1.0 is the older, tighter default; 3.0 gives continent-sized regions.
climateWarmth	0.25	Leans the temperature field warm without narrowing it - frozen peaks and deserts both still happen, with more warm ground between. 0.0 is the raw field.
wildDecoration	"BOTH"	Who decorates wild land on MODERN/APOCALYPSE: BOTH (CityWorld's cover under vanilla's biome features), CITYWORLD, or VANILLA - which hands the wild to vanilla and any biome mod you have installed. City, road and structure land is always CityWorld's.
useModdedBiomes	true	Let TerraBlender biome mods (Biomes O' Plenty and the like) contribute biomes. Does nothing without one. Oceans, shores and peaks stay CityWorld's, since those follow the terrain.
moddedBiomeShare	0.35	How much contested ground a biome mod may own outright, in regions you can walk across. 0.0 = only where its biomes win anyway; 1.0 = every contested column. Needs useModdedBiomes.
broadcastSpecialPlaces	false	Announce rare landmarks in chat as they generate, to the players in that world.
announcedLandmarks	the rares	Which landmark kinds may announce - airship, saucer, vault, zoo, biodome, hospital, schematic and mall by default; subway and the other kinds can be added. With JourneyMap installed, this list also decides which landmarks become map waypoints, announcements on or not.

`radius` - where cities may appear (distances in chunks; 16 blocks each)

Leave these at their defaults for "cities everywhere" - the SPARSE style uses them to confine cities to a region.

Setting	Default	What it does
centerPointOfChunkRadiusX/Z	0	Centre the radius here.
constructChunkRadius	1875000 (no limit)	Max distance for quarries/gravel constructs.
roadChunkRadius	1875000	Max distance for the road network.
cityChunkRadius	1875000	Max distance for cities/buildings/farms.
buildOutsideRadius	false	true = build the ring outside the radius instead of the disc inside it.
minInbetweenChunkDistanceOfCities	0	>0 tiles cities on a grid this many chunks apart (SPARSE uses 100).

`naming` - your own villager and street names

Each list is empty by default (= keep the built-in hundreds). List your own to replace a list, or add "append": true to add to it instead.

List	What it's for
villagerGivenNames / villagerSurnames	Villager names.
streetTerms	Cardinal/central words (declaration, N, Main, S, W, Central, E).
streetPrefixes	Optional street prefixes (Old, New, Fort, ...).
streetStarts / streetEnds	Invented street name syllables (Elm + wood, Oak + ville, ...).
streetSuffixes	Road types (Street, Avenue, Boulevard, ...).
fossilPrefixes / fossilSuffixes	Museum fossil names (Tyranno + saurus, ...).
professionNames	Occupational surnames for employed shop/farm workers, as "profession:Surname" (e.g. "fisherman:Angler"). Profession ids: farmer, fisherman, fletcher, cartographer, mason, armorer, weaponsmith, toolsmith, butcher, leatherworker, cleric, shepherd, librarian.

`mobs` - your own creature lists (weighted by repetition)

Each list is empty by default (= keep the built-in bag). List entity ids to replace a bag, or add "append": true to add to it. Repetition is weight - unknown ids are logged and skipped, not guessed.

List	What it's for
goodies	Friendly beings in populated spots (villagers, ...).
baddies	Surface hostiles.
animals	Farm/wild animals.
seaAnimals	Fish and sea life.
vagrants	The Wanderers: strays out of town (see spawnVagrants).
sewers / mine / bunker	What lurks in each.
waterPit / lavaPit	What's dropped in water pits/cisterns, and lava pits.

Mod compatibility

Your other mods' blocks build cities too.

CityWorld decides what a wall, floor or roof is made of by drawing from a palette - a weighted list of blocks. Most palettes are built on the ordinary vanilla and NeoForge common tags, so a mod that tags its blocks the normal way (its planks in #minecraft:planks, its stone in #c:stones) already shows up in CityWorld cities the moment you install it - no patch, no compatibility pack required. This is also how a "CityWorld × some other mod" compatibility pack works, for the mods that don't tag their blocks, or when you want a mod's blocks somewhere they wouldn't naturally go.

The palettes

Each of these is a block tag CityWorld resolves when a world is created. Add to one and the blocks you add start appearing in that palette.

Tag	Used for	Ships as
cityworld:build/planks	House and building walls, floors, ceilings, roofs; shacks and sheds.	#minecraft:planks
cityworld:build/wool	Building walls, house floors.	#minecraft:wool
cityworld:build/terracotta	House walls, water towers, bunkers, factory and bunker tanks.	#minecraft:terracotta
cityworld:build/glazed_terracotta	House floors.	#c:glazed_terracottas
cityworld:build/concrete	House walls, factories, bunkers, oil platforms, water towers.	#c:concretes
cityworld:build/concrete_powder	Factory and bunker tanks.	#minecraft:concrete_powder
cityworld:build/stained_glass	Factory and bunker tanks.	the sixteen dyed glasses
cityworld:build/modern_stones	The decorative stone palette used by the MODERN and APOCALYPSE styles.	24 curated blocks

Palettes that are a deliberate look rather than "all of a family" are not tags and are not meant to be extended: the muted greyscale of unfinished buildings, the pale civic palette of government offices, and the ordered road and maze lists.

Writing a compatibility pack

A pack is just tag files. To add a mod's wood to every wooden thing CityWorld builds, create data/cityworld/tags/block/build/planks.json:

{
  "values": [
    { "id": "examplemod:ashwood_planks", "required": false },
    { "id": "examplemod:silverwood_planks", "required": false }
  ]
}

▸ Don't set "replace": true unless you mean it - leaving it out (the default) adds to the palette; setting it throws away everything CityWorld and vanilla put there.
▸ Use "required": false - if the player removes that mod, an entry marked required breaks the whole tag and the palette falls back to nothing. Marked optional, it's simply skipped, and it's what lets one pack work across several Minecraft versions.
▸ You can reference whole tags, not just blocks - { "id": "#examplemod:planks", "required": false } picks up everything that mod tags, including blocks it adds later.

Drop the pack in the world's datapacks/ folder, or in config/openloader/data/ if you use OpenLoader, and create a new world - palettes are resolved once, when a world is first generated.

How weighting works, and why your blocks might feel rare

A palette isn't a flat list. Each tag occupies a fixed number of slots, and that number doesn't change when the tag grows. House walls, for example, give planks 6 slots out of 53 - that was six slots when there were six wood types in the game and it's still six now that there are twelve, so wooden houses are exactly as common as they always were, and which wood gets used is what widened.

The practical consequence: adding ten modded wood types to cityworld:build/planks does not make wooden buildings ten times more likely - it splits the existing wooden share across more woods. That's deliberate, it stops a heavily modded world turning every city into a timber yard, but it does mean that in a pack with lots of wood, any one specific plank becomes uncommon. If you want a mod's blocks to be genuinely prominent, add them to a palette with fewer competitors (cityworld:build/modern_stones has 24) rather than to the biggest one.

Swapping a block everywhere

Where a tag widens a palette, a substitute replaces a block outright. The block data map cityworld:substitute swaps any block CityWorld places for another, keeping its shape and facing, in its own buildings and in schematics, optionally only in some of the overworld, Nether and End. CityWorld ships it empty. The Neutral Palette add-on is built on it: no iron, gold or copper blocks in buildings, coloured wool to planks, concrete to terracotta, stained glass to clear.

▸

Determinism: palette contents are sorted by block id before anything picks from them, so the same seed always builds the same city. Installing or removing a mod that contributes to these tags will change what a given seed generates from that point on - the terrain stays put, the materials shift - but already-generated chunks never change; palette edits show up in new land only.