KSHRAM 命令指南（简体中文版）ver. 2025.10.28

原作者：3kanAlpha / m4gnett
原始 Gist · 日文 Markdown raw

程序下载链接

Terminal 版是 CUI 应用，Qt 版是 GUI 应用。Terminal 版可以把谱面直接拖放到 exe 文件上运行，因此更推荐这一版。

通用说明

如何在谱面（KSH 格式）中写命令

KSHRAM 命令以 KSM 谱面内注释的形式书写。在 KSM 编辑器中使用铅笔工具 + 选择模式时，按 Ctrl+Shift+左键 可添加注释。要让命令正常工作，KSH 文件行首的 // 必须保留；但在 KSM 编辑器内输入时不必自己加，保存谱面时会自动附加。（反过来，如果在编辑器内的注释开头再加 //，就能把命令变成真正的普通注释。）

命令语法如下：

COMMAND_NAME ARGS ARGS ARGS...
コマンド名 引数1 引数2 引数3...

目前命令有两种类型。一种需要 end 标记来指定范围；另一种不需要对应的 end 命令，通常放在某个对象的起点（例如激光线的起点），并自动识别范围。

需要 end 标记的同类命令之间不能重叠。如果要在前一条同类命令的结束时刻立刻再用一次，新的“start”命令必须写在 end 后面。

命令名以及用于决定类型的大多数参数，不区分大小写。

RANGED_COMMAND
...
end RANGED_COMMAND;RANGED_COMMAND
...
end RANGED_COMMAND

如果要在一条注释里放多条命令，用 ; （分号）分隔。执行顺序如下：

从谱面开头到末尾；
同一条注释内，从第一条命令到最后一条。

下例先执行 cl p2 t g，再执行 cr p2 f g：

cl p2 t g; cr p2 f g

要显式延后命令的执行时机，可添加前缀 #N。N 是延迟编号（正整数）。延迟命令只会在所有延迟编号比它小的命令全部执行完毕后执行。

需要 end 标记的命令，必须与其 end 标记使用相同的延迟编号。
多条命令具有同一延迟编号时，按前述规则确定顺序。

cl p2 t g; #1 tiltstyle mid 2x

如果命令以 # 开头，但后面没有正整数，就不会被识别为延迟命令。

在注释前面再写 //，KSHRAM 就会忽略它，不执行命令。实际上，所有不以命令关键字开头的内容都不会被当成命令，而会原样保留在输出谱面里。

(エディタ内)
// your comment
(ksh ファイル内)
//// your comment

图示

命令示例

本文档的参数定义语法

xxx：字面字符串（常量）xxx。

(xxx)：可选的字面字符串（常量）xxx。

[xxx]：名为 xxx 的必填参数。

([xxx])：名为 xxx 的可选参数。

可选参数通常只出现在命令末尾。与调用带默认参数的 C++ 函数一样，如果想设定某个靠后的可选参数，必须同时设定它之前的全部可选参数。

[xxx...]：同一类型的参数列表，会在文档内另行说明。不指定不一定总会出错，但建议至少指定一个。

参数类型

INT：整数（多数情况为正整数）。例：1, 3, 16

REAL：实数，支持小数和指数记法。例：1.0, 0.67, 1.0e-2

RATIO：实数，同时支持分数（a/b）。例：0.67, 2/3

BOOL：布尔值，必须为 t, true, f, false 之一。

ENUM：枚举字符串，从有效值中选一个。

ANY：任意类型的字符串，本文档中很少出现。

通用参数

[length]

以拍为单位的时间长度。支持小数和分数。可设值：1, 1.0, 1/3。

[div]

一拍的分割数，主要用于决定命令生成的两个标记之间的间隔。

div = 16：每 1/4 拍（16 分）一个标记。
div = 24：每 1/6 拍（24 分）一个标记。

[amp]

增幅倍率（Amplifier）。具体含义因命令而异，支持小数和分数。

[reverse]

布尔值。reverse = true 时，命令的特定属性会改变。这不等于在时间轴上反转输出。可设值：t / true; f / false。

命令列表

添加指定标记

