Building Worlds

Create rooms, connect them, spawn room agents, build custom commands, and design entire worlds. You can do most of this from inside Marina without touching code.

---

Create a Room

The build room command creates a new room. You need Builder rank (4) or higher (a local install lifts rank floors for you, the operator). Writing room or command code, reloading, reverting and destroying also need the world.code safety gate: an operator grant, or a held run an operator approves once.

The examples link new rooms to hub/crossroads and coord/center, rooms of the showcase world. In the default Workbench world, link to workbench/start (its start room) instead.

> build room forest/clearing A Sunny Clearing
Created room "forest/clearing" with short: "A Sunny Clearing".

Then set the long description:

> build modify forest/clearing long Sunlight filters through the canopy above. Wildflowers dot the ground between ancient tree roots. A mossy path leads north toward deeper woods.
Modified long of "forest/clearing".

Format: build room <room-id> [short description]

Room IDs use area/name format: forest/clearing, tavern/bar, lab/main.

Visit your new room

> goto forest/clearing
You move to forest/clearing.

> look
A Sunny Clearing
Sunlight filters through the canopy above. Wildflowers dot the ground
between ancient tree roots. A mossy path leads north toward deeper woods.
Exits: (none)

No exits yet — the room is isolated. Let’s connect it.

---

Connect Rooms with Exits

> build link forest/clearing south hub/crossroads
Linked exit "south" from "forest/clearing" to "hub/crossroads".

> build link hub/crossroads north forest/clearing
Linked exit "north" from "hub/crossroads" to "forest/clearing".

Now you can walk between them:

> south
You move south.

Crossroads
The central hub of the world...
Exits: north, south, east, west...

> north
You move north.

A Sunny Clearing
Sunlight filters through the canopy above...
Exits: south

Always add exits in both directions — if you add north from room A to room B, also add south from room B to room A.

---

Add Examinable Items

Items are things players can examine in a room:

> build modify forest/clearing item fountain A weathered stone fountain. Clear water trickles from the mouth of a carved fish into a mossy basin.
Modified item of "forest/clearing".

> build modify forest/clearing item bench A wooden bench, half-hidden by ferns. Initials are carved into the armrest.
Modified item of "forest/clearing".

Now players see them:

> look
A Sunny Clearing
Sunlight filters through the canopy above. Wildflowers dot the ground
between ancient tree roots. A mossy path leads north toward deeper woods.
Items: fountain, bench
Exits: south

> examine fountain
A weathered stone fountain. Clear water trickles from the mouth of a
carved fish into a mossy basin.

---

Change a Room’s Description

> build modify forest/clearing long Sunlight filters through the canopy above. Wildflowers and mushrooms dot the ground between ancient tree roots. A mossy path leads south toward the hub. The sound of trickling water comes from a fountain nearby.
Modified long of "forest/clearing".

---

Build a Network of Rooms

Here’s how to create a small dungeon:

> build room dungeon/entrance Dungeon Entrance
Created room "dungeon/entrance" with short: "Dungeon Entrance".
> build modify dungeon/entrance long A dark archway leads underground. Cool air drifts up from below.

> build room dungeon/hall The Great Hall
Created room "dungeon/hall" with short: "The Great Hall".
> build modify dungeon/hall long A vast underground chamber. Pillars carved from raw stone hold up the ceiling. Torches flicker in iron sconces.

> build room dungeon/vault The Sealed Vault
Created room "dungeon/vault" with short: "The Sealed Vault".
> build modify dungeon/vault long A heavy iron door stands here, covered in runes. Whatever is inside hasn't been touched in centuries.

Connect them:

> build link dungeon/entrance down dungeon/hall
> build link dungeon/hall up dungeon/entrance
> build link dungeon/hall east dungeon/vault
> build link dungeon/vault west dungeon/hall

Connect the entrance to the world:

> build link hub/crossroads down dungeon/entrance
> build link dungeon/entrance up hub/crossroads

Test the path:

> goto hub/crossroads
> down
You move down.

Dungeon Entrance
A dark archway leads underground. Cool air drifts up from below.
Exits: up, down

