[+] Ongeki的谱面IR

Author: Starrah

README.md

@@ -356,3 +356,12 @@ public sealed class FooGenerator : IGenerator<MaiChart>
    - 详见上文[多语言(i18n)相关](#多语言i18n相关)部分的说明。
 7. **CLI**（可选）：如需实现CLI，可在`Program.cs`中增加相应的功能。
 
+### Ongeki谱面的数据结构实现
+- 关于ogkr格式中各种指令的含义，可参考[ogkr格式详解](https://github.com/MikiraSora/OngekiFumianDescription/blob/master/ongeki.md)和[补充说明](https://github.com/MikiraSora/OngekiFumianDescription/blob/master/description.md)。
+- ogkr格式当中，大量的采用列举Pallete列表+使用ID引用具体的数据的实现方式。
+  - 例如子弹`BLT`指令，要通过`strId`引用`[B_PALLETE]`中内容，Tap、Hold等音符需要通过`groupId`引用`Lane`相关的内容，等
+- 而我们的数据结构实现的过程中，采用直接的对象引用而不是ID字符串引用；同时对于`BulletPallete`和`Lane`，谱面数据结构中**不会保存其ID**。
+- 因此，推荐的做法是：
+  - 在Parser的解析过程中，在Parser内部缓存ID和具体对象的映射关系，每次解析完一个`[B_PALLETE]`或`Lane`对象时就把它放进该内部缓存中，以供后面解析具体的`BLT`、Tap时直接找到对象。
+  - 在Generator的生成过程中，也是在内部建立缓存、为每个相关对象编好ID，然后生成引用这些对象的具体音符的时候直接写入编号。
+  - 也就是说，**ID相关的逻辑应当由Parser和Generator内部自行实现，谱面数据结构中不会保存ID。**

chart/ogk/Bullet.cs

@@ -0,0 +1,46 @@
+using MuConvert.utils;
+using Rationals;
+
+namespace MuConvert.ogk;
+
+
+public interface IBullet
+{
+    public BulletPallete? Detail { get; set; }
+}
+
+/**
+ * 声明子弹的细节行为，包括运动路径、速度、类型、尺寸等。
+ *
+ * record各项声明的默认值，对应于一种子弹静止不动的最简单情况，也就是官谱中的A0（绿谱当中能见到的子弹基本都是这种情况）
+ */
+public record BulletPallete(
+    BulletShooter Shooter = BulletShooter.UPS, // 发出子弹的位置
+
+    bool TargetToPlayer = false, // true表示该子弹射向玩家（取子弹生成时玩家的当前位置为目标位置）；false表示子弹射向基于TargetOffset所算出的目标位置。
+    int TargetOffset = 0, // 子弹的终点位置相对于起点位置的偏移量 (仅当TargetToPlayer为false时有效)。多数情况下，此值设置为0，得到的是不动的子弹，反之就是动的子弹。
+    int RandomOffsetDist = 0, // 如果不为0，则是随机子弹，结束位置会在正常位置的基础上随机偏移至多N格。
+    
+    decimal Speed = 1.0m,
+    BulletSize Size = BulletSize.N,
+    BulletType Type = BulletType.CIR
+);
+
+public class Bullet: IBullet
+{
+    public BulletPallete Detail { get; set; } = new();
+    
+    public Rational Time;
+    public int Pos;
+
+    public BulletDamage Damage = BulletDamage.NML;
+}
+
+public record BeamPoint(Rational Time, int Pos, int Width) : OgkLanePoint(Time, Pos);
+public class Beam: OgkBaseLane<BeamPoint>, IBullet
+{
+    public int ObliqueOffset = 0; // 如果不为0，表示这个激光是倾斜激光(OBS)，否则是一般的激光(BMS)
+    
+    // 激光是没有IBullet的Detail属性的。但接口还必须实现一个，所以实现成返回null、不准设置。
+    public BulletPallete? Detail { get => null; set => throw new InvalidOperationException("Beam has no bullet detail!"); }
+}

chart/ogk/Lane.cs

@@ -0,0 +1,44 @@
+using MuConvert.utils;
+using Rationals;
+
+namespace MuConvert.ogk;
+
+public record OgkLanePoint(Rational Time, int Pos);
+
+public abstract class OgkBaseLane<T> where T: OgkLanePoint
+{
+    public List<T> Points;
+
+    public Rational Time => Points.First().Time;
+}
+
+public class Lane(LaneType type): OgkBaseLane<OgkLanePoint>
+{
+    public LaneType Type = type;
+    public bool IsTransparent = false;
+}
+
+public class ColorfulLane() : Lane(LaneType.Colorful)
+{
+    public ColorfulLaneColor Color;
+    public int Brightness;
+}
+
+// 这里的Start，是相对于Wall的开始时刻的！不是绝对时间！
+public record Block(Rational Start, Rational Duration, int Pos, int EndPos);
+
+public class Wall() : Lane(LaneType.Wall)
+{
+    public Direction Direction;
+    
+    /**
+     * 给墙壁上添加“阻挡区域”。
+     * 注意！Block中的Start是相对于Wall的起始时刻(Time)的，而不是绝对时间。
+     * 
+     * 默认的“墙壁”描述的仅仅是场地的有效范围，显然玩家摇杆是可以穿越出去的；
+     * 但如果这里加上Blocks的话，玩家摇杆就无法穿越出去了。
+     */
+    public List<Block> Blocks = [];
+}
+
+public class EnemyMovement: OgkBaseLane<OgkLanePoint>;

chart/ogk/OgkChart.cs

@@ -1,8 +1,38 @@
 using MuConvert.chart;
+using MuConvert.utils;
+using Rationals;
 
 namespace MuConvert.ogk;
 
 public class OgkChart: BaseChart<OgkNote>
 {
+    public string Designer { get; set; } = ""; // 谱师
+
+    // 全局声明的“子弹伤害类型与伤害数值的映射关系”。绝大多数情况下都是这个默认值，不需要做改动。
+    public Dictionary<BulletDamage, decimal> BulletDamages = new() {
+        [BulletDamage.NML] = 1.0m, [BulletDamage.STR] = 2.0m, [BulletDamage.DNG] = 4.0m,
+    };
+    
+    /**
+     * 游戏中所有的轨道。
+     * 包括：红绿蓝线、左墙右墙（也就是侧键的轨道）、以及部分谱面中会出现的彩色线
+     */
+    public List<Lane> Lanes = [];
+
+    /**
+     * 游戏中所有的伤害弹。
+     * 目前包括子弹(Bullet)和激光(Beam)两种子类型。
+     */
+    public List<IBullet> Bullets = [];
+
+    /**
+     * 指定切换敌人的时刻。
+     *
+     * 可以不显式指定（保持默认的空数组状态），此时游戏会自动应用“前半小怪、后半boss”的机制。
+     * Type是一个字符串，游戏内的典型取值："WAVE1" "WAVE2" "BOSS"
+     */
+    public List<(Rational Time, string Type)> EnemyList = [];
 
+    // 部分谱面中会有，上方的敌人在上面进行水平方向的移动的情况。
+    public List<EnemyMovement> EnemyMovements = [];
 }

chart/ogk/OgkNote.cs

@@ -1,8 +1,41 @@
 using MuConvert.chart;
+using MuConvert.utils;
+using Rationals;
 
 namespace MuConvert.ogk;
 
-public class OgkNote: BaseNote
+/**
+ * 所有游戏内的参与计分的基础音符所构成的基类。
+ * 包括：Tap(普通键和侧键)、Hold(普通键和侧键)、Flick、Bell四种子类。
+ */
+public abstract class OgkNote: BaseNote
 {
+    /**
+     * 音符的水平位置。取值范围[-24,24]。
+     * 之所以用Rational，是因为极个别TAP/HOLD音符可能不在整数位置上；但绝大多数音符，包括所有的bell、flick，都一定是在整数位置上的。
+     */
+    public Rational Pos { get; set; }
 
-}
+    public bool IsEx;
+}
+
+public class Tap: OgkNote
+{
+    public required Lane Lane;
+}
+
+public class Hold : Tap
+{
+    public override Rational EndTime { get; set; }
+    public Rational EndPos;
+}
+
+public class Flick : OgkNote
+{
+    public Direction Direction;
+}
+
+public class Bell: OgkNote, IBullet
+{
+    public BulletPallete? Detail { get; set; } = null; // 大多数的bell默认是原地不动的。如果指定此属性，则可以实现和子弹类似的可动bell的效果。
+}

utils/OgkEnums.cs

@@ -0,0 +1,59 @@
+namespace MuConvert.utils;
+
+public enum LaneType
+{
+    Red,
+    Green,
+    Blue,
+    Colorful, // 多彩线，颜色详见ColorfulLaneColor枚举
+    Wall, // 墙壁，即场地的左右边界
+}
+
+public enum ColorfulLaneColor
+{
+    Akari = 0,
+    Yuzu = 1,
+    Rio = 2,
+    Riku = 3,
+    Tsubaki = 4,
+    Ayaka = 5,
+    Kaede = 6,
+    Saki = 7,
+    Koboshi = 8,
+    Arisu = 9,
+    Mia = 10,
+    Chinatsu = 11,
+    Tsumugi = 12,
+    Setsuna = 13,
+    Brown = 14,
+    Haruna = 15,
+    Black = 16,
+    Akane = 17,
+    G = 18,
+    Aoi = 19,
+}
+
+public enum Direction { L, R }
+
+public enum BulletSize { N, L } // Normal or Large
+
+public enum BulletType
+{
+    CIR, // 圆形子弹
+    NDL, // 针状子弹
+    SQR, // 圆柱形(方状)子弹
+}
+
+public enum BulletShooter
+{ 
+    UPS, // 从具体BLT命令行中所指定的那个Pos位置
+    ENE, // 从敌人位置
+    CEN, // 从谱面中心即Pos=0的位置
+}
+
+public enum BulletDamage
+{ 
+    NML, // Normal 使用BULLET_DAMAGE伤害
+    STR, // Hard 使用HARDBULLET_DAMAGE伤害
+    DNG, // Danger 使用DANGERBULLET_DAMAGE伤害
+}