Modchart（音符修饰器系统）

适用版本：Parker Engine 0.2.8（Project.xml 的 <app version>）。参考工具链：Haxe 4.3.7 + HaxeFlixel。

本文以源码为准。 修饰器注册名、参数（次模）、排序值、事件类型都是从 source/modchart/ 逐个读出来的；源码里有、但当前版本实际跑不到的东西（例如 Modifier.active、HScriptModifier 这条路径）都在 §7 / §8 明确标注。

引擎里的 Modchart 是 Schmovin' / Andromeda 风格的「修饰器栈」，源码全在 source/modchart/。它和 backend/Paths.hx 那套「mod 文件夹」毫无关系——ModManager 是修饰器（modifier）注册表，不是模组管理器。也不同于维基里另一页记录的 Andromeda「ModChat / Modifiers」（note-field + startMod() 那套）：那是另一套系统，本页只讲 source/modchart/。

1. 概念

• Modifier（修饰器）：一个有名、有值（percent）、可带次模（submod）的变换单元。同一个修饰器对两侧玩家各存一个值（percents = [0, 0]），值 = 百分比 / 100——setValue('drunk', 0.5) 表示 50%。
• 玩家编号：player = 0 是玩家侧（playerStrums / bf），player = 1 是对手侧（opponentStrums / dad）。传 -1 表示「两侧都设」。
• 两类修饰器（ModifierType）：
• NOTE_MOD —— 参与 note / receptor 的位置与渲染管线（getPos / updateNote / updateReceptor）。
• MISC_MOD —— 其他一切，只作为 Modifier 基类默认值。
• 管线（每帧，PlayState.update()）：

``` modManager.updateTimeline(curDecStep) // 跑 EventTimeline 上的计划事件（step 为单位） modManager.update(elapsed) // 见 §8 的注意：当前实际不会调用任何修饰器的 update()

// 每根 strum（startedCountdown && songIsModcharted） pos = modManager.getPos(0, 0, 0, curDecBeat, strum.noteData, player, strum, [], strum.vec3Cache) modManager.updateObject(curDecBeat, strum, pos, player) // 让 NOTE_MOD 改缩放/角度/alpha strum.x = pos.x; strum.y = pos.y

// 每个 note（同上，getPos 用 strumTime + getVisPos 求视觉差） pos = modManager.getPos(strumTime, visDiff, strumTime - songPosition, curBeat, noteData, player, note, [], note.vec3Cache) modManager.updateObject(curBeat, note, pos, player) note.x = pos.x; note.y = pos.y // sustain 尾巴：对「75ms 之后」的位置再算一次 getPos，用两点方向给 note.mAngle ```

• getPos(time, diff, tDiff, beat, data, player, obj, ?exclusions, ?pos) 的初始位置：

haxe pos.x = getBaseX(data, player); // strum 基准 x（含左右两侧偏移） pos.y = 50 + diff; // diff = 视觉滚动差 pos.z = 0;

然后按 activeMods[player] 的顺序（已按 getOrder() 升序排好）依次调用 mod.getPos(...)；exclusions 里的名字会被跳过（AlphaModifier 就靠它重算一次「不含 reverse」的位置）。getVisPos(songPos, strumTime, songSpeed) = -(0.45 * (songPos - strumTime) * songSpeed)。

• 单位：EventTimeline 用 step（curDecStep，可以是小数），不是 beat、不是秒。

2. 启用与注册时序

Modchart 不需要「手工开启」——引擎默认就开着，开关是一个 gameplay setting：

songIsModcharted == false 时，PlayState 完全跳过 strum/note 的 getPos + updateObject（修饰器的值照样能设、事件照样跑，只是不会作用到画面上）。

注册时序（PlayState.startCountdown() → 完成时）：

modManager.receptors = [playerStrums.members, opponentStrums.members];  // 注意 0 = 玩家侧
callOnLuas('preModifierRegister', []);
callOnScripts('preModifierRegister', []);      // HScript + LScript + Python
modManager.registerDefaultModifiers();         // ← 内置修饰器在这里注册
callOnLuas('postModifierRegister', []);
callOnScripts('postModifierRegister', []);
// Modcharts.loadModchart(modManager, SONG.song);   ← 源码里被注释掉了

