Information
# Religion Agent Map Simulation
AI-driven multi-agent simulation for religious conversion dynamics with OpenAI-compatible providers + Three.js.
[](https://nodejs.org/)
[](https://threejs.org/)
[](https://platform.openai.com/docs/api-reference)
[](./LICENSE)
[](https://github.com/crazywoola/religion-agent-simulation/stargazers)
[](https://github.com/crazywoola/religion-agent-simulation/network/members)
[](https://github.com/crazywoola/religion-agent-simulation/issues)
[](https://github.com/crazywoola/religion-agent-simulation/commits/main)
English | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md)
## Welcome
This project simulates how multiple religion agents influence each other over time while preserving a constant total population. The backend combines rule-based constraints with AI-generated structured transfer links, and the frontend visualizes conversion flows as animated ant-path lines on a 3D world map.
## Full Game Screenshot
Captured from a live run at round 3 using the current local \`.env\` configuration.
## Key Features
- Multi-agent simulation for 8 religions (including Shinto).
- Constant-total followers invariant (\`sum followers\` stays fixed each round).
- Built-in i18n UI (\`en\`, \`zh-CN\`, \`ja\`) with runtime language switch.
- Hybrid transfer engine:
- Rule engine computes baseline transfers.
- AI transfer agent outputs \`structureOutput.links\` with structured quantities.
- Three.js map UI with:
- Regional dominance towers.
- Dynamic conversion ant-path lines.
- Transfer source labels (\`AI\` / \`Rule\`).
- Rich doctrine model per religion:
- Short doctrine, long description, classic texts.
- Social traits and regional affinity vectors.
## Architecture
- Backend: Express + OpenAI-compatible API clients (OpenAI, Moonshot/Kimi)
- Frontend: Vanilla JS + Three.js
- Data models:
- \`data/religion-doctrines.js\`
- \`data/world-context.js\`
\`\`\`text
AI Provider (OpenAI / Moonshot Kimi)
|
v
server.js simulation core
(rule + AI hybrid transfer plan)
|
v
/api/simulation/* snapshot JSON
|
v
Three.js world map + ant links
\`\`\`
## Quick Start
\`\`\`bash
npm install
cp .env.example .env
# fill AI_API_KEY (and optional AI_PROVIDER) in .env
npm run dev
\`\`\`
Open: \`http://localhost:3000\`
## Environment Variables
See \`.env.example\`:
- \`AI_PROVIDER\` (\`openai\` | \`moonshot\`)
- \`AI_API_KEY\`
- \`AI_MODEL\`
- \`AI_API_BASE\`
- \`AI_API_LOG\`
- \`AI_API_LOG_PAYLOAD\`
- \`AI_TRANSFER_AGENT\`
- \`AI_API_TIMEOUT_MS\`
- \`AI_API_MAX_RETRIES\`
- \`AI_API_RETRY_BASE_DELAY_MS\`
- \`NODE_USE_ENV_PROXY\`
- \`PORT\`
Provider defaults:
- \`openai\`: model \`gpt-4o-mini\`, base \`https://api.openai.com/v1\`
- \`moonshot\`: model \`kimi-k2-turbo-preview\`, base \`https://api.moonshot.cn/v1\`
If you see frequent \`fetch failed | code=ECONNRESET\`, increase \`AI_API_TIMEOUT_MS\` and \`AI_API_MAX_RETRIES\`, and make sure \`AI_API_BASE\` / proxy settings are reachable.
## API
- \`POST /api/simulation/start\`
- body: \`\{ "useAI": true | false, "provider": "openai|moonshot", "locale": "en|zh-CN|ja" \}\`
- \`POST /api/simulation/tick\`
- body: \`\{ "locale": "en|zh-CN|ja" \}\`
- \`GET /api/simulation/state\`
- \`GET /api/health\`
Structured output example:
\`\`\`json
\{
"transferEngine": "ai|hybrid|rule",
"structureOutput": \{
"antLinks": [
\{
"fromReligionId": "buddhism",
"toReligionId": "shinto",
"fromRegionId": "south_asia",
"toRegionId": "east_asia",
"amount": 128,
"reason": "digital outreach"
\}
]
\}
\}
\`\`\`
## Security Notes
- Secrets are excluded from git via \`.gitignore\` (\`.env\`, \`.env.*\`).
- Keep real keys only in local \`.env\`.
- Use \`.env.example\` for shared templates.
## Disclaimer
This is a technical simulation demo for agent systems and visualization. It does not represent real-world religious statistics, truth claims, or value judgments.