wehub/xiaoluolyg--god
1
0
Fork 0
Code Issues Pull Requests Actions 2 Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution
CI / Release hygiene (push) Waiting to run
Details
CI / Python targeted tests (push) Waiting to run
Details
CI / Frontend build (push) Waiting to run
Details
Pages / Build and deploy public pages (push) Waiting to run
Details

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 13:18:17 +08:00
commit aa1a5d5763
2493 changed files with 717989 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.env.example
+22
View File
@@ -0,0 +1,22 @@
# GOD - Govern, Observe, Direct
# Copy this file to .env, or run `./scripts/god.sh start` and follow the prompts.
# ----- Required model settings ---------------------------------------------
# OpenAI-compatible API. Any provider that speaks /v1/chat/completions works.
GOD_LLM_API_KEY=
GOD_LLM_API_BASE=https://api.openai.com/v1
# Required. Examples: qwen-plus, gpt-4o-mini, claude-3-5-sonnet-latest.
GOD_LLM_MODEL=
# Embedding model. Leave the base/key blank to reuse GOD_LLM_API_BASE / GOD_LLM_API_KEY.
GOD_EMBEDDING_API_KEY=
GOD_EMBEDDING_API_BASE=
GOD_EMBEDDING_MODEL=text-embedding-3-large
# Local bind ports. Override only on port conflicts.
GOD_BACKEND_HOST=127.0.0.1
GOD_BACKEND_PORT=8001
GOD_FRONTEND_PORT=5174
# Set to 1 to skip dependency checks/install when starting.
GOD_SKIP_SETUP=0
.github/ISSUE_TEMPLATE/bug_report.yml
+68
View File
@@ -0,0 +1,68 @@
name: Bug report
description: Report something that is not working in GOD.
title: "[Bug]: "
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
Thanks for taking the time to report this. Clear reproduction steps are the fastest way to help us fix it.
- type: input
id: version
attributes:
label: Commit or version
description: Paste the commit SHA, branch name, or release tag you are running.
placeholder: main @ abc1234
validations:
required: true
- type: dropdown
id: surface
attributes:
label: Area
options:
- Startup / scripts
- Setup wizard
- Live control room
- PixelReplay
- Agent runtime / JiuwenClaw
- Map packages
- Experiment config
- Docs
- Other
validations:
required: true
- type: textarea
id: steps
attributes:
label: Reproduction steps
description: What did you do, and what happened?
placeholder: |
1. Run ...
2. Open ...
3. Click ...
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected behavior
description: What did you expect to happen?
validations:
required: true
- type: textarea
id: status
attributes:
label: Status output
description: Paste `./scripts/god.sh status` and any relevant log excerpt. Redact API keys or private data.
render: text
- type: textarea
id: environment
attributes:
label: Environment
description: OS, Python, Node.js, browser, and model provider/base URL if relevant.
placeholder: macOS 15, Python 3.11, Node 22, Chrome, OpenAI-compatible endpoint
- type: textarea
id: screenshots
attributes:
label: Screenshots or recordings
description: Drag in images or short clips if the issue is visual.
.github/ISSUE_TEMPLATE/config.yml
+5
View File
@@ -0,0 +1,5 @@
blank_issues_enabled: true
contact_links:
- name: Security report
url: https://github.com/XiaoLuoLYG/GOD/security/advisories/new
about: Please report suspected vulnerabilities privately instead of opening a public issue.
.github/ISSUE_TEMPLATE/feature_request.yml
+46
View File
@@ -0,0 +1,46 @@
name: Feature request
description: Suggest an improvement or new capability for GOD.
title: "[Feature]: "
labels: ["enhancement"]
body:
- type: textarea
id: problem
attributes:
label: Problem or use case
description: What are you trying to do that GOD cannot do well today?
placeholder: I want to...
validations:
required: true
- type: textarea
id: proposal
attributes:
label: Proposed behavior
description: What should happen instead?
validations:
required: true
- type: dropdown
id: area
attributes:
label: Area
options:
- Setup wizard
- Live control room
- PixelReplay
- Agent runtime
- Map packages
- Experiment authoring
- Evaluation / metrics
- Docs
- Other
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives considered
description: Any workaround or different design you have considered?
- type: textarea
id: media
attributes:
label: References or sketches
description: Links, screenshots, sketches, or examples from other tools.
.github/pull_request_template.md
+21
View File
@@ -0,0 +1,21 @@
## Summary
- TBD
## Scope
- [ ] This PR is focused on one logical change.
- [ ] I did not commit runtime outputs, local credentials, `.god/`, `.live/`, `.DS_Store`, `promos/`, `docs/press-kit/`, or local-only large map assets.
- [ ] If this PR changes public docs, both English and Chinese docs were updated where applicable.
- [ ] If this PR changes maps or experiments, the added assets are intentionally part of the public repository.
## Validation
- [ ] `bash -n scripts/god.sh`
- [ ] `npm run build --prefix agentsociety/frontend`
- [ ] `cd agentsociety && uv run pytest -q packages/agentsociety2/tests/test_god_setup_router.py packages/agentsociety2/tests/test_map_packages.py packages/agentsociety2/tests/test_pixel_town_social_env.py`
- [ ] Map package validation, if applicable: `cd agentsociety && uv run python scripts/validate_map_package.py custom/maps/<map_id>`
## Screenshots / Clips
Add screenshots or short clips for UI, replay, map, setup, or docs changes.
.github/workflows/ci.yml
+150
View File
@@ -0,0 +1,150 @@
name: CI
on:
pull_request:
branches: [main]
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
release-hygiene:
name: Release hygiene
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v6
with:
fetch-depth: 0
- name: Check diff whitespace
shell: bash
env:
BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
run: |
set -euo pipefail
if git rev-parse --verify "${BASE_SHA}^{commit}" >/dev/null 2>&1; then
git diff --check "${BASE_SHA}...${HEAD_SHA}"
elif git rev-parse --verify HEAD~1 >/dev/null 2>&1; then
git diff --check HEAD~1..HEAD
else
git diff --check
fi
- name: Guard release-only artifacts
shell: bash
run: |
set -euo pipefail
banned_paths="$(
git ls-files \
| grep -Ev '^agentsociety/quick_experiments/(hypothesis_god_town|hypothesis_pku_trump_visit)/experiment_1/run/' \
| grep -E '(^promos/|^docs/press-kit/|^agentsociety/quick_experiments/hypothesis_pku_trump_visit/experiment_2/|^\.god/|^\.live/|(^|/)\.DS_Store$|(^|/)run_launcher\.log$|^agentsociety/quick_experiments/.*/run(_[^/]*)?/)' || true
)"
if [[ -n "${banned_paths}" ]]; then
echo "These paths should not be committed to the public release branch:"
echo "${banned_paths}"
exit 1
fi
- name: Check local README images
shell: bash
run: |
set -euo pipefail
python3 - <<'PY'
import pathlib
import re
import sys
public_docs = [
pathlib.Path("README.md"),
pathlib.Path("README.zh-CN.md"),
pathlib.Path("QUICKSTART.md"),
pathlib.Path("QUICKSTART.zh-CN.md"),
pathlib.Path("CONTRIBUTING.md"),
pathlib.Path("CONTRIBUTING.zh-CN.md"),
pathlib.Path("docs/MAP_PACKAGES.md"),
pathlib.Path("docs/MAP_PACKAGES.zh-CN.md"),
]
public_docs.extend(sorted(pathlib.Path("docs/developer").rglob("*.rst")))
public_docs.extend(sorted(pathlib.Path("docs/developer").rglob("*.md")))
public_docs.extend(sorted(pathlib.Path("docs/site").rglob("*.html")))
failures = []
for md_path in public_docs:
if not md_path.exists():
continue
text = md_path.read_text(encoding="utf-8")
targets = []
targets.extend(re.findall(r"<img[^>]+src=[\"']([^\"']+)[\"']", text, flags=re.I))
targets.extend(re.findall(r"!\[[^\]]*\]\(([^)]+)\)", text))
targets.extend(re.findall(r"\.\. image::\s+([^\s]+)", text))
for raw_target in targets:
target = raw_target.strip().split("#", 1)[0].split("?", 1)[0]
if not target or re.match(r"^[a-z][a-z0-9+.-]*:", target, flags=re.I):
continue
resolved = (md_path.parent / target).resolve()
if not resolved.exists():
failures.append(f"{md_path}: missing image asset {raw_target}")
if failures:
print("\n".join(failures))
sys.exit(1)
PY
python-tests:
name: Python targeted tests
runs-on: ubuntu-latest
timeout-minutes: 40
defaults:
run:
working-directory: agentsociety
steps:
- name: Checkout
uses: actions/checkout@v6
- name: Set up Python
uses: actions/setup-python@v6
with:
python-version: "3.11"
- name: Set up uv
uses: astral-sh/setup-uv@v7
with:
enable-cache: true
cache-dependency-glob: agentsociety/uv.lock
- name: Run targeted backend tests
run: |
uv run pytest -q \
packages/agentsociety2/tests/test_god_setup_router.py \
packages/agentsociety2/tests/test_map_packages.py \
packages/agentsociety2/tests/test_pixel_town_social_env.py
frontend-build:
name: Frontend build
runs-on: ubuntu-latest
timeout-minutes: 25
steps:
- name: Checkout
uses: actions/checkout@v6
- name: Set up Node.js
uses: actions/setup-node@v6
with:
node-version: "22"
cache: npm
cache-dependency-path: agentsociety/frontend/package-lock.json
- name: Install frontend dependencies
run: npm ci --prefix agentsociety/frontend
- name: Build frontend
run: npm run build --prefix agentsociety/frontend
.github/workflows/pages.yml
+73
View File
@@ -0,0 +1,73 @@
name: Pages
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: false
jobs:
deploy:
name: Build and deploy public pages
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Checkout
uses: actions/checkout@v6
- name: Set up Python
uses: actions/setup-python@v6
with:
python-version: "3.11"
- name: Install developer docs dependencies
run: |
python -m pip install --upgrade pip
python -m pip install -r docs/developer/requirements.txt
- name: Build public pages
run: |
set -euo pipefail
mkdir -p _site
cp -R docs/site/. _site/
sphinx-build -W -b html docs/developer _site/developer
- name: Guard release asset boundary
run: |
set -euo pipefail
banned="$(
find _site/public-data \( \
-path '*/downloads/*' -o \
-path '*/map-packs/*/assets/*' -o \
-path '*/map-packs/*/characters/*' -o \
-path '*/map-packs/*/location-assets/*' -o \
-name '*.zip' \
\) -print 2>/dev/null | head -50
)"
if [[ -n "${banned}" ]]; then
echo "Large public pack assets must be uploaded as GitHub Release assets, not deployed from Git:"
echo "${banned}"
exit 1
fi
- name: Configure Pages
uses: actions/configure-pages@v6
- name: Upload artifact
uses: actions/upload-pages-artifact@v4
with:
path: _site
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
.gitignore
+77
View File
@@ -0,0 +1,77 @@
.DS_Store
.cursor/
/.env
/.env.*
!/.env.example
.god/
.live/
# Public site download assets are published to GitHub Releases, not Git.
docs/site/public-data/**/*.zip
docs/site/public-data/**/downloads/
docs/site/public-data/map-packs/*/assets/
docs/site/public-data/map-packs/*/characters/
docs/site/public-data/map-packs/*/location-assets/
docs/site/public-data/map-packs/*/tiled-map.json
# Python
.venv/
__pycache__/
*.py[cod]
.pytest_cache/
.ruff_cache/
.mypy_cache/
*.egg-info/
# Node
node_modules/
dist/
build/
coverage/
test-results/
promos/
# Runtime data
*.log
*.db
*.sqlite
*.sqlite3
.superpowers/
logs/
agentsociety_data/
agentsociety/agentsociety_data/
agentsociety/logs/
jiuwenclaw/logs/
agentsociety/quick_experiments/**/run/
agentsociety/quick_experiments/**/run_*/
agentsociety/quick_experiments/**/run_failed*/
agentsociety/quick_experiments/**/run_stuck*/
agentsociety/quick_experiments/**/run_launcher.log
agentsociety/quick_experiments/**/.runtime/
agentsociety/quick_experiments/hypothesis_*/
!agentsociety/quick_experiments/hypothesis_god_town/
!agentsociety/quick_experiments/hypothesis_god_town/**
!agentsociety/quick_experiments/hypothesis_pku_trump_visit/
!agentsociety/quick_experiments/hypothesis_pku_trump_visit/**
**/.DS_Store
agentsociety/quick_experiments/hypothesis_god_town/**/run/
agentsociety/quick_experiments/hypothesis_pku_trump_visit/**/run/
agentsociety/quick_experiments/hypothesis_god_town/**/run_*/
agentsociety/quick_experiments/hypothesis_god_town/**/run_failed*/
agentsociety/quick_experiments/hypothesis_god_town/**/run_stuck*/
agentsociety/quick_experiments/hypothesis_god_town/**/run_launcher.log
agentsociety/quick_experiments/hypothesis_god_town/**/.runtime/
agentsociety/quick_experiments/hypothesis_pku_trump_visit/**/run_*/
agentsociety/quick_experiments/hypothesis_pku_trump_visit/**/run_failed*/
agentsociety/quick_experiments/hypothesis_pku_trump_visit/**/run_stuck*/
agentsociety/quick_experiments/hypothesis_pku_trump_visit/**/run_launcher.log
agentsociety/quick_experiments/hypothesis_pku_trump_visit/**/.runtime/
# Agent Studio generates these locally; configs should not depend on committed test sprites.
agentsociety/custom/maps/*/characters/Generated_Agent_*.png
# Local Superpowers planning/spec artifacts are development process notes, not product docs.
docs/superpowers/
# Map Studio generated packages are local user output by default.
agentsociety/custom/generated_maps/
.readthedocs.yaml
+17
View File
@@ -0,0 +1,17 @@
# Read the Docs configuration for the GOD developer documentation.
version: 2
build:
os: ubuntu-22.04
tools:
python: "3.12"
python:
install:
- requirements: docs/developer/requirements.txt
sphinx:
configuration: docs/developer/conf.py
formats:
- htmlzip
CODE_OF_CONDUCT.md
+34
View File
@@ -0,0 +1,34 @@
# Code of Conduct
GOD is a project for building and discussing agent-society experiments. The community should be useful, curious, and safe for people with different backgrounds, research interests, and levels of experience.
## Expected Behavior
- Be respectful and constructive in issues, pull requests, discussions, reviews, and demos.
- Assume good intent, but be willing to clarify and correct mistakes.
- Keep criticism focused on the work, the evidence, and the user impact.
- Give credit for ideas, code, experiments, and assets.
- Be careful with screenshots, logs, generated profiles, and scenario data that may contain private or sensitive information.
## Unacceptable Behavior
- Harassment, threats, hate speech, personal attacks, or discriminatory comments.
- Sexualized language or imagery in project spaces.
- Publishing another person's private information without permission.
- Posting API keys, credentials, private logs, or other sensitive data.
- Repeated low-effort disruption after maintainers ask for a change in behavior.
- Encouraging abuse, deception, or unsafe use of the project.
## Scope
This code of conduct applies to this repository and related project spaces, including GitHub issues, pull requests, discussions, documentation, demos, and community support conversations.
## Enforcement
Maintainers may edit, hide, or remove comments; close issues or discussions; block users from participation; or take other reasonable moderation actions when behavior harms the project or its community.
If you need to report a conduct concern, contact the maintainers through the least public safe channel available. For public, non-sensitive concerns, open an issue or discussion and keep personal details out of the report. For platform-level abuse or urgent safety issues, use GitHub's own abuse-reporting tools.
## Maintainer Responsibilities
Maintainers should apply this code of conduct consistently and proportionally. Reports should be handled with care, and private or sensitive information should not be exposed unnecessarily.
CONTRIBUTING.md
+111
View File
@@ -0,0 +1,111 @@
<h1 align="center">🤝 Contributing to GOD</h1>
<p align="center">
<b>Issues and pull requests are very welcome.</b><br/>
<sub>Whether you're fixing a typo, shipping a new map, or rewiring the runtime — thank you.</sub>
</p>
<p align="center">
<a href="CONTRIBUTING.zh-CN.md">🌏 中文</a>
</p>
---
## 🧭 Ways to contribute
| | |
| --- | --- |
| 🐛 **Report a bug** | Open an [issue](https://github.com/XiaoLuoLYG/GOD/issues/new) with reproduction steps, screenshots, and the output of `./scripts/god.sh status`. |
| 💡 **Propose a feature** | Open an issue first. A short description + a one-paragraph use case is enough. |
| 🗺️ **Add a new map** | Drop a folder under `agentsociety/custom/maps/<your_map_id>/` and follow [`docs/MAP_PACKAGES.md`](docs/MAP_PACKAGES.md). PRs welcome. |
| 🧪 **Add a new experiment** | Drop a folder under `agentsociety/quick_experiments/<your_hypothesis>/<your_experiment>/`. See [`hypothesis_god_town/experiment_1/`](agentsociety/quick_experiments/hypothesis_god_town/experiment_1/README.md) as the reference shape. |
| ✏️ **Improve docs** | Fix translations, polish wording, add screenshots, add diagrams. |
| 🔌 **Wire in a runtime** | Adapter PRs for new LLM runtimes or persona templates are very welcome — see `agentsociety/custom/agents/`. |
## 🚀 Dev environment
```bash
git clone https://github.com/XiaoLuoLYG/GOD.git
cd GOD
./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.
Useful day-to-day commands:
```bash
./scripts/god.sh restart # stop everything cleanly, then start again
./scripts/god.sh new-run # wipe replay data and start a fresh session
./scripts/god.sh status # check ports, URLs, model status
./scripts/god.sh tail # follow logs
./scripts/god.sh stop # stop everything
```
## 🌳 Branching & PR flow
1. Fork the repo and create a topic branch off `main`.
2. Keep PRs **small and focused** — one logical change per PR.
3. Run the validators you've touched:
```bash
# If you changed a map package
cd agentsociety
uv run python scripts/validate_map_package.py custom/maps/<map_id>
# If you changed Python services
cd agentsociety/packages/agentsociety2
uv run pytest
```
4. Open the PR against `main`. Describe **what** changed and **why** in the
body. Screenshots and short clips go a long way for UI changes.
5. Be patient — the reviewer might be in another time zone.
## 📝 Style
- **Python:** 4-space indent, type hints where they help, no unused imports.
We don't enforce a single formatter yet; match the surrounding code.
- **TypeScript / React:** match the surrounding component style.
- **Line width:** keep lines under **120 characters** where reasonable.
- **No forward declarations** (per project rule).
- **Comments** should explain non-obvious intent, not narrate the code.
- **Commits:** present tense, short subject (~60 chars), longer body if needed.
- **Docs:** when you change a Markdown doc with both `.md` and `.zh-CN.md`,
update both. Use idiomatic English and Chinese — not literal translations.
## 🗺️ Adding a new map package — checklist
- [ ] Folder named `agentsociety/custom/maps/<map_id>/`
- [ ] `map.yaml`, `README.md`, `ATTRIBUTION.md` present
- [ ] Tiled JSON has a `Collisions` layer
- [ ] All tileset images resolve inside the package folder
- [ ] `uv run python scripts/validate_map_package.py custom/maps/<map_id>` passes
- [ ] At least one screenshot in the PR description
## 🧪 Adding a new experiment — checklist
- [ ] Folder under `agentsociety/quick_experiments/<hypothesis>/<experiment>/`
- [ ] `README.md` (English) + `README.zh-CN.md` (Chinese)
- [ ] `init/init_config.json` + `init/steps.yaml`
- [ ] A `run.sh` that boots the experiment via the AgentSociety CLI
- [ ] Manual run notes if there's an operator script (see PKU Trump experiment for the pattern)
## 📜 License
By contributing to GOD you agree that your contributions will be licensed under
the [Apache License 2.0](LICENSE). Upstream LICENSE and NOTICE files are kept
inside the integrated runtime checkouts (`agentsociety/`, `jiuwenclaw/`) and
apply to those subtrees.
## 🛡️ Be kind
GOD is a small open-source project. Be patient, be specific, and give the kind
of feedback you'd want to receive. We're here to build a town of agents — and
hopefully a small, warm community of humans around it.
---
<p align="center"><sub>Thank you for making GOD better. ⭐</sub></p>
CONTRIBUTING.zh-CN.md
+107
View File
@@ -0,0 +1,107 @@
<h1 align="center">🤝 为 GOD 做贡献</h1>
<p align="center">
<b>欢迎提 issue 与 PR。</b><br/>
<sub>无论是修一个错别字、加一张地图，还是重写一段 runtime —— 谢谢你。</sub>
</p>
<p align="center">
<a href="CONTRIBUTING.md">🌏 English</a>
</p>
---
## 🧭 你可以怎么贡献
| | |
| --- | --- |
| 🐛 **报 bug** | 提一个 [issue](https://github.com/XiaoLuoLYG/GOD/issues/new)，附上复现步骤、截图，以及 `./scripts/god.sh status` 的输出。 |
| 💡 **提需求** | 先提一个 issue，简短描述 + 一段使用场景就够。 |
| 🗺️ **加新地图** | 把文件夹丢到 `agentsociety/custom/maps/<your_map_id>/`，遵循 [`docs/MAP_PACKAGES.zh-CN.md`](docs/MAP_PACKAGES.zh-CN.md)。欢迎 PR。 |
| 🧪 **加新实验** | 把文件夹丢到 `agentsociety/quick_experiments/<your_hypothesis>/<your_experiment>/`。参考 [`hypothesis_god_town/experiment_1/`](agentsociety/quick_experiments/hypothesis_god_town/experiment_1/README.zh-CN.md) 的形态。 |
| ✏️ **改文档** | 修翻译、打磨措辞、加截图、加图示。 |
| 🔌 **接 Runtime** | 欢迎为新的 LLM runtime 或 persona 模板提 adapter PR —— 见 `agentsociety/custom/agents/`。 |
## 🚀 开发环境
```bash
git clone https://github.com/XiaoLuoLYG/GOD.git
cd GOD
./scripts/god.sh start
```
会自动装好 Python 和 Node 依赖，启动完整栈，创建 live session，先跑完第 1 步，
让控制台打开时就是已初始化的小镇。改完代码刷新即可。
常用命令：
```bash
./scripts/god.sh restart # 先干净停止，再重新启动
./scripts/god.sh new-run # 清掉 replay 数据，开一个新 session
./scripts/god.sh status # 查看端口、URL、模型状态
./scripts/god.sh tail # 跟随日志
./scripts/god.sh stop # 停止所有服务
```
## 🌳 分支与 PR 流程
1. Fork 仓库，从 `main` 拉一个 topic 分支。
2. PR 要 **小而聚焦** —— 每个 PR 只做一件事。
3. 跑你改过部分的校验器：
```bash
# 改过地图包
cd agentsociety
uv run python scripts/validate_map_package.py custom/maps/<map_id>
# 改过 Python 服务
cd agentsociety/packages/agentsociety2
uv run pytest
```
4. 把 PR 提到 `main`。正文里写清楚 **改了什么** 和 **为什么**。UI 改动配上截图或短视频效果更好。
5. 耐心等等 —— reviewer 可能在另一个时区。
## 📝 代码风格
- **Python:** 4 空格缩进，必要的地方加类型注解，不要留无用 import。
目前没有强制统一 formatter，跟周围代码风格一致即可。
- **TypeScript / React:** 跟周围组件风格保持一致。
- **行宽:** 合理的地方控制在 **120 字符以内**。
- **不使用前置声明**（项目规则）。
- **注释** 只解释非显然的意图，不要复述代码做了什么。
- **Commit:** 现在时、短主题（约 60 字符）、需要再加正文。
- **文档:** 同时存在 `.md` 和 `.zh-CN.md` 的，改一个就两个都改。
请用地道的中英文，不要直译。
## 🗺️ 提交新地图包 · 检查表
- [ ] 目录名 `agentsociety/custom/maps/<map_id>/`
- [ ] 含 `map.yaml`、`README.md`、`ATTRIBUTION.md`
- [ ] Tiled JSON 包含 `Collisions` 层
- [ ] 所有图块素材路径都落在地图包内
- [ ] `uv run python scripts/validate_map_package.py custom/maps/<map_id>` 通过
- [ ] PR 正文至少附一张截图
## 🧪 提交新实验 · 检查表
- [ ] 目录在 `agentsociety/quick_experiments/<hypothesis>/<experiment>/`
- [ ] `README.md`（英文）+ `README.zh-CN.md`（中文）
- [ ] `init/init_config.json` + `init/steps.yaml`
- [ ] `run.sh` 能用 AgentSociety CLI 拉起实验
- [ ] 如果有操作员脚本，补一份手动运行说明（参考 PKU Trump 实验的模式）
## 📜 License
向 GOD 贡献内容，即表示你同意按 [Apache License 2.0](LICENSE) 授权你的贡献。
集成的上游代码（`agentsociety/`、`jiuwenclaw/`）各自保留了它们的 LICENSE / NOTICE，
对应子树仍受其约束。
## 🛡️ 友善些
GOD 是一个小型开源项目。请保持耐心、具体描述，给出你也愿意收到的那种反馈。
我们要做的是一座由 Agent 组成的小镇 —— 也希望围绕它，慢慢长出一个温暖的小社区。
---
<p align="center"><sub>谢谢你让 GOD 变得更好。⭐</sub></p>
LICENSE
+201
View File
@@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright 2026 GOD project authors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
QUICKSTART.md
+131
View File
@@ -0,0 +1,131 @@
# GOD Quick Start
The shortest path from a clean machine to the setup wizard and then a live GOD control room.
> Chinese version: [QUICKSTART.zh-CN.md](QUICKSTART.zh-CN.md)
---
## 1. Prerequisites
You will need:
- macOS/Linux: Python 3.11+, Node.js & `npm`, [`uv`](https://docs.astral.sh/uv/), and `screen`
- Windows: PowerShell 5.1+ and `winget`; the startup script installs missing Git, Node.js LTS/npm, and `uv`
macOS:
```bash
brew install python node uv screen
```
If `git clone` is not available on Windows yet, install Git first with `winget install --id Git.Git -e --accept-package-agreements --accept-source-agreements` or download the repository ZIP.
## 2. Clone
```bash
git clone https://github.com/XiaoLuoLYG/GOD.git
cd GOD
```
## 3. Start
macOS/Linux:
```bash
./scripts/god.sh start
```
Windows PowerShell:
```powershell
.\scripts\god.cmd start
```
`start` is the normal one-command path. It is idempotent, so running it again reuses services that are already up.
On first run, GOD will:
1. Create `.env` from `.env.example`.
2. Install Python + Node dependencies.
3. Start the setup backend/control room.
4. Open the browser setup wizard at `/setup`.
5. Wait for you to save model settings and choose an experiment.
6. Bring up the full stack for that current experiment, create a live session, run the first step, and open the control room.
<p align="center">
<img src="docs/assets/screenshots/02-setup-wizard-en.png" alt="GOD setup wizard" width="100%" />
</p>
In the wizard you can choose one of three paths:
- **Open GOD Town** launches the built-in The Ville baseline.
- **Open PKU Trump Visit** launches the built-in PKU campus experiment.
- **Create Custom Experiment** lets you describe a scenario, generate an editable experiment draft, adjust agents/steps, and then click **Save and Launch**.
Three settings are required:
| Variable | Example |
| --- | --- |
| `GOD_LLM_API_KEY` | `sk-...` |
| `GOD_LLM_API_BASE` | `https://api.openai.com/v1` |
| `GOD_LLM_MODEL` | `gpt-5.4` |
Any OpenAI-compatible endpoint works. The API key is saved only in local `.env`; the browser only receives redacted status. Experiment selection is saved separately in `.god/current_experiment.json`, so `.env` does not control which map or experiment starts.
To switch between built-in experiments or create another experiment later, run:
```bash
./scripts/god.sh configure
```
## 4. Open the control room
When startup finishes, the script opens the control room for the current experiment and prints a URL like:
```text
http://127.0.0.1:5174/pixel-replay/god_town/1
```
If the browser did not open automatically, open that URL. You should see the pixel town, the resident roster, step controls, and the live console.
## 5. Verify
```bash
./scripts/god.sh status
```
You should see every service marked `up`.
## 6. Restart or run fresh
Use `restart` when you want a clean process restart without wiping the current run:
```bash
./scripts/god.sh restart
```
Use `new-run` when the UI shows old replay data or you want a fresh live session:
```bash
./scripts/god.sh new-run
```
`new-run` prints the current experiment run directory, stops services, wipes only that current run state, and starts a clean live session.
## 7. Day-to-day commands
```bash
./scripts/god.sh start # idempotent; reuses running services
./scripts/god.sh setup # install/check dependencies only
./scripts/god.sh configure # switch built-in experiments or create a custom one
./scripts/god.sh restart # stop everything cleanly, then start again
./scripts/god.sh new-run # wipe the current experiment run and start fresh
./scripts/god.sh status # print URLs, ports, and model status
./scripts/god.sh stop # stop everything
./scripts/god.sh tail # follow logs
./scripts/god.sh open # open the frontend pages in the browser
```
On Windows, replace `./scripts/god.sh` with `.\scripts\god.cmd`.
QUICKSTART.zh-CN.md
+131
View File
@@ -0,0 +1,131 @@
# GOD 快速开始
从一台干净机器进入配置向导，再跑到 GOD 控制台所需的最短路径。
> English: [QUICKSTART.md](QUICKSTART.md)
---
## 1. 前置依赖
需要安装：
- macOS/Linux：Python 3.11+、Node.js 与 `npm`、[`uv`](https://docs.astral.sh/uv/) 和 `screen`
- Windows：PowerShell 5.1+ 和 `winget`；启动脚本会补齐缺失的 Git、Node.js LTS/npm 与 `uv`
macOS：
```bash
brew install python node uv screen
```
Windows 如果还不能执行 `git clone`，先运行 `winget install --id Git.Git -e --accept-package-agreements --accept-source-agreements` 安装 Git，或直接下载仓库 ZIP。
## 2. 克隆
```bash
git clone https://github.com/XiaoLuoLYG/GOD.git
cd GOD
```
## 3. 启动
macOS/Linux：
```bash
./scripts/god.sh start
```
Windows PowerShell：
```powershell
.\scripts\god.cmd start
```
`start` 是日常使用的一键入口；它可以重复执行，已经运行的服务会被复用。
第一次运行会自动完成：
1. 从 `.env.example` 创建 `.env`。
2. 安装 Python 和 Node 依赖。
3. 启动 setup 模式的后端/控制台。
4. 在浏览器打开 `/setup` 配置向导。
5. 等你保存模型配置，并选择要打开的实验。
6. 为这个当前实验启动完整栈，创建 live session，先跑完第 1 步，并打开控制台。
<p align="center">
<img src="docs/assets/screenshots/02-setup-wizard-zh.png" alt="GOD 实验配置向导" width="100%" />
</p>
向导里有三条路径：
- **打开 GOD Town**：直接启动内置 The Ville 小镇实验。
- **打开 PKU Trump Visit**：直接启动内置北大校园实验。
- **新建自定义实验**：填写场景，生成可编辑实验草案，调整 agent/steps，最后点击 **保存并启动**。
必需的三个配置：
| 变量 | 示例 |
| :-- | :-- |
| `GOD_LLM_API_KEY` | `sk-...` |
| `GOD_LLM_API_BASE` | `https://api.openai.com/v1` |
| `GOD_LLM_MODEL` | `gpt-5.4` |
任意 OpenAI 兼容接口都可以。API key 只保存在本地 `.env`；浏览器只会拿到脱敏后的状态。实验选择单独保存在 `.god/current_experiment.json`，所以 `.env` 不再控制启动哪个实验或哪张地图。
之后如果想切换两个内置实验，或创建另一个实验，运行：
```bash
./scripts/god.sh configure
```
## 4. 打开控制台
启动完成后，脚本会自动打开当前实验的控制台，并打印类似这样的 URL：
```text
http://127.0.0.1:5174/pixel-replay/god_town/1
```
如果浏览器没有自动打开，手动打开这个 URL。你应该能看到像素小镇、居民列表、step 控制条和实时控制台。
## 5. 验证
```bash
./scripts/god.sh status
```
所有服务都应显示 `up`。
## 6. 重启或重新开跑
如果只是想干净重启进程，但保留当前 run：
```bash
./scripts/god.sh restart
```
如果 UI 里还显示旧的 replay 数据，或你想开一个全新的 live session：
```bash
./scripts/god.sh new-run
```
`new-run` 会先打印当前实验的 run 目录，停止服务，只清掉当前实验的 replay/run 状态，并开一个干净的 live session。
## 7. 日常命令
```bash
./scripts/god.sh start # 可重复执行；已运行的服务会被复用
./scripts/god.sh setup # 只安装/检查依赖
./scripts/god.sh configure # 切换内置实验，或创建自定义实验
./scripts/god.sh restart # 先干净停止，再重新启动
./scripts/god.sh new-run # 清空当前实验 run，并开一个新 session
./scripts/god.sh status # 查看 URL、端口和模型状态
./scripts/god.sh stop # 停止所有服务
./scripts/god.sh tail # 跟随日志
./scripts/god.sh open # 在浏览器里打开前端页面
```
Windows 下把 `./scripts/god.sh` 替换成 `.\scripts\god.cmd` 即可。
README.md
+393
View File
@@ -0,0 +1,393 @@
<h1 align="center">
<img src="docs/assets/logo_no_bg.png" alt="GOD logo" height="32" />
&nbsp;GOD · Govern · Observe · Direct
</h1>
<p align="center">
<img src="docs/assets/screenshots/00-hero.png" alt="GOD — Govern · Observe · Direct" width="100%" />
</p>
<p align="center">
<b>🌩️ Be like a god to a town of agents.</b><br/>
Pause time. Whisper to a soul. Bend the next step. Reset the world — all from a single click.
</p>
<p align="center">
<a href="https://xiaoluolyg.github.io/GOD/replays/god-town/"><b>▶ Try browser replay</b></a>
&nbsp;·&nbsp; no install, no API key &nbsp;·&nbsp;
<a href="#-quick-start"><b>Run locally</b></a>
</p>
<p align="center">
<a href="#-live-demo"><b>🌐 Live Demo</b></a> ·
<a href="#-quick-start"><b>🚀 Quick Start</b></a> ·
<a href="#-updates">Updates</a> ·
<a href="#%EF%B8%8F-roadmap">Roadmap</a> ·
<a href="#-highlights">Highlights</a> ·
<a href="#-features">Features</a> ·
<a href="#-built-in-experiments">Built-in Experiments</a> ·
<a href="https://xiaoluolyg.github.io/GOD/">Public Site</a> ·
<a href="https://xiaoluolyg.github.io/GOD/developer/">Developer Docs</a> ·
<a href="CONTRIBUTING.md">Contributing</a> ·
<a href="README.zh-CN.md">🌏 中文</a>
</p>
<p align="center">
<a href="https://github.com/XiaoLuoLYG/GOD/releases/tag/v0.2.0">
<img alt="Release" src="https://img.shields.io/github/v/release/XiaoLuoLYG/GOD?style=flat-square" />
</a>
<a href="https://xiaoluolyg.github.io/GOD/replays/god-town/">
<img alt="Live replay" src="https://img.shields.io/badge/demo-browser%20replay-22c55e?style=flat-square" />
</a>
<img alt="Python" src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" />
<img alt="React" src="https://img.shields.io/badge/React-18-61DAFB?style=flat-square&logo=react&logoColor=black" />
<img alt="Vite" src="https://img.shields.io/badge/Vite-6-646CFF?style=flat-square&logo=vite&logoColor=white" />
<img alt="No-Code Setup" src="https://img.shields.io/badge/setup-no--code-22c55e?style=flat-square&logo=googlechrome&logoColor=white" />
<img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square" />
<img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-14b8a6?style=flat-square" />
</p>
---
> 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](https://github.com/XiaoLuoLYG/GOD/releases/tag/v0.2.0):** public site with browser replays;
Experiment / Map / Agent pack hubs and ZIP import-export; Windows launcher; hardened first-run startup.
([#64](https://github.com/XiaoLuoLYG/GOD/pull/64) [#65](https://github.com/XiaoLuoLYG/GOD/pull/65))
- **2026-06-06 · Site & packs:** rebuilt public site and frontend; site packs delivered through release assets; map pack preview pages. ([#61](https://github.com/XiaoLuoLYG/GOD/pull/61) [#62](https://github.com/XiaoLuoLYG/GOD/pull/62) [#63](https://github.com/XiaoLuoLYG/GOD/pull/63))
- **2026-06-01 · Portable packs:** unified ExperimentPack downloads; GOD package import/export; curated experiment library.
([#57](https://github.com/XiaoLuoLYG/GOD/pull/57) [#59](https://github.com/XiaoLuoLYG/GOD/pull/59) [#60](https://github.com/XiaoLuoLYG/GOD/pull/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](https://github.com/XiaoLuoLYG/GOD/pull/45) [#49](https://github.com/XiaoLuoLYG/GOD/pull/49) [#50](https://github.com/XiaoLuoLYG/GOD/pull/50))
- **2026-05 · Operator studios:** bilingual control room, map-first `/ask` + `/intervene` rail,
Agent Studio, Map Studio, unified skill runtime.([#26](https://github.com/XiaoLuoLYG/GOD/pull/26) to [#31](https://github.com/XiaoLuoLYG/GOD/pull/31))
- **2026-05-21 · [v0.1.0](https://github.com/XiaoLuoLYG/GOD/releases/tag/v0.1.0):** first tagged release with two built-in experiments and the PKU campus map. ([#21](https://github.com/XiaoLuoLYG/GOD/pull/21) [#24](https://github.com/XiaoLuoLYG/GOD/pull/24))
## ✨ Highlights
<table>
<tr>
<td align="center" width="20%">⏯️<br/><b>Pause time</b><br/><sub>Stop, scrub, fast-forward, auto-play any live step.</sub></td>
<td align="center" width="20%">💬<br/><b>Ask anyone</b><br/><sub>Ask one resident, a group, or the whole town, mid-run.</sub></td>
<td align="center" width="20%">🎛️<br/><b>Steer the next step</b><br/><sub>Inject instructions and inspect how agents respond.</sub></td>
<td align="center" width="20%">🪄<br/><b>No-code setup</b><br/><sub>Configure model, scenario and agents from a browser wizard.</sub></td>
<td align="center" width="20%">🔄<br/><b>Reset run state</b><br/><sub>One command wipes a stale run and re-seeds a clean world.</sub></td>
</tr>
</table>
## 🖼️ Screenshots
<p align="center">
<img src="docs/assets/screenshots/01-control-room.png" alt="GOD control room" width="94%" />
</p>
<p align="center"><sub>Live control room: PKU map, step controls, targeted ask, and resident roster in one view.</sub></p>
## 🌐 Live Demo
Browse everything in your browser on the [**public site**](https://xiaoluolyg.github.io/GOD/): curated replays, map packs, agent packs, and downloadable experiments. No install or API key needed.
<p align="center">
<a href="https://xiaoluolyg.github.io/GOD/">
<img src="docs/assets/screenshots/03-public-site.png" alt="GOD public site" height="190" />
</a>
&nbsp;
<a href="https://xiaoluolyg.github.io/GOD/map-packs/">
<img src="docs/assets/screenshots/04-map-packs.png" alt="GOD map packs" height="190" />
</a>
&nbsp;
<a href="https://xiaoluolyg.github.io/GOD/agent-packs/">
<img src="docs/assets/screenshots/05-agent-packs.png" alt="GOD agent packs" height="190" />
</a>
</p>
<p align="center"><sub>Left to right: the public site homepage, downloadable map packs, and downloadable agent packs.</sub></p>
## 🚀 Quick Start
```bash
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.
<p align="center">
<img src="docs/assets/screenshots/02-setup-wizard-en.png" alt="GOD setup wizard" width="100%" />
</p>
<p align="center"><sub>The Setup Wizard: model config, experiment choice, and custom society creation in one browser flow.</sub></p>
<table>
<tr>
<td align="center" width="16%">🔌<br/><b>1. Model</b><br/><sub>Paste an OpenAI-compatible API key, base URL, and model name.</sub></td>
<td align="center" width="16%">🧭<br/><b>2. Choose</b><br/><sub>Open GOD Town, open PKU Trump Visit, or create your own.</sub></td>
<td align="center" width="16%">🧪<br/><b>3. Scenario</b><br/><sub>Describe your world: date, weather, vibes, rules.</sub></td>
<td align="center" width="16%">🤖<br/><b>4. Generate</b><br/><sub>The GOD agent drafts agent profiles and a step plan.</sub></td>
<td align="center" width="16%">✏️<br/><b>5. Edit</b><br/><sub>Tweak personalities, relationships, locations, or steps.</sub></td>
<td align="center" width="16%">▶️<br/><b>6. Launch</b><br/><sub>Publish the experiment and step into the control room.</sub></td>
</tr>
</table>
Any OpenAI-compatible endpoint works. When the wizard hands off, the script prints a URL like:
```text
http://127.0.0.1:5174/pixel-replay/god_town/1
```
Full walkthrough: **[Quickstart →](QUICKSTART.md)**
## 🧩 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
- [x] 🗺️ **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`](docs/MAP_PACKAGES.md).
- [x] 🏫 **PKU campus map**: the PKU map package is bundled as a first-class map alongside The Ville.
- [x] 🪄 **No-code setup wizard**: browser flow for model setup, built-in experiment choice, custom experiment generation/editing, and launch.
- [x] 🧪 **Scripted experiments**: reproducible experiments ship as plain folders under `quick_experiments/<hypothesis>/<experiment>/`; choosing or publishing one makes it the current experiment.
- [x] 🎮 **Control Room command rail**: replay controls, resident roster, live console, targeted Ask, and Intervene now live in one map-first operator surface.
- [x] 🧬 **Agent Studio v1**: map-aware add/edit flow with structured profile metadata, ID validation, setup integration, and sprite generation support.
- [x] 🧭 **Map Studio v1**: prompt/reference-image map draft generation, anchor and collision calibration, package validation, publishing, and Setup handoff.
- [x] 🌏 **Bilingual runtime UI**: English/Chinese UI and runtime-owned labels for setup, replay, maps, statuses, actions, and system events.
- [x] 🔌 **Agent skill-runtime path**: the shipped JiuwenClaw agent adapter now uses the AgentSociety skill runtime as the canonical execution path.
- [x] 🌐 **Public site & browser replays**: GitHub Pages hosts curated replays, map packs, agent packs, and downloadable experiments, with no local setup or API key.
- [x] 📦 **Portable packs & import/export**: Experiment, Map, and Agent packs with ZIP import/export, delivered through release assets.
- [x] 🪟 **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](#-contributing).
## 🏗️ How It Works
```mermaid
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
```bash
./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**](https://xiaoluolyg.github.io/GOD/experiments/): 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/`](agentsociety/quick_experiments/hypothesis_god_town/experiment_1/README.md) for the full breakdown of locations, profiles, and interactions.
<p align="center">
<img src="docs/assets/screenshots/map-the-ville.png" alt="The Ville map" width="94%" />
</p>
<p align="center"><sub>The Ville: all 10 residents going about a typical day across home, school, library, cafe, park, market, pharmacy, pub, and dorm.</sub></p>
<table>
<tr><td colspan="5" align="center"><b>🗺️ 10 Locations · 65 location-scoped interactions</b></td></tr>
<tr>
<td align="center" width="20%">🏠<br/><b>Home</b><br/><sub>cook · sleep · tidy · read · WFH · video-call</sub></td>
<td align="center" width="20%">🏫<br/><b>School</b><br/><sub>attend / teach class · grade · office hours</sub></td>
<td align="center" width="20%">📚<br/><b>Library</b><br/><sub>read · study · research · borrow / return</sub></td>
<td align="center" width="20%">☕<br/><b>Hobbs Cafe</b><br/><sub>light meal · coffee chat · cafe shift · meetup</sub></td>
<td align="center" width="20%">🌳<br/><b>Johnson Park</b><br/><sub>walk · meet · exercise · public announcement</sub></td>
</tr>
<tr>
<td align="center" width="20%">🛠️<br/><b>Supply Store</b><br/><sub>repair · restock · lend tools · customer service</sub></td>
<td align="center" width="20%">🛒<br/><b>Market</b><br/><sub>buy food · haggle · deliver · chat w/ regulars</sub></td>
<td align="center" width="20%">💊<br/><b>Pharmacy</b><br/><sub>buy medicine · refill · check BP · home visit prep</sub></td>
<td align="center" width="20%">🍻<br/><b>Pub</b><br/><sub>socialize · watch match · host small event</sub></td>
<td align="center" width="20%">🛏️<br/><b>Dorm</b><br/><sub>rest · self-study · common-room hangout · video call</sub></td>
</tr>
</table>
<table>
<tr><td colspan="5" align="center"><b>👥 10 residents, each with a real life</b></td></tr>
<tr>
<td align="center" width="20%">🧭<br/><b>Alice</b> · 34<br/><sub>Neighborhood coordinator</sub></td>
<td align="center" width="20%">🛠️<br/><b>Bob</b> · 45<br/><sub>Supply-store shopkeeper</sub></td>
<td align="center" width="20%">📖<br/><b>Charlie</b> · 39<br/><sub>High-school history teacher</sub></td>
<td align="center" width="20%">💊<br/><b>Dana</b> · 41<br/><sub>Pharmacy nurse</sub></td>
<td align="center" width="20%">☕<br/><b>Elena</b> · 36<br/><sub>Cafe owner</sub></td>
</tr>
<tr>
<td align="center" width="20%">🎒<br/><b>Farah</b> · 16<br/><sub>High-school student</sub></td>
<td align="center" width="20%">📮<br/><b>George</b> · 68<br/><sub>Retired postman</sub></td>
<td align="center" width="20%">💻<br/><b>Hana</b> · 28<br/><sub>Remote software engineer</sub></td>
<td align="center" width="20%">🦺<br/><b>Ivan</b> · 52<br/><sub>Public-safety volunteer</sub></td>
<td align="center" width="20%">🍅<br/><b>Mei</b> · 47<br/><sub>Market vegetable vendor</sub></td>
</tr>
</table>
<sub>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.</sub>
### 🏫 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/`](agentsociety/quick_experiments/hypothesis_pku_trump_visit/experiment_1/README.md) for the full scenario, cast, operator notes, and replay data.
<p align="center">
<img src="docs/assets/screenshots/map-pku.png" alt="PKU campus map" width="94%" />
</p>
<p align="center"><sub>PKU campus map: gates, classrooms, library, Weiming Lake, Boya Pagoda, dining hall, dorm, and Centennial Hall, with named residents and the Trump-visit cast.</sub></p>
## 🗺️ Pluggable Map Packages
GOD now discovers map packages automatically from `agentsociety/custom/maps/<map_id>/`. To add a map, copy [`agentsociety/custom/maps/_template/`](agentsociety/custom/maps/_template/), replace `map.yaml`, `visuals/map.json`, tileset PNGs, and optional `characters/` or `location_assets/`, then run:
```bash
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](docs/MAP_PACKAGES.md) for the full package contract.
## 🤝 Contributing
Issues and pull requests are very welcome. To set up a dev environment:
```bash
./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 →](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](https://github.com/tsinghua-fib-lab/AgentSociety): large-scale generative-agent simulation framework.
- [JiuwenClaw](https://github.com/openJiuwen-ai/jiuwenclaw): out-of-process agent runtime.
And takes inspiration from [Generative Agents](https://arxiv.org/abs/2304.03442) and [OASIS](https://github.com/camel-ai/oasis).
## 📚 Citation
```bibtex
@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
<a href="https://www.star-history.com/?repos=xiaoluolyg%2Fgod&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=xiaoluolyg/god&type=date&theme=dark&legend=top-left" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=xiaoluolyg/god&type=date&legend=top-left" />
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=xiaoluolyg/god&type=date&legend=top-left" />
</picture>
</a>
## 📄 License
Released under the [Apache-2.0](LICENSE) license. Upstream LICENSE and NOTICE files are kept inside the integrated runtime checkouts and apply to those subtrees.
<p align="center"><sub>If GOD is useful to you, a ⭐ helps other people find it.</sub></p>
README.wehub.md
+7
View File
@@ -0,0 +1,7 @@
# WeHub 来源说明
- 原始项目：`XiaoLuoLYG/GOD`
- 原始仓库：https://github.com/XiaoLuoLYG/GOD
- 导入方式：上游默认分支的最新快照
- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准
- 本文件仅用于记录来源，不代表 WeHub 是原项目作者
README.zh-CN.md
+390
View File
@@ -0,0 +1,390 @@
<h1 align="center">
<img src="docs/assets/logo_no_bg.png" alt="GOD logo" height="32" />
&nbsp;GOD · Govern · Observe · Direct
</h1>
<p align="center">
<img src="docs/assets/screenshots/00-hero.png" alt="GOD — Govern · Observe · Direct" width="100%" />
</p>
<p align="center">
<b>🌩️ 像上帝一样，俯瞰一座由 Agent 组成的小镇。</b><br/>
暂停时间。操控环境。对某个灵魂发问。一键重置 —— 全部在一个屏幕里完成。
</p>
<p align="center">
<a href="https://xiaoluolyg.github.io/GOD/replays/god-town/"><b>▶ 浏览器回放</b></a>
&nbsp;·&nbsp; 无需安装、无需 API key &nbsp;·&nbsp;
<a href="#-快速开始"><b>本地运行</b></a>
</p>
<p align="center">
<a href="#-浏览器回放"><b>🌐 浏览器回放</b></a> ·
<a href="#-快速开始"><b>🚀 快速开始</b></a> ·
<a href="#-更新">更新</a> ·
<a href="#%EF%B8%8F-roadmap">Roadmap</a> ·
<a href="#-亮点">亮点</a> ·
<a href="#-核心能力">核心能力</a> ·
<a href="#-内置实验">内置实验</a> ·
<a href="https://xiaoluolyg.github.io/GOD/zh/">公开站</a> ·
<a href="https://xiaoluolyg.github.io/GOD/developer/zh/">开发者文档</a> ·
<a href="CONTRIBUTING.zh-CN.md">参与开发</a> ·
<a href="README.md">🌏 English</a>
</p>
<p align="center">
<a href="https://github.com/XiaoLuoLYG/GOD/releases/tag/v0.2.0">
<img alt="Release" src="https://img.shields.io/github/v/release/XiaoLuoLYG/GOD?style=flat-square" />
</a>
<a href="https://xiaoluolyg.github.io/GOD/replays/god-town/">
<img alt="Live replay" src="https://img.shields.io/badge/demo-浏览器回放-22c55e?style=flat-square" />
</a>
<img alt="Python" src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" />
<img alt="React" src="https://img.shields.io/badge/React-18-61DAFB?style=flat-square&logo=react&logoColor=black" />
<img alt="Vite" src="https://img.shields.io/badge/Vite-6-646CFF?style=flat-square&logo=vite&logoColor=white" />
<img alt="No-Code Setup" src="https://img.shields.io/badge/setup-no--code-22c55e?style=flat-square&logo=googlechrome&logoColor=white" />
<img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square" />
<img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-14b8a6?style=flat-square" />
</p>
---
> 大多数 agent-society demo 只能让你看着仿真自己跑完，GOD 把控制权交回到你手里。
>
> 在同一个屏幕里回放一次运行、向任意居民提问、改变接下来发生的事，再导出一个别人能照着复现的包。
> 它是用来检查 language-agent society 的，不负责声称它们有多接近真实社会。
## 🗓️ 更新
- **2026-06-11 · [v0.2.0](https://github.com/XiaoLuoLYG/GOD/releases/tag/v0.2.0)：** 公开站与浏览器回放；
Experiment / Map / Agent 包 hub 与 ZIP 导入导出；Windows 一键启动；首次启动硬化。([#64](https://github.com/XiaoLuoLYG/GOD/pull/64) [#65](https://github.com/XiaoLuoLYG/GOD/pull/65))
- **2026-06-06 · 公开站与资源包：** 重做公开站与前端；站点资源包改走 release assets；地图包预览页。
([#61](https://github.com/XiaoLuoLYG/GOD/pull/61) [#62](https://github.com/XiaoLuoLYG/GOD/pull/62) [#63](https://github.com/XiaoLuoLYG/GOD/pull/63))
- **2026-06-01 · 可移植包：** 统一 ExperimentPack 下载；GOD 包导入导出；精选实验库。([#57](https://github.com/XiaoLuoLYG/GOD/pull/57) [#59](https://github.com/XiaoLuoLYG/GOD/pull/59) [#60](https://github.com/XiaoLuoLYG/GOD/pull/60))
- **2026-05-30 · Windows 启动器与 hub：** `god.cmd start` 对齐 macOS/Linux 流程；AgentPack hub 与公开 replay 导出；JiuwenClaw 请求并行化。([#45](https://github.com/XiaoLuoLYG/GOD/pull/45) [#49](https://github.com/XiaoLuoLYG/GOD/pull/49) [#50](https://github.com/XiaoLuoLYG/GOD/pull/50))
- **2026-05 · 操作台与 Studio：** 双语控制台、地图优先 `/ask` + `/intervene` rail、
Agent Studio、Map Studio、统一 skill runtime。([#26](https://github.com/XiaoLuoLYG/GOD/pull/26) 到 [#31](https://github.com/XiaoLuoLYG/GOD/pull/31))
- **2026-05-21 · [v0.1.0](https://github.com/XiaoLuoLYG/GOD/releases/tag/v0.1.0)：** 首个打标发布，内置两个实验和 PKU 校园地图。([#21](https://github.com/XiaoLuoLYG/GOD/pull/21) [#24](https://github.com/XiaoLuoLYG/GOD/pull/24))
## ✨ 亮点
<table>
<tr>
<td align="center" width="20%">⏯️<br/><b>暂停时间</b><br/><sub>任意 step replay、暂停、加速、自动推进。</sub></td>
<td align="center" width="20%">💬<br/><b>定向提问</b><br/><sub>在 live session 里向某个居民、群组或全镇发问。</sub></td>
<td align="center" width="20%">🎛️<br/><b>引导下一步</b><br/><sub>注入指令，并检查 Agent 后续响应。</sub></td>
<td align="center" width="20%">🪄<br/><b>零代码上手</b><br/><sub>浏览器配置向导：模型、剧本、Agent 一站搞定。</sub></td>
<td align="center" width="20%">🔄<br/><b>重置运行状态</b><br/><sub>一条命令清掉旧数据，重新生成干净的小镇状态。</sub></td>
</tr>
</table>
## 🖼️ 截图
<p align="center">
<img src="docs/assets/screenshots/01-control-room-zh.png" alt="GOD 控制台" width="94%" />
</p>
<p align="center"><sub>实时控制台：PKU 地图、step 控制、定向提问、居民列表全在一个界面里。</sub></p>
## 🌐 浏览器回放
打开 [**公开站**](https://xiaoluolyg.github.io/GOD/zh/) 在浏览器里逛一圈：精选回放、地图包、Agent 包和可下载实验。无需安装，也不用 API key。
<p align="center">
<a href="https://xiaoluolyg.github.io/GOD/zh/">
<img src="docs/assets/screenshots/03-public-site-zh.png" alt="GOD 公开站" height="190" />
</a>
&nbsp;
<a href="https://xiaoluolyg.github.io/GOD/map-packs/">
<img src="docs/assets/screenshots/04-map-packs-zh.png" alt="GOD 地图包" height="190" />
</a>
&nbsp;
<a href="https://xiaoluolyg.github.io/GOD/agent-packs/">
<img src="docs/assets/screenshots/05-agent-packs-zh.png" alt="GOD Agent 包" height="190" />
</a>
</p>
<p align="center"><sub>从左到右：公开站首页、可下载地图包、可下载 Agent 包。</sub></p>
## 🚀 快速开始
```bash
git clone https://github.com/XiaoLuoLYG/GOD.git
cd GOD
./scripts/god.sh start
```
Windows PowerShell：进入仓库根目录后运行 `.\scripts\god.cmd start`。
首次启动会自动装好依赖，打开 **浏览器中的实验配置向导**，然后等你填完。你不用手改 `.env`，也不用记命令行参数。
<p align="center">
<img src="docs/assets/screenshots/02-setup-wizard-zh.png" alt="GOD 实验配置向导" width="100%" />
</p>
<p align="center"><sub>实验配置向导：模型配置、默认实验选择、自建实验发布都在同一个浏览器流程里。</sub></p>
<table>
<tr>
<td align="center" width="16%">🔌<br/><b>1. 模型</b><br/><sub>填入 OpenAI 兼容的 API key、base URL 和模型名。</sub></td>
<td align="center" width="16%">🧭<br/><b>2. 选择</b><br/><sub>打开 GOD Town、打开 PKU Trump Visit，或新建实验。</sub></td>
<td align="center" width="16%">🧪<br/><b>3. 剧本</b><br/><sub>用自然语言描述世界：日期、天气、氛围、规则。</sub></td>
<td align="center" width="16%">🤖<br/><b>4. 生成</b><br/><sub>GOD agent 自动起草 agent profile 和 step 计划。</sub></td>
<td align="center" width="16%">✏️<br/><b>5. 编辑</b><br/><sub>调整人物性格、关系、地点、步骤。</sub></td>
<td align="center" width="16%">▶️<br/><b>6. 启动</b><br/><sub>发布为当前实验，直接进入控制台。</sub></td>
</tr>
</table>
任意 OpenAI 兼容接口都可以。向导收尾后，脚本会打印类似这样的地址：
```text
http://127.0.0.1:5174/pixel-replay/god_town/1
```
完整步骤见 **[快速开始 →](QUICKSTART.zh-CN.md)**
## 🧩 核心能力
| | 能力 | 你得到什么 |
| --- | --- | --- |
| 🎬 | **Replay 控制** | 按 step 拖动、暂停、跳转、自动推进，live 或已记录 replay 都行。 |
| 💬 | **定向提问** | 用自然语言向某个 Agent、某组人或全镇提问。 |
| 🎛️ | **实时干预** | 给即将执行的 step 注入指令，Agent 下一回合就读得到。 |
| ⌨️ | **命令输入器** | 在地图上直接输入 `/ask` 或 `/intervene`，用 `@Name #id` 自动补全目标。 |
| 🪄 | **零代码配置向导** | 浏览器里配置模型 + 剧本，让 GOD 生成 Agent 和 step，编辑后启动。 |
| 🧬 | **Agent Studio** | 用地图感知的向导新增 / 编辑居民：seed、身份、外貌、性格、日程、review 一步步完成。 |
| 🧭 | **地图工作台** | 生成或上传地图草稿，校准地点与碰撞层，校验后发布为本地地图包。 |
| 🧼 | **一键重开** | 一条命令清掉 replay 数据，孵化一座干净的小镇。 |
| 🗺️ | **像素小镇世界** | 地点、动作、消息、状态都是结构化、replay 友好的。 |
| 🧱 | **唯一当前实验** | `.env` 只保存模型、API、端口等本机配置；`.god/current_experiment.json` 保存唯一 active 实验。 |
| 🌐 | **浏览器回放** | GitHub Pages 上的精选回放，无需本地安装或 API key。 |
| 📦 | **资源包库** | Experiment / Map / Agent 包导入导出；公开站还有更多可下载场景。 |
| 🪟 | **Windows 启动器** | PowerShell 下 `god.cmd start`，与 macOS/Linux 同样一条命令。 |
## 🛣️ Roadmap
### ✅ 已完成
- [x] 🗺️ **可拔插地图包**：把一个文件夹丢到 `agentsociety/custom/maps/<map_id>/`，刷新向导即出现新世界。自动发现、自动校验、热插拔。详见 [`docs/MAP_PACKAGES.zh-CN.md`](docs/MAP_PACKAGES.zh-CN.md)。
- [x] 🏫 **PKU 校园地图**：PKU 地图包已经作为一等地图随仓库发布，和 The Ville 一起可选。
- [x] 🪄 **零代码配置向导**：浏览器流程，模型配置、内置实验选择、自建实验生成 / 编辑 / 发布，一台空机器到真实的小镇。
- [x] 🧪 **可复现实验**：实验以普通文件夹形式发布，位于 `quick_experiments/<hypothesis>/<experiment>/`。选择或发布一个实验后，它就会成为 current。
- [x] 🎮 **控制台命令 rail**：replay 控制、居民列表、Live Console、定向 Ask 和 Intervene 都合并在一个地图优先的操作界面里。
- [x] 🧬 **Agent Studio v1**：地图感知的新增 / 编辑 Agent 流程，包含结构化 profile metadata、ID 校验、Setup 集成和 sprite 生成支持。
- [x] 🧭 **Map Studio v1**：prompt / 参考图生成地图草稿，锚点与碰撞层校准，地图包校验、发布，以及返回 Setup 的 handoff。
- [x] 🌏 **双语运行时 UI**：setup、replay、地图、状态、动作和系统事件中的产品侧文本支持 English / 中文。
- [x] 🔌 **Agent skill-runtime 路径**：随仓库发布的 JiuwenClaw adapter 现在以 AgentSociety skill runtime 作为标准执行路径。
- [x] 🌐 **公开站与浏览器回放**：GitHub Pages 托管精选回放、地图包、Agent 包和可下载实验，无需本地安装或 API key。
- [x] 📦 **可移植包与导入导出**：Experiment / Map / Agent 包支持 ZIP 导入导出，通过 release assets 分发。
- [x] 🪟 **Windows 一键启动**：`god.cmd start`，与 macOS/Linux 一样一条命令。
### 🛣️ 未完成 / 进行中
- [ ] 🤖 **可拔插 Agent 运行时**：让 LLM runtime 和 persona 模板能像地图一样干净地替换。
- [ ] 🧪 **多实验编排**：在同一个控制台里跑实验、对照组、重复试验和 ablation。
- [ ] 🗺️ **实时地图生成**：地图随事件、修缮、阻塞、人群动态演化。
- [ ] 🌦️ **事件响应世界**：天气、事故、节日、谣言、供应短缺影响 Agent 行为。
- [ ] 🌐 **大规模仿真**：接入 AgentSociety 的批量 Agent、分片运行、采样 replay 和性能友好的 replay 摘要。
- [ ] 📊 **实验评估**：跨实验指标、行为差异、干预效果分析和可分享报告。
- [ ] 📝 **操作员工作流**：每个 step 的笔记、标签、书签、保存命令宏和关键事件摘要。
- [ ] 🌍 **托管 live 控制台**：一个可以真正操控运行（而不只是看回放）的托管 demo，外加社区场景模板。
有想法？欢迎来 [issue 和 PR](#-参与开发) 聊。
## 🏗️ 架构
```mermaid
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 是 local-first：控制台、后端、runtime bridge、实验文件和 replay store 都运行在本机。唯一外部服务是你选择的模型接口。
GOD 把三个概念分开：
- **Experiment** 是可玩的实验设定：地图、智能体、场景上下文和 step 计划。
- **Replay** 是实验被运行之后可以观看的结果。
- **本地运行状态** 是 SQLite replay store、日志、agent snapshot 等机器数据；它不属于 ExperimentPack，也不应该提交到仓库。
| 层 | 职责 |
| --- | --- |
| 🎮 **Control Room** | React/Vite 控制台，replay、ask、intervention、status 都在这里。 |
| ⚙️ **Backend** | 本地 FastAPI，提供 live 和 replay API。 |
| 🗺️ **Pixel Town** | 像素小镇社会状态：地点、动作、消息、Agent 状态。 |
| 🤖 **Agent Runtime** | 独立进程的 LLM Agent，通过本地 WebSocket 连接。 |
## ⚙️ 常用命令
```bash
./scripts/god.sh start # 启动完整栈（可重复执行）
./scripts/god.sh configure # 打开配置向导，切换默认实验或新建实验
./scripts/god.sh restart # 先干净停止，再重新启动
./scripts/god.sh new-run # 清空当前实验的本地运行状态，并开一个新的 session
./scripts/god.sh status # 查看端口、URL、模型状态
./scripts/god.sh stop # 停止所有服务
./scripts/god.sh tail # 跟随日志
./scripts/god.sh open # 在浏览器里打开前端页面
```
Windows 下把 `./scripts/god.sh` 替换成 `.\scripts\god.cmd` 即可。
## 🧪 内置实验
GOD 现在内置两个默认实验，并且和你自己发布的实验使用同一套 current model。配置向导会把你选择的实验写到 `.god/current_experiment.json`；之后 `start`、`open`、`new-run` 都只作用于这个当前实验。
[**公开站**](https://xiaoluolyg.github.io/GOD/zh/experiments/) 上还有更多可下载场景，比如空城计、高考停电、霍格沃茨家长会。
`.env` 只保存本机模型、API、端口等配置，不再决定默认实验或地图。因此即使旧 `.env` 里残留 `GOD_MAP_ID=pku`，选择 GOD Town 时仍然会使用 `the_ville` 地图，不会串台。
### 🏘️ The Ville 的一个普通工作日
晚春的工作日清晨 8:20，晴朗微风，气温 18°C。一座 200 多人的小镇，**10 位常住居民彼此熟识但各过各的生活**。它是一段日常生活切片，不是任务驱动的剧本。
➡️ **在配置向导选择 `god_town` 即可把它设为当前实验。** 它固定绑定 `hypothesis_god_town/experiment_1` 和 `the_ville` 地图。
➡️ 完整的地点 / 居民 / 交互拆解见 [`hypothesis_god_town/experiment_1/`](agentsociety/quick_experiments/hypothesis_god_town/experiment_1/README.md)。
<p align="center">
<img src="docs/assets/screenshots/map-the-ville.png" alt="The Ville 地图" width="94%" />
</p>
<p align="center"><sub>The Ville 地图：10 位居民在家、学校、图书馆、咖啡馆、公园、市场、药房、酒馆、宿舍之间度过普通一天。</sub></p>
<table>
<tr><td colspan="5" align="center"><b>🗺️ 10 个地点 · 65 个 location-scoped 交互</b></td></tr>
<tr>
<td align="center" width="20%">🏠<br/><b>家</b><br/><sub>做饭 · 睡觉 · 整理 · 阅读 · 居家办公 · 视频家人</sub></td>
<td align="center" width="20%">🏫<br/><b>学校</b><br/><sub>上课 / 教书 · 批改 · 课后答疑</sub></td>
<td align="center" width="20%">📚<br/><b>图书馆</b><br/><sub>阅读 · 学习 · 查资料 · 借还书</sub></td>
<td align="center" width="20%">☕<br/><b>Hobbs Cafe</b><br/><sub>简餐 · 咖啡聊天 · 值班 · 随性碰头</sub></td>
<td align="center" width="20%">🌳<br/><b>Johnson Park</b><br/><sub>散步 · 见友 · 晨练 · 公共播报</sub></td>
</tr>
<tr>
<td align="center" width="20%">🛠️<br/><b>供给店</b><br/><sub>修理 · 上货 · 借工具 · 顾客接待</sub></td>
<td align="center" width="20%">🛒<br/><b>市场</b><br/><sub>买食物 · 议价 · 送单 · 和老客闲聊</sub></td>
<td align="center" width="20%">💊<br/><b>药房</b><br/><sub>买药 · 续方 · 量血压 · 上门准备</sub></td>
<td align="center" width="20%">🍻<br/><b>酒馆</b><br/><sub>社交 · 看比赛 · 主持小活动</sub></td>
<td align="center" width="20%">🛏️<br/><b>宿舍</b><br/><sub>休息 · 自习 · 公共区休闲 · 视频家里</sub></td>
</tr>
</table>
<table>
<tr><td colspan="5" align="center"><b>👥 10 位居民，每个人都有真实生活</b></td></tr>
<tr>
<td align="center" width="20%">🧭<br/><b>Alice</b> · 34<br/><sub>社区协调员</sub></td>
<td align="center" width="20%">🛠️<br/><b>Bob</b> · 45<br/><sub>市场五金店主</sub></td>
<td align="center" width="20%">📖<br/><b>Charlie</b> · 39<br/><sub>中学历史老师</sub></td>
<td align="center" width="20%">💊<br/><b>Dana</b> · 41<br/><sub>社区药房护理员</sub></td>
<td align="center" width="20%">☕<br/><b>Elena</b> · 36<br/><sub>咖啡馆老板</sub></td>
</tr>
<tr>
<td align="center" width="20%">🎒<br/><b>Farah</b> · 16<br/><sub>高中学生</sub></td>
<td align="center" width="20%">📮<br/><b>George</b> · 68<br/><sub>退休邮递员</sub></td>
<td align="center" width="20%">💻<br/><b>Hana</b> · 28<br/><sub>远程软件工程师</sub></td>
<td align="center" width="20%">🦺<br/><b>Ivan</b> · 52<br/><sub>社区安全志愿者</sub></td>
<td align="center" width="20%">🍅<br/><b>Mei</b> · 47<br/><sub>市场蔬果摊主</sub></td>
</tr>
</table>
<sub>每位居民都有完整 profile：年龄、家庭、住房、经济状况、健康、日常作息、技能、需求、担忧、秘密、社交圈、语言风格、小怪癖、短期/长期目标。</sub>
### 🏫 PKU Trump Visit
这是一个发生在风格化北大校园地图上的公共事件实验。Agent 会先在校门、教学楼、图书馆、未名湖、食堂、宿舍、百周年纪念讲堂等地点开始日常行动，然后在一次高关注访问事件中表现出注意、询问、聚集和讨论。
➡️ **在配置向导选择 `pku_trump_visit` 即可把它设为当前实验。** 它固定绑定 `hypothesis_pku_trump_visit/experiment_1` 和 `pku` 地图。
➡️ 完整场景、角色、操作脚本和 replay 数据见 [`hypothesis_pku_trump_visit/experiment_1/`](agentsociety/quick_experiments/hypothesis_pku_trump_visit/experiment_1/README.md)。
<p align="center">
<img src="docs/assets/screenshots/map-pku.png" alt="PKU 校园地图" width="94%" />
</p>
<p align="center"><sub>PKU 校园地图：校门、教学楼、图书馆、未名湖、博雅塔、食堂、宿舍、百周年纪念讲堂，以及 PKU Trump Visit 的角色阵容。</sub></p>
## 🗺️ 可拔插地图包
GOD 会自动从 `agentsociety/custom/maps/<map_id>/` 发现地图包。想加一张新地图？复制 [`agentsociety/custom/maps/_template/`](agentsociety/custom/maps/_template/README.zh-CN.md)，替换 `map.yaml`、`visuals/map.json`、tileset PNG，以及可选的 `characters/` 和 `location_assets/`，然后跑：
```bash
cd agentsociety
uv run python scripts/validate_map_package.py custom/maps/<map_id>
```
配置向导会自动列出所有合法的地图包，完全不用改代码。v1 支持带 PNG tileset 的 Tiled JSON 地图，并要求一个 `Collisions` 层（`0` 表示可走）。PKU 校园地图包现在已经随仓库发布，路径是 `agentsociety/custom/maps/pku/`。完整契约见 [docs/MAP_PACKAGES.zh-CN.md](docs/MAP_PACKAGES.zh-CN.md)。
## 🤝 参与开发
```bash
./scripts/god.sh start
```
会自动装好 Python、Node 依赖，启动完整栈，创建 live session，并先跑完第 1 步，让控制台打开时就是已初始化的小镇。改完代码刷新即可。
完整指南见 **[CONTRIBUTING.zh-CN.md →](CONTRIBUTING.zh-CN.md)**：分支策略、PR 检查表、代码风格，以及怎么提交一张新地图或新实验。
## 🙌 致谢
GOD 构建在开源研究和开源代码之上。仓库内集成了两份精简过的上游代码：
- [AgentSociety](https://github.com/tsinghua-fib-lab/AgentSociety)：大规模 generative-agent 模拟框架。
- [JiuwenClaw](https://github.com/openJiuwen-ai/jiuwenclaw)：进程外 Agent runtime。
同时受 [Generative Agents](https://arxiv.org/abs/2304.03442) 与 [OASIS](https://github.com/camel-ai/oasis) 启发。
## 📚 引用
```bibtex
@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
<a href="https://www.star-history.com/?repos=xiaoluolyg%2Fgod&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=xiaoluolyg/god&type=date&theme=dark&legend=top-left" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=xiaoluolyg/god&type=date&legend=top-left" />
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=xiaoluolyg/god&type=date&legend=top-left" />
</picture>
</a>
## 📄 License
[Apache-2.0](LICENSE)。集成的上游代码各自保留了它们的 LICENSE / NOTICE，对应子树仍受其约束。
<p align="center"><sub>如果 GOD 对你有用，点个 ⭐ 能帮更多人找到它。</sub></p>
SECURITY.md
+31
View File
@@ -0,0 +1,31 @@
# Security Policy
GOD is an open-source research and product prototype for running, observing, and steering agent societies. Because local experiments can involve model API keys, generated profiles, logs, replay databases, and user-authored scenario data, please report security concerns privately.
## Supported Versions
Security fixes are handled on the default branch, `main`. Older local clones, experiment snapshots, and unpublished branches are not separately supported.
## Reporting a Vulnerability
Please do not open a public issue for suspected vulnerabilities. Use GitHub's private vulnerability reporting flow instead:
https://github.com/XiaoLuoLYG/GOD/security/advisories/new
Include as much of the following as you can:
- The affected commit, branch, or release.
- A clear description of the vulnerability and the impacted component.
- Minimal reproduction steps or a proof of concept.
- Whether any secrets, private data, logs, replay databases, or model-provider credentials may be exposed.
- Any suggested mitigation, if you already have one.
## Handling Expectations
The maintainers will review incoming reports, ask for clarification when needed, and coordinate a fix or mitigation before public disclosure when the issue is confirmed. Please avoid destructive testing, accessing data that is not yours, or sharing exploit details publicly before the maintainers have had a chance to respond.
## Secrets and Local Data
If you accidentally commit or publish an API key, token, credential, private dataset, or local runtime artifact, revoke or rotate the credential first. Then open a private report if the exposure affects this repository or its users.
Runtime outputs such as `.god/`, `.live/`, generated experiment folders, replay databases, logs, and local `.env` files should stay out of normal pull requests unless they are intentionally sanitized sample assets.
agentsociety/.env.example
+67
View File
@@ -0,0 +1,67 @@
# ============================================================
# LLM 配置（必需）
# ============================================================
# 默认大语言模型配置，作为所有其他 LLM 配置的回退选项
AGENTSOCIETY_LLM_API_KEY=your_api_key
AGENTSOCIETY_LLM_API_BASE=https://api.openai.com/v1
AGENTSOCIETY_LLM_MODEL=gpt-5.4
# ============================================================
# Coder LLM 配置（可选）
# ============================================================
# 用于代码生成的专用模型，如未设置则回退到默认 LLM 配置
AGENTSOCIETY_CODER_LLM_API_KEY=your_coder_api_key
AGENTSOCIETY_CODER_LLM_API_BASE=https://api.openai.com/v1
AGENTSOCIETY_CODER_LLM_MODEL=gpt-5.4
# ============================================================
# Nano LLM 配置（可选）
# ============================================================
# 用于高频操作的轻量级模型，如未设置则回退到默认 LLM 配置
AGENTSOCIETY_NANO_LLM_API_KEY=your_nano_api_key
AGENTSOCIETY_NANO_LLM_API_BASE=https://api.openai.com/v1
AGENTSOCIETY_NANO_LLM_MODEL=gpt-5.4-nano
# ============================================================
# Analysis LLM 配置（可选）
# ============================================================
# 用于数据分析、洞察生成和报告撰写，建议使用推理能力强的模型
AGENTSOCIETY_ANALYSIS_LLM_API_KEY=your_analysis_api_key
AGENTSOCIETY_ANALYSIS_LLM_API_BASE=https://api.openai.com/v1
AGENTSOCIETY_ANALYSIS_LLM_MODEL=gpt-5.4
# ============================================================
# Embedding 模型配置（可选）
# ============================================================
# 文本嵌入模型，用于向量化文本，如未设置则回退到默认 LLM 配置
AGENTSOCIETY_EMBEDDING_API_KEY=your_embedding_api_key
AGENTSOCIETY_EMBEDDING_API_BASE=https://api.openai.com/v1
AGENTSOCIETY_EMBEDDING_MODEL=text-embedding-3-large
AGENTSOCIETY_EMBEDDING_DIMS=1024
# ============================================================
# 后端服务配置
# ============================================================
BACKEND_HOST=0.0.0.0
BACKEND_PORT=8001
# ============================================================
# 工作区路径
# ============================================================
# 自定义模块的工作区根目录（custom/ 文件夹所在位置）
WORKSPACE_PATH=/path/to/workspace
# ============================================================
# 外部 API 配置
# ============================================================
# 学术文献检索服务
LITERATURE_SEARCH_API_URL=http://localhost:8008/api/search
LITERATURE_SEARCH_API_KEY=lit-your-api-key-here
# 网络搜索服务（用于 miro_web_research 工具）
WEB_SEARCH_API_URL=http://localhost:8003/mcp
WEB_SEARCH_API_TOKEN=your_web_search_api_bearer_token
# 论文生成服务（部署自 https://github.com/tsinghua-fib-lab/EasyPaper）
EASYPAPER_API_URL=http://localhost:8004
agentsociety/LICENSE
+201
View File
@@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [2025] [FIB LAB, Tsinghua University]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
agentsociety/custom/agents/jiuwenclaw_agent.py
+1885
View File
File diff suppressed because it is too large Load Diff
agentsociety/custom/agents/scripted_pixel_town_agent.py
+154
View File
@@ -0,0 +1,154 @@
"""Deterministic pixel-town agent for replayable multi-step demos."""
from __future__ import annotations
from datetime import datetime
import re
from typing import Any
from agentsociety2.agent.base import AgentBase
class ScriptedPixelTownAgent(AgentBase):
"""Agent that executes a configured step script against PixelTownSocialEnv."""
def __init__(
self,
id: int,
profile: Any,
name: str | None = None,
script: list[dict[str, Any]] | None = None,
) -> None:
super().__init__(id=id, profile=profile, name=name)
self._script = script or []
self._step_index = 0
self._last_result: dict[str, Any] = {}
self._queued_interventions: list[dict[str, Any]] = []
@classmethod
def mcp_description(cls) -> str:
return """ScriptedPixelTownAgent: deterministic replay demo agent.
Provide a `script` list. Each entry can set location/action/status/emotion,
phase, direct_messages, and group_messages. It is useful for fast multi-step
frontend replay validation without spending LLM calls.
"""
async def ask(self, message: str, readonly: bool = True) -> str:
if any(keyword in message for keyword in ("今天", "干了什么", "做了什么", "what did")):
completed = self._script[: min(self._step_index, len(self._script))]
if completed:
summaries = []
for index, action in enumerate(completed, start=1):
phase = action.get("phase") or "阶段"
location = action.get("location") or "未知地点"
activity = action.get("action") or action.get("status") or "等待"
summaries.append(f"{index}. {phase}：在{location}{activity}")
return (
f"{self.name} 今天已经执行到第 {self._step_index} 步。"
"主要做了：\n" + "\n".join(summaries)
)
return f"{self.name} 今天还没有执行新的行动。"
if any(keyword in message for keyword in ("听到", "收到", "实时提问", "身份回答")):
role = self.get_profile().get("role", "居民")
return (
f"我是 {self.name}，身份是{role}。我收到了你的实时提问。"
f"当前我执行到第 {self._step_index} 步，最近状态是：{self._last_result or '暂无'}。"
)
return (
f"{self.name} is a scripted pixel-town agent. "
f"Current script step: {self._step_index}. Last result: {self._last_result}"
)
async def step(self, tick: int, t: datetime) -> str:
if self._queued_interventions:
action = self._queued_interventions.pop(0)
else:
action = (
self._script[self._step_index]
if self._step_index < len(self._script)
else {}
)
env = self._find_pixel_env()
if env is None:
result = {"error": "PixelTownSocialEnv not found"}
else:
result = await env.apply_scripted_action(self.id, action)
self._last_result = result
self._step_index += 1
return str(result)
def queue_intervention(self, instruction: str) -> str:
action = self._build_intervention_action(instruction)
self._queued_interventions.append(action)
return "已排队到下一次 step"
def _build_intervention_action(self, instruction: str) -> dict[str, Any]:
clean_instruction = " ".join(str(instruction).split())
location = self._match_first(
clean_instruction,
[
r"(?:前往|移动到|去到|去|到)([^，。,；;、]+)",
r"(?:location|地点|位置)[:：= ]+([^，。,；;]+)",
],
)
status = self._match_first(
clean_instruction,
[
r"(?:状态设为|状态设置为|将状态设为|status[:：= ]+)([^，。,；;]+)",
r"(?:设为|设置为)([^，。,；;]+)",
],
)
return {
"phase": "实时干预",
"location": location,
"action": f"执行实时干预：{clean_instruction}",
"status": status or "intervened",
"emotion": "focused",
"event": f"{self.name} 接收到实时干预：{clean_instruction}",
}
@staticmethod
def _match_first(text: str, patterns: list[str]) -> str | None:
for pattern in patterns:
match = re.search(pattern, text, flags=re.IGNORECASE)
if match:
value = match.group(1).strip()
return value or None
return None
async def dump(self) -> dict[str, Any]:
return {
"id": self.id,
"name": self.name,
"profile": self.get_profile(),
"script": self._script,
"step_index": self._step_index,
"last_result": self._last_result,
"queued_interventions": self._queued_interventions,
}
async def load(self, dump_data: dict[str, Any]) -> None:
self._id = int(dump_data.get("id", self._id))
self._name = str(dump_data.get("name", self._name))
self._profile = dump_data.get("profile", self._profile)
script = dump_data.get("script")
if isinstance(script, list):
self._script = script
self._step_index = int(dump_data.get("step_index", self._step_index))
last_result = dump_data.get("last_result")
if isinstance(last_result, dict):
self._last_result = last_result
queued_interventions = dump_data.get("queued_interventions")
if isinstance(queued_interventions, list):
self._queued_interventions = [
item for item in queued_interventions if isinstance(item, dict)
]
def _find_pixel_env(self) -> Any:
if self._env is None:
return None
for module in getattr(self._env, "env_modules", []):
if hasattr(module, "apply_scripted_action"):
return module
return None
agentsociety/custom/envs/pixel_town_social_env.py
+1450
View File
File diff suppressed because it is too large Load Diff
agentsociety/custom/maps/_template/ATTRIBUTION.md
+4
View File
@@ -0,0 +1,4 @@
# Attribution
List all map, tileset, character sprite, and icon sources here. Include license
names and source URLs before publishing a map package.
agentsociety/custom/maps/_template/README.md
+37
View File
@@ -0,0 +1,37 @@
<h1 align="center">📐 GOD Map Package Template</h1>
<p align="center">
<b>Minimal starter — copy, rename, drop in your assets.</b>
</p>
<p align="center">
<a href="README.zh-CN.md">🌏 中文</a> ·
<a href="../../../../docs/MAP_PACKAGES.md">📘 Map Packages Guide</a>
</p>
---
Copy this directory to `agentsociety/custom/maps/<your_map_id>/`, rename it, and
replace `map.yaml`, `visuals/map.json`, and the assets.
The v1 contract expects a Tiled JSON map with a tile layer named **`Collisions`**.
In that layer, `0` means walkable and any non-zero tile means blocked.
## 🚀 Three-step Start
```bash
# 1. Copy this template
cp -r agentsociety/custom/maps/_template agentsociety/custom/maps/my_town
# 2. Edit map.yaml, drop in your Tiled JSON and tilesets
# 3. Validate
cd agentsociety
uv run python scripts/validate_map_package.py custom/maps/my_town
```
When validation passes, restart GOD and the new map appears in the setup wizard.
See [`docs/MAP_PACKAGES.md`](../../../../docs/MAP_PACKAGES.md) for the full
package contract and [`the_ville/`](../the_ville/README.md) for a complete
working example.
agentsociety/custom/maps/_template/README.zh-CN.md
+36
View File
@@ -0,0 +1,36 @@
<h1 align="center">📐 GOD 地图包模板</h1>
<p align="center">
<b>最小起步模板 —— 复制、改名、放入你的素材即可。</b>
</p>
<p align="center">
<a href="README.md">🌏 English</a> ·
<a href="../../../../docs/MAP_PACKAGES.zh-CN.md">📘 地图包指南</a>
</p>
---
把这个目录复制到 `agentsociety/custom/maps/<your_map_id>/`、改名，然后替换
`map.yaml`、`visuals/map.json` 与素材。
v1 约定要求一份 Tiled JSON 地图，并带一个名为 **`Collisions`** 的瓦片层。
在该层中，`0` 表示可走，任何非零图块表示阻挡。
## 🚀 三步上手
```bash
# 1. 复制模板
cp -r agentsociety/custom/maps/_template agentsociety/custom/maps/my_town
# 2. 编辑 map.yaml，放入你的 Tiled JSON 和图块
# 3. 校验
cd agentsociety
uv run python scripts/validate_map_package.py custom/maps/my_town
```
校验通过后，重启 GOD，新地图就会出现在配置向导里。
完整包契约见 [`docs/MAP_PACKAGES.zh-CN.md`](../../../../docs/MAP_PACKAGES.zh-CN.md)，
完整可运行的范例见 [`the_ville/`](../the_ville/README.zh-CN.md)。
agentsociety/custom/maps/_template/characters/.gitkeep
+1
View File
@@ -0,0 +1 @@
agentsociety/custom/maps/_template/location_assets/.gitkeep
+1
View File
@@ -0,0 +1 @@
agentsociety/custom/maps/_template/map.yaml
+38
View File
@@ -0,0 +1,38 @@
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
default_location_order:
- plaza
spawn_points:
- id: resident_start
location_id: plaza
locations:
- id: plaza
name: Plaza
aliases:
- plaza
anchor_tile:
x: 1
y: 1
scene_type: public
bounds:
x: 0
y: 0
w: 4
h: 4
interaction_ids:
- wait
interactions:
- id: wait
name: 等待
description: 在广场短暂停留。
allowed_location_ids:
- plaza
effects:
action: "{agent_name} 在广场等待"
status: 休息中
emotion: 平静
latest_event: "{agent_name} 在广场短暂停留。"
agentsociety/custom/maps/_template/visuals/map.json
+39
View File
@@ -0,0 +1,39 @@
{
"type": "map",
"version": "1.10",
"tiledversion": "1.10.2",
"orientation": "orthogonal",
"renderorder": "right-down",
"width": 4,
"height": 4,
"tilewidth": 32,
"tileheight": 32,
"infinite": false,
"tilesets": [],
"layers": [
{
"id": 1,
"name": "Ground",
"type": "tilelayer",
"visible": true,
"opacity": 1,
"x": 0,
"y": 0,
"width": 4,
"height": 4,
"data": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"id": 2,
"name": "Collisions",
"type": "tilelayer",
"visible": true,
"opacity": 1,
"x": 0,
"y": 0,
"width": 4,
"height": 4,
"data": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
}
]
}
agentsociety/custom/maps/pku/ATTRIBUTION.md
+10
View File
@@ -0,0 +1,10 @@
# Attribution
This PKU map package uses generated package-local campus artwork. The replay-ready PKU tileset family lives in `visuals/map_assets/` and mirrors The Ville's exterior, interior, room-builder, and block sheet structure. The character sprites in `characters/` are generated 32px spritesheets compatible with PixelReplay.
The semantic layout references public Peking University campus knowledge and official visitor-facing pages for landmark names and relative campus semantics, including the Peking University visitor map and public descriptions of Yanyuan landmarks such as Weiming Lake and Boya Pagoda. The package does not embed official map imagery, photos, logos, or scanned campus-map artwork.
Useful public references:
- Peking University visitor map: https://english.pku.edu.cn/map.html
- Peking University official site: https://english.pku.edu.cn/
agentsociety/custom/maps/pku/README.md
+25
View File
@@ -0,0 +1,25 @@
# Peking University Yanyuan Map Package
This package is a self-contained GOD v1 map package for a stylized Peking University Yanyuan campus. The visual layer is built from package-local imagegen assets and keeps the same Tiled/tileset shape as `custom/maps/the_ville`: exterior tilesets, room builder, five interior sheets, block sheets, and 32px character spritesheets.
It is not a surveyed GIS map. The layout preserves simulation-friendly PKU semantics: West Gate, East Gate, South Gate, Weiming Lake, Boya Pagoda, PKU Library, Centennial Hall, teaching buildings, dormitory, canteen, gym, lab, offices, and a campus green.
## Files
- `map.yaml` - semantic manifest with spawn points, locations, aliases, interactions, and asset paths.
- `visuals/map.json` - orthogonal Tiled JSON, 140x100 tiles, 32px tile size.
- `visuals/map_assets/cute_rpg_word_VXAce/tilesets/*.png` - generated PKU exterior tilesets matching The Ville's tileset names and dimensions.
- `visuals/map_assets/v1/Room_Builder_32x32.png` and `visuals/map_assets/v1/interiors_pt*.png` - generated PKU interior/room tilesets.
- `visuals/map_assets/blocks/*.png` - generated interaction/collision block tilesets.
- `visuals/map_assets/pku_generated/pku_full_map_tileset.png` - high-detail PKU campus render sliced into a 32px Tiled tileset for the assembled replay map.
- `characters/*.png` - generated 32px PKU character spritesheets.
## Validation
```bash
uv run python scripts/validate_map_package.py custom/maps/pku
```
## Notes
Location anchors are placed on walkable paths adjacent to landmark footprints so agents can route to them. Replay marker overlays are intentionally not used, matching The Ville's visual presentation.
agentsociety/custom/maps/pku/characters/PKU_Agent_01.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.3 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_02.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.4 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_03.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.3 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_04.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.3 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_05.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.4 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_06.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.3 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_07.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.5 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_08.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.3 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_09.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.7 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_10.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.0 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_11.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.2 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_12.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.4 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_13.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.1 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_14.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.6 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_15.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.9 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_16.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.2 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_17.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.2 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_18.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.4 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_19_Donald_Trump.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.1 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_20_Elon_Musk.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.1 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_21_Jensen_Huang.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.0 KiB

agentsociety/custom/maps/pku/characters/PKU_Agent_22_Coordinator.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.7 KiB

agentsociety/custom/maps/pku/characters/atlas.json
+278
View File
@@ -0,0 +1,278 @@
{
"frames": [
{
"filename": "down-walk.000",
"frame": {
"w": 32,
"h": 32,
"x": 0,
"y": 0
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "down-walk.001",
"frame": {
"w": 32,
"h": 32,
"x": 32,
"y": 0
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "down-walk.002",
"frame": {
"w": 32,
"h": 32,
"x": 64,
"y": 0
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "down-walk.003",
"frame": {
"w": 32,
"h": 32,
"x": 32,
"y": 0
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "down",
"frame": {
"w": 32,
"h": 32,
"x": 32,
"y": 0
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "left-walk.000",
"frame": {
"w": 32,
"h": 32,
"x": 0,
"y": 32
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "left-walk.001",
"frame": {
"w": 32,
"h": 32,
"x": 32,
"y": 32
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "left-walk.002",
"frame": {
"w": 32,
"h": 32,
"x": 64,
"y": 32
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "left-walk.003",
"frame": {
"w": 32,
"h": 32,
"x": 32,
"y": 32
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "left",
"frame": {
"w": 32,
"h": 32,
"x": 32,
"y": 32
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "right-walk.000",
"frame": {
"w": 32,
"h": 32,
"x": 0,
"y": 64
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "right-walk.001",
"frame": {
"w": 32,
"h": 32,
"x": 32,
"y": 64
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "right-walk.002",
"frame": {
"w": 32,
"h": 32,
"x": 64,
"y": 64
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "right-walk.003",
"frame": {
"w": 32,
"h": 32,
"x": 32,
"y": 64
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "right",
"frame": {
"w": 32,
"h": 32,
"x": 32,
"y": 64
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "up-walk.000",
"frame": {
"w": 32,
"h": 32,
"x": 0,
"y": 96
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "up-walk.001",
"frame": {
"w": 32,
"h": 32,
"x": 32,
"y": 96
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "up-walk.002",
"frame": {
"w": 32,
"h": 32,
"x": 64,
"y": 96
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "up-walk.003",
"frame": {
"w": 32,
"h": 32,
"x": 32,
"y": 96
},
"anchor": {
"x": 0.5,
"y": 0.5
}
},
{
"filename": "up",
"frame": {
"w": 32,
"h": 32,
"x": 32,
"y": 96
},
"anchor": {
"x": 0.5,
"y": 0.5
}
}
],
"meta": {
"description": "Atlas generado con Atlas Packer Gamma V2",
"web": "https://gammafp.github.io/atlas-packer-phaser/"
}
}
agentsociety/custom/maps/pku/location_assets/admin_building.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 596 B

agentsociety/custom/maps/pku/location_assets/boya_pagoda.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 483 B

agentsociety/custom/maps/pku/location_assets/campus_green.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 662 B

agentsociety/custom/maps/pku/location_assets/canteen.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 558 B

agentsociety/custom/maps/pku/location_assets/centennial_hall.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 509 B

agentsociety/custom/maps/pku/location_assets/dormitory.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 544 B

agentsociety/custom/maps/pku/location_assets/east_gate.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 537 B

agentsociety/custom/maps/pku/location_assets/gymnasium.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 616 B

agentsociety/custom/maps/pku/location_assets/lab_building.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 466 B

agentsociety/custom/maps/pku/location_assets/library.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 465 B

agentsociety/custom/maps/pku/location_assets/south_gate.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 677 B

agentsociety/custom/maps/pku/location_assets/teaching_building.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 505 B

agentsociety/custom/maps/pku/location_assets/weiming_lake.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 469 B

agentsociety/custom/maps/pku/location_assets/west_gate.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 715 B

agentsociety/custom/maps/pku/map.yaml
+823
View File
@@ -0,0 +1,823 @@
schema_version: 1
map_id: pku
display_name: 北京大学燕园
localized:
en:
display_name: "Peking University Yanyuan"
zh:
display_name: "北京大学燕园"
tiled_map_path: visuals/map.json
tile_size: 32
character_root: characters
character_frame_width: 32
character_frame_height: 32
default_location_order:
- dormitory
- canteen
- teaching_building
- library
- weiming_lake
- boya_pagoda
- centennial_hall
- lab_building
- gymnasium
- campus_green
- west_gate
- east_gate
recommended_roles:
- role: undergraduate student
default_location_id: dormitory
- role: graduate researcher
default_location_id: lab_building
- role: librarian
default_location_id: library
- role: professor
default_location_id: teaching_building
- role: visitor
default_location_id: west_gate
- role: student organizer
default_location_id: campus_green
spawn_points:
- id: student_start
location_id: dormitory
- id: researcher_start
location_id: lab_building
- id: library_start
location_id: library
- id: visitor_start
location_id: west_gate
- id: lake_start
location_id: weiming_lake
- id: canteen_start
location_id: canteen
locations:
- id: west_gate
name: 北京大学西门
localized:
en:
name: "Peking University West Gate"
zh:
name: "北京大学西门"
aliases:
- west gate
- pku west gate
- 西门
- 北大西门
source_note: High-detail PKU Yanyuan pixel map generated from package-local imagegen
exterior, interior, character, and campus-reference assets; not surveyed GIS coordinates.
anchor_tile:
x: 7
y: 52
interaction_ids:
- enter_campus
- campus_tour
scene_type: gate
bounds:
x: 1
y: 48
w: 12
h: 10
- id: east_gate
name: 北京大学东门
localized:
en:
name: "Peking University East Gate"
zh:
name: "北京大学东门"
aliases:
- east gate
- pku east gate
- 东门
- 北大东门
source_note: High-detail PKU Yanyuan pixel map generated from package-local imagegen
exterior, interior, character, and campus-reference assets; not surveyed GIS coordinates.
anchor_tile:
x: 134
y: 52
interaction_ids:
- enter_campus
- meet_at_gate
scene_type: gate
bounds:
x: 132
y: 47
w: 7
h: 10
- id: south_gate
name: 北京大学南门
localized:
en:
name: "Peking University South Gate"
zh:
name: "北京大学南门"
aliases:
- south gate
- 南门
- campus entrance
source_note: High-detail PKU Yanyuan pixel map generated from package-local imagegen
exterior, interior, character, and campus-reference assets; not surveyed GIS coordinates.
anchor_tile:
x: 70
y: 91
interaction_ids:
- enter_campus
- campus_tour
scene_type: gate
bounds:
x: 65
y: 89
w: 12
h: 9
- id: weiming_lake
name: 未名湖
localized:
en:
name: "Weiming Lake"
zh:
name: "未名湖"
aliases:
- Weiming Lake
- lake
- 未名湖
- 湖边
source_note: High-detail PKU Yanyuan pixel map generated from package-local imagegen
exterior, interior, character, and campus-reference assets; not surveyed GIS coordinates.
anchor_tile:
x: 49
y: 51
interaction_ids:
- walk_lake
- outdoor_reflection
- campus_tour
scene_type: park
bounds:
x: 22
y: 14
w: 43
h: 40
- id: boya_pagoda
name: 博雅塔
localized:
en:
name: "Boya Pagoda"
zh:
name: "博雅塔"
aliases:
- Boya Pagoda
- pagoda
- 博雅塔
source_note: High-detail PKU Yanyuan pixel map generated from package-local imagegen
exterior, interior, character, and campus-reference assets; not surveyed GIS coordinates.
anchor_tile:
x: 66
y: 51
interaction_ids:
- campus_tour
- take_photo
- outdoor_reflection
scene_type: landmark
bounds:
x: 60
y: 39
w: 7
h: 13
- id: library
name: 北京大学图书馆
localized:
en:
name: "Peking University Library"
zh:
name: "北京大学图书馆"
aliases:
- library
- PKU Library
- 图书馆
source_note: High-detail PKU Yanyuan pixel map generated from package-local imagegen
exterior, interior, character, and campus-reference assets; not surveyed GIS coordinates.
anchor_tile:
x: 79
y: 34
interaction_ids:
- study_library
- borrow_book
- research_discussion
scene_type: library
bounds:
x: 70
y: 21
w: 23
h: 14
- id: centennial_hall
name: 百周年纪念讲堂
localized:
en:
name: "Centennial Hall"
zh:
name: "百周年纪念讲堂"
aliases:
- Centennial Hall
- 百年讲堂
- 讲堂
source_note: High-detail PKU Yanyuan pixel map generated from package-local imagegen
exterior, interior, character, and campus-reference assets; not surveyed GIS coordinates.
anchor_tile:
x: 80
y: 57
interaction_ids:
- attend_lecture
- club_event
- public_talk
scene_type: auditorium
bounds:
x: 72
y: 47
w: 16
h: 13
- id: teaching_building
name: 教学楼
localized:
en:
name: "Teaching Building"
zh:
name: "教学楼"
aliases:
- teaching building
- classroom
- 教学楼
- 教室
source_note: High-detail PKU Yanyuan pixel map generated from package-local imagegen
exterior, interior, character, and campus-reference assets; not surveyed GIS coordinates.
anchor_tile:
x: 114
y: 27
interaction_ids:
- attend_class
- office_hours
- group_project
scene_type: school
bounds:
x: 100
y: 12
w: 27
h: 16
- id: dormitory
name: 学生宿舍
localized:
en:
name: "Student Dormitory"
zh:
name: "学生宿舍"
aliases:
- dorm
- dormitory
- 宿舍
source_note: High-detail PKU Yanyuan pixel map generated from package-local imagegen
exterior, interior, character, and campus-reference assets; not surveyed GIS coordinates.
anchor_tile:
x: 30
y: 76
interaction_ids:
- rest_dorm
- chat_roommates
- prepare_day
scene_type: home
bounds:
x: 18
y: 66
w: 24
h: 17
- id: canteen
name: 学生食堂
localized:
en:
name: "Student Canteen"
zh:
name: "学生食堂"
aliases:
- canteen
- dining hall
- 食堂
source_note: High-detail PKU Yanyuan pixel map generated from package-local imagegen
exterior, interior, character, and campus-reference assets; not surveyed GIS coordinates.
anchor_tile:
x: 50
y: 69
interaction_ids:
- eat_canteen
- casual_meetup
- share_news
scene_type: cafe
bounds:
x: 42
y: 60
w: 16
h: 15
- id: gymnasium
name: 体育馆
localized:
en:
name: "Gymnasium"
zh:
name: "体育馆"
aliases:
- gym
- gymnasium
- 体育馆
source_note: High-detail PKU Yanyuan pixel map generated from package-local imagegen
exterior, interior, character, and campus-reference assets; not surveyed GIS coordinates.
anchor_tile:
x: 118
y: 80
interaction_ids:
- exercise
- team_practice
- wellness_check
scene_type: sports
bounds:
x: 106
y: 70
w: 27
h: 17
- id: lab_building
name: 理科实验楼
localized:
en:
name: "Science Laboratory Building"
zh:
name: "理科实验楼"
aliases:
- lab
- laboratory
- 实验楼
source_note: High-detail PKU Yanyuan pixel map generated from package-local imagegen
exterior, interior, character, and campus-reference assets; not surveyed GIS coordinates.
anchor_tile:
x: 120
y: 42
interaction_ids:
- run_experiment
- research_discussion
- lab_safety_check
scene_type: lab
bounds:
x: 104
y: 30
w: 29
h: 17
- id: admin_building
name: 办公楼
localized:
en:
name: "Administration Building"
zh:
name: "办公楼"
aliases:
- admin
- office
- 办公楼
source_note: High-detail PKU Yanyuan pixel map generated from package-local imagegen
exterior, interior, character, and campus-reference assets; not surveyed GIS coordinates.
anchor_tile:
x: 76
y: 41
interaction_ids:
- office_hours
- department_meeting
- paperwork
scene_type: office
bounds:
x: 66
y: 30
w: 22
h: 12
- id: campus_green
name: 校园草坪
localized:
en:
name: "Campus Green"
zh:
name: "校园草坪"
aliases:
- green
- quad
- 草坪
source_note: High-detail PKU Yanyuan pixel map generated from package-local imagegen
exterior, interior, character, and campus-reference assets; not surveyed GIS coordinates.
anchor_tile:
x: 60
y: 60
interaction_ids:
- club_event
- outdoor_reflection
- campus_tour
scene_type: park
bounds:
x: 51
y: 54
w: 21
h: 13
interactions:
- id: enter_campus
name: 进入校园
description: Enter or leave campus through a gate while checking plans.
localized:
en:
name: "Enter Campus"
description: "Enter or leave campus through a gate while checking plans."
zh:
name: "进入校园"
description: "通过校门进出校园并确认行程。"
allowed_location_ids:
- west_gate
- east_gate
- south_gate
effects:
social_context: campus_daily_life
- id: meet_at_gate
name: 校门碰头
description: Meet someone at a campus gate before moving inward.
localized:
en:
name: "Gate Meetup"
description: "Meet someone at a campus gate before moving inward."
zh:
name: "校门碰头"
description: "在校门与他人会合后再进入校园。"
allowed_location_ids:
- east_gate
- west_gate
effects:
social_context: campus_daily_life
- id: campus_tour
name: 校园导览
description: Guide visitors through landmark routes and share campus context.
localized:
en:
name: "Campus Tour"
description: "Guide visitors through landmark routes and share campus context."
zh:
name: "校园导览"
description: "带领访客走过校园地标路线并介绍背景。"
allowed_location_ids:
- west_gate
- south_gate
- weiming_lake
- boya_pagoda
- campus_green
effects:
social_context: campus_daily_life
- id: walk_lake
name: 湖边散步
description: Walk around Weiming Lake and hold a quiet conversation.
localized:
en:
name: "Lake Walk"
description: "Walk around Weiming Lake and hold a quiet conversation."
zh:
name: "湖边散步"
description: "沿未名湖散步并安静交谈。"
allowed_location_ids:
- weiming_lake
effects:
social_context: campus_daily_life
- id: outdoor_reflection
name: 户外思考
description: Pause outdoors to reflect, plan, or decompress.
localized:
en:
name: "Outdoor Reflection"
description: "Pause outdoors to reflect, plan, or decompress."
zh:
name: "户外思考"
description: "在户外停下来思考、规划或放松。"
allowed_location_ids:
- weiming_lake
- boya_pagoda
- campus_green
effects:
social_context: campus_daily_life
- id: take_photo
name: 地标拍照
description: Take a landmark photo or describe what can be seen from the spot.
localized:
en:
name: "Landmark Photo"
description: "Take a landmark photo or describe what can be seen from the spot."
zh:
name: "地标拍照"
description: "拍摄地标照片或描述当前位置所见。"
allowed_location_ids:
- boya_pagoda
effects:
social_context: campus_daily_life
- id: study_library
name: 图书馆自习
description: Study quietly, read notes, or prepare for class.
localized:
en:
name: "Library Study"
description: "Study quietly, read notes, or prepare for class."
zh:
name: "图书馆自习"
description: "安静自习、阅读笔记或准备课程。"
allowed_location_ids:
- library
effects:
social_context: campus_daily_life
- id: borrow_book
name: 借还图书
description: Borrow, return, or search for a book.
localized:
en:
name: "Borrow or Return Books"
description: "Borrow, return, or search for a book."
zh:
name: "借还图书"
description: "借书、还书或检索图书。"
allowed_location_ids:
- library
effects:
social_context: campus_daily_life
- id: research_discussion
name: 科研讨论
description: Discuss papers, experiments, or a research question.
localized:
en:
name: "Research Discussion"
description: "Discuss papers, experiments, or a research question."
zh:
name: "科研讨论"
description: "讨论论文、实验或科研问题。"
allowed_location_ids:
- library
- lab_building
effects:
social_context: campus_daily_life
- id: attend_lecture
name: 参加讲座
description: Attend a lecture, forum, or talk.
localized:
en:
name: "Attend Lecture"
description: "Attend a lecture, forum, or talk."
zh:
name: "参加讲座"
description: "参加讲座、论坛或报告。"
allowed_location_ids:
- centennial_hall
effects:
social_context: campus_daily_life
- id: public_talk
name: 公共报告
description: Give or listen to a public campus talk.
localized:
en:
name: "Public Talk"
description: "Give or listen to a public campus talk."
zh:
name: "公共报告"
description: "发表或聆听校园公共报告。"
allowed_location_ids:
- centennial_hall
effects:
social_context: campus_daily_life
- id: club_event
name: 社团活动
description: Coordinate a student club event.
localized:
en:
name: "Club Event"
description: "Coordinate a student club event."
zh:
name: "社团活动"
description: "协调学生社团活动。"
allowed_location_ids:
- centennial_hall
- campus_green
effects:
social_context: campus_daily_life
- id: attend_class
name: 上课
description: Attend or teach a scheduled class.
localized:
en:
name: "Attend Class"
description: "Attend or teach a scheduled class."
zh:
name: "上课"
description: "参加或讲授计划中的课程。"
allowed_location_ids:
- teaching_building
effects:
social_context: campus_daily_life
- id: office_hours
name: 答疑办公
description: Ask questions, tutor, or hold office hours.
localized:
en:
name: "Office Hours"
description: "Ask questions, tutor, or hold office hours."
zh:
name: "答疑办公"
description: "答疑、辅导或开展办公时间。"
allowed_location_ids:
- teaching_building
- admin_building
effects:
social_context: campus_daily_life
- id: group_project
name: 小组作业
description: Work with classmates on a group task.
localized:
en:
name: "Group Project"
description: "Work with classmates on a group task."
zh:
name: "小组作业"
description: "与同学合作完成小组任务。"
allowed_location_ids:
- teaching_building
effects:
social_context: campus_daily_life
- id: rest_dorm
name: 宿舍休息
description: Rest, reset, or return to the dorm.
localized:
en:
name: "Dorm Rest"
description: "Rest, reset, or return to the dorm."
zh:
name: "宿舍休息"
description: "在宿舍休息、调整或返回宿舍。"
allowed_location_ids:
- dormitory
effects:
social_context: campus_daily_life
- id: chat_roommates
name: 宿舍聊天
description: Talk with roommates about daily campus life.
localized:
en:
name: "Roommate Chat"
description: "Talk with roommates about daily campus life."
zh:
name: "宿舍聊天"
description: "和室友聊校园日常。"
allowed_location_ids:
- dormitory
effects:
social_context: campus_daily_life
- id: prepare_day
name: 准备出门
description: Pack books, check schedule, and prepare for the next activity.
localized:
en:
name: "Prepare to Leave"
description: "Pack books, check schedule, and prepare for the next activity."
zh:
name: "准备出门"
description: "整理书本、查看日程并准备下一项活动。"
allowed_location_ids:
- dormitory
effects:
social_context: campus_daily_life
- id: eat_canteen
name: 食堂用餐
description: Eat a meal in the student canteen.
localized:
en:
name: "Canteen Meal"
description: "Eat a meal in the student canteen."
zh:
name: "食堂用餐"
description: "在学生食堂用餐。"
allowed_location_ids:
- canteen
effects:
social_context: campus_daily_life
- id: casual_meetup
name: 随意见面
description: Meet informally over food or a break.
localized:
en:
name: "Casual Meetup"
description: "Meet informally over food or a break."
zh:
name: "随意见面"
description: "在用餐或休息时随意见面。"
allowed_location_ids:
- canteen
effects:
social_context: campus_daily_life
- id: share_news
name: 交换消息
description: Share recent campus news or plans.
localized:
en:
name: "Share News"
description: "Share recent campus news or plans."
zh:
name: "交换消息"
description: "交流近期校园消息或计划。"
allowed_location_ids:
- canteen
effects:
social_context: campus_daily_life
- id: exercise
name: 运动锻炼
description: Exercise indoors or on nearby sports grounds.
localized:
en:
name: "Exercise"
description: "Exercise indoors or on nearby sports grounds."
zh:
name: "运动锻炼"
description: "在室内或附近运动场锻炼。"
allowed_location_ids:
- gymnasium
effects:
social_context: campus_daily_life
- id: team_practice
name: 团队训练
description: Coordinate sports practice or a team routine.
localized:
en:
name: "Team Practice"
description: "Coordinate sports practice or a team routine."
zh:
name: "团队训练"
description: "协调体育训练或团队练习。"
allowed_location_ids:
- gymnasium
effects:
social_context: campus_daily_life
- id: wellness_check
name: 健康打卡
description: Check personal health and energy after exercise.
localized:
en:
name: "Wellness Check"
description: "Check personal health and energy after exercise."
zh:
name: "健康打卡"
description: "运动后确认个人健康和精力状态。"
allowed_location_ids:
- gymnasium
effects:
social_context: campus_daily_life
- id: run_experiment
name: 实验操作
description: Run a lab task or inspect experimental results.
localized:
en:
name: "Run Experiment"
description: "Run a lab task or inspect experimental results."
zh:
name: "实验操作"
description: "执行实验任务或检查实验结果。"
allowed_location_ids:
- lab_building
effects:
social_context: campus_daily_life
- id: lab_safety_check
name: 实验安全检查
description: Check equipment, lab safety, or experiment setup.
localized:
en:
name: "Lab Safety Check"
description: "Check equipment, lab safety, or experiment setup."
zh:
name: "实验安全检查"
description: "检查设备、实验安全或实验准备情况。"
allowed_location_ids:
- lab_building
effects:
social_context: campus_daily_life
- id: department_meeting
name: 院系会议
description: Attend an administrative or academic meeting.
localized:
en:
name: "Department Meeting"
description: "Attend an administrative or academic meeting."
zh:
name: "院系会议"
description: "参加行政或学术会议。"
allowed_location_ids:
- admin_building
effects:
social_context: campus_daily_life
- id: paperwork
name: 事务办理
description: Handle paperwork, permissions, or coordination tasks.
localized:
en:
name: "Paperwork"
description: "Handle paperwork, permissions, or coordination tasks."
zh:
name: "事务办理"
description: "处理材料、权限或协调事务。"
allowed_location_ids:
- admin_building
effects:
social_context: campus_daily_life
agentsociety/custom/maps/pku/visuals/map.json
+238487
View File
File diff suppressed because it is too large Load Diff
agentsociety/custom/maps/pku/visuals/map_assets/blocks/blocks_1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.0 KiB

agentsociety/custom/maps/pku/visuals/map_assets/blocks/blocks_2.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.1 KiB

agentsociety/custom/maps/pku/visuals/map_assets/blocks/blocks_3.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.6 KiB

agentsociety/custom/maps/pku/visuals/map_assets/cute_rpg_word_VXAce/tilesets/CuteRPG_Desert_B.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 455 KiB

agentsociety/custom/maps/pku/visuals/map_assets/cute_rpg_word_VXAce/tilesets/CuteRPG_Desert_C.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 386 KiB

agentsociety/custom/maps/pku/visuals/map_assets/cute_rpg_word_VXAce/tilesets/CuteRPG_Field_B.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 431 KiB

agentsociety/custom/maps/pku/visuals/map_assets/cute_rpg_word_VXAce/tilesets/CuteRPG_Field_C.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 395 KiB

agentsociety/custom/maps/pku/visuals/map_assets/cute_rpg_word_VXAce/tilesets/CuteRPG_Forest_B.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 494 KiB

agentsociety/custom/maps/pku/visuals/map_assets/cute_rpg_word_VXAce/tilesets/CuteRPG_Forest_C.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 487 KiB

agentsociety/custom/maps/pku/visuals/map_assets/cute_rpg_word_VXAce/tilesets/CuteRPG_Harbor_C.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 482 KiB

agentsociety/custom/maps/pku/visuals/map_assets/cute_rpg_word_VXAce/tilesets/CuteRPG_Mountains_B.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 458 KiB

agentsociety/custom/maps/pku/visuals/map_assets/cute_rpg_word_VXAce/tilesets/CuteRPG_Village_B.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 486 KiB

agentsociety/custom/maps/pku/visuals/map_assets/pku_generated/pku_full_map_tileset.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.1 MiB

agentsociety/custom/maps/pku/visuals/map_assets/v1/Room_Builder_32x32.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 MiB

agentsociety/custom/maps/pku/visuals/map_assets/v1/interiors_pt1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 MiB

agentsociety/custom/maps/pku/visuals/map_assets/v1/interiors_pt2.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 MiB

agentsociety/custom/maps/pku/visuals/map_assets/v1/interiors_pt3.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 MiB

agentsociety/custom/maps/pku/visuals/map_assets/v1/interiors_pt4.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 553 KiB

agentsociety/custom/maps/pku/visuals/map_assets/v1/interiors_pt5.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.3 MiB

agentsociety/custom/maps/pku/visuals/preview.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 538 KiB

agentsociety/custom/maps/the_ville/ATTRIBUTION.md
+10
View File
@@ -0,0 +1,10 @@
# Pixel Town Assets
The Smallville pixel map, tilesets, and character sprites in this directory are copied from the original Generative Agents asset directory.
Original project:
Generative Agents: Interactive Simulacra of Human Behavior
https://github.com/joonspk-research/generative_agents
The original README credits the visual assets to PixyMoon, LimeZu, and pipohi.
agentsociety/custom/maps/the_ville/README.md
+57
View File
@@ -0,0 +1,57 @@
<h1 align="center">🏘️ The Ville · GOD Map Package</h1>
<p align="center">
<b>The default pixel-town world that ships with GOD.</b><br/>
<sub>10 locations · 65 interactions · the reference shape for every new map.</sub>
</p>
<p align="center">
<a href="README.zh-CN.md">🌏 中文</a> ·
<a href="../../../../docs/MAP_PACKAGES.md">📘 Map Packages Guide</a>
</p>
---
This is the **default GOD pixel-town map package**. Use this directory as the
reference shape when you build your own world. A new map can be added by
copying [`_template/`](../_template/README.md), replacing `map.yaml`,
`visuals/map.json`, the tileset images, and (optionally) character or location
assets.
## 📦 Layout
```text
the_ville/
├── map.yaml ← semantic manifest used by GOD
├── README.md ← you are here
├── ATTRIBUTION.md ← visual asset credits
├── visuals/
│ ├── the_ville_jan7.json ← Tiled JSON map (orthogonal)
│ └── map_assets/**/*.png ← tileset images
└── characters/
└── *.png ← 32×32 character sprites
```
## 🗺️ World
| Stat | Value |
| --- | --- |
| Map id | `the_ville` |
| Display name | The Ville |
| Tile size | 32 × 32 |
| Locations | 10 (`home`, `school`, `library`, `cafe`, `park`, `supply_store`, `market`, `pharmacy`, `pub`, `dorm`) |
| Interactions | 65 location-scoped actions |
| Tiled JSON | `visuals/the_ville_jan7.json` |
## ✅ Validation
```bash
cd agentsociety
uv run python scripts/validate_map_package.py custom/maps/the_ville
```
## 🙏 Credits
The pixel tiles, characters, and tilesets were originally produced for the
[Generative Agents](https://github.com/joonspk-research/generative_agents)
project. Full attribution lives in [`ATTRIBUTION.md`](ATTRIBUTION.md).
agentsociety/custom/maps/the_ville/README.zh-CN.md
+55
View File
@@ -0,0 +1,55 @@
<h1 align="center">🏘️ The Ville · GOD 地图包</h1>
<p align="center">
<b>GOD 内置的默认像素小镇世界。</b><br/>
<sub>10 个地点 · 65 个交互 · 所有新地图的参考形态。</sub>
</p>
<p align="center">
<a href="README.md">🌏 English</a> ·
<a href="../../../../docs/MAP_PACKAGES.zh-CN.md">📘 地图包指南</a>
</p>
---
这是 **GOD 默认的像素小镇地图包**。当你想做自己的世界时，把这个目录当作参考样本。
复制 [`_template/`](../_template/README.zh-CN.md)、替换 `map.yaml`、`visuals/map.json`、
图块素材，以及（可选的）人物或地点资产，新地图就能加入。
## 📦 目录结构
```text
the_ville/
├── map.yaml ← GOD 读取的语义清单
├── README.md ← 你正在看
├── ATTRIBUTION.md ← 图块素材版权归属
├── visuals/
│ ├── the_ville_jan7.json ← Tiled JSON 地图（orthogonal 正交投影）
│ └── map_assets/**/*.png ← 图块素材
└── characters/
└── *.png ← 32×32 人物精灵
```
## 🗺️ 世界概览
| 指标 | 值 |
| --- | --- |
| Map id | `the_ville` |
| 显示名 | The Ville |
| 图块尺寸 | 32 × 32 |
| 地点 | 10 个（`home`、`school`、`library`、`cafe`、`park`、`supply_store`、`market`、`pharmacy`、`pub`、`dorm`） |
| 交互 | 65 个 location-scoped 动作 |
| Tiled JSON | `visuals/the_ville_jan7.json` |
## ✅ 校验
```bash
cd agentsociety
uv run python scripts/validate_map_package.py custom/maps/the_ville
```
## 🙏 致谢
像素图块、人物、tileset 原始作品来自
[Generative Agents](https://github.com/joonspk-research/generative_agents) 项目。
完整版权归属见 [`ATTRIBUTION.md`](ATTRIBUTION.md)。
agentsociety/custom/maps/the_ville/characters/Abigail_Chen.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.4 KiB

agentsociety/custom/maps/the_ville/characters/Adam_Smith.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.8 KiB

agentsociety/custom/maps/the_ville/characters/Arthur_Burton.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.1 KiB

agentsociety/custom/maps/the_ville/characters/Ayesha_Khan.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.8 KiB

agentsociety/custom/maps/the_ville/characters/Carlos_Gomez.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.2 KiB

Some files were not shown because too many files have changed in this diff Show More