QuestUtils.zh CN

QuestUtils API（中文）

QuestUtils 是面向 KubeJS 的可选 FTB Quests 桥接层，提供直接查询和编辑任务书内容的方法。

可用性与执行侧

只有安装 KubeJS 时才会注册 QuestUtils，因此脚本可以直接写：

const quest = QuestUtils.getQuest('1234567890123')

进度和任务书结构写操作应从服务端 KubeJS 事件触发。从服务端事件打开任务书时使用带玩家参数的 open。

KubeJS 中统一使用字符串 ID。所有按 ID 操作的分组都提供 String 重载；数字重载主要给 Java 调用，不建议在 JavaScript 中使用。

返回值约定

返回值	含义
对象	找到的或刚创建的 FTB 对象。
`null`	找不到对象、ID 无效、资源无效或创建被拒绝。
`true`	操作已接受。
`false`	校验失败、对象不存在或当前上下文不允许操作。
空列表 / `0`	没有对应画布元素、前置或进度。

对象查询与画布查询

方法	用途
`getObject(id)`	查询任意 `QuestObjectBase`。
`getQuest(id)`	查询任务节点。
`getChapter(id)`	查询章节。
`getTask(id)`	查询任务目标。
`getChapterImages(chapterId)`	返回章节画布元素的不可变快照。
`getChapterImageCount(chapterId)`	统计章节画布元素数量。
`getChapterImage(chapterId, index)`	按列表索引查询元素，找不到返回 `null`。
`getChapterImageData(image)`	将元素序列化为独立的 NBT 数据副本。
`getChapterImageType(image)`	返回 `image`、`gif`、`video`、`text` 或 `anchor`。
`getChapterGifResource(image)`	返回 GIF 资源 ID，找不到返回 `null`。
`getChapterVideoPath(image)`	返回规范化视频路径，找不到返回 `null`。
`getChapterText(image)`	返回画布文字，找不到返回 `null`。
`getChapterTextFont(image)`	返回文字字体资源 ID，找不到返回 `null`。
`getDecorativeAnchorKey(image)`	返回辅助点稳定 key，找不到返回 `null`。

画布列表是快照。不要直接修改列表或 NBT 对象，使用后面的专用修改方法。

玩家与队伍状态

这些方法使用传入 Entity 对应的 FTB 队伍数据。

方法	用途
`isStarted(player, id)`	判断队伍是否开始了任务对象。
`isCompleted(player, id)`	判断队伍是否完成了任务对象。
`isVisible(player, id)`	判断对象对队伍是否可见。
`getProgress(player, id)`	对任务目标返回目标进度，对任务节点返回相对进度。
`getQuestProgress(player, id)`	获取任务节点相对进度整数。
`getMaxProgress(taskId)`	获取目标最大进度。
`getCompletionCount(player, questId)`	获取队伍完成任务的次数。

getProgress 和 getMaxProgress 使用 long。ID 仍使用字符串，进度计算则可以按数字处理。

进度写操作

方法	用途
`complete(player, id)`	按 FTB 进度逻辑完成任务对象。
`reset(player, id)`	按 FTB 进度逻辑重置任务对象。
`completeTask(player, taskId)`	将目标设置为最大进度。
`setProgress(player, taskId, progress)`	设置目标进度。
`addProgress(player, taskId, amount)`	增加一个可正可负的进度值。
`resetTask(player, taskId)`	将目标进度设为零。

目标不存在、队伍数据不存在或队伍被锁定时，写操作会拒绝。

前置任务

方法	用途
`arePrerequisitesCompleted(player, questId)`	判断所有前置任务是否完成。
`completedPrerequisiteCount(player, questId)`	统计队伍已完成的前置数量。
`prerequisiteCount(questId)`	统计全部前置数量。
`prerequisites(questId)`	返回前置任务 ID 字符串列表。
`hasPrerequisite(prerequisiteQuestId, questId)`	判断一条前置关系。
`setPrerequisite(prerequisiteQuestId, questId)`	添加前置关系，循环依赖会被拒绝。
`removePrerequisite(prerequisiteQuestId, questId)`	删除一条前置关系。
`clearPrerequisites(questId)`	清空任务的全部前置关系。

