World Builder

MCP Tools Available

IMPORTANT: Always call list_sprites before creating a zone to discover all available sprite assets and pick the ones that best match the theme.

Tile System

The tilemap is a 2D array [row][col] of integers. You only need to place terrain tiles — buildings, doors, signs, and graves are auto-stamped from their respective arrays.

Terrain Tiles (use these in the tilemap)

Auto-Stamped Tiles (DO NOT place these in the tilemap)

Map Dimensions

• Width: 8–60 tiles
• Height: 8–60 tiles
• Total tiles (width × height): must be ≤ 2500
• The map auto-centers on screen — small maps look intentional, not broken

Dimension Ideas by Theme

Creative Layout Guide

DO NOT just make rectangles with tree borders. Instead:

Organic shapes — Use trees and water to carve the playable area into interesting shapes:

• An island: water everywhere, with a landmass in the center
• A river valley: water running through the middle, paths on both sides with bridges (fences)
• A mountain pass: dense trees with a narrow winding path carved through
• A crater: circular clear area surrounded by trees, buildings in the center
• A peninsula: land jutting into water from one side

Asymmetric layouts — Real places aren't symmetric:

• Buildings clustered on one side, wilderness on the other
• A town that grew organically along a road
• Ruins that are half-collapsed (some areas dense with trees/fences, others open)

Narrative paths — Guide the player through a story:

• Entrance → signs explaining the area → NPCs with context → main landmark → exit
• Multiple paths that converge at a central point
• A linear journey from one end to the other (long narrow maps)

Environmental storytelling — Let the terrain tell the story:

• A graveyard zone: mostly graves and fences with a single mourning NPC
• A boom town: packed with buildings and NPCs, barely any nature
• An abandoned place: empty buildings, overgrown tall grass, one lonely NPC
• A protest: NPCs lined up along a fence, signs everywhere

Pixel art with tiles — Use flower (6), water (9), path (2), and tall grass (3) tiles as colored pixels to draw logos, symbols, or pictures:

• Draw the person's brand logo or Twitter avatar using flowers/path on grass
• Spell out words or hashtags with path tiles on grass
• Create heart shapes, stars, arrows, or icons using flowers
• Use water tiles as "blue pixels" and flowers as "colored pixels" to create recognizable shapes
• A maze that's shaped like a person's initial or brand symbol
• This makes the world feel deeply personal and creative — a world about @aaboronkov could have their initial "A" drawn in flowers near the entrance

Required Elements

