Content format

Jobs, research nodes, housing tiers, export entries, blueprints and professions are all datapack JSON. Adding a job, a research branch, a trade good, a building or a whole trade needs no Java at all.

Where files go#

data/<namespace>/nerocolonies/jobs/<path>.json
data/<namespace>/nerocolonies/research/<path>.json
data/<namespace>/nerocolonies/housing/<path>.json
data/<namespace>/nerocolonies/exports/<path>.json
data/<namespace>/nerocolonies/blueprints/<path>.json
data/<namespace>/nerocolonies/professions/<path>.json

The id is the file path. data/mypack/nerocolonies/research/mining/drills.json is the node mypack:mining/drills. Subdirectories are part of the id, which is how the shipped research tree gets its habitation/, industry/, life_support/ and trade/ grouping.

The job, research, housing and export schemas accept an id field and ignore it — it exists only so a file that was written out by a generator still loads. The path always wins.

A pack overrides a definition by shipping the same id. Drop your own data/nerocolonies/nerocolonies/jobs/farm.json into a datapack and it replaces the shipped farm job entirely; ordinary datapack precedence decides which pack wins.

Content is re-read whenever the server's datapacks are reloaded, so /reload applies changes immediately. Nothing is migrated and nothing needs to be: what a colony stores is a set of ids, and every number is derived from the currently loaded definitions on demand.

Three more things a pack can change live in vanilla locations rather than here: the block tags that govern land clearing (Buildings), the item tags that define colony food (Colony basics) and the Gratitude Cache's loot tables (Gratitude cache).

Item targets and item amounts#

Two small shapes appear throughout.

An item target (job inputs, export targets, blueprint materials) selects exactly one of a single item id or an item tag, plus a count:

{ "item": "minecraft:wheat", "count": 4 }
{ "tag":  "c:crops",         "count": 4 }

Declaring both, or neither, is a decode error and drops the owning definition with a warning.

Tags are the preferred form throughout the shipped content: a tag lets a farming mod, a planet mod or any third party satisfy a colony job with its own produce, and needs no compat code on either side. Hard item ids are used only where the item is unmistakably vanilla.

An item amount (job outputs, research costs, what a trade gathers) is always a concrete item:

{ "item": "minecraft:iron_ingot", "count": 8 }

Jobs#

data/<namespace>/nerocolonies/jobs/<path>.json

The shipped nerocolonies:fabricate:

{
  "station": "nerocolonies:fabricator_station",
  "inputs": [
    { "item": "minecraft:iron_ingot", "count": 1 },
    { "item": "minecraft:redstone", "count": 2 }
  ],
  "outputs": [
    { "item": "minecraft:repeater", "count": 1 }
  ],
  "ticks": 400,
  "colonists": 2,
  "morale_floor": 35.0,
  "research": "nerocolonies:industry/fabrication",
  "export": true
}

Every magnitude here is scaled at runtime by jobBaseRateMultiplier and by the colony's morale multiplier, so the JSON expresses shape — what turns into what, and roughly how fast — not balance.

A job is dropped when it has no outputs, when its station block is not registered, when one of its inputs resolves to nothing in this launch, or when one of its outputs names an unregistered item. A recipe missing an ingredient is not a cheaper recipe, it is a broken one.

Research nodes#

data/<namespace>/nerocolonies/research/<path>.json

The shipped nerocolonies:habitation/pressurised_modules:

{
  "branch": "habitation",
  "title": "research.nerocolonies.habitation.pressurised_modules",
  "requires": [ "nerocolonies:habitation/shelter" ],
  "cost": [
    { "item": "minecraft:iron_ingot", "count": 8 },
    { "item": "minecraft:glass", "count": 4 }
  ],
  "effects": [
    { "type": "nerocolonies:housing_tier", "tier": "nerocolonies:habitat_module" },
    { "type": "nerocolonies:morale_bonus", "amount": 2.0 }
  ]
}

Costs are paid from colony storage, and unlocks are written to the colony record — research is colony-local and is not personal data.

Research effects#

Effects are a dispatched type keyed on type:

A blueprint can also name a research node as its prerequisite, with its own research field; that needs no effect on the node.