mark [type] [value] ([value2])
      ENUM   ANY      ANY

在命令执行位置写入一个标记。如果给出两个值，写入的标记会形成从前者到后者的突变（sudden change）。该命令不检查值是否有效，也不检查该标记类型是否支持突变；[value] 和 [value2] 会按原字符串直接赋值。

[type]

设定值	说明	设定值	说明
bpm	BPM	sig / signature	拍号
fxlong_l / fxlong_r	FX 长键效果	fxchip_l / fxchip_r	FX chip 音效
filter	激光效果	slamsound	激光直角音效
knobvol	激光效果音量	slamvol	激光直角音量
zt / zoomtop	镜头缩放（上）	zb / zoombottom	镜头缩放（下）
zs / zoomside	镜头缩放（横向）	tilt	轨道倾斜
split	轨道分割的左右移动	stop	谱面停止
laser2x_l / laser2x_r	超出轨道的激光

[value] 与 [value2]：要写入的值，原字符串直接赋值。如果其中需包含分号 ;，请用花括号 { } 包住。

mark fxlong_l {gate;16}

目前没有转义字符，因为 [value] 没有包含花括号的必要。

⚠ 用本命令添加轨道倾斜标记时，请注意：KSH 格式中记录的实际 tilt 值是 KSM 编辑器显示值的 1/100。[value]（和 [value2]）必须写实际标记值。

添加指定音符

note [type] [start_time] ([end_time])
      ENUM      RATIO        RATIO

在相对于命令执行时刻的 start_time 添加 chip 音符或长音符。长音符在相对时刻 end_time 结束。是否给出 end_time 决定添加 chip 还是长音符。

新长音符会覆盖与它重叠的现有 chip，以及起点落在新音符范围内的现有长音符。

[type]

设定值	说明
a	BT-A
b	BT-B
c	BT-C
d	BT-D
l	BT-L
r	BT-R

[start_time] 和 [end_time]：以拍为单位，相对于命令执行时刻。也可以设置 KSH 格式无法精确记录的 tick（例如 1/5）；此时 KSHRAM 会取最接近的近似值。

添加直线激光和直角

`knob` 命令

knob [side] [start_time] [end_time] [start_pos] [end_pos]
      ENUM     RATIO       RATIO        INT        INT

在相对于命令执行时刻的 start_time 与 end_time 之间添加直线激光。新激光不得与现有直线激光重叠；如果冲突，命令会报错并失败。

由于 KSH 格式限制，两个激光对象之间至少要间隔 1/24 拍，否则它们会被连接起来。

[side]：l 为左侧（蓝），r 为右侧（红）。

[start_time] 与 [end_time]：以拍为单位的相对时间。无法在 KSH 中精确记录的 tick 会取最近近似值。

[start_pos] 与 [end_pos]：激光的起点与终点位置，必须在 0～50 之间。如果要用超出轨道的激光，请在其起始时刻使用 mark 命令。

`knobadd` 命令

knobadd [side] [end_time] [end_pos]
         ENUM     RATIO      INT

从 end_time 之前最后一个激光终点，连接到相对时刻 end_time。执行成功时，可保证它与前一段激光的终点连接。

新增激光必须长于 1/8 拍（否则在 KSH 中会成为直角），或者前后位置不变。否则命令会报错并失败。

[side]：l 为左侧（蓝），r 为右侧（红）。

[end_time]：以拍为单位的相对时间；无法精确记录的 tick 会取最近近似值。

[end_pos]：激光终点位置，必须在 0～50 之间。

`slam` 命令

slam [side] [time] [start_pos] [end_pos] ([duration])
      ENUM  RATIO    INT          INT        RATIO

在相对时刻 time 添加激光直角。直角不得与现有激光冲突，否则命令会报错并失败。

[side]：l 为左侧（蓝），r 为右侧（红）。

[time]：以拍为单位的相对时间；无法精确记录的 tick 会取最近近似值。

[start_pos] 与 [end_pos]：必须在 0～50 之间。为了形成直角，两者必须不同。

[duration]：直角长度，默认为 1/8 拍。没有特殊需求时请保持默认值。小于 1/8 拍的直角可能看起来非常奇怪。

