framework
GameKitCore 游戏框架(godot-rust GDExtension)GDScript 侧用法手册。当需要用该框架创建游戏项目代码、组装场景节点、编写战斗/对话/地图/UI/数据/协程等功能的 GDScript 示例时使用。按功能模块分类,每个模块文档含真实可用的 GDScript 示例代码与 API 签名。
SKILL.mdskills/framework/SKILL.md
GitHubGameKitCore 框架用法手册
本 skill 是 gamecore 框架的 GDScript 侧用法参考。框架结构(Rust 模块划分)见
rust/src/FRAMEWORK.md;本 skill 只回答"怎么用"。可运行的完整示例在 example/ 各目录。
使用规则
- 写游戏代码前,先按功能查对应模块文档(
references/),示例代码可直接套用。 - 框架类均为 GDExtension 类(
Gd前缀),直接GdXxx.new()或在场景中挂载即可,无需 preload。 - 单例通过
Engine.get_singleton("名字")获取,共 5 个:GDCORE、GdConsole、GDEVENTBUS、GDSPAWNPOOL、GDDEBUGDRAW。 - 节点组装后属性赋值必须在
add_child之前/之后遵循各文档说明;export 属性可直接节点.属性 = 值。
模块索引
| 模块文档 | 覆盖内容 | 对应 Rust 源码 |
|---|---|---|
| references/scene-manager.md | 场景切换/页面栈、全局暂停、设置持久化、相机、音频、输入 | rust/src/manager/ |
| references/role.md | 角色移动/动画驱动/NPC AI 行为 | rust/src/role/ |
| references/combat.md | 血量/攻击受击判定/射击/子弹、对象池、事件总线、调试绘制 | rust/src/components/ pool/ event/ debug/ |
| references/dialogue.md | 对话控制、触发器、角色绑定、对话 UI 回调 | rust/src/dialog/ |
| references/map.md | 双网格地形地图、噪声生成、寻路、网格移动联动 | rust/src/map/ |
| references/environment.md | 天气系统(白天/夜晚/雨/雪/风)、画布绘图 | rust/src/environment/ drawer/ |
| references/state-data.md | GDCore 单例、GdCoreData 存档数据、GdBean 数据绑定 | rust/src/state/ |
| references/coroutine.md | 协程等待原语、可暂停协程任务 | rust/src/runtime/ |
| references/ui-gml.md | GML 标记语言 UI、列表控件、弹窗、主题、Bean 数据驱动 | rust/src/ui/ |
| references/console.md | Lua 调试控制台、注册命令 | rust/src/console/ |
| references/rogue.md | 肉鸽卡牌引擎、实体生成、卡堆 | rust/src/rogue/ |
全局约定(必读)
场景结构
Main (GdSceneRoot) # 场景管理器根节点
└── Game (业务脚本, PROCESS_MODE_PAUSABLE)
├── World (游戏世界节点)
└── HUD (CanvasLayer, PROCESS_MODE_ALWAYS)
- 场景切换统一走
GdSceneRoot.change_scene(),不要用get_tree().change_scene_to_file()(绕过页面栈与转场)。 - 全局暂停用
GdSceneRoot.set_game_paused(),不要直接改get_tree().paused;HUD 等需要在暂停时响应的节点设process_mode = Node.PROCESS_MODE_ALWAYS。
碰撞层约定(战斗)
| 层 | 值 | 用途 |
|---|---|---|
| layer 2 | 2 | 玩家受击盒(GdHurtbox) |
| layer 3 | 4 | 敌方受击盒(GdHurtbox) |
- 子弹(GdBullet)
collision_mask = 4;敌方 Hitboxcollision_mask = 2。 - Hitbox 的
collision_mask永远指向目标 Hurtbox 所在 layer。
角色组装公式
Player (GdRoleMover)
├── AnimatedSprite2D / GdRoleAnimator
├── GdHealth (max_health / invincible_time)
├── GdHurtbox + CollisionShape2D (collision_layer=2, mask=0)
├── GdShooter (玩家) 或 GdNpcBrain (NPC)
└── GdRoleSpeaker + GdDialogTrigger (需要对话的 NPC)
缓动与 juice
rust/src/anim/(easing/juice/EaseMover)为 Rust 内部实现,无 GDScript 导出;
GDScript 侧动画直接用原生 create_tween()。
无头测试红线(demo 实测沉淀)
- 无头帧率不节流:
await process_frame帧数 ≠ 墙钟时间(900 帧可 <1s), 等真实时间流逝的轮询必须用Time.get_ticks_msec()墙钟时限 - lambda 按值捕获标量:GDScript lambda 内
counter += 1改的是副本, 计数断言用 Array.append 收集 - rust 扩展类
get_class()返回注册类名(如 GdDigLayer 而非基类 GdQuickMap),类型断言勿写死基类 - 改 tscn 数值必 grep 测试硬断言(旧数值硬编码连带失败的教训)
- 装配期重入:do_swap_scene rust 栈内场景
_ready禁调组件表方法—— 引导/事件宿主用节流轮询(0.5s)或_process快照,不用 Bean watch