setPrerequisite 的第一个参数是前置任务，第二个参数是依赖它的目标任务。

隐藏与任务字段

方法	用途
`hideQuest(questId)` / `unhideQuest(questId)`	隐藏或取消隐藏任务。
`isQuestHidden(questId)`	查询任务隐藏状态。
`hideChapter(chapterId)` / `unhideChapter(chapterId)`	隐藏或取消隐藏章节。
`isChapterHidden(chapterId)`	查询章节隐藏状态。
`setTitle(questId, title)`	修改任务标题。
`setQuestSubtitle(questId, subtitle)`	修改副标题。
`setQuestDescription(questId, ...lines)`	替换原始描述行。
`setQuestSize(questId, size)`	修改画布节点缩放。
`setQuestShape(questId, shape)`	修改节点形状，例如 `circle`。
`setQuestOptional(questId, optional)`	设置任务是否可选。
`setTaskOptional(taskId, optional)`	设置目标是否可选。

原始 NBT

方法	用途
`getData(id)`	返回对象原始 NBT 数据副本。
`mergeData(id, changes)`	将 `CompoundTag` 合并到对象。

只有没有专用方法的字段才应使用原始 NBT。已有专用方法时优先使用专用方法，因为它会校验值。

动态创建对象

方法	用途
`createChapter(groupId, title)`	在 FTB 分组中创建并注册章节。
`createQuest(chapterId, x, y, title?)`	在画布坐标创建任务节点。
`createTask(questId, type, title?)`	使用 FTB 目标类型 ID 创建目标。
`createReward(questId, type, title?)`	使用 FTB 奖励类型 ID 创建奖励。

创建方法返回真实 FTB 对象，可以用 getCodeString() 读取新 ID。传回 KubeJS 时继续将 ID 当作字符串保存。

const chapter = QuestUtils.createChapter('0', 'KubeJS 测试章节')
if (chapter !== null) {
  const chapterId = chapter.getCodeString()
  const quest = QuestUtils.createQuest(chapterId, 0, 0, '第一个任务')
  if (quest !== null) {
    QuestUtils.createTask(quest.getCodeString(), 'checkmark', '完成这个目标')
  }
}

任务描述组件

所有描述构造方法都返回一行原始描述文本，并自动处理 JSON 转义、URL 校验、Base64、尺寸、对齐和物品 NBT，脚本不需要手工拼接易错的解析器语法。

方法	用途
`descriptionWebLink(displayText, url)`	打开网页的 JSON 文字组件。
`descriptionCopy(displayText, value)`	点击复制内容的 JSON 文字组件。
`descriptionCommand(displayText, command)`	点击执行命令的 JSON 文字组件。
`descriptionImage(url, width, height, alignment, fit, hoverText)`	网络图片组件。
`descriptionItemIcon(stack, width, height, alignment, fit, hoverText)`	保留数量、损伤值和完整 NBT 的物品图片。
`descriptionItemHover(displayText, stack)`	保留完整 NBT 的 JSON 物品悬停组件。
`descriptionGif(resourceId, width, height, alignment, fit, hoverText)`	GIF 描述组件。
`descriptionVideo(videoPath, displayText)`	使用安全相对路径的视频描述组件。
`descriptionHoverText(displayText, hoverText)`	带文字悬停提示的 JSON 文字组件。
`descriptionFont(displayText, fontId)`	使用校验过的字体资源显示文字。
`descriptionTranslation(displayText, translationKey)`	带回退文字的本地化组件。
`descriptionKeybind(keybind)`	按键绑定组件。
`descriptionTable(rows, header, alignment)`	使用默认布局参数创建表格。
`descriptionTable(columns, rows, header, alignment, tableWidth, rowHeight, lineWidth, borderColor, headerColor, cellColor, textColor)`	使用完整布局和颜色参数创建表格。

对齐值为 left、center 或 right。尺寸会限制在渲染器支持的范围内。GIF 必须是 Quest Enhance 的纹理资源；视频路径必须是配置视频目录下的相对路径；物品图标输入必须是非空 KubeJS ItemStack。