An unregistered type is not an error. It decodes to an inert Unknown effect: the node still loads, that one effect does nothing, and the id is logged once per session. A datapack written for a newer NeroColonies therefore degrades rather than bricking an older jar. An add-on mod may register its own effect types the same way the built-ins are registered; ids are namespaced, so a collision is the registering mod's own doing.

How the research graph is validated#

Three passes, in order:

1. Effects that point at content which did not load are reported and kept. They simply match nothing. Keeping them means removing one mod does not silently reshape a tree.
2. Dangling prerequisites are pruned and the node stays. A node that requires an id no longer in any pack loses that one requirement rather than the whole node.
3. Cycles are dropped. The graph is peeled from its roots; anything left is in — or behind — a prerequisite cycle and can never be unlocked, so it is removed.

Housing tiers#

data/<namespace>/nerocolonies/housing/<path>.json

The shipped nerocolonies:habitat_module:

{
  "block": "nerocolonies:habitat_module",
  "tier": 2,
  "capacity": 4,
  "comfort": 0.65,
  "research": "nerocolonies:habitation/pressurised_modules"
}

Housing is matched by block, not by block entity: one block-state comparison during the sweep, no block entity needed, and a pack can declare any block in the game — vanilla beds, another mod's crew module — as colony housing.

A tier is dropped when its block is not registered or when its capacity is zero. If two tiers claim the same block, the one with the higher tier wins, deterministically.

Export entries#

data/<namespace>/nerocolonies/exports/<path>.json

The shipped nerocolonies:refined_metals:

{
  "target": { "item": "minecraft:iron_ingot", "count": 1 },
  "base_value": 4.0,
  "stack_size": 64,
  "research": "nerocolonies:trade/manifest"
}

An entry is dropped when its target resolves to no item in this launch — an empty tag sells nothing.

Blueprints#

data/<namespace>/nerocolonies/blueprints/<path>.json

A blueprint is one building a colony can put up. An example that uses every field:

{
  "name": "blueprint.mypack.storehouse",
  "category": "storage",
  "stage": "settled",
  "priority": 35,
  "max": 2,
  "level": 1,
  "upgrade_to": "mypack:storehouse_2",
  "unlocks": [ "nerocolonies:hauler" ],
  "roles": [ "eat" ],
  "capacity": { "housing": 0, "storage": 27, "jobs": 2 },
  "research": "nerocolonies:habitation/shelter",
  "palette": {
    "#": "minecraft:oak_planks",
    "S": "minecraft:oak_stairs[facing=south,half=bottom]",
    "D": "nerocolonies:colony_depot",
    "_": "minecraft:air"
  },
  "layers": [
    [ "###", "###", "###" ],
    [ "###", "#D#", "#_#" ],
    [ "###", "#_#", "#_#" ],
    [ "###", "###", "SSS" ]
  ],
  "materials": [
    { "tag": "minecraft:planks", "count": 24 },
    { "item": "nerocolonies:colony_depot", "count": 1 }
  ],
  "rotate": true
}

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). The front of a building is its south side, the last row of each slice: that is where an entrance belongs, and it is the side the colony turns towards the beacon.

Rows are padded with spaces to the widest row in the blueprint, so a ragged grid is a shape rather than an error. Cells are built bottom layer first, then north → south, then west → east.

Every character means one of three things:

Block-state strings#

A palette value is a block id, optionally followed by properties in square brackets, exactly as the /setblock command writes them:

minecraft:oak_planks
minecraft:oak_stairs[facing=north,half=bottom]
minecraft:oak_door[facing=south,half=lower,hinge=left,open=false]

A bare id means the block's default state. A property or a value the block does not have is ignored and the rest of the state still applies, so a blueprint written for one Minecraft version degrades on another rather than vanishing. Two-block things — doors, tall plants, beds — need both halves in the palette, as in the door example above and its half=upper twin.

Structure files#

Instead of palette and layers, a blueprint may point at a vanilla structure file:

{ "structure": "mypack:town_hall" }

reads data/mypack/structure/town_hall.nbt, the file a structure block saves. Every other blueprint field works as usual. At load time the structure becomes an ordinary grid:

• each distinct block state becomes a palette entry;
• air in the structure becomes a clear cell;
• minecraft:structure_void, and any position the file does not mention, becomes a hole;
• block-entity contents and entities in the file are ignored. A chest in the structure is built as an empty chest. Copying inventories out of a datapack would be an item duplication path.

The building still goes up a few blocks per cycle like any other.

