StarNight Engine

注意

本章节可按需查阅，编写剧本时可通过智能提示获得与本章节相同的命令介绍、参数说明等完整信息。

# 设置背景

设置背景图片，使用 GSAP 实现，支持位置、缩放、滤镜等属性。

备注

  • 持续时间 仅控制背景图片的入场动画时长（淡入效果），其他属性（如位置、缩放、滤镜等）会立即应用。
  • 参数值支持数值或字符串（如 "+=100"），+= 表示相对于当前值的增量，但并非所有参数支持此相对值语法。

# 使用演示

$.设置背景({ 资源路径: "/咸鱼池塘.jpg", 持续时间: 500, X坐标: -120, 模糊: 5, 亮度: 1.2 })
参数 功能
资源路径 背景图片的文件路径（必需）
持续时间 入场动画持续时间，单位毫秒（可选，默认 225）
X 坐标 横坐标（可选，默认 0）
Y 坐标 纵坐标（可选，默认 0）
宽度 图片宽度（可选，默认图片自身宽度）
高度 图片高度（可选，默认图片自身高度）
X 轴缩放 横轴缩放比例（可选，默认 1）
Y 轴缩放 纵轴缩放比例（可选，默认 1）
旋转角度 图片旋转角度，单位为度（可选）
斜切 整体斜切变换（可选）
X 轴斜切 横轴斜切变换（可选）
Y 轴斜切 纵轴斜切变换（可选）
中心点 图片整体变换的基准点（可选）
X 轴中心点 横轴变换的基准点（可选）
Y 轴中心点 纵轴变换的基准点（可选）
锚点 图片整体纹理的锚点，范围 0 到 1（可选）
X 轴锚点 横轴纹理的锚点（可选）
Y 轴锚点 纵轴纹理的锚点（可选）
模糊 整体模糊效果强度（可选）
横向模糊 横向模糊效果强度（可选）
纵向模糊 纵向模糊效果强度（可选）
模糊边距 模糊效果的边距（可选）
亮度 亮度调整，范围 0 到无穷大（可选，1 为无调整）
对比度 对比度调整，范围 0 到无穷大（可选，1 为无调整）
色相 色相调整，单位为度（可选，0 为无调整）
饱和度 饱和度调整，范围 0 到无穷大（可选，1 为无调整）
着色 着色效果，接受颜色值（如 "#ff0000" 或 0xff0000）（可选）
着色强度 着色效果强度，范围 0 到 1（可选，0 为无着色，1 为完全着色）
颜色矩阵滤镜 自定义颜色矩阵滤镜对象（可选）
合并颜色矩阵 是否合并颜色矩阵滤镜（可选，默认 false）
变换矩阵 自定义变换矩阵，类型为 PixiPlugin.PixiMatrix（可选）

# 设置立绘

设置角色立绘图片，使用 GSAP 实现，支持位置、缩放、滤镜等属性。

备注

  • 多次为同一标识符设置新立绘时，应确保之前的入场动画已完成，以避免亮度异常的错误。
  • 持续时间 仅控制立绘图片的入场动画时长（淡入效果），其他属性（如位置、缩放、滤镜等）会立即应用。
  • 参数值支持数值或字符串（如 "+=100"），+= 表示相对于当前值的增量，但并非所有参数支持此相对值语法。

# 使用演示

$.设置立绘({ 标识符: "咸鱼", 资源路径: "/saltfish/fish.jpg", 持续时间: 500, X坐标: 640, Y坐标: 640, 模糊: 5 })
参数 功能
标识符 立绘的标识符，用于后续操作（必需）
资源路径 立绘图片的文件路径（必需）
持续时间 入场动画持续时间，单位毫秒（可选，默认 225）
图层高度 立绘的图层高度，控制遮挡关系，值越大越靠前显示（可选，默认 1）
X 坐标 横坐标（可选，默认 0）
Y 坐标 纵坐标（可选，默认 0）
宽度 图片宽度（可选，默认图片自身宽度）
高度 图片高度（可选，默认图片自身高度）
X 轴缩放 横轴缩放比例（可选，默认 1）
Y 轴缩放 纵轴缩放比例（可选，默认 1）
旋转角度 图片旋转角度，单位为度（可选）
斜切 整体斜切变换（可选）
X 轴斜切 横轴斜切变换（可选）
Y 轴斜切 纵轴斜切变换（可选）
中心点 图片整体变换的基准点（可选）
X 轴中心点 横轴变换的基准点（可选）
Y 轴中心点 纵轴变换的基准点（可选）
锚点 图片整体纹理的锚点，范围 0 到 1（可选）
X 轴锚点 横轴纹理的锚点（可选）
Y 轴锚点 纵轴纹理的锚点（可选）
模糊 整体模糊效果强度（可选）
横向模糊 横向模糊效果强度（可选）
纵向模糊 纵向模糊效果强度（可选）
模糊边距 模糊效果的边距（可选）
亮度 亮度调整，范围 0 到无穷大（可选，1 为无调整）
对比度 对比度调整，范围 0 到无穷大（可选，1 为无调整）
色相 色相调整，单位为度（可选，0 为无调整）
饱和度 饱和度调整，范围 0 到无穷大（可选，1 为无调整）
着色 着色效果，接受颜色值（如 "#ff0000" 或 0xff0000）（可选）
着色强度 着色效果强度，范围 0 到 1（可选，0 为无着色，1 为完全着色）
颜色矩阵滤镜 自定义颜色矩阵滤镜对象（可选）
合并颜色矩阵 是否合并颜色矩阵滤镜（可选，默认 false）
变换矩阵 自定义变换矩阵，类型为 PixiPlugin.PixiMatrix（可选）