const sword = Item.of('minecraft:diamond_sword')
sword.getOrCreateTag().putInt('Damage', 2)
sword.getOrCreateTag().putString('quest_enhance_test', 'NBT 测试')

const itemLine = QuestUtils.descriptionItemIcon(
  sword, 24, 24, 'center', false, '带 NBT 的钻石剑'
)
QuestUtils.setQuestDescription('1234567890123', itemLine)

画布创建与编辑

创建

方法	用途
`createChapterImage(chapterId, resource, x, y, width, height)`	创建普通资源图片。
`createChapterGif(chapterId, resource, x, y, width, height)`	创建 GIF 画布元素。
`createChapterVideo(chapterId, videoPath, x, y, width, height)`	创建视频画布元素。
`createChapterText(chapterId, text, font, x, y, width, height)`	创建文字画布元素。
`createDecorativeAnchor(chapterId, x, y)`	创建带新稳定 key 的辅助点。

创建方法返回 ChapterImage 或 null。资源 ID 必须能解析为 Minecraft ResourceLocation；坐标和尺寸必须是有限值，尺寸必须为正数。

原生图片字段

方法	用途
`setChapterImagePosition(image, x, y)`	修改位置。
`setChapterImageSize(image, width, height)`	修改正数尺寸。
`setChapterImageRotation(image, rotation)`	修改 -180 到 180 度的旋转。
`setChapterImageResource(image, resource)`	修改资源位置。
`setChapterImageColor(image, rgb)`	修改 RGB 颜色。
`setChapterImageAlpha(image, alpha)`	修改 0 到 255 的透明度。
`setChapterImageOrder(image, order)`	修改绘制层级。
`setChapterImageHover(image, ...lines)`	替换悬停文本行。
`setChapterImageClick(image, click)`	设置或清空点击动作。
`setChapterImageEditorsOnly(image, editorsOnly)`	限制为编辑者可见。
`setChapterImageAlignToCorner(image, alignToCorner)`	开关角落对齐。
`setChapterImageDependency(image, questId)`	添加任务依赖。
`clearChapterImageDependency(image)`	清除任务依赖。

专用画布字段

方法	用途
`setChapterGifResource(image, resource)`	替换 GIF 资源并保留 GIF 类型。
`setChapterVideoPath(image, videoPath)`	替换视频路径并保留视频类型。
`setChapterText(image, text)`	替换文字并保留字体。
`setChapterTextFont(image, font)`	替换字体并保留文字。

专用 setter 遇到错误元素类型时会拒绝操作，避免 GIF、视频或文字的 click 数据被静默改成其他类型。

画布移动、复制和删除

方法	用途
`copyChapterImage(image, chapterId, x, y)`	复制元素到章节并返回副本；辅助点会生成新 key。
`moveChapterImage(image, chapterId, x, y)`	在章节内或跨章节移动并返回结果元素。
`deleteChapterImage(image)`	删除指定画布元素。
`deleteChapterImage(chapterId, index)`	按章节索引删除元素。
`deleteObject(id)`	按 ID 删除任务书对象。
`moveQuest(questId, chapterId, x, y)`	将任务移动到章节和坐标。
`setQuestPosition(questId, x, y)`	在当前章节移动任务。
`moveTaskLeft(taskId)` / `moveTaskRight(taskId)`	在任务节点内部调整目标顺序。

使用查询到的 ChapterImage 调用上面的修改方法；元素无效或不存在时会返回 false 或 null。

打开任务书

方法	用途
`open(id)`	在客户端上下文打开任务书并定位对象。
`open(player, id)`	在服务端事件中为指定玩家打开任务书。

服务端事件中使用玩家重载：

QuestUtils.open(event.player, '1234567890123')

Navigation Menu

QuestUtils.zh CN

QuestUtils API（中文）

可用性与执行侧

返回值约定

对象查询与画布查询

玩家与队伍状态

进度写操作

前置任务

隐藏与任务字段

原始 NBT

动态创建对象

任务描述组件

画布创建与编辑

创建

原生图片字段

专用画布字段

画布移动、复制和删除

打开任务书

Uh oh!

Uh oh!

Uh oh!

Quest Enhance

中文

Clone this wiki locally