请尝试以下示例：

batch define knob_example
{
    // Left side
    knob L 0 2 0 50;
    slam L 2 50 0;
    knobadd L 4 50;
    slam L 4 50 0;
    // Right side
    knob R 0 2/3 0 50;
    knobadd R 4/3 0;
    knobadd R 2 50;
    slam R 2 50 0;
    knobadd R 8/3 50;
    knobadd R 10/3 0;
    knobadd R 4 50;
    slam R 4 50 0;
}

组合命令

把这些命令放进同一批处理（batch），可以生成复杂图案。第一段用 knob 或 slam 绘制，其余部分用 knobadd 连接。

生成曲线激光

cl / cr [type] [reverse] ([mode]) ([amp])
         ENUM   BOOL       ENUM    REAL

将命令放在一段“笔直激光”的起点，会把它转换为曲线激光。“笔直激光”指中间没有中间点的激光；选中看起来是直线的激光时，如果整段一起高亮，那它（大概）就算“笔直激光”。cl 用于左（蓝），cr 用于右（红）。

[type]

设定值	说明
p / parabola	抛物线 #1
p2 / parabola2	抛物线 #2（稍有不同）
c / cubic	三次曲线 #1
c2 / cubic2	三次曲线 #2（稍有不同）
sl / smoothlinear	平滑起始的直线 #1
sl2 / smoothlinear2	平滑起始的直线 #2（圆滑范围更长）
s / sine	正弦波（1/4 周期）
e / exp	指数函数 `e^ax - ax`，`a` 由 `amp` 指定
xn	幂函数 `x^n`，`n` 由 `amp` 指定

[reverse]：见通用参数。true 时斜率递减，形如“J”；否则斜率递增，形如“r”。

[mode]

设定值	说明
s / static	步进固定为 1/6 拍的倍数
d / dynamic	步进不固定
g / global	Itoda Raleph 的算法

未指定时，生成器会根据激光长度自动选择。

Dynamic / Global 模式可能显著增大一小节的记录大小。短曲线请使用 static 模式。

[amp]：只影响部分曲线类型。

曲线类型	默认值	范围	说明
e / exp	1.0	0.0001～5.0	值越大，曲线越缓
xn	2.0	1.0～5.0	值越大，曲线越陡

平滑镜头效果（视点移动）

zt / zb / zs / tilt / split [type] [reverse] [div] ([amp])
                             ENUM   BOOL      INT   REAL

该命令与对应的镜头关键点标记放在同一时刻，下一个同类镜头关键点是终点，两者之间的过渡用曲线插值。

zt = zoom_top；zb = zoom_bottom；zs = zoom_side；tilt = 轨道倾斜；split = 中央分割（center splitting）。

注意：在 tilt 模式下，起止两个标记都必须是数值，不能是 NORMAL 或 ZERO 这类自动 tilt 模式。

[type]：可设值与“生成曲线激光”相同：p/parabola, p2/parabola2, c/cubic, c2/cubic2, sl/smoothlinear, sl2/smoothlinear2, s/sine, e/exp, xn；含义也相同。

[reverse]：见通用参数。true 时斜率递减，形如“J”；否则斜率递增，形如“r”。

[div]：见通用参数。

[amp]：只影响部分曲线类型。e/exp 默认 1.0，范围 0.0001～5.0，越大越缓；xn 默认 2.0，范围 1.0～5.0，越大越陡。

平滑镜头效果（差分）

ztadd / zbadd / zsadd / splitadd [mode] [curve_type] [length] [div] [offset] ([amp])
                                  ENUm   ENUM         RATIO    INT   REAL     REAL

把命令放在想开始增量效果的位置，会在现有镜头效果上叠加额外变化。

[mode]

设定值	说明
i / impact	冲击效果：突然增大到 offset，再逐渐回归
ri / rimpact	冲击效果的反向
c / charge	蓄力/触发效果：逐渐积累到 offset，再突然归零
rc / rcharge	蓄力/触发效果的反向
a / arch	形如“C”：增加到 offset 后返回