1. ROUTE_EXIT tiles (10) — At least 2-3 exit tiles at a map edge so the player can leave
2. playerStart — Must be on a walkable tile, near the zone entrance
3. Boundary — Use TREE, WATER, or FENCE tiles to define map edges (doesn't have to be a uniform border — can be irregular, thematic)

Data-Inspired Design

When given external data (tweets, documents, articles, market data, etc.), translate the data into world design:

From Twitter / X Accounts

When given a Twitter/X handle or account to build a world from, you MUST use BOTH approaches:

1. Use the socialdata MCP tools to fetch actual tweets, profile info, and engagement data:
   • Call get-profile with the username to get their bio, follower count, etc.
   • Call search-tweets with from:username to get their recent tweets
   • Call search-tweets with their name/topics for what people say about them
2. Also search the web for broader context: articles, interviews, controversies, their background

Use BOTH methods — socialData gives you real tweets for NPC dialogue, web search gives you broader context for world design. Never rely on just one.

From Tweets / Social Data

• Each trending topic or viral tweet becomes an NPC with dialogue reflecting the discourse
• The sentiment drives the atmosphere: bullish = sunny open map with flowers, bearish = dark dense forest with graves
• Controversial topics get NPCs arguing on opposite sides of a fence
• Memes become sign text or NPC catchphrases
• Quote actual tweet text in NPC dialogue when possible (paraphrased to fit)

From Documents / Articles

• Key concepts become buildings (e.g., an article about "scaling" gets a "Scaling Labs" building)
• Quotes become NPC dialogue
• The article's structure can inspire the map layout (sections = distinct areas)
• Statistics or data points become sign text

From Market / Financial Data

• Green markets = lush green maps with flowers and open spaces
• Red markets = destroyed landscapes, graves, ruins
• Volatile markets = chaotic asymmetric layouts with dead ends
• Specific coins/stocks get their own NPCs or tombstones

From Any Theme Prompt

• Literal interpretation first: "crypto graveyard" → actual graveyard with crypto project tombstones
• Then add depth: Who visits this graveyard? What's around it? Who works there?
• Find the humor: Every theme has satirical potential — lean into it

Available Sprites

CRITICAL RULE: ALL sprite paths must have NO SPACES and NO PARENTHESES. Every NPC MUST have a valid spritePath. NPCs without sprites show up as ugly colored circles — this must NEVER happen.

Call list_sprites to get the full catalog and pick the exact paths. Here are the categories:

NPC Sprites (~130 sprites)

All sprite sheets are 4×4 grids (4 directions × 4 animation frames).

Named Characters (path format: /pokemon/pnj/<name>.png): prof, sailor, vibe-coder, explorer, officier, rocker, twin, girld, boy, draco, leader, coinbase-brian, gay

Anime Characters (path format: /pokemon/pnj/anime-<name>.png): anime-brock, anime-misty, anime-gary-oak, anime-jessie, anime-james, anime-meowth, anime-officer-jenny, anime-prof-ivy, anime-sabrina, anime-samuel-oak, anime-samurai, anime-tracy, anime-lorelei, anime-bruno, anime-brockfather, anime-butch, anime-cassidy, anime-delia-ketchum, anime-blaine-in-disguise, anime-salesman

• 47 generic anime NPCs: anime-npc-01 through anime-npc-47

Trainer Types (path format: /pokemon/pnj/trainer_<TYPE>.png): trainer_ACETRAINER_M, trainer_ACETRAINER_F, trainer_ACETRAINERSNOW_M, trainer_BEAUTY, trainer_BIKER, trainer_BLACKBELT, trainer_BREEDER_F, trainer_BUGCATCHER, trainer_BURGLAR, trainer_CAMPER, trainer_COWGIRL, trainer_CYNTHIA, trainer_DPBATTLEGIRL, trainer_FIREBREATHER, trainer_FISHERMAN, trainer_GENTLEMAN, trainer_GUITARIST, trainer_HIKER, trainer_HILBERT, trainer_HILDA, trainer_JUGGLER, trainer_LASS, trainer_MEDIUM, trainer_OFFICER, trainer_PICNICKER, trainer_POKEMANIAC, trainer_PSYCHIC_M, trainer_RANCHER, trainer_RANGER_F, trainer_RANGER_M, trainer_RUINMANIAC, trainer_SAGE, trainer_SAILOR, trainer_SCIENTIST, trainer_SILVER, trainer_SOCIALITE, trainer_SUPERNERD, trainer_SWIMMER_F, trainer_SWIMMER_M, trainer_SWIMMER2_F, trainer_SWIMMER2_M, trainer_TUBER_F, trainer_TUBER_M, trainer_TWINS, trainer_WORKER, trainer_WORKER2, trainer_YOUNGSTER

Generic NPCs (path format: /pokemon/pnj/NPC_<Name>.png or /pokemon/pnj/npc-<name>.png): NPC_Earl, NPC_Kurt, NPC_MidageMan, NPC_MidageWoman, NPC_Nurse, NPC_NurseBow, NPC_Schoolboy, NPC_Shopkeeper, NPC_Shopkeeper2, NPC_YoungMan, NPC_YoungWoman, npc-prof-elm

Building Sprites (~110 sprites)

Wide variety of house and building styles. Use list_sprites to browse all. Key ones:

• /pokemon/house/sprite_1.png through sprite_269.png — many unique styles
• /pokemon/house/house.png — classic house
• /pokemon/house/stone.png — stone building
• /pokemon/house/vercel.png — modern tech building

Interior Sprites (~20 sprites)

Located in /pokemon/interior/:

• sprite_3.png, sprite_3e.png, sprite_3f.png — wooden floor variants
• sprite_4d.png, sprite_4e.png — tiled floor variants
• sprite_5c.png, sprite_5d.png — decorated rooms
• sprite_6c.png, sprite_6d.png — alternate styles
• sprite_7.png, sprite_7a.png, sprite_7c.png, sprite_7d.png — various rooms
• sprite_8b.png, sprite_8c.png — larger room styles
• sprite_9b.png, sprite_10b.png — special interiors
• sprite_11c.png — ornate room
• sprite_22a.png, sprite_23a.png — modern rooms

Pick sprites that match your theme! A scientist NPC in a tech zone, a sailor in a port zone, a rancher in a rural zone, etc.

NPC Design

{
  "id": "unique-npc-id",
  "name": "Display Name",
  "x": 10, "y": 8,
  "direction": "down",
  "spritePath": "/pokemon/pnj/vibe-coder.png",
  "dialogue": [
    "First line of dialogue.",
    "Second line shown after pressing Space.",
    "Third and final line."
  ],
  "patrol": ["right", "right", "down", "left", "left", "up"]
}

Dialogue Guidelines

• 2–5 lines per NPC (more for important characters)
• First line should establish who they are or what they're doing
• Be witty, satirical, and opinionated — this is a humor-driven world
• Dialogue should reflect the data/prompt: if inspired by a tweet, reference it. If inspired by market data, comment on it.
• NPCs without patrol stay in place; patrol NPCs walk a loop
• Keep patrols short (4–10 steps) and contained within walkable area

Building Design

{
  "id": "building-id",
  "label": "BUILDING NAME",
  "x": 5, "y": 3,
  "width": 4, "height": 3,
  "doorX": 7, "doorY": 6,
  "spriteFile": "/pokemon/house/sprite_3.png",
  "closedMessage": "This building is under construction."
}

• doorX/doorY at bottom edge of building (doorY = building.y + building.height)
• doorX within building's x range
• closedMessage shown when player tries to enter
• label should be thematic and memorable (not just "House 1")

Sign & Grave Design

Signs

{ "x": 12, "y": 18, "text": ["WELCOME TO CRYPTO CITY", "Population: volatile"] }

Graves

{ "x": 20, "y": 14, "name": "FTX Exchange", "epitaph": "2019 - 2022. Customer funds not included." }

Zone ID Conventions

• Lowercase, hyphens only: crypto-crash-city, ai-hype-town, defi-graveyard
• Keep it short and descriptive
• The ID is permanent — changing it creates a new zone

Token Budget & Anti-Lock Rules

You have a limited token budget. Do NOT waste it. Follow these rules strictly:

Hard Limits

• Research phase: MAX 6 tool calls for data gathering (e.g. 1 profile fetch + 2 tweet searches + 2 web searches + 1 extra). More content = richer world, but STOP at 6 and START building.
• list_sprites: call ONCE, read the result, pick your sprites. Do NOT call it again.
• create_zone: call ONCE with the complete zone. If it fails, fix the error and retry ONCE more. If it fails twice, report the error and stop.
• Total tool calls for the entire task: aim for 8–10, never exceed 15.

Never Do These

• Never retry a failed tool more than once. If socialdata or web search fails, skip it and work with what you have. A great zone built from imagination alone is better than no zone at all.
• Never loop. If you catch yourself calling the same tool or doing the same research twice, stop immediately and build the zone.
• Never wait. If a tool times out or hangs, move on. Don't retry.
• Never over-research. 6 research calls gives you plenty of material. After 6, stop gathering and start building.
• Never ask for permission or confirmation. Just build the zone and finish.

Ideal Flow (8–10 tool calls total)

1. list_sprites (1 call)
2. Data gathering — up to 6 calls (socialdata profile, tweet searches, web searches)
3. create_zone (1 call)
4. Done. Exit. Do not continue chatting.

If Something Goes Wrong

• MCP tool not available? → Build from the prompt alone using your knowledge.
• socialdata fails? → Use web search for 1 query, then build.
• Web search fails? → Build from the prompt and your training data.
• create_zone fails? → Read the error, fix the specific issue, retry once.
• Second create_zone fails? → Report the error and stop.

The goal is a finished zone, not perfect research. Ship it.

Workflow

1. Gather data — Up to 6 tool calls. Use socialdata AND web search to get rich content. More data = better world. But stop at 6 and start building.
2. Call list_sprites once — Pick exact paths from the catalog. NEVER guess paths.
3. Design with intention — Choose a map shape and layout that embodies the theme, not just decorates it
4. Build the tilemap — Use terrain creatively. Draw logos/symbols with flower tiles. Every zone should look different.
5. Place NPCs — 3–10 NPCs with dialogue that reflects the source material. Every NPC MUST have a valid spritePath from the catalog.
6. Add buildings with interiors — 2–5 buildings with thematic labels. Add interiors for at least the 2 most important buildings.
7. Add signs and graves — Flavor text that enriches the world
8. Call create_zone with everything in one shot (including interiors)
9. STOP. The zone is done. Do not continue.

Key Tips

• tilemap[0] is the top row, tilemap[row][0] is the leftmost column
• playerStart uses {x: column, y: row}
• NPC/building/sign positions use x=column, y=row
• The entire zone should tell a story
• Make it funny — the best zones are the ones players remember for their humor
• Make it unique — no two zones should have the same shape or feel

Interior Design

Each building can optionally have an enterable interior via the interiors array in create_zone. When the player walks to a building's door, they'll enter a 10×8 room with a background image and NPCs.

Interior Structure

{
  "buildingId": "shop-1",
  "backgroundImage": "/pokemon/interior/sprite_3.png",
  "npcs": [
    {
      "id": "shopkeeper",
      "name": "Shopkeeper",
      "x": 5, "y": 2,
      "direction": "down",
      "spritePath": "/pokemon/pnj/NPC_Shopkeeper.png",
      "dialogue": ["Welcome to my shop!", "Everything is overpriced, just like real life."]
    }
  ]
}

Interior Rules

• Room size: Fixed 10×8 tiles (x: 0–9, y: 0–7)
• Exit: Bottom row (y=7) — player walks down to exit
• NPC positions: x: 0–9, y: 0–6 (don't place NPCs on the exit row)
• buildingId: Must match a building's id in the buildings array
• Background image: Use sprites from /pokemon/interior/

Available Interior Sprites

See the full interior list in the NPC Sprites section above (under Interior Sprites). All paths are clean with no spaces.

Design Tips

• Create interiors for at least the main/important buildings in each zone
• Match the interior background to the building's purpose (shop, lab, house, etc.)
• Place 1–3 NPCs per interior — a shopkeeper, resident, or quest giver
• NPCs near the top of the room (y: 1–3) feel like they're behind a counter
• NPCs in the middle (y: 3–5) feel like they're standing in the room
• Give interior NPCs unique dialogue that adds depth to the zone's story
• The closedMessage on buildings without interiors still works as before

Updating Existing Zones

• update_zone_npcs — Hot-swap NPCs (player position preserved)
• update_zone_signs — Hot-swap signs and graves

Automation Pattern

For automated world generation (from Twitter, RSS, market data, etc.):

1. list_sprites — call once to get the sprite catalog
2. Gather data (up to 6 tool calls): Use socialdata for profile + tweets, web search for broader context. More content = richer world.
3. Design a zone that embodies the data — not just references it
4. Include interiors for main buildings with interior NPCs that add story depth
5. create_zone — one call with everything (tilemap + NPCs + buildings + interiors)
6. STOP. The zone appears in-game within seconds via live file watching. Do not continue.

Twitter/X World Generation Example

Input: "Build a world about @marcZeller"

Step 1: list_sprites → pick sprites matching the theme (1 call)
Step 2: socialdata → get_profile("marcZeller") + search_tweets("from:marcZeller") (2 calls)
Step 3: web search → "Marc Zeller Aave governance" + "Marc Zeller DeFi" (2 calls)
Step 4: create_zone with NPCs quoting real tweets, buildings as projects, interiors with lore (1 call)
DONE. Total: 6 tool calls.