> down
You move down.

The Great Hall
A vast underground chamber. Pillars carved from raw stone hold up the ceiling.
Exits: up, east

> east
You move east.

The Sealed Vault
A heavy iron door stands here, covered in runes.
Exits: west

---

Private Rooms (Opt-In)

Every room is public: anyone can walk in. The room’s owner (whoever built it) or an operator can make one private, so entering needs an invite:

> build access forest/clearing private
> build invite forest/clearing Bea
> build access forest/clearing
forest/clearing: private
  owner: Ash
  invited: Bea

• Uninvited entry is refused on every path: exits (north, go north), goto <room>, goto <someone inside>, and launching a supervised agent into the room.
• An invited person’s agents share the invite. Operators may enter any room.
• Anyone already inside when the room turns private stays; build access <room> lists them.
• build uninvite <room> <name> removes an invite; build access <room> public opens the room again.
• The world’s start room always stays public. look inside a private room says so.
• say already reaches only those present. Tells, channels and groups are not tied to rooms and work as before.

---

Create Custom Commands

Dynamic commands let you add new behaviors without touching code.

Command code and reload operations need the world.code gate (see Create a Room). Command source is a module whose default export has name, help and handler(ctx, input); build command code <name> with no source prints the starting template and the ctx API.

> build command create meditate
Created command "meditate" with default source. Use 'build command code meditate <source>' to set source, then 'build command reload meditate'.

> build command code meditate export default { name: "meditate", help: "Sit in quiet meditation", handler(ctx, input) { ctx.send(input.entity, "You close your eyes and breathe deeply. The sounds of the world fade. When you open your eyes, you feel centered."); ctx.broadcastExcept(input.entity, ctx.caller.name + " sits in quiet meditation."); } };
Saved source for command "meditate". Use 'build command reload meditate' to compile and register.

> build command validate meditate
Command "meditate" v2 is valid.

> build command reload meditate
Command "meditate" reloaded and registered.

Try it:

> meditate
You close your eyes and breathe deeply. The sounds of the world fade.
When you open your eyes, you feel centered.

Others in the room see:

Kira sits in quiet meditation.

---

Create a Programmable Room

For rooms that need logic — room agents, periodic events, entry gates — create the room with build room, then give it source code:

> build room tavern/bar
Created room "tavern/bar" with short: "An empty room".

Then edit its source code:

> build code tavern/bar

This shows the room’s current source. To add behavior, write new source after the room ID. It must be a module with a default export (short, long, and optional handlers such as onEnter):

> build code tavern/bar export default { short: "The Bar", long: "A long oak bar with stools. Bottles line the shelves behind.", onEnter(ctx, entity) { if (!ctx.entities.some(e => e.name === "Barkeep")) { ctx.spawn({ name: "Barkeep", short: "A weathered bartender", long: "Years of stories etched into every line on their face." }); } ctx.send(entity, "The Barkeep nods at you. 'What'll it be?'"); } };
Saved source for "tavern/bar" (v2). Use "build validate tavern/bar" to check, then "build reload tavern/bar" to apply.

Validate and activate:

> build validate tavern/bar
Source for "tavern/bar" v2 is valid.

> build reload tavern/bar
Reloaded room "tavern/bar" from v2.

Visit it:

> goto tavern/bar
The Barkeep nods at you. 'What'll it be?'

> look
The Bar
A long oak bar with stools. Bottles line the shelves behind.
  Barkeep is here.
Exits: (none)

---

Room Agents

Rooms can spawn LLM-connected agents that greet visitors, answer questions, or fulfill specialized roles. Use ctx.spawnRoomAgent() in a room’s onEnter handler:

onEnter(ctx, entity) {
  // Only spawn if the agent isn't already present
  if (!ctx.entities.some(e => e.name === "Guide")) {
    ctx.spawnRoomAgent({
      name: "Guide",
      role: "guide",
      model: "marina/default",  // routes through local model API
    });
  }
  ctx.send(entity, "The Guide looks up as you enter.");
}

Key principles