Rotation#

With "rotate": true the colony turns the building in quarter turns so that its front faces the beacon, and a member placing it with the Colony Planner may turn it by hand. Block states are turned with it using the game's own rotation, so stairs, doors and logs stay correct. Set rotate to false for a building that only makes sense one way round.

Stages, levels and upgrades#

• stage gates the blueprint. founding blueprints are the Starter Works: they are the only thing a Founding colony builds, they are built only from supplied materials while it is Founding, and a colony becomes Settled when each has been built once. A pack with no founding blueprints has no such gate. See Progression.
• To make an upgrade chain, give the first building "level": 1 and "upgrade_to" its successor, and give the successor "level": 2 and the same width and depth. The successor's own stage and research decide when the upgrade may happen. A successor with a different footprint is never upgraded to.
• max counts the first level only; an upgrade does not use up any of it.

Roles, unlocks and capacity#

unlocks lists professions. Each finished building opens that profession's per_building places.

roles are short tags. The colony acts on these six:

Any other string is accepted and carried along without effect. The shipped content uses sleep, planning and needs_board that way, as labels.

capacity is descriptive. Nothing in the colony reads it: beds are counted by the housing sweep from the housing blocks actually in the building, storage is what colony storage holds, and job places come from unlocks. Keep it truthful for anything that displays it.

Limits#

A blueprint over the format's limits is dropped at load. One within them but over a server's configured limits loads, and is skipped by the planner and the Colony Planner on that server.

Professions#

data/<namespace>/nerocolonies/professions/<path>.json

A profession is a Neran trade. The shipped nerocolonies:farmer:

{
  "name": "profession.nerocolonies.farmer",
  "behaviour": "nerocolonies:farmer",
  "tool": "minecraft:iron_hoe",
  "stations": [
    "nerocolonies:farm_station",
    "nerocolonies:hydroponics_station"
  ],
  "priority": 10,
  "per_building": 2,
  "max_per_colony": 8,
  "xp_per_level": 100,
  "max_level": 5,
  "work_radius": 10,
  "outputs": [
    { "item": "minecraft:wheat", "count": 1 },
    { "item": "minecraft:potato", "count": 1 },
    { "item": "minecraft:carrot", "count": 1 },
    { "item": "minecraft:wheat_seeds", "count": 1 }
  ],
  "output_chance": 0.5
}

Numbers and bindings are data; behaviours are code. behaviour names one of the twelve behaviours compiled into the mod: nerocolonies:farmer, forester, miner, builder, hauler, cook, toolsmith, guard, beastkeeper, researcher, quartermaster and medic. An unknown id falls back to standing at the workplace.

A profession is opened by any blueprint that lists it in unlocks. One that no blueprint unlocks loads, is reported, and is never assigned.

The special trades are tied to the profession's id, not to its behaviour. Fighting belongs to nerocolonies:guard; the site speed bonus to nerocolonies:builder; meals, tool-making, the morale lift, cache stocking and guardian upkeep to nerocolonies:cook, toolsmith, medic, quartermaster and beastkeeper. To retune one of those, override the shipped file under the same id. A new profession that borrows the nerocolonies:guard behaviour patrols the guard posts but does not fight.

How these numbers play out is on Nerans and professions.

Bad content is never fatal#

This is a hard rule. Every malformed file, unknown effect type, dangling reference, cycle and unregistered id is logged at warning level against its resource id, and the offending entry is dropped or pruned — the rest of the pack still loads. Even a load that fails outright leaves the server running with no colony content rather than crashing it.

The same complaints are collected as a report so an operator can see what a pack got wrong without reading the server log:

/nerocolonies reload-check

Issues come in two severities: DROPPED (the definition is not loaded at all) and IGNORED (the definition loaded, but part of it was skipped). Nothing in the report is player data — resource ids and codec messages only, and never a filesystem path.

What is checked#

The report also gives the number of definitions of each kind that loaded. Content is validated in the order housing, jobs, exports, research, blueprints, professions, so each kind is checked against what actually survived before it.

See also#

• Buildings — how blueprints are chosen and placed, and the shipped set
• Nerans and professions — how professions behave in play
• Jobs & research — how job and research definitions behave in play
• Exports & outposts — how export entries are valued
• Colony basics — the housing sweep that reads housing tiers
• Commands — reload-check