godot-toolbox

AI 原生 Godot 4.6+ 工程基线与插件 pack 组装控制仓库。

快速开始

交互式一键部署（新用户推荐）

git clone https://github.com/codefromkarl/godot-toolbox.git
cd godot-toolbox

# 交互式向导，按分类浏览和选择 pack
./scripts/quickstart.sh /path/to/new-project

手动指定 pack 组装

./scripts/bootstrap_toolbox_project.sh /path/to/new-project --packs=validation,debug

预览 pack 组合产物（不写入文件）：

./scripts/bootstrap_toolbox_project.sh ../preview \
  --packs=flow-core,simulation-core,data-core,save-core,flow-test-kit \
  --dry-run-report

RPG pack 组合预览：

# 背包 + 数据 + 存档
./scripts/bootstrap_toolbox_project.sh ../preview \
  --packs=inventory,data-core,save-core --dry-run-report

# 任务 + 事件 + 存档
./scripts/bootstrap_toolbox_project.sh ../preview \
  --packs=quest,data-core,save-core,rules-events-core --dry-run-report

# 完整 RPG 栈
./scripts/bootstrap_toolbox_project.sh ../preview \
  --packs=rpg-core,rpg-battle-core,rpg-save-adapter,rpg-test-kit,flow-core,data-core,save-core,rules-events-core \
  --dry-run-report

Showcase 项目

开箱即用的游戏类型模板，5 分钟内跑起来。详见 showcases/。

Showcase	类型	一键部署
RPG Starter	回合制 RPG	`./scripts/quickstart.sh ../my-rpg --showcase=rpg-starter`
Platformer Starter	平台动作	`./scripts/quickstart.sh ../my-platformer --showcase=platformer-starter`
Simulation Starter	模拟/策略	`./scripts/quickstart.sh ../my-sim --showcase=simulation-starter`
Visual Novel Starter	视觉小说	`./scripts/quickstart.sh ../my-vn --showcase=visual-novel-starter`
Roguelike Starter	Roguelike	`./scripts/quickstart.sh ../my-roguelike --showcase=roguelike-starter`
Tower Defense Starter	塔防	`./scripts/quickstart.sh ../my-td --showcase=tower-defense-starter`
Top-down Shooter Starter	俯视角射击	`./scripts/quickstart.sh ../my-shooter --showcase=topdown-shooter-starter`
Card Game Starter	卡牌游戏	`./scripts/quickstart.sh ../my-cardgame --showcase=card-game-starter`
Adventure Starter	探索冒险	`./scripts/quickstart.sh ../my-adventure --showcase=adventure-starter`

每个 showcase 包含：经过依赖验证的 pack 组合、示例内容 JSON 和一键部署脚本。不引入新 pack，仅使用已有 pack 的最佳组合。

这个仓库做什么

设计原则：

默认最小化 — 只启用适合自动化和 CI 的基线能力
复杂度按需引入 — 玩法、调试、表现层插件做成可选 pack，不强绑到每个新项目
Vendored 分离 — 第三方 addon 与仓库自有脚本、测试、文档分离管理
按价值选型 — 优先看自动化价值、复用面、耦合度和维护成本，而非功能数量

核心特性：

Manifest 驱动组装 — packs.manifest.json 定义每个 pack 的依赖、autoload、冲突和验证入口
上游版本锁定 — upstreams.lock.json 锁定所有 vendored 插件的精确 git ref
预集成测试 — 基线模板内置 gdUnit4 + godot-gdscript-toolkit，CI-ready
CI 流水线 — 每次推送自动运行 Godot 4.6.3 headless import + gdUnit4 smoke
架构 pack — 工具箱自有 autoload 合约，覆盖 flow、data、save、rules、RPG 等
验证套件 — 分层脚本验证 manifest 合约、bootstrap 产物和 pack 一致性

这个仓库不是：

不是官方 Godot demo 镜像
不是单一游戏 starter 模板
是 选择 → 锁定版本 → 组装 → 验证 → 发行 的控制仓库

Pack 目录

基线 Pack（始终包含）

