aetherforge

git clone https://github.com/hvrrgfe/aetherforge.git
cd aetherforge

pip install -r requirements.txt

pip install pymunk

pip install pygame

pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install diffusers transformers

pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install audiocraft --no-build-isolation --no-deps --no-cache-dir
pip install julius flashy hydra-core hydra_colorlog num2words tqdm
pip install spacy transformers huggingface_hub
pip install librosa torchmetrics xformers

# ① 拉取最新代码
git pull

# ② 同步安装新依赖
pip install -r requirements.txt

# ③ 如果需要，更新配置文件（保留你的自定义配置）
python -c "from aetherforge.config import get_config, save_config; save_config(get_config()); print('Config updated')"

python -c "from aetherforge.api.engine_v2 import EngineToolsV2; from aetherforge.core.world_model import WorldModel; t = EngineToolsV2(WorldModel()); print('OK:', len(t.list_tools().data['tools']), 'tools')"

python -m aetherforge.mcp_server
# 输出：AetherForge MCP Server v2.0.0 started - waiting for MCP client...

# 2D + 3D 画面
python -m aetherforge.main --demo

# 查看所有工具
python -m aetherforge.cli --tool list_tools

# 交互模式
python -m aetherforge.cli

create_entity    modify_entity    remove_entity    get_entity       find_entities
create_rule      remove_rule      create_quest     complete_quest_step  update_quest_state
set_behavior     set_weather      set_player       trigger_event    read_project
observe          commit_change    rollback_change  set_audio        set_art_intent
save_project     load_project

init_physics  add_physics_body  remove_physics_body  apply_force
set_gravity   ray_cast          get_physics_info

init_audio  load_sound  play_sound  play_music
stop_music  set_audio_volume  get_audio_state

set_3d_mesh  set_3d_transform  add_3d_light
set_3d_camera  get_3d_state

init_image_gen  generate_image  set_image_model  get_image_models

init_music_gen  generate_music  set_music_model  get_music_models

load_demo  run_tests  execute_workflow

{
  "mcpServers": {
    "aetherforge": {
      "command": "python",
      "args": ["-m", "aetherforge.mcp_server"],
      "cwd": "C:\\path\\to\\aetherforge"
    }
  }
}

## AetherForge 引擎指令

你已经连上了 AetherForge MCP Server。有 53 个工具可用。

### 几条原则
- 别去改 Python 文件——所有操作走工具
- 描述实体时带上语义（type、description、capabilities、state）
- 事务安全——失败了可以 rollback_change() 撤回
- 工具返回 JSON——解析结果，别搜日志

### 开发流程
read_project → create_entity → create_rule → set_behavior → observe → run_tests → commit_change

### 常用工具速查
| 想干啥 | 用啥工具 | 参数 |
|------|------|------|
| 创建场景 | create_entity | semantic_type, name, position, visual |
| 改天气 | set_weather | weather: "rainy"/"clear" |
| 设玩家 | set_player | entity_id |
| 加规则 | create_rule | when, then, trigger_type |
| 创建任务 | create_quest | name, description, steps |
| NPC 行为 | set_behavior | entity_id, behavior_type, goals |
| 物理 | init_physics → add_physics_body | shape, mass, dynamic |
| 音频 | init_audio → play_music | name, volume, loop |
| 3D | set_3d_mesh → set_3d_transform | geometry, color, x/y/z |
| AI 画图 | generate_image | prompt, width, height |
| AI 音乐 | generate_music | description, duration |

### 怎么看结果
- 游戏画面：http://localhost:7890/
- 3D 画面：http://localhost:7890/viewer-3d
- 世界状态：http://localhost:7890/api/observe

# 看看有哪些模型
python -m aetherforge.cli --tool list_image_models
python -m aetherforge.cli --tool list_music_models

# 切换模型（名字或本地路径都行）
python -m aetherforge.cli --tool select_image_model --params '{"name_or_path":"sdxl"}'
python -m aetherforge.cli --tool select_music_model --params '{"name_or_path":"musicgen-large"}'

# 开画
python -m aetherforge.cli --tool generate_image --params '{"prompt":"a rusty iron door"}'

---

## 📁 本地模型放置指南

引擎启动时会自己扫 models/ 目录，模型扔进去就能用。

### 目录结构

### 支持的模型格式

| 格式 | 说明 | 必须包含 |
|------|------|----------|
| **Diffusers** | 完整 pipeline 目录 | `model_index.json` + `unet/`、`vae/`、`text_encoder/` 等子目录 |
| **SafeTensors** | 单个或多个 `.safetensors` 文件 | 至少一个 `.safetensors` 文件 |
| **HuggingFace 缓存** | HF 自动下载到缓存目录 | 无需手动操作，`~/.cache/huggingface/hub/` 自动识别 |

### 放置步骤

**① 创建 `models/` 目录**

```powershell
# 在项目根目录创建
mkdir models

# 方法 A：使用 huggingface-cli 下载到本地
pip install huggingface-hub
huggingface-cli download stablediffusionapi/anything-v5 --local-dir models/anything-v5

# 方法 B：直接复制已有文件夹
Copy-Item -Recurse D:\path\to\your\model models\my-model

python -m aetherforge.cli --tool list_image_models
python -m aetherforge.cli --tool list_music_models

Available image models: anything-v5 (local), sdxl (downloadable)...
Available music models: musicgen-medium (local), musicgen-small (downloadable)...

# ~/.aetherforge/config.yaml
image_gen:
  model_path: "D:/my_models/sd-model"
music_gen:
  model_id: "facebook/musicgen-small"

python -m aetherforge.cli --tool select_image_model --params '{"name_or_path":"D:/my_models/sd-model"}'

error: Failed building wheel for av
LINK : fatal error LNK1181: 无法打开输入文件 avformat.lib

pip install av>=12.0.0
pip install audiocraft --no-build-isolation --no-deps --no-cache-dir
pip install julius flashy hydra-core hydra_colorlog num2words tqdm
pip install spacy transformers huggingface_hub
pip install librosa torchmetrics xformers

choco install ffmpeg   # 需要管理员权限
pip install audiocraft

Received exception from stream: 1 validation error for JSONRPCMessage
{"method":"notifications/message","params":{"data":"Internal Server Error"}}

git pull