# ichni 编辑器指南

## 前言
ichni Editor 是一款功能强大的 3D 谱面编辑器（被戏称为“建模软件”），相比 arcade/RPE 等工具更复杂。  
**新手建议**：在编辑器中实操体验，结合本指南学习。  
**反馈渠道**：教程问题请向 sls 反馈（更新速度存疑）。

---

## 一、新建项目
| 配置项               | 说明                                                                 |
|----------------------|----------------------------------------------------------------------|
| **Project Name**     | 谱面名称，建议格式：`曲名 + 空格 + 难度名`（例：`SongName Hard`）    |
| **Creator**          | 谱师名称/马甲                                                        |
| **BPM**              | 固定节拍值（因 ichni 按秒存储谱面，且变 BPM 场景极少）               |
| **Delay**            | 谱面整体时间偏移：负数=提前开始，正数=延后开始（推荐优先裁剪音频）   |
| **Song Location**    | 音频文件路径（导入后与原文件无关）                                   |
| **Theme Bundle**     | 主题包选择（后续详解）                                               |

> **BPM 工具参考**：  
> - [BPM 概念解释](https://cn.bing.com/search?q=歌曲bpm是什么&FORM=QSRE1)  
> - [BPM 检测工具](https://vocalremover.org/zh/key-bpm-finder)

---

## 二、快捷键速查
### 场景操作
| 按键          | 功能                 |
|---------------|----------------------|
| **W/A/S/D**   | 前后左右移动相机     |
| **E/Q**       | 上/下移动相机        |
| **鼠标右键**  | 按住旋转相机         |

### 轨道操作
| 快捷键       | 功能                     |
|--------------|--------------------------|
| `Alt + P`    | 显示/隐藏路径节点        |
| `Alt + D`    | 启用/禁用轨道路径显示    |

### 工作流
| 快捷键       | 功能                     |
|--------------|--------------------------|
| `Ctrl + S`   | 保存项目                 |
| `Ctrl + E`   | 导出项目                 |
| `Ctrl + C/V` | 复制/粘贴选中元素        |
| `Ctrl + D`   | 删除选中元素             |

### 显示控制
| 快捷键         | 功能                         |
|----------------|------------------------------|
| `Ctrl + 1/2/3` | 切换手机/平板/安全区域提示   |
| `Ctrl + U`     | 切换静态窗口显示             |
| `Ctrl + ↑/↓`   | 放大/缩小 UI                |
| `Ctrl + M`     | 切换摄像机                  |

> **注意**：多数快捷键需鼠标聚焦对应 UI 区域生效。

---

## 三、核心界面功能
### Logger 窗口
- **位置**：播放控制器上方
- **日志颜色含义**：
  - 🟢 绿色：操作正常
  - ⚪ 白色：提示信息
  - 🟡 黄色：非致命警告（通常可忽略）
  - 🔴 红色：严重错误（需截图保存并联系开发者）

### EditorManager
- **功能**：  
  显示谱面元数据、开关网格/判定模式、创建特殊元素。

---

## 四、谱面结构详解
### 1. Element Folder
- **本质**：空容器节点（可嵌套）
- **作用**：管理子元素的位置属性

### 2. Camera
- **关键规则**：单谱面仅允许 **1 个 Camera**
- **位置**：
  - 简单场景：直接放在 Folder 下
  - 多机位场景：置于 Cross Track Point 内
- **运动逻辑**：随父节点（Folder/Track）移动而移动

### 3. Track 轨道系统
#### 类型对比
| 属性         | Movable Track                     | Static Track                     |
|--------------|-----------------------------------|----------------------------------|
| **运动逻辑** | Note 在轨道上固定位置生成         | Note 从轨道尾部运动到头部        |
| **核心参数** | 开始/结束时间、可视长度、缓动     | 下落时间、下落缓动               |
| **Note 放置**| 判定时间需在轨道启停时间范围内    | 无时间限制                      |

#### 显示模式
| 模式                  | 适用场景                          | 特点                          |
|-----------------------|-----------------------------------|-------------------------------|
| **AutoOrient**        | 3D 空间轨道（如螺旋线）          | 轨道面始终朝向摄像机          |
| **TrackPath**         | 平面内规则轨道                   | 随 PathNode 方向改变朝向      |
| **TrackRenderSurface**| 闭合轨道区域渲染                | 需手动调整法向量避免扭曲      |

#### PathNode 节点
- **作用**：控制轨道的形状、旋转、缩放、颜色
- **操作建议**：通过实操理解参数影响

### 4. 事件系统 (Events)
- **功能**：驱动位移(Displacement)/旋转(Swirl)/缩放(Scale)动画
- **最佳实践**：在 0-1 位置放置基础事件避免编辑器异常
- **特殊事件**：
  - `TrackPercentPoint`：用 0-1 值控制轨道进程（配合 Trail 实现精细动画）
  - `TrackHeadPoint`：简化版进程控制器

### 5. 缓动系统 (Easing)
- **作用**：控制数值变化速率（默认匀速 `Linear`）
- **选型建议**：
  - 加速/减速 → `InQuad`/`OutQuad`
  - 平滑过渡 → `Sine` 系列
  - 长动画（>1秒）才能明显体现缓动差异
- **参考工具**：[缓动函数可视化](https://easings.net/zh-cn)

### 6. Trail 拖尾效果
- **生成限制**：需依附于 `TrackPercentPoint`
- **高级技巧**：复制 Trail 粘贴到 Folder 下可通过事件自由控制
- **⚠️ 已知问题**：编辑模式下暂停时 Trail 会消失（游戏本体无此问题）

### 7. Note 系统
#### 基础配置
1. 设置判定时间 `exactJudgeTime`
2. 创建 Note Visual：
   - 选择主题包
   - 调整位置/大小（小屏设备需增大尺寸）
3. 保存为 Prefab：  
   通过 `Save Note Prefab` + `Use Note Prefab` 实现批量复用

#### 设计规范
- **下落时间**：直轨 ≤1秒，斜轨需实测设备显示效果
- **安全区域**：用 `Ctrl+1/2/3` 确保 Note 在安全范围内
- **材质规范**：
  - ✅ Stay 可用 Tap 材质
  - ❌ Tap 不可用 Stay/Hold 材质

### 8. 特效系统 (Effect)
- **触发方式**：
  - Note 判定事件（Perfect/Good/Bad/Miss）
  - 时间轴事件 (Time Effects Collection)
- **配置**：输入特效代码（需配合主题包文档）

---

## 五、工作流指南
### 标准流程
```mermaid
graph TD
    A[准备音源与主题包] --> B[创建摄像机轨道]
    B --> C[设计轨道系统]
    C --> D[放置Note]
    D --> E[添加事件/特效]
    E --> F[测试与优化]