也就是说：preModifierRegister 里内置修饰器还不存在（改它们的值要等到 postModifierRegister）；registerDefaultModifiers() 会把每个内置修饰器的值重置为 0。

相关回调

3. 内置修饰器全表（16 个注册名）

registerDefaultModifiers() 实际注册的名字如下（注册名 = Modifier.getName()，也就是 setValue('名字', ...) 里用的字串）：

说明：

• PerspectiveModifier 的 getOrder() 是 LAST + 100（= 1100），RotateModifier 是 LAST + 2（= 1002），ScaleModifier 是 PRE_REVERSE（= -3），ReverseModifier 是 REVERSE（= -2），LocalRotateModifier 是 POST_REVERSE（= -1），TransformModifier 是 LAST（= 1000），其余为 DEFAULT（= 0）。顺序决定 getPos 乘算的先后。
• 所有 getSubmods() 列出的次模 也会以各自的名字被单独注册（registerMod 里递归 quickRegister），所以 setValue('hidden', 1, 0) 这类写法合法；次模带 parent，设置次模的值会连带把父修饰器激活（ModManager.setValue 里靠 mod.parent 找父级）。
• noteSpawnTime：源码里除注册与 setValue(..., 1250) 之外没有任何地方读它，是留给脚本的数值槽。
• Modcharts.hx 目前是死代码：isModcharted()（只有 ["fresh"] 在列表里）与 loadModchart() 都没有调用者，PlayState 里唯一那行是注释（// Modcharts.loadModchart(modManager, SONG.song);）。它原本要做的是：ClientPrefs.middleScroll 时给对手侧设 opponentSwap = 0.5、alpha = 1。

3.1 flip

3.2 reverse

3.3 invert

3.4 drunk

3.5 beat

3.6 stealth

3.7 mini

（getScale() 里 var angle = 0; 是硬编码的，所以旋转相关的两项其实恒等于 1×……它只影响 stretch/squish 的组合系数。）

3.8 confusion

3.9 opponentSwap

3.10 transformX

（ClientPrefs.middleScroll 时 PlayState 给对手侧设的就是 transform0X…transform3X。）

3.11 infinite

PathModifier 基类的注册名是 basePath（getMoveSpeed() = 5000、getPath() 返回空），没有被注册；路径在构造时预计算成 PathInfo{position, start, end, dist} 数组，并整体偏移 -Note.swagWidth / 2。

3.12 perspectiveDONTUSE

3.13 rotateX

角度单位是弧度：内部用 CoolUtil.rotate(x, y, angle)，而它是 Math.cos(angle) / Math.sin(angle)。

3.14 centerrotateX

3.15 localrotateX

3.16 noteSpawnTime

4. 数值与次模 API

次模在脚本里的用法举例：setValue('hidden', 1, 0)（玩家侧上半渐隐）、setValue('cross', 1)（中间两列反向）、setValue('transform0X', -100, 1)。

5. 事件系统（EventTimeline）

ModManager.timeline 是一个 EventTimeline，由 updateTimeline(curDecStep) 每帧驱动。事件按 executionStep 排序，step >= executionStep 时 run(step)；跑完（finished）就移出队列。

ModManager 上暴露的排队 API（脚本通过代理表调用的就是这些）：

style 是 FlxEase 上的字段名（Reflect.getProperty(FlxEase, style)），例如 'linear'、'quadInOut'、'cubeOut'、'sineIn'……找不到就退回 linear。step / endStep 都可以是小数。

6. 从脚本操控

LScript / HScript

引擎把 modManager 直接塞成脚本全局（PlayState:1048 的 setDefaultLScripts / setDefaultHScripts），所以：

function postModifierRegister()
    modManager:setValue('opponentSwap', 0.5)          -- 两侧
    modManager:setValue('mini', 0.25, 1)              -- 只对手侧
end

function generateModchart()
    modManager:queueEase(0, 16, 'drunk', 0.5, 'quadOut', 0)
    modManager:queueSet(32, 'reverse', 1)
    modManager:queueFuncOnce(48, function(event, step)
        modManager:setValue('flip', 0)
    end)
end

ModManager 的 getValue / getPercent / get / getVisPos / quickRegister / setPercent 都是 inline，经代理表 Reflect.getProperty() 反射未必取得到实体；稳妥做法是只用上表里那些非 inline 方法，要记数就自己维护变量。

Lua