Pack	插件	用途
`base`	gdUnit4 6.1.2, godot-gdscript-toolkit 4.5.0	测试 + 代码检查基线

开发工具（仅依赖 base）

Pack	插件	版本	何时启用
`validation`	Godot Doctor	2.1.2	需要把场景/资源约束纳入 CI
`debug`	Signal Lens	1.4.1	Signal 密集型项目，需要可视化调试
`stateful`	Godot State Charts	0.22.3	复杂状态机架构
`juice`	Sparkle Lite	1.0.0	Game-feel 和反馈 authoring
`ai-behavior`	Beehave	2.9.2	行为树 AI（NPC/敌人）
`save-state-lite`	SaveState Lite	1.2.0	独立存档工具（⚠️ 与 save-core 冲突）

输入 & 自动化

Pack	插件	版本	何时启用
`input`	G.U.I.D.E	0.12.0	跨设备输入映射与提示图标
`automation`	GodotE2E	1.1.0	运行时 UI/E2E 自动化（pytest bridge）

架构核心（自研）

Pack	Autoload	依赖	用途
`flow-core`	`FlowCore`	base	游戏模式栈、Flow 请求和结果合约
`simulation-core`	`SimulationCore`	flow-core	Tick 调度器，长生命周期状态管理
`data-core`	`DataCore`	base	数据注册表与稳定 ID 合约
`save-core`	`SaveCore`	data-core	版本化快照与原子 JSON 写入
`rules-events-core`	`RulesEventsCore`	base	事件/条件/效果执行 spine
`ui-game-shell`	—	base	Menu stack, pause overlay, modal layer, loading overlay, popup manager, settings panel, widget factory, and UI event bus
`flow-test-kit`	—	flow-core	Flow smoke fixture 与 gdUnit4 测试
`ai-testing`	`AITestingCore`	automation	AI 驱动的测试探索与覆盖率追踪
`behavior-composer`	—	data-core, rules-events-core	声明式 AI 行为编排（BehaviorProfile + 适配器）
`content-pipeline`	—	data-core, rules-events-core	内容组装管线（WeightedSelector + ContentAssembler）
`entity-composer`	—	data-core	数据驱动实体组合工厂（EntityFactory + 模板 + 组件）
`content-forge`	`ForgeBridge`	content-pipeline, entity-composer	创意表达层（模板库 + Forge CLI + 热重载）

游戏系统（第三方 Vendor）

Pack	插件	版本	依赖	何时启用
`inventory`	GLoot	3.0.1	data-core, save-core	背包与装备槽
`quest`	QuestSystem	2.0.1.4	data-core, save-core, rules-events-core	资源化任务管理
`scene-transition`	Scene Manager	1.2.0	base	场景过渡动画（fade/dissolve/shader）
`dialogue`	Dialogue Manager	3.10.4	data-core, save-core, rules-events-core	对话图/文本资源

RPG 扩展（自研）

Pack	Autoload	依赖	用途
`rpg-core`	`RPGCore`	data-core, save-core	角色/队伍/钱包/装备状态
`rpg-battle-core`	`RPGBattleCore`	rpg-core, flow-core, rules-events-core	确定性回合制战斗
`rpg-save-adapter`	`RPGSaveAdapter`	rpg-core, save-core, rules-events-core	RPG 存档适配
`rpg-test-kit`	—	rpg-core, rpg-battle-core, rpg-save-adapter	战斗回放/事件流/状态转储
`rpg-art-demo`	—	base	Asset pipeline (normalize.py + generate_scenes.py), imported character/projectile sprites, UI icons, and playable sample scaffold

Asset Pipeline

rpg-art-demo 包含一个两阶段 asset pipeline，用于将原始美术素材标准化并生成可运行的 Godot 场景：

Phase	组件	功能
Phase 1	`normalize.py`	文件重命名、目录结构标准化、动画帧分组
Phase 1	`generate_scenes.py`	自动生成 `.tscn`（AnimatedSprite2D + CollisionShape2D）
Phase 2	`AssetDB` autoload	集中式资源注册表，AssetRef 类型提供稳定 ID 和元数据
Phase 3	AI Semantic Tagging	自动为素材生成语义标签（角色、武器、地形等）