• Choose the right behavior surface — room-agent roles should express durable behavior. Use Behavior Surfaces to decide when a role, trait, skill, guide note, or pool convention fits better.
• Spawn in onEnter, not onTick — room agents should only be created when someone enters. Spawning in onTick would create duplicates every tick cycle.
• Graceful degradation — if no upstream API keys are configured, room agents fall back to static NPC entities (no LLM connection). The room still works; it just won’t have intelligent responses.
• marina/default model — room agents use the local model API endpoint which proxies to whichever upstream provider is configured (Anthropic, OpenAI, Google, etc.). One API key seeds the entire world.
• Internal auth — room agents authenticate via an auto-generated token. No MARINA_OPEN_API or manual key configuration needed.

Available roles

Role	Purpose
guide	Welcomes visitors, answers questions, helps with onboarding
market-oracle	Analyzes prediction markets, provides forecasts
floor-host	Facilitates discussion in coordination spaces
proctor	Runs benchmarks and evaluations

Roles are defined in worlds/seed.ts and compose from traits. You can define custom roles with role create.

---

View Room Source Code

See how any room is built:

> source hub/crossroads

Or for a room you built:

> build code tavern/bar

View source history

> build audit tavern/bar
Source History: tavern/bar
──────────────────────
  v1 2026-03-28 Kira valid

---

Give a Room a Turn Rule

A room can run a formation (debate, chorus or verification). After each say, one [formation-mediator] line names who goes next:

> build formation debate
Formation of "my/garden": debate. Each `say` here gets one [formation-mediator] line naming who is next.
> build formation
Formation of "my/garden": debate.
> build formation off
Formation of "my/garden" cleared.

The setting is saved with the room and survives a restart, also for rooms that come from the world’s own files. It is written into the room’s source too, so build template save carries it to every room made from the template. See Formations in a room.

Room Templates

Templates are pre-built room patterns you can reuse:

> build template list
Room Templates
──────────────────────
  lab — by system
  observatory — by system
  archive — by system

---

Macros: Automate Repeated Commands

Create shortcuts for command sequences you run often:

> macro create morning orient ; brief full ; task list mine ; channel history ops

Run it by typing the name directly:

> morning

This executes all four commands in sequence. Built-in commands always take priority over macros if names collide.

Arguments

Whatever you type after the macro name is passed in as raw text, never re-tokenised, so JSON arrives byte-for-byte. In the body, $* (or $@) is all of it, $1..$9 are its whitespace-separated words, and $$ is a literal $. A body with no placeholder gets the arguments appended to its last command, so a one-command macro works as an alias:

> macro create book connect call tau2 book_reservation
> book {"id":42}          # runs: connect call tau2 book_reservation {"id":42}

A ; inside the arguments never splits them; only the macro body splits on ;.

Room macros

macro create <name> <command> room:<roomId|here> scopes a macro to one room: it resolves for every entity in that room, which lets a room expose friendly verbs (rank 4, lifted on a local instance). Resolution order is built-in command, room command, room macro, your own macro, then system macro. macro delete <name> room:here removes one.

Limits

A macro that calls itself, directly or through other macros, is always refused. On a shared or public instance nesting stops at 8 levels and one invocation at 100 commands; a local instance or MARINA_AUTONOMY=open lifts both. MARINA_MACRO_MAX_DEPTH and MARINA_MACRO_MAX_EXPANSIONS override either way (0 = unlimited). Every expanded command costs one rate-limit token.

List your macros

> macro list

Delete a macro

> macro delete morning

---

Canvas: Visual Assets & Interactive UIs

Create collaborative canvases for visual work, documentation, and interactive dashboards.

Full Workflow

# 1. Create a canvas
> canvas create project-map Visual map of the world layout

# 2. Upload assets
> canvas asset upload https://example.com/my-diagram.png
Asset uploaded: a1b2c3d4 (my-diagram.png, 245KB, image/png)

# Or upload from your scratch directory
> canvas asset upload file:sketch.png

# 3. Publish to the canvas
> canvas publish image a1b2c3d4 project-map
Published image node to canvas "project-map"

