Skip to content

Latest commit

 

History

History
381 lines (275 loc) · 8.59 KB

content-authoring.md

File metadata and controls

381 lines (275 loc) · 8.59 KB

Content Authoring

Status: reference for adding resources, machines, recipes, build recipes, and scenarios to the current data-driven slice.

This guide is for the current sim_core content model in content.rs. If a new idea does not fit one of the existing behavior types, it is not a pure data change and will require Rust work in both the simulation and client.

1. Content Files

Primary data files:

Validation happens when the catalog loads. The workspace tests already cover content loading, so broken links should fail fast during cargo test.

2. Authoring Order

Add new slice content in this order:

  1. Add any new resources
  2. Add recipes that use those resources
  3. Add the machine that runs the recipe
  4. Add a build recipe if the machine should be fabricable
  5. Add the machine to a scenario starter inventory if needed
  6. Add or update a scenario that exercises the content
  7. Add a simulation test if the new content introduces a new edge case

3. Resources

Schema is defined by ResourceDef in content.rs.

Fields:

  • id: stable machine-readable id
  • display_name: player-facing label
  • kind: solid, field, or utility
  • color: RGB floats in 0.0..=1.0

Example:

(
    id: "slag",
    display_name: "Slag",
    kind: solid,
    color: (0.42, 0.38, 0.35),
)

Use ids that are short, stable, and lowercase snake case.

4. Recipes

Schema is defined by RecipeDef.

Fields:

  • id
  • machine: machine id that owns the recipe
  • inputs
  • outputs
  • cycle_ticks
  • contamination_risk

Example:

(
    id: "smelt_slag",
    machine: "crusher",
    inputs: [
        (resource: "ore_chunk", amount: 1),
    ],
    outputs: [
        (resource: "slag", amount: 1),
    ],
    cycle_ticks: 8,
    contamination_risk: 0.0,
)

Rules:

  • every referenced resource must exist
  • the owning machine must exist
  • for processor machines, the machine's default recipe must point back to that machine id

5. Machines

Schema is defined by MachineDef, PortDef, and BehaviorDef.

Important fields:

  • id
  • display_name
  • category
  • footprint
  • ports
  • behavior
  • render.color
  • render.model
  • render.model_scale
  • render.model_offset

5.0 Render Hints

render is the current data contract between sim_core content and the Bevy client.

Fields:

  • color: fallback graybox/body tint
  • model: optional asset path such as models/mixer.glb
  • model_scale: optional XYZ scale multiplier for the imported scene
  • model_offset: optional XYZ local offset from the machine origin cell

Rules:

  • omit model to keep the machine on the built-in cube fallback
  • author one canonical north-facing asset and let runtime rotate it
  • keep model_scale at (1.0, 1.0, 1.0) unless the source asset needs correction
  • use model_offset sparingly; fix pivots in Blender first if possible
  • the client still falls back to cube visuals when overlays or slice rules would make the model less readable

Example:

render: (
    color: (0.63, 0.56, 0.42),
    model: "models/mixer.glb",
    model_scale: (1.0, 1.0, 1.0),
    model_offset: (0.0, 0.0, 0.0),
),

5.1 Footprint

footprint is a list of local occupied cells.

Rules:

  • must not be empty
  • must not contain duplicates
  • cells are authored in local north-facing space
  • runtime rotation is horizontal only right now

Example:

footprint: [
    (x: 0, y: 0, z: 0),
    (x: 0, y: 1, z: 0),
]

5.2 Ports

PortDef fields:

  • id
  • cell: local footprint cell
  • face: north, east, south, west, up, down
  • kind: item or power
  • flow: input, output, or bidirectional
  • allowed_resources

Rules:

  • a port cell must belong to the machine footprint
  • every resource in allowed_resources must exist
  • author ports in north-facing local space

World direction convention:

  • north = -Z
  • east = +X
  • up = +Y

5.3 Behaviors

Current supported behaviors:

  • structural
  • wire
  • conveyor
  • lift
  • generator
  • extractor
  • processor
  • fabricator

If the machine idea does not fit one of these, it requires code changes.

Structural

Inert support or construction piece.

behavior: (type: "structural")

Wire

Participates in the power transport network.

behavior: (type: "wire")

Conveyor

Directed item movement on one cell.

behavior: (type: "conveyor", move_ticks: 3)

Lift

Vertical directed item transfer.

behavior: (type: "lift", move_ticks: 5)

Generator

Provides power to the network.

behavior: (type: "generator", power_output: 16)

Extractor

Produces a resource directly from a matching map node.

behavior: (
    type: "extractor",
    allowed_nodes: ["ore_chunk", "biomass"],
    cycle_ticks: 8,
)

Processor

Uses one recipe from recipes.ron.

behavior: (
    type: "processor",
    recipe: "crush_ore",
    contamination_on_interrupt: 0.0,
)

Fabricator

Consumes routed items and credits global build inventory.

behavior: (
    type: "fabricator",
    allowed_build_recipes: [
        "build_belt",
        "build_wire",
    ],
    cycle_ticks: 10,
)

6. Build Recipes

Schema is defined by BuildRecipeDef.

Fields:

  • id
  • output_part
  • inputs
  • cycle_ticks

Rules:

  • output_part must be a valid machine/part id
  • every input resource must exist
  • if a fabricator should be able to produce it, the build recipe id must appear in the fabricator's allowed_build_recipes

Example:

(
    id: "build_belt",
    output_part: "belt",
    inputs: [(resource: "stabilized_plate", amount: 1)],
    cycle_ticks: 6,
)

7. Scenarios

Each scenario lives in its own .ron file under assets/data/scenarios.

Important fields:

  • id
  • display_name
  • size
  • terrain_boxes
  • resource_nodes
  • starter_inventory
  • preplaced_parts
  • objective
  • prompts

Rules:

  • terrain and resource nodes must be in bounds
  • starter inventory parts must exist
  • objective resources must exist
  • preplaced parts should only be used when the scenario truly needs them

8. What Can Stay Data-Only

These changes should usually stay data-only:

  • new resource ids
  • new processor recipes
  • different machine colors
  • different machine footprints
  • different port layouts
  • different starter inventories
  • different scenario terrain/resource distributions
  • new build costs
  • alternate objective definitions using the existing objective variants

9. What Requires Rust Changes

These are not just data edits:

  • new machine behavior families
  • fluids, gases, or continuous transport
  • new objective types
  • new overlay logic
  • new port kinds beyond item and power
  • new simulation commands
  • different rotation rules such as vertical-facing placement

10. Practical Checklist For A New Machine

For a new machine that fits existing behavior:

  1. Add any missing resources in resources.ron
  2. Add a recipe in recipes.ron if needed
  3. Add the machine to machines.ron
  4. Add a build recipe in build_recipes.ron if fabricable
  5. Add the build recipe id to a fabricator's allowed_build_recipes if needed
  6. Add the machine to scenario starter inventory if the scenario depends on it
  7. Run cargo test
  8. Run cargo clippy --workspace --all-targets -- -D warnings

11. Practical Checklist For A New Item

  1. Add the resource to resources.ron
  2. Reference it from recipes and port restrictions
  3. Add scenario nodes only if it is a raw extractable resource
  4. Verify the machine chain can actually route it through valid ports
  5. Run cargo test

12. Current First-Slice Recommendation

Keep authoring narrow. Prefer:

  • more scenario variation
  • clearer machine definitions
  • better balance values

Do not widen the content surface casually. The first slice only proves the current machineworks loop if every added machine still helps readability instead of diluting it.