Lua 侧不需要碰 modManager，FunkinLua 直接注册了一整套同名函数：

7. 自定义修饰器

7.1 HScriptModifier（source/modchart/HScriptModifier.hx）

设计意图：用 HScript 写一个 Modifier，让引擎在 getPos / updateNote / updateReceptor 时回调脚本函数。

• HScriptModifier.fromString(modMgr, ?parent, scriptSource) —— 从字符串建；
• HScriptModifier.fromName(modMgr, ?parent, scriptName) —— 从 modifiers/<scriptName>.hscript 建（先 Paths.modFolders()，再 Paths.getPreloadPath()），并把 mod.name 设成脚本名；找不到就 trace 一条并返回 null。
• 脚本环境：构造时先把 onAddScript 钩子挂上，然后 modchart() 往脚本里塞 this（修饰器本身）、modMgr、parent，以及 getValue / getPercent / getSubmodValue / getSubmodPercent / setValue / setPercent / setSubmodValue / setSubmodPercent，最后依次执行 onCreate、onCreatePost。
• 转发给脚本的成员（script.exitsVar(...) 存在才转，否则用基类实现）：getModType、ignorePos、ignoreUpdateReceptor、ignoreUpdateNote、doesUpdate、shouldExecute(player, value)、getOrder、getName、getValue(player)、getPercent(player)、setValue(value, player)、setPercent(percent, player)、getSubmods、getSubmodPercent、getSubmodValue、updateReceptor(beat, receptor, player)、updateNote(beat, note, player)。
• _scriptEnums（NOTE_MOD / MISC_MOD / FIRST / PRE_REVERSE / REVERSE / POST_REVERSE / DEFAULT / LAST）本来是为 FunkinHScript.fromString(..., enums) 准备的，那两行现在是注释，枚举并没有被真正注入。

完整示例（按上面转发的方法名写）：

// 路径：mods/<mod>/modifiers/wave.hscript
// 注册：Haxe 侧调用 HScriptModifier.fromName(modManager, null, 'wave')
//       —— 引擎没有任何目录扫描逻辑会自动加载它

var amplitude:Float = 40;   // 自定义次模，先写进 getSubmods() 才能被 setValue 驱动

function getName() return 'wave';
function getModType() return NOTE_MOD;                       // 参与 note / receptor 渲染
function getOrder() return DEFAULT;
function shouldExecute(player:Int, value:Float) return true; // 值归 0 时也想继续跑就返回 true
function getSubmods() return ['amplitude'];

function updateNote(beat:Float, note:Note, player:Int)
{
    wave(note, player);
}

function updateReceptor(beat:Float, receptor:StrumNote, player:Int)
{
    wave(receptor, player);
}

function wave(obj:FlxSprite, player:Int)
{
    var amount:Float = getValue(player);
    if (amount == 0) return;

    var amp:Float = getSubmodValue('amplitude', player);
    if (amp == 0) amp = amplitude;

    obj.y += Math.sin(Conductor.songPosition / 1000 * 4) * amp * amount;
}

源码现状（必须知道）：HScriptModifier 在当前树里没有任何已编译代码引用它（HScriptUtil.hx:196 那行是注释），而它自身对着本 fork 的 Modifier 有几处不一致，所以这条路径目前是不可用/未维护的：

1. 大量分支用 script.exitsVar(...)，但 FunkinHScript 上只有 exists()（exitsVar 全仓库只出现在这个文件里）；
2. getPos 的转发被整段注释掉了（// override public function getPos(...)）——也就是说 HScript 修饰器无法参与位置计算，只能在 updateNote / updateReceptor 里直接改精灵；
3. updateNote(beat, note, player) / updateReceptor(beat, receptor, player) 的形参个数与基类 Modifier 的 (beat, note, pos, player) / (beat, receptor, pos, player) 不一致；update(elapsed, beat) 也和 Modifier.update(elapsed) 不一致；
4. getExtraInfo() / isRenderMod() 依赖的 RenderInfo、Modifier.getExtraInfo、Modifier.isRenderMod 在本 fork 里根本不存在；
5. setPercent 内部转发的是 executeFunc("setValue", ...)（疑似笔误）。

因此想加自定义修饰器，当前唯一可靠的做法是加一个 Haxe 类：

// source/modchart/modifiers/WaveModifier.hx
package modchart.modifiers;

