Codex实装，RegularGridFloor

docs/ichni-official-creatorstudio-technical-map.md

@@ -0,0 +1,394 @@
+# ichni Official / IchniCreatorStudio 技术对照文档
+
+生成日期：2026-07-08
+
+本文档记录 `ichni Official` 与 `IchniCreatorStudio` 的当前结构、同步关系和关键技术差异，供后续任务开始前快速参考。本文档基于本地仓库扫描结果，不代表所有运行时行为已经通过 Unity Editor 实机验证。
+
+## 1. 工作区与权限
+
+| 项目 | 路径 | 当前角色 | 当前写入状态 |
+| --- | --- | --- | --- |
+| `ichni Official` | `D:\Projects\ichni Official` | 游戏本体 | 可读写 |
+| `IchniCreatorStudio` | `D:\Projects\IchniCreatorStudio` | 关卡编辑器 / 内容制作工具 | 可读写 |
+
+已完成的权限验证：
+
+- `D:\Projects\IchniCreatorStudio` 已加入当前 Codex workspace writable roots。
+- 已在 `D:\Projects\IchniCreatorStudio\.codex-write-test.tmp` 执行创建、读取、删除测试。
+- 测试结果：`WRITE_RETEST_OK: codex write retest 2026-07-08`。
+
+## 2. 统一工作标准
+
+后续所有工作继续遵循 `D:\Projects\ichni Official\AGENTS.md` 中记录的标准：
+
+- 两个项目遵循统一编码规范。
+- 文档和共享资源应供所有工作区成员查阅。
+- `_BM` 后缀类是序列化存档类，本文档称为 `BM` 类。
+- 新增或修改继承自 `BaseElement` 的游戏元素时，应优先同步检查两个项目。
+- `ichni Official` 使用 `Wwise 2024.1.9.8920`。
+- `IchniCreatorStudio` 使用 Unity 原生音频。
+- `ichni Official` 使用 `Yarn Spinner`，允许修改和扩展。
+- 回复用户使用简体中文，代码、API、类名、路径和特殊术语保留英文。
+
+## 3. Unity 与 Package 基线
+
+两个项目当前 Unity 版本一致，项目文件实际记录为：
+
+- `6000.3.7f1 (696ec25a53d1)`
+
+共同关键 packages：
+
+- `com.unity.inputsystem@1.18.0`
+- `com.unity.render-pipelines.universal@17.3.0`
+- `com.unity.timeline@1.8.10`
+- `com.unity.test-framework@1.6.0`
+- `com.unity.ugui@2.0.0`
+- `com.unity.visualscripting@1.9.9`
+- `com.unity.collections@2.6.2`
+
+仅 `ichni Official` 扫描到的 package：
+
+- `com.taptap.sdk.core@4.10.4`
+- `com.taptap.sdk.login@4.10.4`
+- `com.unity.burst@1.8.27`
+- `com.unity.localization@1.5.12`
+- `com.unity.nuget.newtonsoft-json@3.2.1`
+
+仅 `IchniCreatorStudio` 扫描到的 package：
+
+- `com.unity.burst@1.8.29`
+- `com.unity.ide.vscode@1.2.5`
+- `com.unity.memoryprofiler@1.1.9`
+
+注意：两个项目的 `Burst` patch 版本不同。除非确实需要统一，否则不要为了版本一致性单独改 package。
+
+## 4. 顶层结构对照
+
+`ichni Official` 关键结构：
+
+- `Assets/Scripts/DataCore`
+- `Assets/Scripts/Game`
+- `Assets/Scripts/GameUI`
+- `Assets/Scripts/Generated`
+- `Assets/Scripts/Manager`
+- `Assets/Scripts/Menu`
+- `Assets/Scripts/NewStorySystem`
+- `Assets/Scripts/Online`
+- `Assets/Scripts/Saving`
+- `Assets/Scripts/Settings`
+- `Assets/Scripts/SLSUtilities`
+- `Assets/Story`
+- `Assets/Wwise`
+- `ichni Official_WwiseProject`
+
+`IchniCreatorStudio` 关键结构：
+
+- `Assets/Scripts/CommandSystem`
+- `Assets/Scripts/Console`
+- `Assets/Scripts/DynamicUI`
+- `Assets/Scripts/Editor Tools`
+- `Assets/Scripts/Extensions`
+- `Assets/Scripts/Game/DataCore`
+- `Assets/Scripts/Game/EditorCore`
+- `Assets/Scripts/Game/RuntimeCore`
+- `Assets/Scripts/Gird`
+- `Assets/Scripts/Manager`
+- `Assets/Scripts/Settings`
+- `Assets/Scripts/SLSUtilities`
+- `Assets/Scripts/StartMenu`
+- `NodeScript`
+
+脚本数量快照：
+
+| 项目 | `Assets/Scripts` C# | BM C# | Runtime / Game 核心 C# |
+| --- | ---: | ---: | ---: |
+| `ichni Official` | 340 | 83 | `Assets/Scripts/Game`: 102 |
+| `IchniCreatorStudio` | 401 | 87 | `Assets/Scripts/Game/RuntimeCore`: 108 |
+
+## 5. 核心架构差异
+
+### 5.1 游戏本体
+
+`ichni Official` 的核心运行入口集中在：
+
+- `Assets/Scripts/Manager/GameManager.cs`
+- `Assets/Scripts/Manager/ProjectLoader.cs`
+- `Assets/Scripts/Game`
+- `Assets/Scripts/DataCore`
+- `Assets/Scripts/NewStorySystem`
+
+它更偏向最终运行时：
+
+- 加载打包或导出的项目数据。
+- 使用 `Wwise` 播放音乐和音效。
+- 执行关卡、判定、镜头、视觉元素、故事和存档。
+- 使用 `Yarn Spinner` 驱动剧情。
+- 包含线上、登录、设置、解锁、剧情存档等玩家侧系统。
+
+### 5.2 编辑器
+
+`IchniCreatorStudio` 的核心编辑入口集中在：
+
+- `Assets/Scripts/Manager/EditorManager.cs`
+- `Assets/Scripts/Manager/ProjectManager.cs`
+- `Assets/Scripts/Game/RuntimeCore`
+- `Assets/Scripts/Game/DataCore`
+- `Assets/Scripts/Game/EditorCore`
+
+它更偏向内容制作和导出：
+
+- 管理工程文件、歌曲文件、谱面、命令脚本。
+- 在编辑器内复用大量 runtime 元素。
+- 每个可编辑元素通常还需要配套 `EditorCore` 脚本。
+- 使用 Unity 原生 `AudioSource` 和动态音频加载。
+- 导出给 `ichni Official` 使用的压缩加密 `BM` 数据。
+
+## 6. BM 与 BaseElement 同步关系
+
+### 6.1 BM 覆盖情况
+
+当前 BM 文件名对照结果：
+
+- `ichni Official` BM 文件名数量：100
+- `IchniCreatorStudio` BM 文件名数量：105
+- `ichni Official` 中存在但 `IchniCreatorStudio` 中缺失：0
+- `IchniCreatorStudio` 中存在但 `ichni Official` 中缺失：5
+
+`IchniCreatorStudio` 额外存在的 BM：
+
+- `Custom2DShape_BM.cs`
+- `DisplacementTracker_BM.cs`
+- `ScaleTracker_BM.cs`
+- `SwirlTracker_BM.cs`
+- `Vector3Interferometer_BM.cs`
+
+共同 BM 文件中，只有少数内容完全一致，大多数同名 BM 在两个项目中存在实现差异。这是正常现象，因为编辑器侧需要保存、复制、编辑器行为或导出行为，游戏本体侧需要执行和运行时加载。
+
+重要规则：不要因为同名就直接覆盖 BM 文件。任何 BM 同步都应逐个比较字段、`ExecuteBM()`、`AfterExecute()`、`SaveBM()`、`DuplicateBM()` 和导出兼容性。
+
+### 6.2 BaseElement 差异
+
+`ichni Official`：
+
+- `Assets/Scripts/Game/Base/BaseElement.cs`
+- `IBaseElement` 包含 `matchedBM`、`Refresh()`、`OnDelete()`、`Delete()`、`SetUpInspector()`。
+- `Assets/Scripts/Game/GameElements/Essential/GameElement.cs` 更偏运行时生命周期。
+
+`IchniCreatorStudio`：
+
+- `Assets/Scripts/Game/RuntimeCore/Base/BaseElement.cs`
+- `IBaseElement` 在运行时接口基础上额外包含 `SaveBM()`。
+- `Assets/Scripts/Game/RuntimeCore/GameElements/Essential/GameElement.cs` 额外有 `SetEditorSubmodules()`。
+- `Assets/Scripts/Game/DataCore/Base_BM/GameElement_BM.cs` 额外包含 `DuplicateBM(GameElement attached)`。
+
+新增 `BaseElement` 派生元素时，通常需要同时考虑：
+
+- Official runtime script
+- Official `BM` script
+- Creator `RuntimeCore` script
+- Creator `DataCore` / `BM` script
+- Creator `EditorCore` inspector 或编辑交互脚本
+- 主题包内对应 runtime、data、editor 三侧脚本
+
+## 7. 存档、加载与导出
+
+### 7.1 Official 加载
+
+关键文件：
+
+- `D:\Projects\ichni Official\Assets\Scripts\Manager\ProjectLoader.cs`
+
+当前扫描到的核心设置：
+
+- `SaveSettings`: `compressionType=None`, `encryptionType=None`, `format=JSON`, `location=Resources`
+- `LoadSettings`: `compressionType=Gzip`, `encryptionType=AES`, `format=JSON`, `location=Resources`
+
+主要加载对象：
+
+- `ProjectInformation_BM`
+- `SongInformation_BM`
+- `BeatmapContainer_BM`
+- `CommandScripts_BM`
+
+加载后通过 `ExecuteBM()` 生成运行时对象。
+
+### 7.2 Creator 保存与导出
+
+关键文件：
+
+- `D:\Projects\IchniCreatorStudio\Assets\Scripts\Manager\ProjectManager.cs`
+
+当前扫描到的核心设置：
+
+- `SaveSettings`: `compressionType=None`, `encryptionType=None`, `format=JSON`
+- `ExportSettings`: `compressionType=Gzip`, `encryptionType=AES`, `format=JSON`
+
+导出流程通常会：
+
+- 调用 `SaveBM()`
+- 写出 `ProjectInformation`
+- 写出 `SongInformation`
+- 写出 `Beatmap`
+- 写出 `CommandScripts`
+
+这说明 `IchniCreatorStudio` 是 Official 可加载资源的重要源头。改动序列化字段时，必须同时确认保存、导出和 Official 加载链路。
+
+## 8. 音频系统差异
+
+### 8.1 Official: Wwise
+
+Official 使用：
+
+- `Assets/Wwise`
+- `ichni Official_WwiseProject`
+- `Assets/Scripts/Manager/SongPlayer.cs`
+- `Assets/Scripts/SLSUtilities/WwiseAssistance/AudioManager.cs`
+
+Wwise 版本：
+
+- Wwise SDK `2024.1.9 Build 8920`
+- Unity Integration Bundle `2024.1.9.3788`
+
+Official 音频特点：
+
+- 使用 `AK.Wwise.Event`、`RTPC` 和 `AkUnitySoundEngine`。
+- `SongPlayer` 通过 Wwise event 播放音乐，并读取 segment position。
+- `LowPassFilterEffect` / `HighPassFilterEffect` 通过 Wwise RTPC 控制滤波效果。
+- 音频事件、RTPC、bank 和 Unity 侧引用需要保持一致。
+
+### 8.2 Creator: Unity Native Audio
+
+Creator 使用：
+
+- `Assets/Scripts/Manager/MusicPlayer.cs`
+- `Assets/Scripts/Manager/EditorManager.cs`
+- `Assets/Scripts/Game/RuntimeCore/Base/ProjectFiles/SongInformation.cs`
+- `Assets/Scripts/Game/RuntimeCore/Base/ProjectFiles/NoteAudioCollection.cs`
+
+Creator 音频特点：
+
+- 使用 `AudioSource`、`AudioClip` 和 `AudioMixerGroup`。
+- `SongInformation` 负责加载音频文件。
+- 包含自定义 `LoadMP3` 和 `LoadWav` 流程。
+- `MusicPlayer` 实现 `ISongTimeProvider`，供编辑器时间轴使用。
+
+音频相关游戏元素或效果不能直接从 Official 复制到 Creator。Official 侧通常要接 Wwise，Creator 侧通常要接 Unity 原生音频和编辑器预览。
+
+## 9. 剧情系统
+
+`ichni Official` 使用 `Yarn Spinner`，主要集中在：
+
+- `D:\Projects\ichni Official\Assets\Story`
+- `D:\Projects\ichni Official\Assets\Scripts\NewStorySystem`
+
+已扫描到的关键文件：
+
+- `Assets/Story/Chapter0/Chapter0.yarnproject`
+- `Assets/Story/Chapter0/C0_A0.yarn`
+- `Assets/Story/Chapter0/StoryData_Chapter0.asset`
+- `Assets/Story/Chapter0/CharacterRegistry.asset`
+- `Assets/Scripts/NewStorySystem/StoryDialogueController.cs`
+- `Assets/Scripts/NewStorySystem/YarnFunctions/VariableFunctions.cs`
+- `Assets/Scripts/NewStorySystem/YarnFunctions/StoryTreeCommands.cs`
+- `Assets/Scripts/NewStorySystem/YarnFunctions/PortraitCommands.cs`
+
+当前 `Chapter0.yarnproject` 关键信息：
+
+- `projectFileVersion`: 4
+- `sourceFiles`: `**/*.yarn`
+- `baseLanguage`: `en`
+- 已配置 `zh-CN` localisation
+- 当前 editor options 中可见角色：`SLS`、`Asahi`
+
+`IchniCreatorStudio` 当前没有扫描到对应 Yarn 资源。剧情系统修改一般只影响 Official，除非未来编辑器需要制作剧情内容。
+
+## 10. ThemeBundle 与元素扩展
+
+两个项目都包含主题包结构，例如：
+
+- `Basic`
+- `DepartureToMultiverse`
+- `MetropolisOnOrbit`
+- `Shapes`
+
+主题包脚本通常按职责拆分：
+
+- Official: runtime + data/BM
+- Creator: runtime + data/BM + editor
+
+示例：
+
+- Official `DepartureToMultiverse` 包含 `DTMTrail.cs`、`DTMStarrySkybox.cs`、`DTMRandomGridFloor.cs` 等 runtime 脚本，以及对应 `*_BM.cs`。
+- Creator `DepartureToMultiverse` 除 runtime 和 `*_BM.cs` 外，还包含 `DTMTrail_Editor.cs`、`DTMStarrySkybox_Editor.cs`、`DTMRandomGridFloor_Editor.cs` 等编辑器脚本。
+- Creator `Basic` 中存在 `Custom2DShape_BM.cs` 和 `Custom2DShape_Editor.cs`，但 Official 当前没有同名 BM 文件。
+
+新增主题包元素时，应先找同主题下已有元素作为模板，再分别实现 Official runtime/BM 与 Creator runtime/BM/editor。
+
+## 11. 当前同步风险与注意事项
+
+1. BM 文件名高度重合，但内容大多不一致。
+   - 不能机械同步。
+   - 字段变更必须评估导出兼容性和旧数据加载。
+
+2. Creator 覆盖了所有 Official BM 文件名，并多出 5 个 BM。
+   - 如果 Official 后续需要加载这些 Creator-only 元素，Official 需要新增对应 runtime/BM 支持。
+
+3. Official 与 Creator 的音频系统不同。
+   - Official: `Wwise`
+   - Creator: Unity native audio
+   - 音频效果和播放逻辑必须双实现或抽象到共同时间接口。
+
+4. Official 有剧情系统，Creator 当前没有。
+   - 修改 `Yarn Spinner` 或 `NewStorySystem` 前不应假设 Creator 有对应编辑器支持。
+
+5. Creator 有 `EditorCore`，Official 没有。
+   - 元素编辑能力通常不能只靠 runtime/BM 实现。
+
+6. 当前两个仓库均存在工作区未提交或未跟踪文件。
+   - 后续修改前应先检查 `git status`。
+   - 不要还原或覆盖用户已有改动。
+
+## 12. 后续任务检查清单
+
+修改或新增 `BaseElement` / 游戏元素时：
+
+- 检查 Official runtime 脚本。
+- 检查 Official `BM` 脚本。
+- 检查 Creator `RuntimeCore` 脚本。
+- 检查 Creator `DataCore` / `BM` 脚本。
+- 检查 Creator `EditorCore` 脚本。
+- 检查主题包内是否有同类元素模板。
+- 检查 `SaveBM()`、`ExecuteBM()`、`AfterExecute()`、`DuplicateBM()`。
+- 检查旧数据加载和导出兼容性。
+- 如果涉及音频，分别实现 Wwise 侧和 Unity native audio 侧。
+- 如果涉及剧情，只默认影响 Official，除非明确要求 Creator 支持剧情编辑。
+
+修改 BM 字段时：
+
+- 确认字段默认值。
+- 确认序列化名称和旧文件兼容性。
+- 确认 Creator 保存和导出。
+- 确认 Official 加载和执行。
+- 尽量准备一个最小导出样例进行回归验证。
+
+修改 package、Unity 版本或项目设置时：
+
+- 不要只改一个项目，除非差异有明确原因。
+- 先确认 `Packages/manifest.json` 和 `ProjectSettings/ProjectVersion.txt`。
+- 记录差异原因。
+
+## 13. 关键文件索引
+
+| 主题 | Official | Creator |
+| --- | --- | --- |
+| 工作标准 | `D:\Projects\ichni Official\AGENTS.md` | `D:\Projects\IchniCreatorStudio\AGENTS.md` |
+| Unity 版本 | `D:\Projects\ichni Official\ProjectSettings\ProjectVersion.txt` | `D:\Projects\IchniCreatorStudio\ProjectSettings\ProjectVersion.txt` |
+| Packages | `D:\Projects\ichni Official\Packages\manifest.json` | `D:\Projects\IchniCreatorStudio\Packages\manifest.json` |
+| Runtime elements | `D:\Projects\ichni Official\Assets\Scripts\Game` | `D:\Projects\IchniCreatorStudio\Assets\Scripts\Game\RuntimeCore` |
+| BM data | `D:\Projects\ichni Official\Assets\Scripts\DataCore` | `D:\Projects\IchniCreatorStudio\Assets\Scripts\Game\DataCore` |
+| Editor scripts | 无统一 `EditorCore` | `D:\Projects\IchniCreatorStudio\Assets\Scripts\Game\EditorCore` |
+| Official loader | `D:\Projects\ichni Official\Assets\Scripts\Manager\ProjectLoader.cs` | 不适用 |
+| Creator save/export | 不适用 | `D:\Projects\IchniCreatorStudio\Assets\Scripts\Manager\ProjectManager.cs` |
+| Official audio | `D:\Projects\ichni Official\Assets\Scripts\Manager\SongPlayer.cs` | 不适用 |
+| Creator audio | 不适用 | `D:\Projects\IchniCreatorStudio\Assets\Scripts\Manager\MusicPlayer.cs` |
+| Story/Yarn | `D:\Projects\ichni Official\Assets\Scripts\NewStorySystem` | 当前无对应系统 |