395 lines
14 KiB
Markdown
395 lines
14 KiB
Markdown
# 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` | 当前无对应系统 |
|