# 添加动画

为指定目标添加动画效果，使用 GSAP 实现，支持位置、缩放、滤镜等属性。

备注

  • 针对同一目标的多个动画将按顺序执行，前一个动画完成后触发后一个动画。
  • 可访问 GSAP 文档 (opens new window) 查看 GSAP 缓动预设或创建自定义缓动曲线。
  • 参数值支持数值或字符串（如 "+=100"），+= 表示相对于当前值的增量，但并非所有参数支持此相对值语法。

# 使用演示

$.添加动画({ 作用目标: "咸鱼", 持续时间: 1000, X坐标: "+=100", Y坐标: 720, 缓动函数: "M0,0,C0,0,1,1,1,1" })
参数 功能
作用目标 动画应用的目标标识符，舞台的标识符为 0，背景的标识符为 1（必需）
持续时间 动画持续时间，单位毫秒（可选，默认 0，无动画）
缓动函数 动画缓动函数，支持 GSAP 缓动预设、缓动曲线或函数（可选，默认 "none"）
继承 是否在切换图像后继承当前动画属性（可选，默认 true）
X 坐标 横坐标（可选，默认 0）
Y 坐标 纵坐标（可选，默认 0）
宽度 图片宽度（可选，默认图片自身宽度）
高度 图片高度（可选，默认图片自身高度）
X 轴缩放 横轴缩放比例（可选，默认 1）
Y 轴缩放 纵轴缩放比例（可选，默认 1）
旋转角度 图片旋转角度，单位为度（可选）
斜切 整体斜切变换（可选）
X 轴斜切 横轴斜切变换（可选）
Y 轴斜切 纵轴斜切变换（可选）
中心点 图片整体变换的基准点（可选）
X 轴中心点 横轴变换的基准点（可选）
Y 轴中心点 纵轴变换的基准点（可选）
锚点 图片整体纹理的锚点，范围 0 到 1（可选）
X 轴锚点 横轴纹理的锚点（可选）
Y 轴锚点 纵轴纹理的锚点（可选）
模糊 整体模糊效果强度（可选）
横向模糊 横向模糊效果强度（可选）
纵向模糊 纵向模糊效果强度（可选）
模糊边距 模糊效果的边距（可选）
亮度 亮度调整，范围 0 到无穷大（可选，1 为无调整）
对比度 对比度调整，范围 0 到无穷大（可选，1 为无调整）
色相 色相调整，单位为度（可选，0 为无调整）
饱和度 饱和度调整，范围 0 到无穷大（可选，1 为无调整）
着色 着色效果，接受颜色值（如 "#ff0000" 或 0xff0000）（可选）
着色强度 着色效果强度，范围 0 到 1（可选，0 为无着色，1 为完全着色）
颜色矩阵滤镜 自定义颜色矩阵滤镜对象（可选）
合并颜色矩阵 是否合并颜色矩阵滤镜（可选，默认 false）
变换矩阵 自定义变换矩阵，类型为 PixiPlugin.PixiMatrix（可选）

# 添加滤镜

为指定目标添加滤镜，使用 PixiJS 滤镜实现。

备注

  • 滤镜动画可通过 基本动画 命令实现。

# 使用演示

$.添加滤镜({ 作用目标: "咸鱼", 滤镜实例: new BlurFilter(5) })
参数 功能
作用目标 滤镜应用的目标标识符，舞台的标识符为 0，背景的标识符为 1（必需）
滤镜实例 PixiJS 滤镜实例，需 economia 有效的 Filter 对象（必需）

# 动效动画

为指定目标应用一段动效动画。

备注

  • 动效动画会独立于主动画序列同时运行，但同一时间只应运行一个动效动画。

# 使用演示

