xiaoluolyg--god/README.md

 GOD · Govern · Observe · Direct

🌩️ Be like a god to a town of agents.
Pause time. Whisper to a soul. Bend the next step. Reset the world — all from a single click.

▶ Try browser replay  ·  no install, no API key  ·  Run locally

🌐 Live Demo · 🚀 Quick Start · Updates · Roadmap · Highlights · Features · Built-in Experiments · Public Site · Developer Docs · Contributing · 🌏 中文

---

Most agent-society demos let you watch a simulation play out. GOD gives you the controls.

Replay a run, question any resident, change what happens next, and export a pack others can rerun, all from one screen. It is built for inspecting language-agent societies, not for claiming they are socially realistic.

🗓️ Updates

• 2026-06-11 · v0.2.0: public site with browser replays; Experiment / Map / Agent pack hubs and ZIP import-export; Windows launcher; hardened first-run startup. (#64 #65)
• 2026-06-06 · Site & packs: rebuilt public site and frontend; site packs delivered through release assets; map pack preview pages. (#61 #62 #63)
• 2026-06-01 · Portable packs: unified ExperimentPack downloads; GOD package import/export; curated experiment library. (#57 #59 #60)
• 2026-05-30 · Windows launcher & hubs: god.cmd start matches the macOS/Linux flow; AgentPack hubs and public replay exports; parallel JiuwenClaw requests. (#45 #49 #50)
• 2026-05 · Operator studios: bilingual control room, map-first /ask + /intervene rail, Agent Studio, Map Studio, unified skill runtime.(#26 to #31)
• 2026-05-21 · v0.1.0: first tagged release with two built-in experiments and the PKU campus map. (#21 #24)

✨ Highlights

⏯️ Pause time Stop, scrub, fast-forward, auto-play any live step.

💬 Ask anyone Ask one resident, a group, or the whole town, mid-run.

🎛️ Steer the next step Inject instructions and inspect how agents respond.

🪄 No-code setup Configure model, scenario and agents from a browser wizard.

🔄 Reset run state One command wipes a stale run and re-seeds a clean world.

🖼️ Screenshots

_{Live control room: PKU map, step controls, targeted ask, and resident roster in one view.}

🌐 Live Demo

Browse everything in your browser on the public site: curated replays, map packs, agent packs, and downloadable experiments. No install or API key needed.

   

_{Left to right: the public site homepage, downloadable map packs, and downloadable agent packs.}

🚀 Quick Start

git clone https://github.com/XiaoLuoLYG/GOD.git
cd GOD
./scripts/god.sh start

Windows PowerShell: from the repo root, run .\scripts\god.cmd start.

On the first run the script installs everything, opens a browser-based setup wizard, and waits for you to finish. You never have to edit .env or pass command-line flags by hand.

_{The Setup Wizard: model config, experiment choice, and custom society creation in one browser flow.}

🔌 1. Model Paste an OpenAI-compatible API key, base URL, and model name.

🧭 2. Choose Open GOD Town, open PKU Trump Visit, or create your own.

🧪 3. Scenario Describe your world: date, weather, vibes, rules.

🤖 4. Generate The GOD agent drafts agent profiles and a step plan.

✏️ 5. Edit Tweak personalities, relationships, locations, or steps.

▶️ 6. Launch Publish the experiment and step into the control room.

Any OpenAI-compatible endpoint works. When the wizard hands off, the script prints a URL like:

http://127.0.0.1:5174/pixel-replay/god_town/1

Full walkthrough: Quickstart →

🧩 Features

	Feature	What you get
🎬	Replay control	Scrub a live or recorded replay by step. Pause, jump, auto-play.
💬	Targeted ask	Send a natural-language question to one agent, a group, or the whole town.
🎛️	Real-time intervention	Inject instructions into the next step; agents read them on their next turn.
⌨️	Command composer	Type /ask or /intervene, use @Name #id completions, and send operator commands without leaving the map.
🪄	No-code setup wizard	Browser-based: configure model + scenario, let GOD generate agents and steps, edit, then launch.
🧬	Agent Studio	Add or edit residents through a map-aware wizard for seed, identity, appearance, personality, routine, and review.
🧭	Map Studio	Generate or upload a map draft, calibrate locations and collisions, validate it, then publish it as a local map package.
🧼	One-command reset	Wipe replay data and seed a clean society without leaving the terminal.
🗺️	Pixel town world	A live tiled map: locations, actions, messages, statuses, all replay-friendly per step.
🧱	Single current experiment	.env stores local model/port settings; .god/current_experiment.json stores the one active experiment.
🌐	Browser replays	Curated replays on GitHub Pages, no local setup or API key required.
📦	Pack library	Import and export Experiment, Map, and Agent packs; browse more on the public site.
🪟	Windows launcher	god.cmd start on PowerShell, the same one-command flow as macOS/Linux.

🛣️ Roadmap

✅ Completed

• 🗺️ Pluggable map packages: drop a folder under agentsociety/custom/maps/<map_id>/, refresh the wizard, and a new world is selectable. Auto-discovered, validated, hot-swappable. See docs/MAP_PACKAGES.md.
• 🏫 PKU campus map: the PKU map package is bundled as a first-class map alongside The Ville.
• 🪄 No-code setup wizard: browser flow for model setup, built-in experiment choice, custom experiment generation/editing, and launch.
• 🧪 Scripted experiments: reproducible experiments ship as plain folders under quick_experiments/<hypothesis>/<experiment>/; choosing or publishing one makes it the current experiment.
• 🎮 Control Room command rail: replay controls, resident roster, live console, targeted Ask, and Intervene now live in one map-first operator surface.
• 🧬 Agent Studio v1: map-aware add/edit flow with structured profile metadata, ID validation, setup integration, and sprite generation support.
• 🧭 Map Studio v1: prompt/reference-image map draft generation, anchor and collision calibration, package validation, publishing, and Setup handoff.
• 🌏 Bilingual runtime UI: English/Chinese UI and runtime-owned labels for setup, replay, maps, statuses, actions, and system events.
• 🔌 Agent skill-runtime path: the shipped JiuwenClaw agent adapter now uses the AgentSociety skill runtime as the canonical execution path.
• 🌐 Public site & browser replays: GitHub Pages hosts curated replays, map packs, agent packs, and downloadable experiments, with no local setup or API key.
• 📦 Portable packs & import/export: Experiment, Map, and Agent packs with ZIP import/export, delivered through release assets.
• 🪟 Windows one-key launcher: god.cmd start mirrors the one-command macOS/Linux flow.

🛣️ Not Yet Done

• 🤖 Pluggable agent runtimes: swap LLM runtimes and persona templates as cleanly as we now swap maps.
• 🧪 Multi-experiment orchestration: run experiments, control groups, repeats, and ablations side by side.
• 🗺️ Live map generation: maps that evolve with events, repairs, blockages, and crowds.
• 🌦️ Event-responsive worlds: weather, accidents, festivals, rumors, and shortages that change agent behavior over time.
• 🌐 Large-scale simulation: AgentSociety batching, sharded runs, sampled replay, and performance-minded replay summaries.
• 📊 Experiment evaluation: cross-run metrics, behavior diffs, intervention effect analysis.
• 📝 Operator workflow: per-step notes, tags, bookmarks, key-event summaries.
• 🌍 Hosted live control room: a hosted demo where you can steer a run, not just watch replays, plus community scenario templates.

Have an idea? Open an issue or PR.

🏗️ How It Works

flowchart LR
  O["Operator"]:::operator
  UI["Control Room"]:::surface
  API["Live API"]:::core
  RT["Agent Runtime"]:::runtime
  TOWN["Pixel Town"]:::world
  CFG[["Experiment Files"]]:::data
  DB[("Replay Store")]:::data

  O --> UI
  UI <-->|"commands / updates"| API
  API -->|"prompts"| RT
  RT -->|"actions"| TOWN
  TOWN -->|"frames"| DB
  CFG -->|"scenario"| API

  classDef operator fill:#fff7ed,stroke:#f59e0b,color:#7c2d12,stroke-width:2px;
  classDef surface fill:#eef2ff,stroke:#6366f1,color:#312e81,stroke-width:2px;
  classDef core fill:#ecfeff,stroke:#0891b2,color:#164e63,stroke-width:2px;
  classDef runtime fill:#f0fdf4,stroke:#22c55e,color:#14532d,stroke-width:2px;
  classDef world fill:#fefce8,stroke:#ca8a04,color:#713f12,stroke-width:2px;
  classDef data fill:#fdf2f8,stroke:#db2777,color:#831843,stroke-width:2px;

GOD is intentionally local-first: the control room, backend, runtime bridge, experiment files, and replay store all run on your machine. The model endpoint is the only external service you choose.

GOD keeps three concepts separate:

• Experiment is the playable setup: map, agents, scenario context, and step plan.
• Replay is the viewable result of an experiment after it has been played.
• Runtime state is local machine data such as SQLite replay stores, logs, and agent snapshots; it is not part of an ExperimentPack and should not be committed.

Layer	What it does
🎮 Control Room	React/Vite browser UI: replay, ask, intervention, status.
⚙️ Backend	Local FastAPI service exposing live and replay APIs.
🗺️ Pixel Town	Replay-friendly social world: locations, actions, messages, agent status.
🤖 Agent Runtime	Out-of-process LLM agents reached over a local WebSocket.

⚙️ Commands

./scripts/god.sh start      # start the full stack (idempotent)
./scripts/god.sh configure  # open setup to switch defaults or create an experiment
./scripts/god.sh restart    # stop everything cleanly, then start again
./scripts/god.sh new-run    # wipe local runtime state for the current experiment and start fresh
./scripts/god.sh status     # ports, URLs, model status
./scripts/god.sh stop       # stop everything
./scripts/god.sh tail       # follow logs
./scripts/god.sh open       # open the frontend pages in the default browser

On Windows, replace ./scripts/god.sh with .\scripts\god.cmd.

🧪 Built-in Experiments

GOD ships two built-in experiments and treats them exactly like experiments you publish yourself. The setup wizard writes the selected experiment to .god/current_experiment.json; start, open, and new-run then act only on that current experiment.

More downloadable scenarios live on the public site: Empty City Gate, Gaokao Blackout, Hogwarts Parent Meeting, and others.

.env is intentionally local-only and only stores model, API, port, and similar machine settings. It no longer decides the default experiment or map, so an old GOD_MAP_ID=pku cannot make GOD Town load the PKU map.

🏘️ An ordinary weekday in The Ville

A late-spring Tuesday morning at 8:20. Sunny, 18°C, light breeze. A 200-person town with 10 residents who know each other but don't live in each other's pockets. It is a slice-of-life simulation, not a quest script.

➡️ Choose god_town in the Setup Wizard to make this the current experiment. It is bound to hypothesis_god_town/experiment_1 and the the_ville map.

➡️ See hypothesis_god_town/experiment_1/ for the full breakdown of locations, profiles, and interactions.

_{The Ville: all 10 residents going about a typical day across home, school, library, cafe, park, market, pharmacy, pub, and dorm.}

🗺️ 10 Locations · 65 location-scoped interactions
🏠 Home cook · sleep · tidy · read · WFH · video-call	🏫 School attend / teach class · grade · office hours	📚 Library read · study · research · borrow / return	☕ Hobbs Cafe light meal · coffee chat · cafe shift · meetup	🌳 Johnson Park walk · meet · exercise · public announcement
🛠️ Supply Store repair · restock · lend tools · customer service	🛒 Market buy food · haggle · deliver · chat w/ regulars	💊 Pharmacy buy medicine · refill · check BP · home visit prep	🍻 Pub socialize · watch match · host small event	🛏️ Dorm rest · self-study · common-room hangout · video call

👥 10 residents, each with a real life
🧭 Alice · 34 Neighborhood coordinator	🛠️ Bob · 45 Supply-store shopkeeper	📖 Charlie · 39 High-school history teacher	💊 Dana · 41 Pharmacy nurse	☕ Elena · 36 Cafe owner
🎒 Farah · 16 High-school student	📮 George · 68 Retired postman	💻 Hana · 28 Remote software engineer	🦺 Ivan · 52 Public-safety volunteer	🍅 Mei · 47 Market vegetable vendor

_{Every resident carries a full profile: age, family, housing, economic status, health, daily routine, skills, needs, worries, secrets, social network, language style, quirks, short- & long-term goals.}

🏫 PKU Trump Visit

A campus public-situation experiment on a stylized PKU map. Daily routines begin around gates, classrooms, library, lake, dining hall, dormitory, and Centennial Hall, then a high-attention visit event tests how residents notice, ask, gather, and react.

➡️ Choose pku_trump_visit in the Setup Wizard to make this the current experiment. It is bound to hypothesis_pku_trump_visit/experiment_1 and the pku map.

➡️ See hypothesis_pku_trump_visit/experiment_1/ for the full scenario, cast, operator notes, and replay data.

_{PKU campus map: gates, classrooms, library, Weiming Lake, Boya Pagoda, dining hall, dorm, and Centennial Hall, with named residents and the Trump-visit cast.}

🗺️ Pluggable Map Packages

GOD now discovers map packages automatically from agentsociety/custom/maps/<map_id>/. To add a map, copy agentsociety/custom/maps/_template/, replace map.yaml, visuals/map.json, tileset PNGs, and optional characters/ or location_assets/, then run:

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

The setup wizard will list valid packages without code changes. v1 supports Tiled JSON maps with PNG tilesets and a Collisions layer where 0 means walkable. The PKU campus package now ships in the repository at agentsociety/custom/maps/pku/. See docs/MAP_PACKAGES.md for the full package contract.

🤝 Contributing

Issues and pull requests are very welcome. To set up a dev environment:

./scripts/god.sh start

That installs Python and Node dependencies, brings up the full stack, creates a live session, and runs the first step so the control room opens on a populated town. From there, edit and reload.

Full guide: CONTRIBUTING.md → covers branching, the PR checklist, style, and how to ship a new map or experiment.

🙌 Acknowledgements

GOD builds on open research and open-source work. It bundles two trimmed upstream checkouts:

• AgentSociety: large-scale generative-agent simulation framework.
• JiuwenClaw: out-of-process agent runtime.

And takes inspiration from Generative Agents and OASIS.

📚 Citation

@article{piao2025agentsociety,
  title   = {AgentSociety: Large-Scale Simulation of LLM-Driven Generative Agents Advances Understanding of Human Behaviors and Society},
  author  = {Piao et al.},
  journal = {arXiv preprint arXiv:2502.08691},
  year    = {2025}
}

@misc{park2023generativeagents,
  title         = {Generative Agents: Interactive Simulacra of Human Behavior},
  author        = {Joon Sung Park and Joseph C. O'Brien and Carrie J. Cai and Meredith Ringel Morris and Percy Liang and Michael S. Bernstein},
  year          = {2023},
  eprint        = {2304.03442},
  archivePrefix = {arXiv},
  primaryClass  = {cs.HC},
  url           = {https://arxiv.org/abs/2304.03442}
}

⭐ Star History

📄 License

Released under the Apache-2.0 license. Upstream LICENSE and NOTICE files are kept inside the integrated runtime checkouts and apply to those subtrees.

_{If GOD is useful to you, a ⭐ helps other people find it.}