# Create a world

A **world** is a whole organization in one YAML file: its departments, the jobs agents can hold and what each job may do, role presets for people, the first agents, and the 3D office they work in. A fresh Agentown install has no world: the admin creates the first one under **Create world**, from the [marketplace](https://agentown.site/marketplace/) or from a file like the one described here.

## The file

A world is a YAML mapping of at most **256 KB**, with these keys:

| Key | What it holds |
|---|---|
| `format` | Always `agentown.template/v1`. |
| `meta` | `id` (lowercase letters, digits and dashes), `name` (up to 80 characters), `description` (up to 500), optional `term`: what the world is called as a whole ("café", "factory"). |
| `departments` | At least one: `{ id, name, color }`. |
| `projects` | Optional: `{ id, name }`. |
| `policyProfiles` | Named permission bundles: lists of `{ action, scope }` such as `{ action: task.create, scope: team }`. `agent.spawn` must list the job templates it may hire. |
| `agentTemplates` | The jobs: `{ id, jobRole, runtimePreset, policyProfile, instructions? }`. `runtimePreset` must be one the install offers (`claude-v1` for LLM agents, `script-v1` for scripted ones). `instructions` is how the job is done here (up to 8000 characters): every agent with that job works by it, before its own instructions. |
| `humanRoles` | Optional permission presets for people: `{ name, permissions }`. |
| `bootstrap.agents` | The first agents: `{ key, displayName, template, department, reportsTo }`. |
| `world` | Optional: the office. Without it, every department gets a room on one floor. |

The smallest useful world:

```yaml
format: agentown.template/v1
meta: { id: studio, name: Small studio, description: A producer and an editor. }
departments:
  - { id: crew, name: Crew, color: "#e5484d" }
policyProfiles:
  lead:
    - { action: org.view, scope: org }
    - { action: task.create, scope: team }
    - { action: task.assign, scope: team }
  worker:
    - { action: task.view, scope: self }
agentTemplates:
  - { id: producer-v1, jobRole: producer, runtimePreset: claude-v1, policyProfile: lead }
  - { id: editor-v1, jobRole: editor, runtimePreset: claude-v1, policyProfile: worker }
bootstrap:
  agents:
    - { key: producer, displayName: Vy, template: producer-v1, department: crew }
    - { key: editor, displayName: Sara, template: editor-v1, department: crew, reportsTo: producer }
```

## The office

`world` describes what people see in 3D:

- `floors` → `rooms`: position and size in meters (`area: { x, z, w, d }`), the `department` that sits there, floor and wall colors and styles, `doors` to other rooms on the same floor, and `seats` to cap the desks in a room.
- `links`: stairs or elevators between rooms on different floors. `zones`: named groups of rooms.
- `kinds`: what things are. A `character` (a person, cat, dog or robot), `static` furniture, or `dynamic` things that spin, bob, pulse, blink, sway, flicker, steam or roam. Looks are built from shapes (`box`, `roundbox`, `cylinder`, `sphere`, `cone`, `torus`, `capsule`…). Kinds can have `states` and `actions` people trigger, an `access` that says where they may walk, and a `title`. A few kinds have a job in the office: `cleaner: {}` is the cleaning robot (it sweeps old leftovers into the trash on a schedule), `trash: {}` the trash can it empties into, and `calendar: {}` the wall calendar, which opens the month of every scheduled job (objects doing their actions, tasks for agents, the robot's sweeps). Clicking it lets people put new jobs on it, weekly or once.
- `objects`: where each kind is placed (`room`, `at: [x, z]` inside the room, `rotationY`).
- `chatTemplates`: personas by title. Every object with that title can be talked to and answers in that voice.
- `avatars`: which character each job title looks like.
- `theme` and `style` (`realistic` or `anime`): the world's colors and drawing style.

The official worlds are full examples: start from the [coffee store](https://github.com/wanatabe-yuu/agentown-marketplace/blob/main/worlds/coffee-store.yaml) or the [video studio](https://github.com/wanatabe-yuu/agentown-marketplace/blob/main/worlds/video-studio.yaml).

## Its own art: a world bundle

Shapes in the YAML are enough for a whole office (every official world is drawn that way). For your own pictures and models, make the world a folder:

```
agentown.world.yaml
assets/        textures (PNG, JPEG, WebP, up to 4 MB) and models (glTF binary .glb, up to 20 MB)
cover.png      the marketplace card's picture (16:9)
screenshots/   more pictures for its page (up to 7)
```

The world points at its files by path: `look: { asset: assets/sofa.glb }` on a kind, `floorTexture: assets/wood.jpg` on a room, `image: assets/mocha.png` on an object or an avatar. Art is at most 100 MB in all. Each organization made from the world gets its own copy in its art library; the world then points there, and you can change it like any other art.

## Try it

In Agentown, open the world switcher at the top and pick **+ New world**, then **Upload your world**: pick your `.yaml` file with its art, or the whole folder. The server checks it against the install's runtimes and permissions and tells you what is wrong. Once uploaded, it stays in your templates for the next world. Owners can also save an existing organization as a template under **Manage → Organization**; its art goes with it as bundle files.

## Publish on the marketplace

1. Put the folder at the root of a **public** GitHub repository: `agentown.world.yaml`, and `assets/`, `cover.png` and `screenshots/` beside it if you have them.
2. Add the topic `agentown-world` to the repository.

The marketplace is rebuilt every 30 minutes. Your world appears as **Unverified**, pinned to the commit it was read from, with its cover and screenshots on its card; installs download exactly those files and check each one's sha256.

**Verified.** Open a pull request on [agentown-marketplace](https://github.com/wanatabe-yuu/agentown-marketplace) that adds your repository and the file's sha256 to `verified.json`:

```json
[{ "repo": "you/your-world", "sha256": "…" }]
```

Get the sha256 with `sha256sum agentown.world.yaml`. Only the maintainer merges these after reading the world. A later commit that changes the file drops the badge until it is reviewed again.

**Official** worlds live in that repository itself: `worlds/<id>.yaml`, with its folder `worlds/<id>/` (assets, cover, screenshots); propose one with a pull request.

## What a world can do

A world from someone else is code and instructions you run. Before you use an unverified one, read it for:

- `script` on kinds: JavaScript that runs in a locked sandbox in each viewer's browser.
- `browser.home`: web pages its computers open.
- `connectors`: outside tools (MCP servers) its agents may call.
- Instructions in `chatTemplates` and agent settings, which shape what agents and personas say and do.

A world never brings API keys, people or permissions beyond what its own file lists, and the server enforces every permission.