xiaoluolyg--god/docs/MAP_PACKAGES.md

🗺️ GOD Map Packages

Drop in a folder. Refresh the wizard. Steer agents through a brand new town.

🌏 English · 🌏 中文

---

GOD map packages are local folders under:

agentsociety/custom/maps/<map_id>/

Drop a new folder there, restart or refresh the setup wizard, and the map shows up as a selectable world — no code changes required.

📦 Required Layout

<map_id>/
├── map.yaml                   ← semantic manifest (locations, interactions, spawn points)
├── README.md                  ← package overview
├── ATTRIBUTION.md             ← credits for tiles, sprites, icons
├── visuals/
│   ├── map.json               ← Tiled JSON map (orthogonal)
│   └── map_assets/**/*.png    ← tileset images referenced by the JSON
├── characters/                ← optional: 32×32 sprite PNGs
│   ├── atlas.json             ← optional
│   └── *.png
└── location_assets/           ← optional: location icons used by the UI
    └── *.png

map.yaml is the semantic manifest — it describes what locations exist, what agents can do at each one, and how the world is wired up. visuals/map.json is the Tiled JSON map that gives the world its pixel form. Tileset image paths inside the Tiled JSON must be relative paths that stay inside the package folder.

📝 Manifest Fields

A minimal map.yaml:

schema_version: 1
map_id: your_map_id
display_name: Your Map Name
tiled_map_path: visuals/map.json
tile_size: 32
character_root: characters
spawn_points:
  - id: resident_start
    location_id: plaza
locations:
  - id: plaza
    name: Plaza
    aliases: [plaza]
    anchor_tile: {x: 1, y: 1}
    interaction_ids: [wait]
interactions:
  - id: wait
    name: Wait
    allowed_location_ids: [plaza]

Recommended optional fields:

Field	What it does
default_location_order	Preferred fallback order when an agent has no explicit location.
bounds	{x, y, w, h} region covering a location (for clicks, highlights, status).
scene_type	Compact category such as home, school, market.
visual_asset	Relative path to an icon in location_assets/.
effects	Interaction output fields: action, status, emotion, latest_event, group_message.

Runtime localization is optional and non-breaking. Keep the existing display_name, name, and description fields as the backend/runtime defaults, then add localized.en and localized.zh only for frontend display:

localized:
  en:
    display_name: Your Map Name
  zh:
    display_name: 你的地图名
locations:
  - id: plaza
    name: Plaza
    localized:
      en:
        name: Plaza
      zh:
        name: 广场
interactions:
  - id: wait
    name: Wait
    description: Wait in place.
    localized:
      en:
        name: Wait
        description: Wait in place.
      zh:
        name: 等待
        description: 原地等待。

🧱 Tiled JSON Rules

v1 supports only orthogonal Tiled JSON maps:

• orientation must be orthogonal.
• tilewidth and tileheight should match tile_size.
• The map must include a tile layer named Collisions.
• In Collisions, 0 means walkable and any non-zero tile means blocked.
• Tileset images must be PNG files inside the map package folder.
• TMX, external tileset files, remote images, and single-background-image maps are not supported in v1.

✅ Validation

cd agentsociety
uv run python scripts/validate_map_package.py custom/maps/<map_id>

The validator checks required fields, resource paths, Tiled JSON shape, tileset images, the Collisions layer, location anchors, and interaction references.

The legacy semantic check for The Ville still exists as:

uv run python scripts/validate_the_ville_map.py

🧰 Ready-to-Copy Templates

Package	Purpose
agentsociety/custom/maps/the_ville/	The complete working example — 10 locations, 65 interactions, real tilesets.
agentsociety/custom/maps/_template/	A minimal starter package. Copy, rename, and replace the assets.

🚀 Five-Minute Workflow

# 1. Copy the template
cp -r agentsociety/custom/maps/_template agentsociety/custom/maps/my_town

# 2. Drop in your Tiled JSON, tileset PNGs, and (optionally) character sprites
#    Edit map.yaml: change map_id, display_name, locations, interactions

# 3. Validate
cd agentsociety
uv run python scripts/validate_map_package.py custom/maps/my_town

# 4. Restart GOD and pick the new map in the setup wizard
./scripts/god.sh restart

That's it — no code changes, no registry edits. The setup wizard discovers every valid package on every refresh.