命令与函数索引

这里按名字查，不承担教学顺序。命令以 @ 开头、独占一行，主要改变画面、声音、正文呈现或交互；函数写在 JS 表达式里并返回值。想按用途学习，先读演出命令和变量、条件与逻辑。

背景与声音

签名	参数与效果
@bg_show(image [, treatment])	显示背景图；可写 "no_blur" 只取消当前背景的模糊。
@bg_hide()	隐藏背景图。
@bgm_play(audio)	循环播放背景音乐。
@bgm_pause()	暂停当前背景音乐，保留当前位置。
@bgm_stop()	停止当前背景音乐。
@sfx(audio)	播放一次性音效；同一次推进可触发多条，读档重放不会补播过去的音效。

详见演出命令：场景、背景与音乐。路径均相对项目根，assets/ 只是推荐目录名。

正文流

签名	参数与效果
@img(path [, alt] [, class])	插入随正文滚动的图片。路径必填；替代文字与作品 CSS 类名可省。
@divider([class])	插入随正文滚动的分割线；可给一个作品 CSS 类名。
@clear()	清掉已经显示的正文、插图和分割线；不动背景与背景音乐。

详见演出命令：正文流。class 只含 Unicode 字母数字、_、-，渲染时会加 kin- 前缀。

呈现节奏与阅读视角

签名	参数与效果
@step_mode(mode)	"flow" 连续流到暂停点（默认）；"line" 每段等读者点击。
@text_speed(cps)	每秒显示多少字；默认 80，0 为整段瞬显。
@text_fade(ms)	每个字的淡入毫秒数；默认 300，0 为无淡入。
@scroll_mode(mode)	"auto" 自动跟到最新（默认）；"manual" 在 flow 模式把视角交给读者。
@sleep(ms)	在行与行之间等待非负毫秒数；读者不能跳过，读档重放不等待。

这些设定会持续到再次改写或故事重开。推进与滚动互相独立；句子中间的暂停不是命令，请用 <pause> 或 <pause=毫秒>。详见演出命令：节奏。

固定区域与输入

签名	参数与效果
@panel(slot, template)	登记或更新固定区域。槽位必须是字面量 "left"、"right"、"bottom"、"after" 之一；空模板清空该槽。
@input(var [, hint])	暂停并向读者要一段文字，非空输入写回已声明变量 var；提示文字可省。

@panel 模板里的 {表达式} 会在每个事件边界重估，适合绑定全局变量；它是显示区，不提供按钮或链接。@input 的第一个参数是裸变量名，不是普通右值表达式。详见固定区域与向读者提问。

命令通则

• 形状只能是 @名字(参数)，整行顶格；未知命令会报错。
• 除 @input 的写回目标、@panel 的槽位字面量外，参数都是 JavaScript 表达式，可以传变量。
• 资源路径按项目根解析。路径或参数是动态表达式时，无法在编辑期完全判断，阅读期仍会做兜底。
• 命令不输出正文；它们也是硬边界，文本粘连 <> 不能越过命令。

内置函数

签名	返回值 / 作用
random(min, max)	返回闭区间 [min, max] 内的随机整数，受随机种子控制。
seed_random(n)	设置故事随机种子。
turns()	返回当前总回合数。
turns_since("节点名")	返回距离上次访问该节点的回合数；未访问返回 -1。
seq(...items)	按源码位置依次返回各项，到末项后停住。
cycle(...items)	按源码位置循环返回各项。
once(...items)	按源码位置依次返回各项，用完后返回空串。
shuffle(...items)	随机返回一项，受随机种子控制。

这八个名字是保留标识符，不能拿来命名变量、节点参数或选项标签。seq、cycle、once、shuffle 的计数跟源码位置绑定，见文本变体；其余逻辑直接使用 JavaScript 的 Math、JSON、Array、parseInt 等白名单能力，见变量、条件与逻辑。

作者自己写函数

Kiny 没有另一套函数语法。在顶层 ~~~ 块里写 JavaScript function 或箭头函数；在 {f(value)} 中把返回值插入正文，在 ~ f(value) 中只执行副作用。函数和文件顶部变量一样跨 .kin 文件共享，名字必须全局唯一。