$.动效动画({ 作用目标: "咸鱼", 预设名称: "摇晃", Y轴幅度: 15, 持续时间: 1000 })
参数 功能
作用目标 动画应用的目标标识符，舞台的标识符为 0，背景的标识符为 1（必需）
预设名称 动画名称，如 "震动" 或 "摇晃"（必需）
持续时间 动画持续时间，单位毫秒（必需）
X 轴幅度 横向动画幅度（可选，需至少提供 X 轴幅度 或 Y 轴幅度 之一）
Y 轴幅度 纵向动画幅度（可选，需至少提供 X 轴幅度 或 Y 轴幅度 之一）

# 关闭图像

关闭指定的立绘或背景，支持淡出动画。

备注

  • 持续时间 控制图像消失时的淡出动画时长。
  • 作用目标 可以是一个或多个标识符组成的数组，用于同时关闭多个图像。

# 使用演示

// 关闭单个立绘
$.关闭图像({ 作用目标: "咸鱼" })
// 同时关闭多个立绘
$.关闭图像({ 作用目标: ["咸鱼", "鸽子"] })
参数 功能
作用目标 关闭图像的目标标识符或标识符数组，背景的标识符为 1（必需）
持续时间 淡出动画的持续时间，单位毫秒（可选，默认 225）

# 清空立绘

立即移除所有立绘，无淡出动画。

# 使用演示

$.清空立绘()

# 设置配乐

设置背景音乐（BGM），使用 Howler 实现，支持音量、循环播放等属性。

备注

  • 持续时间 控制音量缓入缓出的持续时间。
  • 如果提供 音量 参数，音频将通过 持续时间 渐入到指定音量。
  • 音量、播放速度 等参数不会在同一音轨上继承，需重新设置。

# 使用演示

$.设置配乐({ 资源路径: "/bgm01.mp3", 持续时间: 1000, 音量: 0.5 })
参数 功能
资源路径 音频的文件路径（必需）
标识符 音轨的标识符（可选，默认 "bgm"）
持续时间 音量缓入缓出时间，单位毫秒（可选，默认 0）
音量 音频的音量，范围 0 到 1（可选，默认 1）
循环播放 是否循环播放（可选，默认 true）
播放速度 音频播放速度，范围 0.5 到 4（可选，1 为无调整）
使用 HTML5 是否使用 HTML5 音频播放，适合大文件以减少加载时间（可选，默认自动选择）

# 设置音效

设置音效（SE），使用 Howler 实现，支持音量、循环播放等属性。

备注

  • 持续时间 控制音量缓入缓出的持续时间。
  • 如果提供 音量 参数，音频将通过 持续时间 渐入到指定音量。
  • 音量、播放速度 等参数不会在同一音轨上继承，需重新设置。

# 使用演示

$.设置音效({ 资源路径: "/se01.mp3", 循环播放: true, 持续时间: 500, 音量: 0.7 })
参数 功能
资源路径 音频的文件路径（必需）
标识符 音轨的标识符（可选，默认 "se"）
持续时间 音量缓入缓出时间，单位毫秒（可选，默认 0）
音量 音频的音量，范围 0 到 1（可选，默认 1）
循环播放 是否循环播放（可选，默认 false）
播放速度 音频播放速度，范围 0.5 到 4（可选，1 为无调整）
使用 HTML5 是否使用 HTML5 音频播放，适合大文件以减少加载时间（可选，默认自动选择）

# 设置配音

设置角色配音（Clip），使用 Howler 实现，支持音量、播放速度等属性。

备注

  • 配音的音轨标识符固定为 "clip"。
  • 通常应使用 对话 命令设置配音，单独使用 设置配音 将不会记录到 Backlog。
  • 音量、播放速度 等参数不会在同一音轨上继承，需重新设置。

# 使用演示

$.设置配音({ 资源路径: "/noi01.mp3", 音量: 0.8, 播放速度: 1.2 })
参数 功能
资源路径 音频的文件路径（必需）
音量 音频的音量，范围 0 到 1（可选，默认 1）
播放速度 音频播放速度，范围 0.5 到 4（可选，1 为无调整）
使用 HTML5 是否使用 HTML5 音频播放，适合大文件以减少加载时间（可选，默认自动选择）

# 设置音量

设置指定音轨的音量，使用 Howler 实现，支持渐变过渡。

备注

  • 持续时间 控制音量渐变的过渡时间，未设置时音量立即应用。

# 使用演示

$.设置音量({ 作用目标: "bgm", 音量: 0.5, 持续时间: 1000 })
参数 功能
作用目标 音轨的标识符（必需）
音量 目标音量，范围 0 到 1（必需）
持续时间 音量渐变过渡时间，单位毫秒（可选）

# 关闭音频

关闭指定音轨的音频，使用 Howler 实现，支持渐变淡出。

备注

  • 持续时间 控制音量渐出的过渡时间，未设置时立即关闭。

# 使用演示

$.关闭音频({ 作用目标: "bgm", 持续时间: 1000 })
参数 功能
作用目标 要关闭的音轨标识符（必需）
持续时间 音量渐出过渡时间，单位毫秒（可选）