运行测试：

pytest packs/rpg-art-demo/tests/ -v

Vendor Pack Adapters

第三方 vendor pack（dialogue、quest、inventory）通过 adapter 模式与工具箱架构 pack（data-core、save-core、rules-events-core）集成，避免直接耦合：

Vendor Pack	Adapter	桥接目标
dialogue	`DialogueEventBridge`	data-core + rules-events-core
quest	`QuestEventBridge`	data-core + rules-events-core
inventory	`InventorySaveAdapter`	data-core + save-core

Adapter 提供：

Vendor 事件 → rules-events-core 事件桥接
Vendor 数据 → data-core 注册表同步
Vendor 状态 → save-core 快照序列化

详见各 pack 内的 *_adapter/ 目录。

System Assemblers

系统组装器是封装底层 pack API 的高层接口，提供 AI 友好的 create() + 信号驱动模式。PRD 描述功能时必须使用对应组装器，禁止从零手写。详见 .trellis/spec/prd-assembly-requirements.md。

功能域	组装器	所属 Pack	用途
回合制战斗	`BattleSystem`	rpg-battle-core	战斗会话、回合队列、伤害结算、奖励发放
角色成长	`ProgressionSystem`	rpg-core	EXP/Level 管理、属性提升、升级事件
任务追踪	`QuestSystem`	rpg-core	任务状态机、完成条件、奖励触发
商店交易	`ShopSystem`	rpg-core	买卖、库存、购买力检查
经济系统	`EconomySystem`	rpg-core	多货币、动态定价、汇率
存档读写	`SaveSystem`	save-core	版本化快照、自动存档、槽位管理
对话分支	`DialogSystem`	ui-game-shell	对话图解析、分支跳转、选项回调
音频管理	`AudioSystem`	ui-game-shell	BGM/SE 播放、淡入淡出、音量控制
场景切换	`SceneSystem`	ui-game-shell	背景切换、过渡动画、情绪调色板
摄像机控制	`CameraSystem`	ui-game-shell	震动、缩放、平滑跟随、平移

使用模式

所有组装器遵循统一模式：

# 1. 工厂创建
var system = SomeSystem.create(config)

# 2. 信号连接
system.some_event.connect(_on_event)

# 3. 方法调用
await system.do_something(params)

WidgetFactory UI 预制件

WidgetFactory（ui-game-shell）提供 UI 预制件，与系统组装器配合使用：

预制件	用途
`modal_dialog(config)`	确认/结果对话框
`list_menu(config)`	垂直菜单列表
`toast(config)`	自动消失提示条
`status_bar(config)`	HUD 状态条
`item_slot(data)`	背包物品槽
`equipment_slot(data)`	装备槽
`stat_row(label, value)`	属性显示行
`reward_row(data)`	奖励显示行
`character_card(data)`	角色信息卡
`shop_panel(config)`	商店界面
`item_tooltip(data)`	物品详情弹窗

依赖关系图