各模式外观如下：

impact 曲线

impact 曲线

charge 曲线

charge 曲线

arch 曲线

arch 曲线

[curve_type]：与曲线激光的 [type] 相同，包括 p, p2, c, c2, sl, sl2, s, e, xn 及各自长名。

[length]：见通用参数。

[div]：见通用参数。

[offset]：曲线的最大偏移量。

[amp]：只影响部分曲线类型。e/exp 默认 1.0，范围 0.0001～5.0，越大越缓；xn 默认 2.0，范围 1.0～5.0，越大越陡。

速度变化效果

svfx [type] [reverse] [length] [div] ([amp]) ([BPM])
      ENUM   BOOL      RATIO    INT   REAL    REAL

[type]：此处的曲线位于 BPM—时间坐标系中。

设定值	说明
l / linear	线性
p / parabola	抛物线
sq / sqrt	平方根
s / sine	正弦波（1/4 周期）
e / exp	指数函数曲线

[reverse]：见通用参数。true 时 BPM 随时间下降，否则上升。

[length]：见通用参数。

[div]：见通用参数。

[amp]：所有 SVFX 曲线类型都可调整。理论范围是 0～+∞，但因 float64 的计算极限，过小或过大可能溢出，不建议使用。除 e/exp 外，amp 越大，BPM 变化越缓；e/exp 则相反。默认值始终是 1.0。

[BPM]：作为参考的等效固定 BPM。未显式指定时，使用命令所在位置的 BPM。

镜头增幅

用于镜头变化幅度过缓，或摇动得过于剧烈的情况。

开始命令：

ztamp / zbamp / zsamp / tiltamp / splitamp [amp] ([ref_center])
                                          REAL        REAL

结束命令：

end ztamp / zbamp / zsamp / tiltamp / splitamp

对范围内所有对应的镜头标记进行增幅。包含起点，不包含终点。NORMAL 等自动 tilt 模式不受 tiltamp 影响。

[amp]：乘数。

[ref_center]：中心值，默认为 0。

增幅遵循下式：

camera_after = amp * (camera_before - ref_center) + ref_center

Swing 化

开始命令：

swing [div] [delay]
       INT   RATIO

结束命令：

end swing

将范围内所有节奏摇摆（swing）化：把第 (2n-1/[div]) 个音符延后 [delay] 拍。所有类型的音符、标记和注释（只要它们处在要 swing 化的 tick 上）都会受影响，但写有 swing 开始/结束命令的注释除外。建议把开始/结束命令放在不需要 swing 化的时刻（例如拍头）。

[div]：见通用参数。

[delay]：第 (2n-1/[div]) 个音符要延后多少拍。delay 必须小于 4/div 拍。

例：[div] = 16, [delay] = 1/12：把第 1/4 拍的音符移到第 1/3 拍，把第 3/4 拍的音符移到第 5/6 拍。

跟随激光的自动 tilt

// 開始コマンド
// [style] でスムージングモードを1つ選択可能
tiltstyle [style...] ([amp])
           ENUM       REAL

// 中間コマンド
// [style] でスムージングモードは選択不可
tiltstyle [style...] ([amp])
           ENUM       REAL

// 終了コマンド
end tiltstyle

在命令范围内，根据激光位置自动生成 tilt 标记。命令只在其范围内放置标记。如果想让范围两端平滑过渡，请把命令范围在激光对象前后各扩展 2 拍。

[style...]：决定如何根据激光位置倾斜。以下每张表中只能选一个 style；一条命令可用空格分隔多个 style。

STYLE	EFFECT
side	激光位于默认位置（L=0, R=50）时 tilt = 0。默认
mid	激光位于中央（25）时 tilt = 0
keep	倾斜规则与 `side` 相同，但只要激光存在，角度就不会减小

STYLE	EFFECT
2x	按激光的视觉位置倾斜。带 laser2x 的激光会生成更大范围的倾斜角。默认关闭

STYLE	EFFECT
left	只有左侧激光影响倾斜角
right	只有右侧激光影响倾斜角
（未指定）	默认同时考虑两侧