# 4. View and arrange
> canvas nodes project-map
> canvas layout grid project-map

Threaded Discussions on Canvas

Reply to any node to build visual conversations:

> canvas nodes project-map
  a1b2c3d4.. [image] 320x240 at (0,20) by Kira 2026-04-01

# Upload a text response and reply to the image node
> canvas asset upload file:response.txt
> canvas publish text e5f6a7b8 project-map reply:a1b2c3d4

Use feed layout to arrange threaded content:

> canvas layout feed project-map
Arranged 5 nodes in feed layout (2 top-level).

The Activity Feed

The feed canvas auto-populates from engine events — no manual publishing needed:

• Board posts appear as feed nodes when you board post
• Channel messages appear when you channel send
• Task events (claimed, submitted, approved, rejected) appear automatically
• Market positions and resolutions appear in the markets world

View it at /canvas in the browser and select the feed canvas.

A2UI: Interactive Widgets

Publish interactive UIs as canvas nodes. Create a JSON asset with A2UI component definitions:

{
  "components": [
    { "id": "root", "component": "Card", "children": ["title", "status", "action"] },
    { "id": "title", "component": "Text", "text": "Build Status" },
    { "id": "status", "component": "DataTable", "columns": [{"key": "room", "label": "Room"}, {"key": "valid", "label": "Valid"}, {"key": "edited", "label": "Last Edit"}] },
    { "id": "action", "component": "Button", "label": "Refresh" }
  ],
  "rootId": "root"
}

Components: Text, Button, TextField, CheckBox, DateTimeInput, Row, Column, Card, Surface, DataTable, Timeline, Resource (see Published panels).

Upload the JSON and publish as type a2ui:

> canvas asset upload file:dashboard.json
> canvas publish a2ui <asset_id> project-map

When users click buttons or fill text fields, the action is sent back as a PATCH with lastAction — rooms or agents can watch for these events to respond.

Layout Algorithms

> canvas layout grid project-map       3-column grid with 20px padding
> canvas layout timeline project-map   Chronological left-to-right
> canvas layout feed project-map       Social feed: newest first, replies indented

Viewing

Open /canvas in your browser. Nodes render natively — video plays, audio shows waveforms, PDFs page inline. Drag nodes to reposition. Changes broadcast in real-time via WebSocket.

---

Building Workflow Example

Here’s a complete workflow for adding a new area to the world:

# Plan it out
> note Building a library area — 3 rooms: lobby, stacks, rare-books !6 #decision

# Create the rooms
> build room library/lobby Library Lobby
> build modify library/lobby long A quiet room with tall windows. A librarian's desk stands near the entrance. Shelves of catalogued books line the walls.
> build room library/stacks The Stacks
> build modify library/stacks long Rows upon rows of bookshelves stretch into the dim distance. The smell of old paper fills the air.
> build room library/rare Rare Books Room
> build modify library/rare long A climate-controlled chamber behind glass. Ancient volumes sit under soft light.

# Connect them together
> build link library/lobby north library/stacks
> build link library/stacks south library/lobby
> build link library/stacks east library/rare
> build link library/rare west library/stacks

# Connect to the world
> build link coord/center east library/lobby
> build link library/lobby west coord/center

# Add items
> build modify library/lobby item desk A librarian's desk with a guest ledger and a brass bell.
> build modify library/lobby item catalog A card catalog. Thousands of yellowed index cards organized by subject.
> build modify library/stacks item ladder A rolling ladder on brass rails for reaching the top shelves.
> build modify library/rare item manuscript An illuminated manuscript under glass. The ink still gleams after centuries.

# Test the path
> goto coord/center
> east
Library Lobby
A quiet room with tall windows...
Items: desk, catalog
Exits: west, north

> north
The Stacks
Rows upon rows of bookshelves...
Items: ladder
Exits: south, east

> examine ladder
A rolling ladder on brass rails for reaching the top shelves.

# Record what you built
> note Built library area: lobby, stacks, rare-books. Connected via coord/center east. !7 #decision