Skip to content

Construction

Jump to bottom
github-actions[bot] edited this page Aug 5, 2026 · 1 revision

Autonomous construction

A colony builds itself. You place a beacon, two founders arrive with it, and they get on with putting up a habitat — no build orders, no assignment screen, no clicking. Your lever is supply: bring the materials and the same structure goes up four times faster.

This page covers the founders, the build loop, blueprints as datapack content, and the levers an operator has.

Founder colonists

Placing a colony beacon puts founderColonistCount colonists (default 2) on the ground next to it, immediately — not on the first colony cycle a minute and a half later. They are the seed of the whole loop: housing is what lets colonists arrive, and building housing is what colonists do, so without founders nothing can ever start.

Founders are held on the roster regardless of housing capacity. That is a floor, not an exemption:

  • they still count toward colonistsPerColony and the server-wide maxLoadedColonists;
  • they get exactly the same life support, food and morale treatment as anybody else — on an airless world the usual curve applies (life support fails → morale decays → work stops → colonists idle), and no colonist is ever killed or deleted for it;
  • a colony that drops below its founder count will replace them even while starving or without atmosphere. That exemption is deliberate: a colony with nobody left has nothing that can build the farm or the oxygen generator that would fix the problem, so gating the bootstrap on food and air would make such a colony permanently dead rather than merely in trouble. It is bounded by founderColonistCount and cannot grow a colony past it.

Set founderColonistCount to 0 to switch founders off. Autonomous construction then never starts on its own — the colony waits for you to build the first housing by hand.

The build loop

Every colony cycle (colonyTickIntervalTicks, default 100 ticks) a colony with nothing under construction picks the highest-priority blueprint it is allowed to build, looks for somewhere to put it, and starts. Thereafter it lays constructionBlocksPerCycle blocks per cycle (default 2) until the structure is finished, then picks the next one.

Deliberately slow. A colony growing visibly over minutes reads as a colony; one that snaps into existence reads as a command block.

Supplied and unsupplied

At the start of every cycle, a build that has not yet been paid for looks for its blueprint's materials in colony storage. If they are all there they are consumed once and the build runs at full rate. If they are not, the colonists fabricate from scrap instead: the same structure, free, at constructionUnsuppliedFactor of the rate (default 0.25).

Nothing is ever blocked on materials. A colony left entirely alone still grows, just slowly — a colony that stops dead waiting for iron is a colony you have to babysit.

The check runs every cycle, not only when the build starts, so dropping materials into colony storage part way through speeds up the build already under way. That is the whole player-facing lever.

Materials go into colony storage, which you reach through a Colony Depot inside the claim, or through any pipe or hopper inserting into the beacon. They do not go in the beacon's six supply slots — those are the food intake and refuse anything that is not food.

Where a colony may build

Rule Why
Inside the claim only, re-checked per block A claim can shrink when a RANGE module is pulled out
Only into blocks that are replaceable — air, grass, snow, water Your chest, wall or torch is never overwritten, and neither is another structure
Loaded chunks only, never loading one The far edge of a 97-block claim is often not loaded; the search skips it rather than paying to load it
Flat ground: the footprint's highest and lowest surface may differ by at most one Colonies level nothing and dig nothing
The base must sit within 4 blocks below and the top within 12 above the beacon Keeps a colony from terracing up a cliff, and keeps what it builds inside the band the housing sweep reads
The bottom layer must have solid ground under it No floating structures

Candidate sites are walked in rings out from the beacon, so a colony grows outward from its centre rather than filling the claim from one corner. Eight candidates are examined per cycle; a colony that is completely boxed in gives up for ten cycles before looking again, so a hemmed-in colony costs nothing.

If a player builds something on a chosen site part way through, that cell is simply skipped — the player wins, always.

When it stops

Construction pauses (never cancels, never demolishes) when:

  • constructionEnabled is false;
  • morale has fallen below moraleWorkStopThreshold and work has stopped;
  • life support is FAILED;
  • constructionRequiresColonist is set (the default) and the colony's roster is empty;
  • the colony has reached maxAutoStructures, or that blueprint's own max.

Nothing NeroColonies built is ever demolished automatically. A half-built structure whose blueprint was removed from the datapack is abandoned in place, not torn down.

Housing pressure

Housing blueprints are only eligible when the colony is actually short of bunks — fewer than two free places. That is what keeps "autonomous" from turning into "sprawls to the edge of the claim". With the shipped content the loop reads:

  1. two founders, no housing → build a Habitat Pod;
  2. capacity 2, population 2 → still no headroom → build a second pod;
  3. capacity 4, population 2 → headroom → stop building housing, build a farm plot instead;
  4. population grows to 4 → no headroom again → third pod.

The builder

One colonist the job board did not need this cycle is pointed at the site and walks over to it, so you can see where the colony is working. That is all it does.

Block placement is colony-tick logic and never consults the builder: constructionRequiresColonist asks whether the colony has anybody, never whether anybody arrived. A colonist that cannot path to a site — a wall, a cliff, deep water, night time — must not be able to stall a colony's growth.

Being a builder is a role, not a personality. It uses the jobId field a colonist already has, it is reassigned from scratch every cycle, and any colonist will do.

While nobody is there

Offline catch-up advances a colony's fabrication credit and places no blocks at all. Laying a backlog's worth of blocks on the tick a chunk loads would be a visible stutter and a lighting-update storm at exactly the worst moment.

