cc8887 / Godot-Locomotion

# Godot ALS
## Lyra Release：资源配置与测试
Lyra Release v0.2.1-lyra 提供与 tag 对应的 ALS 和 Lyra 资源。下面是 Windows 上运行本版本的流程；源代码 zip 本身不含资源，需要同时下载 ALS 资源包和全部 Lyra 分包。
### 1. 准备工具与对应版本的代码
安装 **Godot 4.7.2 .NET/Mono、.NET 8 SDK、PowerShell 7**。使用 Godot 的 `*_console.exe` 可以直接查看导入和测试日志。下载本 Release 的资源后，无需安装 UE 或重新导出动画。
 [code] 
已有检出可以先 `git fetch origin --tags`，再切到 `v0.2.1-lyra`。导出清单随当前资源生成，不锁定某个历史资产批次；校验器检查清单与本次导出文件一致，保留引擎导出的原始资源名称。JSON 资源应保持原始字节，避免手工格式化造成清单不一致。
### 2. 下载、校验并解压资源包
从上述 Release 页面下载 ALS ZIP、全部 Lyra `partNN.zip` 分包及 `SHA256SUMS.txt`。也可以安装 GitHub CLI 后在仓库根目录运行：
 [code] 
每个 zip 内已带 `assets/generated/` 路径，**解压目标是仓库根目录**，不要解压到 `assets/generated/` 后形成双层目录。Lyra 分包是独立 ZIP，应全部解压到同一位置，不需要先拼接文件。校验脚本逐文件检查整组资源的大小和 SHA-256；缺少任意分包中的文件会报错，成功时输出两条 `GODOT_RELEASE_RESOURCES_OK`。
| 解压后的目录 | 内容与用途 |
| --- | --- |
| `assets/generated/als_v4/` | ALS 模型、骨架、动画 FBX、纹理、导出清单及 `compiled/als_animation_set.tres`；ALS 和 Lyra 的人物渲染都使用它 |
| `assets/generated/als_v4_raw/` | ALS 原始动画源 JSON，供 ALS 运行链及相关回归读取 |
| `assets/generated/lyra_als/` | 已重定向到 ALS 骨架的 Unarmed/Pistol/Rifle 动画、武器模型与纹理、Main/Linked Layer/Rig 配置、曲线、属性、通知、Montage，以及当前本地导出的原生参考数据 |
| `resource-bundles/` | 两包的版本与逐文件哈希清单；不参与动画运行 |
资源包保留 FBX/PNG/JSON/TRES 的原始字节，排除 `.import` 和 `.godot` 缓存；Godot 会在首次导入时重新生成缓存。Lyra 包同时包含原生参考轨迹，解压后的资源需要约 **12 GB** 磁盘空间。`native_win64/LyraNativeMath.dll` 是可选 Win64 数值桥，已随包提供；运行 Main RootYaw 也支持托管回退，不需要为普通 Demo 安装 MSVC。
### 3. 构建、首次导入并启动 Lyra
在仓库根目录执行：
 [code] 
启动参数放在 `--` 后。`--lyra-profile=unarmed`、`pistol`、`rifle` 选择初始装备，`--lyra-characters=10` 加入九个 NPC。省略 `--locomotion=lyra` 会运行默认 ALS Demo；Godot 编辑器直接 F5 也默认启动 ALS。**v0.2.1-lyra 的默认入口支持下方的运行时切换。**`res://scenes/demo/lyra_locomotion_demo.tscn` 保留为独立 Lyra 场景及自动回归入口，旧 `lyra_unarmed_demo.tscn` 只用于早期独立诊断。
### 在同一 Demo 中切换 ALS／Lyra（main）
资源就绪后，F5 或运行 `scenes/demo/als_demo.tscn`，按 **F6** 在 ALS 与 Lyra 主控间切换；也可直接点击顶部的 ALS／Lyra 按钮。默认鼠标可见且自由移动，按 Esc 主动捕获后可转动视角，再按 Esc 或切到其他窗口即可释放；返回窗口不会自动捕获。`--locomotion=lyra` 选择初始 Lyra，省略或传 `--locomotion=als` 则以 ALS 启动。
切换共用原场景的地形、移动平台和相机输入，交接脚底位置、朝向、世界速度与蹲伏状态；行走、跑动和空中均可切换。两套动画各自初始化，上一主控的运行时停止更新和碰撞。ALS 的 Overlay、旋转／相机模式及 Lyra 的装备选择分别记忆；Q/E/R 按当前系统解释，HUD 显示当前模式。翻滚、攀爬、Ragdoll／起身和 Lyra Montage 期间先记录请求，动作结束后接管；Ragdoll 需要先用 G 恢复角色。目标资源缺失或初始化失败时保留当前主控，并显示失败原因。
传 `--lyra-characters=10` 时，在首次进入 Lyra 后创建九个 NPC；切回 ALS 时这些 NPC 继续在同一个世界运行。仅使用 ALS 可以先安装 ALS 资源，首次切换 Lyra 时需要对应的 Lyra 资源。
以下测试通过默认入口使用 F6 实际按键和切换请求，覆盖两个初始模式、移动／蹲伏／空中交接、装备记忆、动作延后和失败恢复，每次输出独立报告：
 [code] 
| Lyra 输入 | 行为 |
| --- | --- |
| `W/A/S/D`、鼠标 | 移动、转向视角 |
| `Alt`、`Ctrl`、`Space` | 行走、切换蹲伏、跳跃 |
| `Q` | 循环切换 Unarmed/Pistol/Rifle 的装备 Layer |
| 鼠标右键、左键 | ADS 瞄准、开火 |
| `R`、`E` | 换弹、Emote；移动可打断 Emote |
| `Esc` | 切换鼠标捕获 |
这里的 `R/Q/E` 是 Lyra 的操作，与下面 ALS 操作表中的翻滚/Overlay/道具不同。人工检查步枪方向时，先按住 W 前进，再松开 W 并按 D 右移；短起步切换和持续前进后的切换都应检查。再测试 ADS、蹲伏、换装，以及场景中的台阶、斜坡和落差。
### 4. 自动测试 Lyra
资源校验、构建和首次导入完成后，关闭交互式 Demo，再运行可重复的 Release 测试入口。它使用传入的 Godot 路径，每次创建新的日志/报告目录，不依赖开发机历史 `artifacts/lyra-analysis/` 文件。
 [code] 
每个 Main 场景实际运行 8 秒物理帧，包含取消重试和最终 Rig→ALS 蒙皮检查；地形场景使用自身完整轨迹。成功时输出 `LYRA_RELEASE_TESTS_OK`，日志和