import flixel.FlxSprite;
import math.Vector3;

class WaveModifier extends NoteModifier
{
    override function getName()
        return 'wave';                       // 注册名 / setValue 用的字串

    override function getOrder()
        return Modifier.ModifierOrder.DEFAULT;

    override function getSubmods()
        return ['amplitude'];

    override function getPos(time:Float, visualDiff:Float, timeDiff:Float, beat:Float, pos:Vector3, data:Int, player:Int, obj:FlxSprite)
    {
        var amp:Float = getSubmodValue('amplitude', player);
        if (amp == 0)
            amp = 40;

        pos.y += Math.sin(Conductor.songPosition / 1000 * 4) * amp * getValue(player);
        return pos;
    }
}

然后在 ModManager.registerDefaultModifiers() 的 quickRegs 数组里加 WaveModifier（或另找时机 quickRegister(new WaveModifier(this))），重新编译即可。getPos 里拿到的是待修改的 Vector3，updateNote / updateReceptor 里拿到的是精灵本身。

7.2 「纯数值槽 + 事件」的伪修饰器

如果只是想要一个被谱面驱动的数值（不做位置计算），可以模仿 noteSpawnTime：注册一个 SubModifier，用 queueFunc / queueEase 驱动它，再在自己的脚本回调里读取。Lua 端有现成的 addBlankMod(modName, defaultVal, player)；LScript 端可以 import('modchart.SubModifier') 后用 modManager:registerMod('myValue', SubModifier:new('myValue', modManager)) 做同样的事（SubModifier 的构造签名是 (name, modMgr, ?parent)，默认 getOrder() 是 LAST、doesUpdate() 是 false）。

8. 已知限制与坑

1. Modifier.active 永远是 false。ModManager.update(elapsed) 的条件是 if (mod.active && mod.doesUpdate()) mod.update(elapsed)，而整个 source/modchart/ 里没有任何地方把 active 设成 true。结论：修饰器的 update() 钩子当前不可达，每帧逻辑请写在 queueFunc（StepCallbackEvent）里。另外 ignorePos() / ignoreUpdateNote() / ignoreUpdateReceptor() 这三个开关在整个仓库里都没有被调用过（只有定义和 override），updateObject() 只检查 obj.active（FlxObject 的 active，正常恒为 true）——它们目前只是文档性/预留的成员。
2. 修饰器的值默认是 0，且不影响 activeMods：setValue 里靠 shouldExecute(player, val)（默认 val != 0）决定是否进 activeMods；AlphaModifier / ReverseModifier / ConfusionModifier / ScaleModifier / PerspectiveModifier 覆写成恒 true，所以它们只要被设过值就一直留在 activeMods 里。
3. 次模会连带激活父修饰器，所以「只设某一个次模」是正常用法（setValue('hidden', 1, 0)）。
4. preModifierRegister 时内置修饰器还没注册，设值会被 registerDefaultModifiers() 里的 setValue(modName, 0) 覆盖掉；请用 postModifierRegister 或 generateModchart。
5. songIsModcharted == false 时画面不会变，即使脚本照常设值、事件照常跑。
6. getPos 的 exclusions 数组是按修饰器注册名过滤的（例如 AlphaModifier 传入 ["reverse"] 重算位置）；脚本自己调用 getPos 时也要自己传。
7. rotate* 用弧度、confusion 用度（前者经过 CoolUtil.rotate → Math.cos/sin，后者直接写 FlxSprite.angle）。
8. perspectiveDONTUSE 不要手动设值：它 shouldExecute() 恒 true，被激活后会把 z 按 near = 0、far = 2、fov = π/2、aspect 硬编码 1 投影，是给 z 轴修饰器兜底用的。
9. basePath 未注册：PathModifier 基类只有子类 InfinitePathModifier（注册名 infinite）被 registerDefaultModifiers() 注册。
10. stealth 的 useStealthGlow 无效（代码读的是 dontUseStealthGlow，见 §3.6）。
11. drunk 的 drunkZ / drunkZSpeed / drunkZOffset / drunkZPeriod 无效（只在 getSubmods() 里声明，getPos 未使用）。
12. mini 里的 angle 恒为 0，stretch / squish 的旋转耦合项实际是固定系数。
13. Modcharts.hx 是死代码（isModcharted()、loadModchart() 都没有调用者）。