# 转场动画

播放一段转场动画。

备注

  • 转场动画用于场景切换，但不会自动处理背景或立绘的转场。

# 使用演示

$.转场动画("BlindH8")
参数 功能
预设名称 转场动画名称（如 "BlindH8"）

# 播放视频

播放视频。

# 使用演示

$$.播放视频({ 资源路径: "/OP.mp4", 允许跳过: false })
参数 功能
资源路径 视频的文件路径（必需）
允许跳过 是否允许用户跳过视频（可选，默认 true）

# 用户输入

显示输入框并获取用户输入的文本。

返回值

  • 用户输入的文本

# 使用演示

const res = $$.用户输入({ 描述文本: "请输入你的名字" })
参数 功能
描述文本 输入框显示的提示文本（可选）

# 用户选择

显示选项列表并获取用户所选项的标识符。

返回值

  • 用户所选项的标识符

# 使用演示

const label = $$.用户选择([
  { 标识符: "*そのまま渡す", 描述文本: "直接给她" },
  { 标识符: "*振ってから渡す", 描述文本: "晃晃再给她" },
])
参数 功能
标识符 选项的标识符（必需）
描述文本 选项显示的文本（必需）
禁用 是否禁用该选项（可选，默认 false）

# 用户点击

等待用户点击。

# 使用演示

$$.用户点击()

# 显示界面

显示或隐藏游戏的 UI 界面（如文本框、选项栏等）。

备注

  • 设置 false N 次，需相应设置 true N 次以复位。

# 使用演示

$.显示界面(true)
参数 功能
状态 true 为显示，false 为隐藏 ！

# 允许点击

允许或禁止用户点击以继续剧情。

备注

  • 设置 false N 次，需相应设置 true N 次以复位。

# 使用演示

$.允许点击(true)
参数 功能
状态 true 为允许，false 为禁止点击

# 解锁鉴赏

解锁 CG 或其他鉴赏内容。

备注

  • 在默认情况下，设置背景、立绘、音频等时，将自动解锁相关鉴赏内容。

# 使用演示

$.解锁鉴赏("cg01.jpg")
参数 功能
资源路径 要解锁的 CG 或内容文件路径

# 解锁成就

解锁指定成就。

# 使用演示

$.解锁成就(1)
参数 功能
成就 ID 成就的编号

# 自动继续

自动进入下一幕，无需用户点击。

# 使用演示

$.自动继续()

# 系统计时

等待指定时间。

# 使用演示

$$.系统计时(500)
参数 功能
时间 等待时间，单位毫秒

# 结束剧情

结束剧情，停止后续执行。

备注

  • 在默认情况下，命令执行后将返回标题页。

# 使用演示

$.结束剧情()

# 嵌入页面

嵌入 iframe 页面，显示外部内容。

备注

  • 嵌入的页面需通过 window.parent.postMessage 发送结果，发送的数据将作为命令返回值。

返回值

  • 页面发送的结果数据

# 使用演示

$$.嵌入页面({ 资源路径: "example.com" })
参数 功能
资源路径 iframe 的 URL（必需）

# 基本输入

执行自定义输入并返回结果。

备注

  • 如果程序的结果不是确定的，如获取日期、随机数或外部输入，可以使用此命令。

返回值

  • 回调函数的结果

# 使用演示

$$.基本输入(async () => new Date().toISOString())
参数 功能
回调函数 返回 Promise 的函数（必需）

# 基本动画

为任意对象添加动画效果，使用 GSAP 实现。

备注

  • 可访问 GSAP 文档 (opens new window) 查看 GSAP 位置参数用法。
  • 可访问 GSAP 文档 (opens new window) 查看 GSAP 缓动预设或创建自定义缓动曲线。
  • 参数值支持数值或字符串（如 "+=100"），+= 表示相对于当前值的增量，但并非所有参数支持此相对值语法。

# 使用演示

$.基本动画({ 目标: document.querySelector(".box"), 持续时间: 1000, x: "+=100", opacity: 0.5 })
参数 功能
目标 动画应用的目标对象，接受 GSAP 支持的 TweenTarget（必需）
模式 动画模式，"from" 表示从指定值开始，"to" 表示到指定值结束（可选，默认 "to"）
持续时间 动画持续时间，单位毫秒（可选，默认 0）
缓动函数 动画缓动函数，支持 GSAP 缓动预设、缓动曲线或函数（可选，默认 "none"）
标识符 动画序列的标识符，针对同一标识符的多个动画将按顺序执行（可选，默认与目标参数值相同）
位置 动画在 GSAP 动画序列中的位置，可传入符合 GSAP 位置参数要求的值（可选）
动画属性 目标对象的任意属性，如 scale、opacity 等

← 代码语法 →