Builder guides
Crafting System Builder Workflows
Purpose
This document explains the practical builder workflow for creating, revising, validating, and testing crafts in game.
The intended audience is builders and staff users working through the craft command family rather than editing code directly.
Mental Model
When you build a craft, you are authoring a staged work definition.
You are not just saying "this input becomes this item". You are defining:
- who can see or use the craft
- what the active progress item looks like
- which tools must be present, worn, wielded, or merely nearby
- which materials or target items the craft reserves and consumes
- which phase performs the success check
- what the crafter visibly does during each phase
- what comes out on success and on failure
If a craft feels wrong in play, the problem is often in one of those behavioural choices rather than in the final product alone.
Normal Authoring Workflow
- Find an existing craft to inspect, or create/clone one with
craft list,craft show,craft edit new, orcraft clone. - Set craft-wide metadata such as name, category, blurb, action text, progress-item text, and check settings.
- Author the ordered phases with their timings, echoes, fail echoes, exertion, and stamina settings.
- Add and configure inputs, tools, products, and fail products.
- Assign availability and callback progs.
- Validate with
craft showand fix any errors shown at the bottom. - Test from the player side with
craft view,craft previewormaterials, andcraft begin. - Submit and review through the normal revisable workflow once the craft is valid.
Main Command Surface
Player-facing commands
Use these to test the craft as a player would see it:
craftscraft begin <craft>craft resume <progress item>craft view <craft>craft preview <craft>materials <craft>craft categoriescraft find <item>analyse <carried item>/analyze <carried item>— optional binary capability; see configuration and matching limits
Builder-facing commands
Use these to author and review craft content:
craft list [filters]craft show <craft>craft edit <craft>craft edit newcraft edit closecraft edit submitcraft review <id>|all|minecraft clone <craft> <newName>craft set <...>
Important note:
craft setis the general edit entry point once you have the craft open for editing.
Craft-Wide Command Reference
The following options are the core craft set workflow.
| Command | What it sets | Notes |
|---|---|---|
name <text> |
Craft name | Must remain globally unique across approved and in-design crafts |
category <text> |
Craft category | Used by craft list and category browsing |
blurb <text> |
Short player-facing description | Shown in the crafts list |
action <gerund text> |
Current-action description | Should read like forging a sword blade |
item <passive text> or progress <passive text> |
Active progress item short description | Should read like a sword being forged |
check <free rolls> <trait> <difficulty> |
Main craft outcome check | Controls skill gate and free extra improvement rolls |
practical |
Toggle practical versus theoretical check | Affects trait-use type on the outcome check |
threshold <outcome> |
Failure threshold | Outcome at or below this threshold fails the craft |
failphase <number> |
Phase where success/failure split occurs | Must be a real phase |
interruptable |
Toggle whether interruption pauses or cancels | Non-interruptable crafts are cancelled when interrupted |
appear <prog> |
Craft-list visibility prog | Required for craft validity |
canuse <prog> |
Start-permission prog | Must return boolean for one character |
whycannotuse <prog> |
Failure-message prog | Must return text for one character |
onstart <prog> |
Start callback | Must accept one character |
onfinish <prog> |
Completion callback | Must accept one character |
oncancel <prog> |
Cancellation callback | Must accept one character |
Phase Authoring
Phase commands
| Command | Purpose |
|---|---|
phase add <seconds> "<echo>" ["<failecho>"] |
Add a new phase |
phase edit <number> <seconds> "<echo>" ["<failecho>"] |
Replace an existing phase |
phase remove <number> |
Delete a phase |
phase swap <phase1> <phase2> |
Reorder two phases |
phase exertion <phase> <level> |
Set minimum exertion for that phase |
phase stamina <phase> <value> |
Set stamina cost for that phase |
Important current behaviour:
- if you omit the fail echo when adding or editing a phase, it defaults to the normal echo
- the fail phase is not a separate phase list; it is the phase where the check happens and the craft then follows either the success or failure branch
Token meanings
Craft echoes are functional, not just cosmetic.
| Token | Meaning |
|---|---|
$iN |
input number N |
$tN |
tool number N |
$pN |
normal product number N |
$fN |
fail product number N |
Why token placement matters
The engine uses token placement to decide timing.
Current verified rules:
- the first success-echo use of
$iNdecides when that input becomes consumed - the presence of
$tNin a phase makes that tool part of that phase's tool plan - the first success-echo use of
$pNdecides when that normal product is produced - the first fail-echo use of
$fNdecides when that fail product is produced
Defaulting rules if you never reference something:
- an unreferenced input is treated as consumed at phase 1
- an unreferenced tool is treated as required in every normal phase
- an unreferenced normal product defaults to the fail phase
- an unreferenced fail product defaults to the fail phase
Important fail-echo rule:
- fail products must only appear as
$fNin fail echoes, never in normal echoes
Inputs, Tools, Products, and Fail Products
Inputs
Use:
input add <type>input remove <number>input <number> <subcommand>
Tools
Use:
tool add <type>tool remove <number>tool <number> <subcommand>
Products
Use:
product add <type>product remove <number>product <number> <subcommand>
Fail products
Use:
failproduct add <type>failproduct remove <number>failproduct <number> <subcommand>
Builder Reference: Inputs
| Alias | What it is for | Main subcommands | Important constraints |
|---|---|---|---|
simple |
Exact item prototype input | item, quantity, quality |
Must set a target item |
simplematerial |
Items made from an exact material or material tag | material, tag, quantity, quality |
Must set either the exact material or the material tag |
tag |
Tagged item input | tag, quantity, quality |
Best for generic consumables like thread or padding |
tagvariable |
Tagged item input that also supplies characteristics | tag, quantity, variable, quality |
Item must expose every declared characteristic definition |
commodity |
Exact-material commodity pile input | material, weight, optional tag, quality |
Must set exact material and positive weight |
commoditytag |
Material-tagged commodity pile input | material, weight, optional tag, quality |
Uses a material tag rather than one exact solid |
liquid |
Specific liquid input | liquid, amount, quality |
Must set liquid and positive amount |
tagliquid |
Liquid input from a tagged source | tag, amount, quality |
Useful for tagged vessels or apparatus |
repair |
Target item to repair | tag, repair, quality |
Targets a tagged item and repairs condition by a percentage |
field |
Local agriculture field input | use, crop, woodland, condition, health, yield, consume |
Requires a matching field in the crafter's current cell and can consume crop or woodland yield |
Builder Reference: Tools
All tools also support the shared base tool options:
heldwornwieldroomqualityusetool
| Alias | What it is for | Type-specific subcommands | Important constraints |
|---|---|---|---|
simple |
Require one exact item proto | item |
Use when one specific prototype must be present |
tag |
Require any item matching a tag | tag |
Use for tool families such as hammer, anvil, pliers, or sewing needle |
Builder Reference: Products
| Alias | What it is for | Main subcommands | Important constraints |
|---|---|---|---|
simple |
Load ordinary items | item, skin, quantity, material |
Must set an item proto; skin must match that proto and be approved |
variable |
Load items with inherited and/or deliberately selected characteristics | item, skin, quantity, variable <definition> <input#>, variable <definition> value <value> |
Each definition has one rule; inherited values require a variable-aware input, selected values require an exact compatible value name or ID |
inputvariable |
Load items whose characteristics depend on which item was used for an input | item, skin, quantity, variable ... |
Requires explicit input index and per-item value mappings |
commodity |
Load commodity piles | commodity, weight, tag, material |
Requires material and positive weight |
money |
Produce money | currency, amount |
Requires currency and positive amount |
npc |
Spawn NPCs from a template | template, quantity, optional prog |
Template must be approved; optional prog must be void(Character) |
prog |
Let a prog decide which items to load | prog |
Prog must match the runtime signature expected by the product |
progvariable |
Load an item and fill characteristics from progs | item, quantity, variable <definition> <prog> |
Use when characteristic values are better derived by code than by input lookup |
unusedinput |
Return a portion of a consumed item input | input, percentage |
Target input must consume items or item groups |
scrap |
Convert part of an input into scrap commodity | input, percentage, tag, material |
Good for salvage-style fail outputs |
dnatest |
Compare two liquid inputs | input1, input2 |
Both targeted inputs must consume liquids and must be different |
bloodtyping |
Test one liquid input against a blood model | input, bloodmodel |
Requires a valid blood model plus a liquid-consuming input |
For a variable product, variable Colour 1 copies Colour from the first variable-aware input; variable Accent value white selects white for Accent on that product. Both rules can coexist when the item supports both definitions. An exact selected value affects crafted instances, not every copy of the prototype or skin. variable <definition> removes either rule, and configuring a new rule for the same definition replaces the old one. Invalid selections leave the previous configuration intact. Missing or incompatible input values stop product creation instead of silently choosing another colour. Check garment definitions and permitted palettes as part of content preflight; these product rules do not create characteristic channels on the item.
Review and Debugging Workflow
Inspect the craft definition
Use:
craft show <craft>craft showwhile editing
This is the most important builder command because it shows:
- current settings
- phase ordering
- current input, tool, product, and fail-product numbering
- validity state
- specific validation errors at the bottom when something is wrong
Inspect discoverability
Use:
craft list [filters]craft categoriescraft find <item>
Useful list filters:
+keyword-keyword- category name
*<item proto id>&<tag>^<liquid>
Inspect player feasibility
Use:
craft view <craft>craft preview <craft>materials <craft>
Interpretation:
- missing tools usually means wrong tool state, wrong tool definition, or not enough wielders/hands
- missing materials usually means the input definitions do not match what the test character actually has access to
Test actual execution
Use:
craft begin <craft>craft resume <progress item>
Watch for:
- the active progress item description
- whether the correct phase echoes fire
- whether the right tools are required in the right phases
- whether products and fail products appear when expected
Practical Examples
Simple item assembly
The seeded assembly crafts are the clearest pattern for multi-input, multi-tool item output.
Typical shape:
taginputs for componentstagorsimpletoolssimpleoutput product- phase echoes that reference inputs and tools in the order they are used
Material-driven output
Use this when the output should inherit material from an input rather than always loading in its base proto material.
Typical pattern:
- a material-bearing input such as
commodityor another item-consuming input - a
simpleproduct product <n> material <input#>to tie the output material to that input
Fail-product salvage
This is common in seeded metalworking examples.
Typical pattern:
- a normal success product such as a finished blade
- a fail product such as a twisted hunk of metal or an
unusedinputreturn - fail echo uses
$fNto show the salvage result
Room tool requirements
Forge-style crafts are a good example.
Typical pattern:
- several
tagtools - tools set to
roomstate - phase echoes reference the appropriate room tools
This is the right model for anvils, forges, bellows, and other stationary apparatus.
Common Mistakes
- Forgetting to set the appear prog. A craft without it is invalid even if everything else looks complete.
- Using the wrong FutureProg signature for
appear,canuse,whycannotuse,onstart,onfinish, oroncancel. - Referencing
$iN,$tN,$pN, or$fNnumbers that do not exist after reordering or deleting child entries. - Using fail products in regular echoes instead of only in fail echoes.
- Expecting a product to inherit material automatically without setting its material-defining input.
- Forgetting that tools not referenced in normal echoes are treated as needed in every normal phase.
- Forgetting that inputs not referenced in normal echoes default to phase 1 consumption.
- Choosing the wrong tool state and then reading the problem as a missing-item issue rather than a hold, wield, wear, or room-placement issue.
- Setting a skin before setting the item proto, or choosing a skin that belongs to a different item proto.
- Confusing player commands such as
craft viewandcraft previewwith builder editing commands such ascraft set. - Renaming or cloning a craft into a name that is already in use by another approved or in-design craft.
Final Builder Checklist
Before submitting a craft for review, confirm all of the following:
craft showsays the craft is valid- the appear prog is set
- the fail phase is correct
- the progress-item description reads naturally
- each input, tool, product, and fail product is configured and numbered as expected
- phase echoes reference the right
$i,$t,$p, and$ftokens craft previewshows the intended tools and materials- a real
craft begintest behaves as expected on both success and interruption