Metadata-Version: 2.4
Name: age-kit
Version: 2.1.0
Summary: AI Game Developer Kit — build complete games from pre-built components
Home-page: https://github.com/example/age-kit
Author: AGE Kit Contributors
Author-email: age-kit@example.com
License: MIT
Project-URL: Documentation, https://github.com/example/age-kit
Project-URL: Source, https://github.com/example/age-kit
Project-URL: Tracker, https://github.com/example/age-kit/issues
Keywords: game-development,ai-agent,game-engine,story-graph,narrative,rpg,visual-novel
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: jinja2>=3.0
Requires-Dist: anthropic>=0.30
Requires-Dist: openai>=1.0
Provides-Extra: dev
Requires-Dist: setuptools>=68.0; extra == "dev"
Requires-Dist: wheel>=0.41; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# AGE Engine — AI Game Developer Kit

## 这是什么

一个给 AI Agent 用的游戏开发套件。Agent 读取配置后，能像拼积木一样组装出完整游戏。

集成了 [gstack](https://github.com/garrytan/gstack) 的工程方法论和 [gstack-game](https://github.com/fagemx/gstack-game) 的游戏设计理论（MDA、Flow State、Sink/Faucet 经济模型），让 Agent 不只是"组装组件"，而是像一个真正的游戏开发者一样思考——先设计 Fantasy/Loop/Twist，再选择模板，最后构建、测试、迭代。

## 打包内容

```
AGE_PACKAGE/
├── AGE_KIT/              ★ 核心：Agent开发套件 (独立可用)
│   ├── ACTIVATE.md         Agent激活入口 (含完整方法论)
│   ├── SKILL.md            Claude Code Skill定义 (v3.0)
│   ├── ETHOS.md            ★ 构建者哲学 (Boil the Lake等5大原则)
│   ├── mcp_server.py       22个MCP工具
│   ├── library/            纯Python游戏库
│   │   ├── age_core/       数据模型
│   │   ├── age_bridge/     剧情↔游戏转换
│   │   ├── age_runtime/    引擎HTTP客户端 + AI客户端
│   │   └── age_templates/  预制游戏模板(4个)
│   ├── skills/             5个专家Agent技能 (增强版)
│   │   ├── game_designer.md    Fantasy/Loop/Twist框架 + GDD评分
│   │   ├── level_builder.md    情感弧线设计 + Flow State验证
│   │   ├── mechanic_designer.md Sink/Faucet经济 + Bartle类型
│   │   ├── narrative_writer.md  角色深度 + 分支后果模型
│   │   └── playtester.md        Persona测试 + 情绪追踪
│   ├── recipes/            4个常用构建配方
│   ├── templates/          预制游戏工程
│   ├── config.yaml         配置文件(AI Key已预填)
│   ├── LIBRARY.md          完整API参考
│   └── output/             场景JSON输出目录
│
├── euca-engine/           ★ 游戏运行时引擎 (Rust, 需编译)
│   ├── 25个crate           ECS/渲染/物理/AI/音频/网络...
│   └── 编译后运行在 :3917 端口
│
├── ElyHa/                   AI多Agent写作流水线 (Python)
│   └── Planner→Writer→Reviewer 三阶段写作
│
├── DEMO/                    Mario平台游戏原型
│   ├── index.html           浏览器打开即玩
│   └── sprites/             SVG精灵图
│
├── install.bat              一键安装脚本
└── README.md                本文件
```

## 方法论集成

AGE Kit 从 gstack 和 gstack-game 集成了以下核心方法论：

| 来源 | 集成内容 |
|------|---------|
| **gstack** | Boil the Lake 完整性原则、Search Before Building、AI压缩比、Skill路由、AskUserQuestion格式、Completion Protocol |
| **gstack-game** | Game Design词汇（Core Loop/FTUE/Flow State等）、Fantasy/Loop/Twist框架、Sink/Faucet经济模型、Bartle类型、Persona测试、情感弧线追踪、游戏开发5阶段工作流 |

详细哲学见 [ETHOS.md](AGE_KIT/ETHOS.md)。

## 快速开始

### 1. 安装
```bash
# Windows: 双击 install.bat
# Mac/Linux: 手动执行
pip install httpx pydantic pyyaml jinja2 anthropic openai
```

### 2. 启动引擎（可选，不需要Rust也能构建场景）
```bash
cd euca-engine
cargo run -p euca-agent --example agent_headless --release
```

### 3. 激活Agent
在Claude Code中输入: **"开启游戏开发模式"**

或直接启动MCP Server:
```bash
python AGE_KIT/mcp_server.py
```

### 4. 开始做游戏
```
Agent会:
  ① 读取 ETHOS.md 获取构建者哲学
  ② 读取 ACTIVATE.md 获取游戏开发者身份 (含完整方法论)
  ③ 用 Fantasy/Loop/Twist 框架设计游戏核心
  ④ 用 age_template_instantiate 创建游戏框架
  ⑤ 用 age_template_customize 添加敌人/Boss/道具
  ⑥ 用 age_template_build 生成完整场景JSON
  ⑦ 用 Persona 测试 + 情感弧线追踪验证游戏体验
  ⑧ 用 age_world_spawn/step/observe 在引擎中运行
```

## 游戏开发5阶段工作流

```
Think → Design → Build → Test → Reflect
(思考)  (设计)  (构建)  (测试)  (反思)
```

每个阶段由对应技能驱动，输出自动流入下一阶段。迭代一周期只需数分钟，而非数周。

## 各层级能力

| 层级 | 只需要什么 | 能做什么 |
|------|-----------|---------|
| **仅AGE_KIT** | Python + 依赖包 | 创建剧情图、构建场景JSON、AI对话设计游戏、完整GDD评分 |
| **+Euca引擎** | 上述 + Rust | 实际运行游戏、生成实体、模拟物理、Persona测试 |
| **+ElyHa** | 上述 + Python | AI多Agent写作流水线(Planner→Writer→Reviewer) |
| **+Claude Code** | 上述 + MCP配置 | Agent全自动：设计→构建→运行→测试 |

## 不需要的东西

以下已内置于AGE_KIT/library中，不需要单独打包：
- ~~age-engine/~~ (桥接层已包含在library里)
- ~~age-studio/~~ (GUI已被MCP工具替代)

## MCP配置

复制到 `~/.claude/claude_settings.json`:
```json
{
  "mcpServers": {
    "age-kit": {
      "command": "python",
      "args": ["<AGE_KIT路径>/mcp_server.py"]
    }
  }
}
```

## 支持的AI模型

| 模型 | 配置方式 | 用途 |
|------|---------|------|
| DeepSeek (Anthropic兼容) | 已预填在config.yaml | 默认 |
| Claude (Anthropic) | 改config.yaml的api_key | 原生工具调用 |
| GPT (OpenAI) | 改kind为openai | 对话 |
| 本地模型 (Ollama) | 改kind为local | 离线 |

## 常见问题

**Q: 没有Rust能跑吗？**
A: 能。AGE_KIT可以独立构建场景JSON、设计剧情、AI对话。只是不能运行实时游戏画面。

**Q: AGE_KIT为什么这么小？**
A: 它是Agent的"遥控器"，不是引擎本体。它通过HTTP操控30MB的euca-engine。方法论和设计框架以Markdown形式内嵌，不占运行时体积。

**Q: 能不能不装任何东西直接用？**
A: 最少只需要Python + httpx + pydantic。可以构建场景JSON，在任何地方使用。

**Q: gstack/gstack-game 是什么？**
A: gstack 是 Garry Tan 的 AI 工程工作流系统，gstack-game 是其在游戏开发领域的适配版本。AGE Kit 集成了两者的方法论精华，并针对"AI Agent 组装游戏组件"这个独特场景进行了适配。