graph TD
    BASE["base<br/>gdUnit4 + gdtoolkit"]

    BASE --> VALID["validation<br/>Godot Doctor"]
    BASE --> DEBUG["debug<br/>Signal Lens"]
    BASE --> STATE["stateful<br/>State Charts"]
    BASE --> JUICE["juice<br/>Sparkle Lite"]
    BASE --> AUTO["automation<br/>GodotE2E"]
    BASE --> INPUT["input<br/>G.U.I.D.E"]
    BASE --> FLOW["flow-core<br/>FlowCore"]
    BASE --> DATA["data-core<br/>DataCore"]
    BASE --> RULES["rules-events-core<br/>RulesEventsCore"]
    BASE --> SHELL["ui-game-shell"]
    BASE --> ART["rpg-art-demo"]

    FLOW --> SIM["simulation-core<br/>SimulationCore"]
    FLOW --> FTK["flow-test-kit"]
    DATA --> SAVE["save-core<br/>SaveCore"]
    AUTO --> AITEST["ai-testing<br/>AITestingCore"]

    DATA --> RPGC["rpg-core<br/>RPGCore"]
    SAVE --> RPGC
    RPGC --> RPGB["rpg-battle-core<br/>RPGBattleCore"]
    FLOW --> RPGB
    RULES --> RPGB
    RPGC --> RPGSA["rpg-save-adapter<br/>RPGSaveAdapter"]
    SAVE --> RPGSA
    RULES --> RPGSA
    RPGC --> RPGTK["rpg-test-kit"]
    RPGB --> RPGTK
    RPGSA --> RPGTK

    DATA --> INV["inventory<br/>GLoot"]
    SAVE --> INV
    DATA --> QUEST["quest<br/>QuestSystem"]
    SAVE --> QUEST
    RULES --> QUEST
    DATA --> DIALOG["dialogue<br/>Dialogue Manager"]
    SAVE --> DIALOG
    RULES --> DIALOG
    BASE --> BEH["ai-behavior<br/>Beehave"]
    BASE --> SSL["save-state-lite<br/>SaveState Lite"]

    DATA --> BC["behavior-composer"]
    RULES --> BC
    DATA --> CP["content-pipeline"]
    RULES --> CP
    DATA --> EC["entity-composer"]
    CP --> CF["content-forge<br/>ForgeBridge"]
    EC --> CF

    style BASE fill:#478cbf,color:#fff
    style RPGC fill:#c0392b,color:#fff
    style RPGB fill:#c0392b,color:#fff
    style RPGSA fill:#c0392b,color:#fff
    style RPGTK fill:#c0392b,color:#fff

完整 autoload 合约和扩展依赖图见 docs/architecture.md。

一键部署（交互式）

scripts/quickstart.sh 提供交互式部署向导，自动处理依赖解析和冲突检测。

交互模式（默认）

./scripts/quickstart.sh /path/to/new-project

向导会：

按分类展示所有可选 pack
接受用户选择（逗号分隔的 pack ID）
自动解析依赖（BFS 向上收集 requires）
检测冲突（如 save-state-lite vs save-core）
显示最终 pack 列表 + 依赖关系摘要
确认后调用 bootstrap_toolbox_project.sh 执行组装

非交互模式（CI/自动化）

./scripts/quickstart.sh /path/to/new-project --packs=validation,debug --auto-deps

--auto-deps 自动解析依赖，然后调用 bootstrap_toolbox_project.sh。

验证

本地验证链

bash ./scripts/verify_toolbox_layout.sh
bash ./scripts/verify_game_architecture_packs.sh
bash ./scripts/verify_rules_events_core_pack.sh
bash ./scripts/verify_ui_game_shell_pack.sh
bash ./scripts/verify_pack_matrix.sh --all
bash ./scripts/verify_specialized_pack_candidates.sh
bash ./scripts/verify_input_pack_poc.sh
bash ./scripts/verify_bootstrap_flow.sh

verify_bootstrap_flow.sh 创建临时项目，叠加默认 packs（validation,debug,stateful,juice），然后：

Bootstrap 临时项目
godot --headless --editor --quit-after 1 --import
生成项目内 gdUnit4 smoke

CI 运行相同流程。当前 workflow 使用官方 Linux Godot 4.6.3。本地保持 4.6.x。如果 Godot 不在 PATH，设置 GODOT_BIN=/path/to/godot。

可选 pack 验证

bash ./scripts/verify_automation_pack_poc.sh
bash ./scripts/verify_dialogue_pack.sh

维护

导入新上游插件

./scripts/import_plugin_from_upstream.sh \
  --id=signal_lens \
  --repo=https://github.com/yannlemos/signal-lens \
  --target=packs/debug/godot/addons/signal_lens \
  --pack=debug \
  --version=1.4.1

升级已锁定插件

# 预览升级（dry-run）
./scripts/update_plugin_from_upstream.sh --id=signal_lens --version=1.4.1 --dry-run

# automation pack 上游升级
./scripts/update_plugin_from_upstream.sh --id=godot_e2e --dry-run