下表为平滑模式，只能在开始命令中选一次。

STYLE	EFFECT
ksm	类似 K-Shoot Mania 原版风格的平滑处理。默认
uniform	总是在 1/2 拍内完成过渡
sudden	完全不平滑，倾斜值立即变化

[amp]：倾斜角的增幅倍率，默认 1.0。默认最大角度是 tilt=1.0（编辑器内显示为 100）。如果要反转倾斜方向，可给 amp 负值。

延迟执行（Delay）

delay [step] [subcmds...]
      RATIO   COMMAND

在谱面中更后的时刻立即执行命令。

[step]：从命令位置起算的相对时间（拍），用于指定执行位置。必须为正值。

[subcmds]：要执行的命令。多条时用 { } 包住。

delay 0.5 ztadd i p 0.5 64 100
 -> 0.5拍後に "ztadd i p 0.5 64 100" を実行します。

delay 2 {cl p t;cr p t}
 -> 2拍後に "cl p t" と "cr p t" を実行します。

循环处理

loop [count] [step] [subcmds...]
      INT    RATIO   COMMAND

多次执行同一命令，每步之间保持固定时间间隔。

[count]：循环次数，至少为 2。

[step]：各步之间的时间间隔（拍），必须为正值。首次执行时刻始终是 0，其余分别是 step, 2*step 等。

[subcmds]：要执行的命令。多条时用 { } 包住。

loop 8 0.5 ztadd i p 0.5 64 100
 -> "ztadd i p 0.5 64 100" を 0.5拍間隔で 8回実行します。

loop 4 2 {cl p t;cr p t}
 -> "cl p t" と "cr p t" を 2拍間隔で 4回実行します。

命令批处理

// バッチの定義
batch define [name] [batch commands...]
             STRING      COMMAND

// バッチの呼び出し
batch call [name]
           STRING

// テキストファイルからバッチをロード
batch import [file path]
               STRING

可以定义批处理，并在定义后的任何位置使用。目前所有批处理都可全局调用。也可在外部文本文件中定义并加载。

[name]：批处理名，必须唯一。不能含空白字符、花括号 {} 或分号 ;。未来可能禁用更多特殊字符，因此建议遵循大多数编程语言（Lisp 除外）的符号命名规则。

[batch commands]：批处理内容，多条时用 { } 包住。

[file path]：包含命令定义的文件路径。可用绝对路径，或相对于以下根目录的路径：

如果多个文件匹配，程序会按上述顺序搜索，并打开第一个找到的文件。

在外部文本文件中定义批处理

按以下示例书写：

batch define bump4
{
    loop 4 2
    {
        // ここにコメントを書く
        ztadd sq 1 32 25;
        zbadd sq 1 32 25;
    // 次の行のセミコロンは loop コマンドの終わりです。
    };
}

batch define fifsnake
{
    // つまみの生成
    knob L 0 4/5 0 50;
    knobadd L 8/5 0;
    knobadd L 12/5 50;
    knobadd L 16/5 0;
    knobadd L 4 50;
    slam L 4 50 0;
    // 曲線つまみの作成
    cl p t g;
    delay 4/5 cl p f g;
    delay 8/5 cl p t g;
    delay 12/5 cl p f g;
    delay 16/5 cl p t g;
}

一个文件中可以定义多个批处理。请确保每个 batch define 都从新的一行开始。

只接受单独占据空行的 // 注释。目前不支持行内注释或块注释。

KSHRAM 命令指南（简体中文版）ver. 2025.10.28

程序下载链接

通用说明

如何在谱面（KSH 格式）中写命令

图示

本文档的参数定义语法

参数类型

通用参数

命令列表

添加指定标记

添加指定音符

添加直线激光和直角

knob 命令

knobadd 命令

slam 命令

组合命令

生成曲线激光

平滑镜头效果（视点移动）

平滑镜头效果（差分）

速度变化效果

镜头增幅

Swing 化

跟随激光的自动 tilt

延迟执行（Delay）

循环处理

命令批处理

在外部文本文件中定义批处理

`knob` 命令

`knobadd` 命令

`slam` 命令