Structures¶
Structures define building types that the mod can recognize and validate in the world. Each structure type specifies which blocks are valid for its different parts, and how the building should be shaped. Structures are detected by right clicking their key block with the Leader Staff.
A key block belongs to a single structure. A structure isn't detected if it holds the key block of another registered structure, or if its key block is part of another one: a smeltery with two furnaces is registered through one of them, and can't be registered again through the other. Structures can share other blocks, such as a wall between two buildings.
Keeping structures up to date¶
A registered structure is detected again right before it's used, and unregistered if it no longer passes:
- when a Xoonglin claims it as its home or for its job or needs;
- when the home need or a structure need with
requires_usageis checked, at the need'sfrequency; - when a Xoonglin arrives at it to satisfy a visit need;
- when a Xoonglin starts working at it (each day, or after its work was paused);
- when its leader right clicks its key block with the staff again. This works as a regular detection: the structure is kept if it's still of the same type (taking any blocks added, like a new chest), replaced if it now matches another type, and unregistered if it fails.
Breaking the key block unregisters the structure right away. Xoonglins using an unregistered structure give it up at the next of those moments, and look for another one. The structure a job takes apart as it works (a miner's quarry, for example) isn't detected again while it's in use; the job retires it itself.
All structure types share these base fields:
type: The structure type discriminator (e.g."cft:house","cft:enclosed_building","cft:open_air_platform","cft:pasture","cft:monument","cft:multi_storey_building","cft:compound").key_block: The block that identifies the structure: right clicking it with the leader staff triggers detection. A block, a block tag or a list of them (see Game content).max_users: (Optional, default: 1) Maximum number of Xoonglins that can use this structure at the same time. Set to 0 for structures with no user limit (e.g. monuments).requires_container: (Optional, default: false) Whether the structure must contain a container block (e.g. a chest). Houses that need to store supplies should set this totrue.priority: (Optional, default: 0) Priority for structure selection. Higher values are preferred when multiple structures of the same category are available.
Block rules are specified using ValidBlock objects with these fields:
block: The blocks the rule is about: a block (e.g."minecraft:stone_bricks"), a block tag (e.g."#minecraft:planks") or a list of them (see Game content).min_quantity: At least this many blocks of this type must be present.max_quantity: No more than this many blocks of this type can be present.min_percentage: This part of the structure must have at least this percentage of blocks of this type. Always in [0,1].max_percentage: This part of the structure can't have more than this percentage of blocks of this type. Always in [0,1].
Lighting¶
Buildings with an inside (houses, enclosed buildings and multi-storey buildings) can require it
to be lit, with an optional lighting object:
min_light: The light (0 to 15) a spot needs to count as lit.min_percentage: (Optional, default: 1.0) The share of the floor that must be lit, in [0,1].
The light is measured on the spots where a Xoonglin can stand: right above the floor, on every
storey. Only light from blocks counts (torches, lanterns, glowstone...), not daylight, so a
building is lit or not at any time of day. With "min_light": 1 and the default percentage, the
building can have no dark corner, which is also where monsters can't spawn.
House¶
Houses are enclosed buildings that serve as homes for Xoonglins. They are a specialized form of enclosed buildings with doors as key blocks. A house consists of four parts: floor, walls, interior and roof.
The floor can take any shape. Walls are built over the most exterior part of the floor upwards and must all be of the same height. The roof must be built resting on the walls and covering the full surface of the house.
Houses that need to store supplies for their Xoonglin should declare "requires_container": true
and include the container block (e.g. a chest) in the interior_blocks list.
Sample house structure file
{
"type": "cft:house",
"key_block": "#minecraft:doors",
"max_users": 1,
"requires_container": true,
"priority": 0,
"floor_blocks": [
{
"block": "#minecraft:planks",
"min_quantity": 9,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"wall_blocks": [
{
"block": "#minecraft:logs",
"min_quantity": 14,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "#minecraft:planks",
"min_quantity": 0,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "#minecraft:doors",
"min_quantity": 1,
"max_quantity": 2,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"interior_blocks": [
{
"block": "minecraft:air",
"min_quantity": 0,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "minecraft:chest",
"min_quantity": 1,
"max_quantity": 1,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"roof_blocks": [
{
"block": "#minecraft:wooden_stairs",
"min_quantity": 0,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
}
]
}
floor_blocks: A list of valid block rules for the floor.wall_blocks: A list of valid block rules for the walls. Doors should be included here.interior_blocks: A list of valid block rules for the interior. Air should always be present. Include the container block (e.g. chest) if the house requires one.roof_blocks: A list of valid block rules for the roof.lighting: (Optional) How well lit the inside must be (see Lighting).
Enclosed Building¶
Enclosed buildings follow the same structure as houses (floor, walls, interior, roof) but are not homes. They are used as workplaces or other facilities (e.g. a smithy).
Sample enclosed building structure file
{
"type": "cft:enclosed_building",
"key_block": "minecraft:anvil",
"max_users": 2,
"requires_container": true,
"priority": 0,
"floor_blocks": [
{
"block": "#minecraft:stone_bricks",
"min_quantity": 4,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"wall_blocks": [
{
"block": "#minecraft:stone_bricks",
"min_quantity": 4,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "minecraft:oak_door",
"min_quantity": 1,
"max_quantity": 2,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"interior_blocks": [
{
"block": "minecraft:air",
"min_quantity": 0,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "minecraft:chest",
"min_quantity": 1,
"max_quantity": 1,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "minecraft:anvil",
"min_quantity": 1,
"max_quantity": 1,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"roof_blocks": [
{
"block": "minecraft:oak_planks",
"min_quantity": 4,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
}
]
}
The fields are identical to house structures. The key difference is that enclosed buildings
use a specific key_block (like an anvil) instead of doors, and they are not used as homes.
Open Air Platform¶
Open air platforms are flat structures surrounded by a border, such as farms or pens. They don't have a roof or enclosed walls — instead they have a border (like fences), a ground perimeter, and a surface.
Sample open air platform structure file
{
"type": "cft:open_air_platform",
"key_block": "#minecraft:fence_gates",
"max_users": 1,
"requires_container": false,
"priority": 0,
"wall_height": 1,
"border_blocks": [
{
"block": "#minecraft:fences",
"min_quantity": 4,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "#minecraft:fence_gates",
"min_quantity": 1,
"max_quantity": 1,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "minecraft:chest",
"min_quantity": 1,
"max_quantity": 1,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"ground_perimeter_blocks": [
{
"block": "#minecraft:dirt",
"min_quantity": 0,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "minecraft:grass_block",
"min_quantity": 0,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"surface_blocks": [
{
"block": "minecraft:farmland",
"min_quantity": 4,
"max_quantity": 500,
"min_percentage": 0.5,
"max_percentage": 1.0
},
{
"block": "minecraft:water",
"min_quantity": 1,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 0.25
},
{
"block": "#minecraft:dirt",
"min_quantity": 0,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 0.25
}
]
}
wall_height: (Optional, default: 1) Height of the border/wall around the platform.border_blocks: A list of valid block rules for the border surrounding the platform (e.g. fences, fence gates).ground_perimeter_blocks: A list of valid block rules for the ground below the border.surface_blocks: A list of valid block rules for the interior surface of the platform (e.g. farmland, water).
Pasture¶
A pasture is an open air platform (same border/ground perimeter/surface shape) that additionally requires a minimum — and optionally maximum — number of specific animals to be physically present inside its footprint. The animals are counted again every time the structure is detected again (see Keeping structures up to date), so a pen that's since wandered empty is unregistered rather than staying claimed on stale data.
Sample pasture structure file
{
"type": "cft:pasture",
"key_block": "minecraft:hay_block",
"max_users": 1,
"requires_container": false,
"priority": 0,
"wall_height": 1,
"border_blocks": [
{
"block": "#minecraft:fences",
"min_quantity": 4,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"ground_perimeter_blocks": [
{
"block": "minecraft:grass_block",
"min_quantity": 0,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"surface_blocks": [
{
"block": "minecraft:grass_block",
"min_quantity": 0,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"eligible_mobs": [
"minecraft:cow",
"minecraft:sheep",
"minecraft:pig"
],
"min_mob_count": 3
}
wall_height,border_blocks,ground_perimeter_blocks,surface_blocks: Same as open air platform.eligible_mobs: The animals that count toward the pasture's occupancy: entity types (e.g."minecraft:cow"), entity type tags (e.g."#minecraft:skeletons") or a list of them (see Game content).min_mob_count: (Optional, default: 1) Minimum number of eligible animals that must be inside the footprint.max_mob_count: (Optional, default: unlimited) Maximum number of eligible animals allowed inside the footprint.
Monument¶
Monuments are vertical structures validated layer by layer, such as obelisks or towers. Each layer is a horizontal slice of blocks, and rules can specify which blocks are valid at different height ranges.
Sample monument structure file
{
"type": "cft:monument",
"key_block": "minecraft:chiseled_quartz_block",
"max_users": 0,
"requires_container": false,
"priority": 0,
"min_height": 5,
"max_height": 15,
"layer_rules": [
{
"from": 0,
"to": 0,
"blocks": [
{
"block": "minecraft:chiseled_quartz_block",
"min_quantity": 1,
"max_quantity": 1,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "minecraft:quartz_block",
"min_quantity": 0,
"max_quantity": 8,
"min_percentage": 0.0,
"max_percentage": 1.0
}
]
},
{
"from": 1,
"to": 14,
"blocks": [
{
"block": "minecraft:quartz_block",
"min_quantity": 1,
"max_quantity": 9,
"min_percentage": 0.0,
"max_percentage": 1.0
}
]
}
],
"identical_layer_groups": [
{
"from": 1,
"to": 14
}
]
}
min_height: Minimum height of the monument in blocks.max_height: Maximum height of the monument in blocks.layer_rules: A list of rules, each applying to a range of layers (from bottom to top). Layer 0 is the base.from: First layer index this rule applies to (inclusive).to: Last layer index this rule applies to (inclusive).blocks: A list of valid block rules for layers in this range.
identical_layer_groups: (Optional) Groups of layers that must be identical to each other.from: First layer index of the group (inclusive).to: Last layer index of the group (inclusive).
Multi-Storey Building¶
Multi-storey buildings are made of stacked enclosed-building storeys. Each storey works like an enclosed building — it has its own floor, walls, interior and roof (ceiling) — and on top of it sits the next storey. Storey rules define the valid blocks for each storey or range of storeys, similar to how monument layer rules work.
Two consecutive storeys can be connected in either of two ways, tried in this order:
- Shared layer: the ceiling of the lower storey is at the same time the floor of the
upper one. That layer must satisfy both the lower storey's
roof_blocksrules and the upper storey'sfloor_blocksrules. - Separate layers: the floor of the upper storey sits exactly one block above the ceiling of the lower one, forming a two-block-thick separation.
All storeys share the same footprint, and every ceiling that supports another storey
must be flat (the top roof can take any shape as long as its walls vary in height).
Detection starts from the key block of the ground storey and stacks storeys upward until
one no longer fits; the building is valid if at least min_storeys are found.
Xoonglins need a way to move between storeys, and holes in a ceiling are controlled
through the block rules: list the connection blocks (ladders, or air above stairs) in the
lower storey's roof_blocks — and, when the layer is shared, in the upper storey's
floor_blocks too. Using min_quantity and max_quantity you can require a connection to
exist and limit how large the opening can be. The mod ships two examples:
two_storey_house.json (ladder connection) and two_storey_stairs_house.json (stairs
below an air opening).
Sample multi-storey building structure file
{
"type": "cft:multi_storey_building",
"key_block": "minecraft:oak_door",
"max_users": 2,
"requires_container": true,
"priority": 10,
"min_storeys": 2,
"max_storeys": 2,
"storey_rules": [
{
"from": 1,
"to": 1,
"floor_blocks": [
{
"block": "#minecraft:planks",
"min_quantity": 4,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"wall_blocks": [
{
"block": "#minecraft:logs",
"min_quantity": 4,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "minecraft:oak_door",
"min_quantity": 1,
"max_quantity": 2,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"interior_blocks": [
{
"block": "minecraft:air",
"min_quantity": 0,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "minecraft:ladder",
"min_quantity": 1,
"max_quantity": 10,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "minecraft:chest",
"min_quantity": 1,
"max_quantity": 2,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"roof_blocks": [
{
"block": "#minecraft:planks",
"min_quantity": 4,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "minecraft:ladder",
"min_quantity": 1,
"max_quantity": 1,
"min_percentage": 0.0,
"max_percentage": 1.0
}
]
},
{
"from": 2,
"to": 2,
"floor_blocks": [
{
"block": "#minecraft:planks",
"min_quantity": 4,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "minecraft:ladder",
"min_quantity": 0,
"max_quantity": 1,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"wall_blocks": [
{
"block": "#minecraft:logs",
"min_quantity": 4,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"interior_blocks": [
{
"block": "minecraft:air",
"min_quantity": 0,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "minecraft:ladder",
"min_quantity": 0,
"max_quantity": 10,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"roof_blocks": [
{
"block": "#minecraft:planks",
"min_quantity": 4,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
}
]
}
]
}
min_storeys: Minimum number of storeys the building must have.max_storeys: Maximum number of storeys. Detection never looks beyond this.storey_rules: A list of rules, each applying to a range of storeys (from bottom to top). Storey 1 is the ground storey. Every storey from 1 tomax_storeysmust be covered by exactly one rule.from: First storey this rule applies to (inclusive).to: Last storey this rule applies to (inclusive).floor_blocks: A list of valid block rules for the storey's floor.wall_blocks: A list of valid block rules for the storey's walls. Doors should be included in the ground storey's rules.interior_blocks: A list of valid block rules for the storey's interior.roof_blocks: A list of valid block rules for the storey's roof (ceiling). Include connection blocks (ladders) or air openings here for storeys that must be reachable from below.
lighting: (Optional) How well lit the inside must be, all storeys together (see Lighting).
Compound¶
Compounds are structures composed of other structures: an open surface (a plaza, a village square, a courtyard, a market...) that is only valid if enough already detected structures of the required types stand close to it. Instead of walls or fences, the surrounding buildings act as the compound's "border".
The surface is detected by flood fill starting below the key block, so the paving material must be different from the surrounding ground for the surface to have a defined shape. The key block can stand directly on the paving or on top of a small decorative pillar (up to 5 blocks tall, e.g. a bell on a stone column); the pillar blocks are ignored by validation. The referenced structures must be detected (with the leader staff) before the compound, and must belong to the same leader.
A compound cannot share surface blocks with any already detected compound, so placing a second key block on an already detected square will not create a second compound.
Sample compound structure file
{
"type": "cft:compound",
"key_block": "minecraft:bell",
"max_users": 0,
"requires_container": false,
"priority": 0,
"surface_blocks": [
{
"block": "#minecraft:stone_bricks",
"min_quantity": 25,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
},
{
"block": "minecraft:polished_andesite",
"min_quantity": 0,
"max_quantity": 500,
"min_percentage": 0.0,
"max_percentage": 1.0
}
],
"required_structures": [
{
"structure_type": "cft:settler_house",
"min": 3,
"max_distance": 16
}
],
"requires_sky_access": true
}
surface_blocks: A list of valid block rules for the compound's surface (the paving).required_structures: A list of requirements on nearby detected structures. All of them must be met for the compound to be valid.structure_type: A reference to the structure type ID that must exist nearby.min: (Optional, default: 1) Minimum number of structures of this type.max: (Optional, default: unlimited) Maximum number of structures of this type.max_distance: (Optional, default: 16) Maximum distance (in blocks) from the structure's key block to the nearest surface block of the compound.
requires_sky_access: (Optional, default: true) Whether every surface block must be open to the sky.