# 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` | 当前无对应系统 |