# guga_prototype **Repository Path**: zhengyigitee/guga_prototype ## Basic Information - **Project Name**: guga_prototype - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-11 - **Last Updated**: 2026-11-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # guga_prototype Godot **4.7** 原型仓库,用来存放独立的小原型。 原则:**一个原型 = 一个目录**,主场景、脚本、素材全部关在自己目录里,原型之间不互相引用。 ## 运行 - 用 Godot 4.7 打开本目录的 `project.godot`,按 **F5** 运行当前主场景(现为原型 **7**:战斗音效)。 - 打开某个原型的 `.tscn` 后按 **F6**,可以单独运行该原型,不必改全局配置。 - 本机引擎:`D:/Godot_v4.7.1-stable_mono_win64/Godot_v4.7.1-stable_mono_win64.exe` - 渲染方式:`GL Compatibility`(纯 2D,不依赖 D3D12 设备)。 - 本机引擎是 **mono 版**且未装 .NET 10 SDK,打开编辑器时会打印一条 `ERROR: .NET Sdk not found`。本项目**不含任何 C# 代码**,该提示可忽略,F5 运行不受影响。 ## 目录规范 ``` guga_prototype/ ├── project.godot 全局配置:主场景、窗口、输入映射 ├── README.md 本文件 └── prototypes/ ├── p01_arena/ 原型 1:竞技场(背景叠放 / 移动 / 两套边界) │ ├── arena.tscn 主场景(唯一入口) │ ├── scripts/ 本原型专用脚本 │ ├── assets/ 本原型专用素材 │ └── README.md 本原型说明 ├── p02_weapons/ 原型 2:自动武器 / 训练木桩 ├── p03_combat/ 原型 3:战斗组件 / 怪物追踪 ├── p04_scenes/ 原型 4:场景拆分 / 数据驱动 │ ├── arena.tscn 装配根(只放实例与容器) │ ├── scenes/ 人物 / 怪物 / 武器 / 木桩 / HUD 等独立场景 │ │ └── weapons/ 三把武器各自的 .tscn │ ├── data/ P4UnitData 怪物数据资源(.tres) │ ├── scripts/combat/ 通用战斗组件 │ ├── scripts/weapons/ 武器基类与子类 │ ├── assets/ 本原型专用素材 │ └── README.md 本原型说明 + 扩展指南 ├── p05_impact/ 原型 5:受击闪烁 / 方向击退 ├── p06_loot/ 原型 6:金币掉落 / 拾取音效 │ ├── scenes/coin.tscn 独立金币场景 │ ├── data/ P6UnitData(含 coin_drop_min/max) │ └── assets/ coin.png / coin_pickup.wav └── p07_sound/ 原型 7:战斗音效 / 集中音效库 ├── arena.tscn 装配根,新增 Sfx 节点 ├── scenes/sfx.tscn 音效库(1 个 Bank + 5 条 Channel) ├── scripts/ p7_sfx_bank.gd / p7_sfx_channel.gd ├── assets/ slash / thrust / shoot / monster_hit / coin_pickup.wav └── README.md 本原型说明 + 扩展指南 ``` 原型 2 复制了原型 1、原型 3 复制了原型 2、原型 4 重构了原型 3 的结构、原型 5 扩展受击反馈、原型 6 扩展战利品闭环、原型 7 扩展战斗音效,而不是互相引用:每个原型自洽,改一个不会弄坏另一个。代价是全局类名要分别加 `P2` / `P3` / `P4` / `P5` / `P6` / `P7` 前缀避免重名,这是刻意的取舍。 **原型 4 起结构升级**:`arena.tscn` 不再包含人物 / 怪物 / 武器的内部节点,只做装配;人物、怪物、武器、木桩、箭矢、伤害字、HUD 各自是独立 `.tscn`,怪物数值抽成 `P4UnitData` 数据资源。新增怪物只需加一份 `.tres`,新增武器只需加一份 `.tscn` + 一个子类。详见 `prototypes/p04_scenes/README.md`。 **原型 5 新增受击反馈**:伤害链路从「一个数值」扩成「数值 + 攻击方向 + 击退力度」,由通用组件 `P5HitFeedback` 统一处理玩家与怪物的闪烁和沿攻击方向的推力;击退以附加速度叠加进各自移动,仍遵守人物中心边界 clamp。详见 `prototypes/p05_impact/README.md`。 **原型 6 新增战利品闭环**:敌人死亡时按怪物 `P6UnitData` 的 `coin_drop_min/max` 掉金币,金币弹散 → 漂浮 → 磁吸 → 拾取,掉落数量写在 `.tres` 里。详见 `prototypes/p06_loot/README.md`。 **原型 7 新增集中音效库**:`scenes/sfx.tscn` 用一个 `P7SfxBank` + 5 条 `P7SfxChannel` 管全部音效(挥砍 / 刺击 / 发射 / 怪物受击 / 金币拾取),每条音轨独立配置播放器池、音量与节流;武器 `.tscn` 只写 `attack_sfx_key`,怪物 `HitFeedback` 只写 `hurt_sfx_key`,调用方通过 `sfx_bank` 组解析,不依赖固定 `NodePath`。新增音效 = 加一个 Channel 子节点,零代码改动。详见 `prototypes/p07_sound/README.md`。 > 复制原型时注意两类坑: > ① `.tscn` 里像 `name="P4"` 这样恰好等于类名前缀的节点标签会被机械替换误伤,造成同名节点与引擎泄漏警告(原型 5 踩过,复制脚本已用正则保护)。 > ② 被编辑器保存过的 `.tscn` 会带 `uid://`,复制后 uid 仍指向旧原型的资源,Godot 按 uid 优先解析会加载错脚本(原型 7 的 `rapier.tscn` 踩过,轻剑整个消失)。**复制场景时剔除陈旧 uid,只留 path**。 ## 新增一个原型 1. 在 `prototypes/` 下新建 `pNN_xxx/`,按上面四件套组织(原型 4 起可再加 `scenes/` 与 `data/`)。 2. 不引用其它原型的脚本或素材;确有公共代码时再单独提取,避免原型之间互相污染。 3. 把 `project.godot` 的 `run/main_scene` 指向新原型的 `.tscn`;或直接用 **F6** 运行新场景。 4. 需要新的全局按键时,在 `project.godot` 的 `[input]` 段里加动作,脚本里统一用 `Input.get_vector()` 之类读取。 ## headless 验证 ``` # 导入 + 全局类注册 + 语法检查 Godot_console.exe --headless --path <项目> --editor --quit # 真实运行主场景 Godot_console.exe --headless --path <项目> --fixed-fps 60 --quit-after 600 # 结构化断言(外部 SceneTree 脚本,结果写入 _process/pN_result.txt) Godot_console.exe --headless --path <项目> --fixed-fps 60 --script <绝对路径 .gd> ``` 外部断言脚本不要引用项目内的 `class_name`(会解析失败卡住),不要用 `log()` 作自定义函数名(与内置数学函数冲突),`extends SceneTree` 里直接调 `get_first_node_in_group()` 而不是 `get_tree()`。**必须加 `--fixed-fps 60`**,否则 headless 帧 delta 过小,游戏时间推进不足,怪物移动与复活计时都不准。 ## 全局输入映射 | 动作 | 按键 | | --- | --- | | `move_left` | A / ← | | `move_right` | D / → | | `move_up` | W / ↑ | | `move_down` | S / ↓ | `F1`(切换边界调试线)由原型脚本直接判定键码,不占用全局动作;原型 2 起另有 `F2` 探测圈、`F3` 生成点。 > headless 没有音频设备,只能验证音效的调用链路与计数,真实听感请按 **F5** 手动确认。