Creating Items
Series: world-building · Part 7
Items are the portable world. A lantern carried through dark rooms. A letter sealed before it left its island. A sword with a maker’s mark that announces its origin at every customs gate it crosses.
Everything in the inventory system is an item — including writs, which are items that carry capabilities. The player documentation covers writs; this guide covers building ordinary items and giving them character.
Creating an item
chart> create item iron-lantern
Draft ready:
Name: Iron Lantern
Brief: An iron lantern, cold and unlit.
Room: (unplaced)
[a]ccept [e]dit [r]egenerate [t]weakAccept the draft or revise it. The item exists but is unplaced — it is not in any room yet.
Brief and description
The brief is the one-line that appears in room descriptions and inventory lists:
You are carrying:
an iron lanternThe full description is what look iron lantern returns:
chart> describe iron-lantern
(Enter description. End with a blank line.)
An iron lantern with thick glass panels, cold to the touch.
The wick is trimmed and ready. A small maker's mark is
stamped into the base.
Description set for item:your-realm/iron-lantern.Write the description for the moment of close attention. The traveler has stopped and is looking carefully. Details that imply a state — cold to the touch, wick ready — are an invitation to ask what the item would be like in a different one.
chart> describe iron-lantern/brief
An iron lantern.
Brief set for item:your-realm/iron-lantern.The brief is used in inventory and room item lists. Keep it short — three or four words. The description does the work; the brief is a label.
Tags
Tags are how NPCs, behaviour rules, and customs policy identify items without inspecting their descriptions. An NPC rule can check actor carries item with tags includes "weapon". A customs policy can accept items tagged mundane and quarantine items tagged contraband.
chart> edit iron-lantern tags light-source iron mundaneMultiple tags, space-separated. Common conventions:
| Tag | Used for |
|---|---|
weapon | Items usable in conflict — triggers scrutiny at most borders |
light-source | Illumination items; some rooms respond to their presence |
document | Written items: letters, charts, writs, manifestos |
consumable | Items destroyed when used |
mundane | No scripted behaviour; many customs policies trust these implicitly |
contraband | High-scrutiny items; most realms quarantine or render these inert |
Tags are freeform — an island with its own customs logic can define and use any tags it likes. The conventions above are common enough that other operators’ NPC rules and customs policies will understand them.
Properties
Items carry properties beyond description and tags. Most are set automatically — origin is stamped at creation, seal is derived from your realm’s keypair. Custom properties hold arbitrary string values:
chart> edit iron-lantern maker "Aldric of Winding Stair"
chart> edit iron-lantern forged "third watch, year of federation I"Custom properties appear on examination and can be read by scripts:
let maker = world.property(item, "maker");The origin property is set to your realm’s hostname at creation and cannot be overridden. It is signed by your realm’s keypair and verified at every border. Provenance cannot be forged.
Placing items
Move an item into a room to make it findable:
chart> move iron-lantern to harbor-gate
Placed: item:your-realm/iron-lantern in room:your-realm/harbor-gateThe item appears in the room and can be picked up by travelers. To put it in an NPC’s inventory instead:
chart> move iron-lantern to old-cael
Placed: item:your-realm/iron-lantern in npc:your-realm/old-cael (inventory)Old Cael now carries it. He can give it to travelers; travelers can give it back.
What provenance looks like
When a traveler examines the lantern, they see:
> look iron lantern
An iron lantern with thick glass panels, cold to the touch.
The wick is trimmed and ready. A small maker's mark is stamped
into the base.
Origin: winding-stair ┌╌╌┐╎◆╎└╌╌┘
Tags: light-source · iron · mundaneThe seal — derived deterministically from your realm’s keypair — appears alongside the origin. Travelers learn to read these like postmarks. A sword bearing the ironholt seal was forged there. A letter with an unfamiliar seal came from somewhere else.
When the item crosses into another realm, that realm’s customs policy reads the origin and applies its rules. If the policy renders the item inert — stripping its scripted behaviour — the origin record and seal survive. Provenance is not behaviour. It cannot be stripped.
Items with behaviour
An item can respond to being taken, dropped, given, or examined. Attach a script in rig mode:
chart> /script
rig> edit iron-lantern react:take
// The lantern lights when lifted
emit(effect::emote("flares to life as you lift it, the wick catching without a spark."));When a traveler picks up the lantern, the room sees it respond. Scripts execute with the item’s capability bag — by default, items can emit emotes and speech, but cannot move themselves or reach beyond their own room without explicit grants.
The full signal list and capability model for item scripts is in Scripting with Rhai.
Items are individuals
Items in the archipelago are not stacks. There is no iron-lantern × 3 — there are three distinct lanterns, each with its own event history. If you need several of the same object, create them separately:
chart> create item iron-lantern-2
chart> describe iron-lantern-2
(identical description)
chart> move iron-lantern-2 to market-squareThis is not a limitation. A lantern that has been carried across three straits has a different history from one that has never left the harbor. The event store knows the difference even if the description does not.