WooFramework：面向 Godot 与 AI 协作的轻量框架
项目文档

WooFramework：面向 Godot 与 AI 协作的轻量框架

WooFramework 是一个基于 Godot 4.6+ 的轻量框架，核心目标是让你用更少样板代码完成可维护的模块化项目，同时让 AI 能稳定参与工程开发。

WooFramework 是什么

WooFramework 是一个基于 Godot 4.6+ 的轻量框架，核心目标是让你用更少样板代码完成可维护的模块化项目，同时让 AI 能稳定参与工程开发。

它不复刻传统重框架，而是围绕 Godot 原生能力组织出一套清晰约定：

  1. 状态优先使用 Resource（可编辑、可序列化、可复用）。

  2. 写操作走 CommandBus，读操作走 QueryService。

  3. 跨模块广播走 EventBus。

  4. 业务按 module.gd 为入口进行注册与生命周期管理。

  5. 运行入口统一由 WooBootstrap + WooApp 管理。

解决什么问题

当项目从原型走向中型规模时，常见问题是：

  1. 场景脚本变成“上帝类”，逻辑和 UI 搅在一起。

  2. 状态分散在节点树里，不好保存、复盘和测试。

  3. 团队协作时目录和命名不统一，AI 生成代码风格漂移。

WooFramework 通过“模块边界 + 总线协作 + 文本优先资产”解决这些问题。

核心架构图

flowchart TD A[WooBootstrap] --> B[WooApp] B --> C[ModuleRegistry] B --> D[ModelStore] B --> E[CommandBus] B --> F[QueryService] B --> G[EventBus] B --> H[SystemRegistry] C --> I[module.gd] I --> D I --> E I --> F I --> H J[View/Controller] --> E J --> F E --> D E --> G

运行生命周期

sequenceDiagram
    participant Boot as WooBootstrap
    participant App as WooApp
    participant Registry as ModuleRegistry
    participant Module as module.gd

    Boot->>App: boot(owner)
    Boot->>Registry: boot_from_roots(module_root_paths)
    Registry->>Module: register(registrar)
    Registry->>Module: initialize(context)
    Registry->>Module: ready(context)
    Boot->>App: mount_root_scene(startup_scene)

目录结构

res://addons/woo_framework/
  core/      # 运行时核心：app/module/model/bus/command/query/system
  editor/    # 模板与构建工具
  examples/  # 官方示例模块
  tests/     # 单测与集成测试

你会直接用到的核心对象

  1. Woo.get_app()：拿到 WooApp。

  2. app.commands.execute(command_id, payload)：执行写操作。

  3. app.queries.query(query_id, payload)：执行读操作。

  4. app.models.get_model(model_id)：拿模型实例。

  5. app.systems.get_system(system_id)：拿系统实例（如 SaveSystem、SceneSystem）。

适合什么项目

  1. 需要快速迭代玩法的原型或独立游戏。

  2. 希望把业务按模块拆分并行开发的团队。

  3. 希望 AI 能稳定生成 .gd/.tscn/.tres 且能融入项目结构的工程。

评论