pixi-vn-spine-ink

用途

pixi-vn-spine-ink 为 Pixi'VN 项目提供 ink 脚本层面的 Spine 2D 控制能力。它向 ink 添加一组井号命令，使 .ink 文件可以直接显示、编辑、动画化或移除 canvas 上的 Spine 模型，而无需在 TypeScript 中手写调用。这些命令与 @drincs/pixi-vn-ink 的内置命令（如 # show image、# play sound）共用同一命令系统，每个命令最终调用 pixi-vn-spine 中描述的 TypeScript API。官方文档位于 pixi-vn.com/start/canvas-spine2d（查看其中的 “ink” 标签页）。若需了解 Pixi'VN 中 ink 的通用用法，可参考 pixi-vn-ink 技能集。

安装与注册

按 pixi-vn-spine 的说明安装并注册该包，其中包括在 main.ts 中执行副作用导入 import "@drincs/pixi-vn-spine";。同时确保已安装 @drincs/pixi-vn-ink 与 zod——它们是可选 peer 依赖，仅此入口点需要。

在任何 ink 内容被解析之前，于 addBaseHashtagCommands 旁调用一次 createSpineHandler()：

import { addBaseHashtagCommands } from "@drincs/pixi-vn-ink";
import { createSpineHandler } from "@drincs/pixi-vn-spine/ink";

addBaseHashtagCommands({ bundleIds, assetAliasIds });
createSpineHandler();

重复调用会重复注册命令。spine 命令不会拦截基础命令（# show image、# play sound 等）；如果这些基础命令停止解析，请检查传给 addBaseHashtagCommands 的 assetAliasIds/bundleIds 允许列表——当提供允许列表时，ink 中使用的每个别名（包括 skeleton 与 atlas 别名）都必须列入其中。

命令说明

以下命令中，<alias> 是元素的 canvas 键（即 canvas.add(alias, ...) 中的键），不是资源别名。自由属性以 <key> <value> 对书写并解析为对象，数字与布尔值会转换为对应类型（如 xAlign 0.5、loop true）。

显示

# show spine <alias> skeleton <skeletonAlias> atlas <atlasAlias> [<key> <value> …] [with <transition> [<key> <value> …]]

skeleton 与 atlas（资源别名）为必填项，缺失时命令记录错误且不显示任何内容。该命令会自行加载这两个资源，无需单独的 # load 步骤。其余属性传给 SpineOptions：xAlign、yAlign、align、anchor、percentageX、x、y、alpha、zIndex、scale、skin、animation 等；animation 在轨道 0 上循环播放。入场过渡包括：dissolve、fade、movein、zoomin、pushin，过渡名之后的词为其属性（如 duration 1、direction left）。

=== start ===
# show spine boy skeleton spineboySkeleton atlas spineboyAtlas xAlign 0.5 yAlign 1 animation idle
# show spine goblin skeleton goblinsSkeleton atlas goblinsAtlas skin goblin xAlign 0.2 yAlign 1 animation walk with dissolve duration 1
-> DONE

用 xAlign/yAlign（0..1）做屏幕相对定位；x/y 是像素，因此 x 0 y 1 将模型放在左上角而非底边。

编辑

# edit spine <alias> [<key> <value> …]

直接在已有 Spine 元素上赋值（alpha、tint、x、y、xAlign、yAlign、visible、zIndex、angle 等）。皮肤与动画请使用下方专用命令。若不存在该别名的元素，命令会记录错误。

# edit spine boy xAlign 0.8 alpha 0.5

移除

# remove spine <alias> [with <transition> [<key> <value> …]]

退场过渡包括：dissolve、fade、moveout、zoomout、pushout。仅限入场的名称（如 movein）在此被忽略，元素会立即移除且无过渡。

# remove spine boy with fade duration 0.5

切换皮肤

# change skin <skinName> on spine <alias>

调用 setSkin。皮肤名区分大小写，且必须存在于 Spine 工程中。

播放动画

# play <animationName> on spine <alias> [loop <bool>] [trackIndex <n>] [delay <seconds>] [completeOnContinue <bool>]

调用 addAnimation，动画会排在该轨道当前播放内容之后。传入 trackIndex 可在已有轨道上排队；不传则动画进入新轨道并叠加在当前轨道之上。例如在 # show spine boy ... animation idle（轨道 0）之后：

# play walk on spine boy trackIndex 0 loop true   // walk 接在轨道 0 的 idle 之后
# play wave on spine boy trackIndex 1             // wave 叠加在身体之上，位于轨道 1

completeOnContinue true 会在下一个叙述步骤清除该轨道，适用于不应延续到下一行的一次性动画。ink 中没有用于 setAnimation（立即替换）或 playSequence 的命令；如需这些，可先 # clear tracks 再 # play，或在 TypeScript 中编写自定义 hashtag 命令（见 pixi-vn-ink-hashtag-commands 技能）调用 Spine API。

清除轨道

# clear tracks on spine <alias>

调用 clearTracks()，停止所有轨道与正在运行的序列，骨架保持当前姿态。

完整示例

=== start ===
# show spine boy skeleton spineboySkeleton atlas spineboyAtlas xAlign 0.5 yAlign 1 animation idle with fade duration 0.5
Boy: Hi!
# play walk on spine boy trackIndex 0 loop true
# edit spine boy xAlign 0.8
Boy: Let's go.
# clear tracks on spine boy
# change skin alt on spine boy
# pause
# remove spine boy with dissolve
-> DONE

导出的辅助函数

createSpineHandler(): void —— 通过 @drincs/pixi-vn-ink 的 HashtagCommands.add 注册上述所有命令。每个命令都有 zod 校验与 keySchemas，因此 @drincs/pixi-vn-ink 的 Vite 开发服务器会列出这些命令并检查其属性。
parseShowSpineTail(tail: string[]) —— 将 # show spine 行中 <alias> 之后的 token 拆分为 { propsList, transitionType?, transitionPropsList }。它供内部使用，同时对外导出以便自定义命令复用同一语法。

注意事项

未调用 createSpineHandler 时，# show spine ... 会被报告为未知的 hashtag 命令。
# show spine 中缺少 skeleton 或 atlas 键时，会记录错误且不显示任何内容。
# play 不带 trackIndex 时会叠加新轨道，而非排队（见上文）。
addBaseHashtagCommands 的资源允许列表若遗漏 Spine 别名，开发服务器 linter 会标出这些别名。