The credit is capped at four cycles' worth, so a returning player sees the build resume briskly for a few cycles and then settle to the normal rate. A colony never starts a new structure while nobody is there.

Watching it happen

The beacon's Colony tab shows one line:

  • Building Habitat Pod - 34% — supplied, running at full rate;
  • Fabricating Habitat Pod - 34% — unsupplied, running at constructionUnsuppliedFactor. Put the materials in colony storage;
  • Not building - 3 structure(s) up — idle.

A completed structure also:

  • publishes Core's nerocolonies:structures threshold crossing, scoped to the colony id and carrying the new total, so a NeroQuests objective can key off "this colony has built its third structure" with no coupling to this mod;
  • pushes a construction event to the colony owner's companion sessions (Link module);
  • triggers an immediate housing rescan, so a finished habitat raises capacity within seconds rather than at the next scheduled sweep.

Blueprints

Blueprints are plain datapack JSON at data/<namespace>/nerocolonies/blueprints/<path>.json. The id is the file's namespace plus its path without the extension, so a pack overrides a shipped blueprint by shipping the same id.

{
  "name": "blueprint.nerocolonies.habitat_pod",
  "category": "housing",
  "priority": 10,
  "max": 6,
  "research": "nerocolonies:habitation/shelter",
  "palette": {
    "#": "minecraft:smooth_stone",
    "G": "minecraft:glass",
    "H": "nerocolonies:habitat_pod"
  },
  "layers": [
    [ "###", "###", "###" ],
    [ "###", "#H#", "#.#" ],
    [ "###", "#G#", "#.#" ],
    [ "###", "###", "###" ]
  ],
  "materials": [
    { "item": "minecraft:smooth_stone", "count": 16 },
    { "item": "minecraft:iron_ingot", "count": 6 },
    { "item": "minecraft:glass", "count": 2 }
  ]
}
Field Type Default Meaning
name string derived from the id Translation key for the display name
category string other housing, farm, industry, storage, life_support, other. Only housing behaves differently (the pressure rule). An unrecognised value becomes other
priority int 100 Lower is built first
max int 4 How many of this structure one colony may build. 0 disables the blueprint
research id — Optional research node the colony must have unlocked
palette map required One character → one block id
layers array required The layout, see below
materials array [] ItemTarget list — {"item": …} or {"tag": …} plus count. An empty list always builds at full speed

The layout

layers is a list of horizontal slices bottom-up. Each slice is a list of rows running north → south (+Z); each row is a string running west → east (+X).

A character with no palette entry is a hole: nothing is placed and whatever is there is left alone. . and a space are the conventions used by the shipped content, but any unmapped character works.

Rows are padded to the widest row in the blueprint, so a ragged grid is a shape rather than an error. Blocks are placed in their default block state — a blueprint describes a layout, not block states, which is exactly what keeps it hand-authorable. Maximum size is 16 × 16 blocks and 12 layers.

Cells are built bottom layer first, then north → south, then west → east.

Validation

Bad content is never fatal, and the severity split matters:

Problem Result
A palette entry naming an unregistered block Ignored — those cells become holes and the rest of the structure still builds. Removing a mod from a pack leaves gaps, not a broken colony
A material naming an item that is not installed Ignored — the blueprint simply always builds unsupplied
research naming a node that did not load Ignored — the blueprint stays and never becomes eligible, which is more use in the report than deleting it
Every cell is a hole Dropped — it can never do anything
No layers, an empty grid, or bigger than 16 × 16 × 12 Dropped

/nerocolonies reload-check lists everything the last load complained about, and reports the blueprint count alongside jobs, research, housing and exports.

Shipped blueprints

Id Category Priority Max Puts up
nerocolonies:habitat_pod housing 10 6 A 3 × 3 stone pod around a Habitat Pod (capacity 2)
nerocolonies:farm_plot farm 20 2 A 5 × 5 farmland patch with a water source and a Farm Station
nerocolonies:depot_shed storage 30 2 A 3 × 3 shed around a Colony Depot
nerocolonies:oxygen_hut life_support 40 1 A glazed 3 × 3 hut around an Oxygen Generator
nerocolonies:research_cabin industry 50 1 A 4 × 4 cabin around a Research Station

None of them require research, so a brand-new colony can work through the whole list. The Oxygen Hut is useless on a breathable world and harmless there — it simply idles.

The stations and machines a colony builds for itself still need power and inputs from you. A colony can put up a refinery; it cannot run a cable to it.

Configuration

Key Default Effect
founderColonistCount 2 Colonists that arrive with a new beacon. 0 disables the bootstrap
constructionEnabled true Master switch
constructionBlocksPerCycle 2 Blocks placed per colony cycle at full rate
constructionUnsuppliedFactor 0.25 Rate multiplier without materials. 0 means an unsupplied colony never builds
constructionRequiresColonist true Whether an empty roster stops building
maxAutoStructures 12 Total structures one colony may build for itself

See Config for the full table.

Privacy

Nothing on this page involves player data. A build plan is keyed by a colony id — a place, not a person — and holds blueprint ids, a block position and counters. The threshold channel is colony-scoped by contract; the companion event is owner-scoped and names no other player. See Data storage.

See also

Clone this wiki locally