Soullies/ichni_Official
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d474a8929c15685955098356af8c54efffec2cfc
ichni_Official/docs/ichni-official-creatorstudio-technical-map.md
SoulliesOfficial d474a8929c Codex实装，RegularGridFloor
2026-07-08 04:29:20 -04:00

14 KiB
Raw Blame History

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 当前无对应系统
Reference in New Issue View Git Blame Copy Permalink