# shell 候选 pack 上游升级
./scripts/update_plugin_from_upstream.sh --id=maaacks_game_template --dry-run

贡献 & 许可

参见 CONTRIBUTING.md：

Pack 提案 — 使用 Pack Request 模板开 issue
提交规范 — Conventional Commits（feat:, fix:, docs:, test:, chore:）
PR 检查清单 — manifest/lock 一致性、验证脚本通过

本项目使用 MIT License — 详见 LICENSE。

packs/*/godot/addons/ 中的第三方插件保留各自原始许可证。完整归属摘要见 docs/rpg-vendor.md。

RPG 模板方向

RPG 相关第三方来源、vendor 版本、本地路径、吸收边界和后续任务清单见：

docs/rpg-guide.md (quickstart, recipes, sample recipe, content authoring)
docs/rpg-architecture.md (adapter boundaries, implementation plan, execution log)
docs/rpg-acceptance.md (acceptance matrix, acceptance receipt, experience review)
docs/rpg-vendor.md (vendor license notice, upgrade checklist, art sources, absorption plan)
docs/asset-pipeline-plan.md (asset normalization & runtime binding roadmap)
docs/rpg-playable-sample-recipe.md (playable sample route document)
docs/research/ — pack candidate evaluation research（plugin scout, hot plugin scan, similar projects）

当前已吸收为非默认 pack 的来源：

GLoot：https://github.com/peter-kish/gloot
QuestSystem：https://github.com/shomykohai/quest-system
Beehave：https://github.com/bitbrain/beehave
SaveState Lite：https://github.com/youssof20/savestate
Dialogue Manager：https://github.com/nathanhoad/godot_dialogue_manager

RPG 核心规则已自研落地，包括 rpg-core、rpg-battle-core、rpg-save-adapter 和 rpg-test-kit。这些内容负责角色成长、战斗规则、奖励、队伍状态和存档格式，不应由第三方插件直接持有项目真相。

Name		Name	Last commit message	Last commit date
.agents/tasks		.agents/tasks
.github		.github
.trellis		.trellis
agent		agent
docs		docs
packs		packs
research		research
scripts		scripts
showcases		showcases
templates		templates
tests		tests
tools		tools
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.roborev.toml		.roborev.toml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
LOOPEXPEDITION_SYNC.md		LOOPEXPEDITION_SYNC.md
README.md		README.md
README_EN.md		README_EN.md
gdlintrc		gdlintrc
llms.txt		llms.txt
packs.manifest.json		packs.manifest.json
pyproject.toml		pyproject.toml
tasks.json		tasks.json
upstreams.lock.json		upstreams.lock.json

Navigation Menu

Repository files navigation

godot-toolbox

目录

快速开始

交互式一键部署（新用户推荐）

手动指定 pack 组装

Showcase 项目

这个仓库做什么

Pack 目录

基线 Pack（始终包含）

开发工具（仅依赖 base）

输入 & 自动化

架构核心（自研）

游戏系统（第三方 Vendor）

RPG 扩展（自研）

Asset Pipeline

Vendor Pack Adapters

System Assemblers

使用模式

WidgetFactory UI 预制件

依赖关系图

一键部署（交互式）

交互模式（默认）

非交互模式（CI/自动化）

验证

本地验证链

可选 pack 验证

维护

导入新上游插件

升级已锁定插件

贡献 & 许可

RPG 模板方向

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

godot-toolbox

目录

快速开始

交互式一键部署（新用户推荐）

手动指定 pack 组装

Showcase 项目

这个仓库做什么

Pack 目录

基线 Pack（始终包含）

开发工具（仅依赖 base）

输入 & 自动化

架构核心（自研）

游戏系统（第三方 Vendor）

RPG 扩展（自研）

Asset Pipeline

Vendor Pack Adapters

System Assemblers

使用模式

WidgetFactory UI 预制件

依赖关系图

一键部署（交互式）

交互模式（默认）

非交互模式（CI/自动化）

验证

本地验证链

可选 pack 验证

维护

导入新上游插件

升级已锁定插件

贡献 & 许可

RPG 模板方向

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages