QuestUtils

QuestUtils API

QuestUtils is the optional KubeJS bridge for FTB Quests. It provides ready-to-use methods for reading and editing quest-book content.

Availability and execution

The binding is registered as QuestUtils only when KubeJS is installed. A script can therefore use:

const quest = QuestUtils.getQuest('1234567890123')

Run progress and structure mutations from a server-side KubeJS event. Use the player overload of open when opening a book from a server event.

Use string IDs everywhere in KubeJS. Every ID-based group has a String overload; numeric overloads exist for Java callers and are not recommended for JavaScript.

Return conventions

Result	Meaning
Object	The requested or newly created FTB object.
`null`	No matching object, invalid ID, invalid resource, or rejected creation.
`true`	The operation was accepted.
`false`	Validation failed, the object was not found, or the operation is not valid in the current context.
Empty list / `0`	No matching canvas elements, dependencies, or progress.

Object lookup and canvas inspection

Method	Purpose
`getObject(id)`	Look up any `QuestObjectBase`.
`getQuest(id)`	Look up a quest node.
`getChapter(id)`	Look up a chapter.
`getTask(id)`	Look up a task.
`getChapterImages(chapterId)`	Return an immutable snapshot of chapter canvas elements.
`getChapterImageCount(chapterId)`	Count chapter canvas elements.
`getChapterImage(chapterId, index)`	Get an element by list index, or `null`.
`getChapterImageData(image)`	Serialize an element to a copy of its NBT data.
`getChapterImageType(image)`	Return `image`, `gif`, `video`, `text`, or `anchor`.
`getChapterGifResource(image)`	Return a GIF resource ID, or `null`.
`getChapterVideoPath(image)`	Return a normalized video path, or `null`.
`getChapterText(image)`	Return canvas text, or `null`.
`getChapterTextFont(image)`	Return the text font resource ID, or `null`.
`getDecorativeAnchorKey(image)`	Return the stable decorative-anchor key, or `null`.

The returned canvas list is a snapshot. Use the element-specific mutators below instead of changing an NBT object or list in place.

Player and team state

These methods use the FTB team data associated with the supplied Entity.

Method	Purpose
`isStarted(player, id)`	Whether the team has started a quest object.
`isCompleted(player, id)`	Whether the team has completed a quest object.
`isVisible(player, id)`	Whether the object is visible to the team.
`getProgress(player, id)`	Task progress, or relative quest progress for a quest node.
`getQuestProgress(player, id)`	Relative quest progress as an integer.
`getMaxProgress(taskId)`	Maximum progress of a task.
`getCompletionCount(player, questId)`	Number of times the team completed a quest.

getProgress and getMaxProgress use long values. Treat them as strings for IDs, but as numbers when doing progress arithmetic.

Progress mutations

Method	Purpose
`complete(player, id)`	Complete a quest object through FTB progress handling.
`reset(player, id)`	Reset a quest object through FTB progress handling.
`completeTask(player, taskId)`	Set a task to its maximum progress.
`setProgress(player, taskId, progress)`	Set a task progress value.
`addProgress(player, taskId, amount)`	Add a signed progress amount.
`resetTask(player, taskId)`	Set a task progress value to zero.

These methods reject missing objects, missing team data, and locked teams.

Prerequisites

Method	Purpose
`arePrerequisitesCompleted(player, questId)`	Test whether all prerequisites are complete.
`completedPrerequisiteCount(player, questId)`	Count completed prerequisites for the team.
`prerequisiteCount(questId)`	Count all prerequisites.
`prerequisites(questId)`	Return prerequisite IDs as strings.
`hasPrerequisite(prerequisiteQuestId, questId)`	Test one dependency edge.
`setPrerequisite(prerequisiteQuestId, questId)`	Add a dependency edge; cyclic dependencies are rejected.
`removePrerequisite(prerequisiteQuestId, questId)`	Remove one dependency edge.
`clearPrerequisites(questId)`	Remove all dependency edges from a quest.

The first argument of setPrerequisite is the prerequisite; the second is the quest that depends on it.

Visibility and quest fields

Method	Purpose
`hideQuest(questId)` / `unhideQuest(questId)`	Hide or show a quest.
`isQuestHidden(questId)`	Read quest hidden state.
`hideChapter(chapterId)` / `unhideChapter(chapterId)`	Hide or show a chapter.
`isChapterHidden(chapterId)`	Read chapter hidden state.
`setTitle(questId, title)`	Change a quest title.
`setQuestSubtitle(questId, subtitle)`	Change the subtitle.
`setQuestDescription(questId, ...lines)`	Replace the raw description lines.
`setQuestSize(questId, size)`	Change the canvas node scale.
`setQuestShape(questId, shape)`	Change the node shape, such as `circle`.
`setQuestOptional(questId, optional)`	Set quest optional state.
`setTaskOptional(taskId, optional)`	Set task optional state.

Raw NBT data

Method	Purpose
`getData(id)`	Return a copy of an object's raw NBT data.
`mergeData(id, changes)`	Merge a `CompoundTag` into an object.

Use raw NBT only for fields without a dedicated method. Prefer a dedicated method when one exists, because it validates values.

Dynamic object creation

Method	Purpose
`createChapter(groupId, title)`	Create and register a chapter in an FTB group.
`createQuest(chapterId, x, y, title?)`	Create a quest at canvas coordinates.
`createTask(questId, type, title?)`	Create a task using an FTB task type ID.
`createReward(questId, type, title?)`	Create a reward using an FTB reward type ID.

Creation returns the actual FTB object so its generated ID can immediately be read with getCodeString(). Keep that value as a string when passing it back to KubeJS.

const chapter = QuestUtils.createChapter('0', 'KubeJS chapter')
if (chapter !== null) {
  const chapterId = chapter.getCodeString()
  const quest = QuestUtils.createQuest(chapterId, 0, 0, 'First quest')
  if (quest !== null) {
    QuestUtils.createTask(quest.getCodeString(), 'checkmark', 'Complete this')
  }
}

Description components

All description builders return one raw description line. They handle JSON escaping, URL validation, Base64 payloads, dimensions, alignment, and item NBT so scripts do not have to concatenate parser syntax by hand.

Method	Purpose
`descriptionWebLink(displayText, url)`	JSON text component opening a web URL.
`descriptionCopy(displayText, value)`	JSON text component copying a value.
`descriptionCommand(displayText, command)`	JSON text component running a command.
`descriptionImage(url, width, height, alignment, fit, hoverText)`	Remote image component.
`descriptionItemIcon(stack, width, height, alignment, fit, hoverText)`	Item image retaining count, damage, and full NBT.
`descriptionItemHover(displayText, stack)`	JSON item hover component retaining full NBT.
`descriptionGif(resourceId, width, height, alignment, fit, hoverText)`	GIF description component.
`descriptionVideo(videoPath, displayText)`	Video description component with a safe relative path.
`descriptionHoverText(displayText, hoverText)`	JSON text component with a text tooltip.
`descriptionFont(displayText, fontId)`	Text using a validated font resource.
`descriptionTranslation(displayText, translationKey)`	Localized text with fallback text.
`descriptionKeybind(keybind)`	Keybind component.
`descriptionTable(rows, header, alignment)`	Table with default layout values.
`descriptionTable(columns, rows, header, alignment, tableWidth, rowHeight, lineWidth, borderColor, headerColor, cellColor, textColor)`	Table with explicit layout and colors.

Alignment is left, center, or right. Dimensions are clamped to the renderer's supported range. GIF resources must be Quest Enhance texture resources; video paths must remain relative to the configured video directory. Item icon input should be a non-empty KubeJS ItemStack.

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

const itemLine = QuestUtils.descriptionItemIcon(
  sword, 24, 24, 'center', false, 'Sword with NBT'
)
QuestUtils.setQuestDescription('1234567890123', itemLine)

Canvas creation and editing

Creation

Method	Purpose
`createChapterImage(chapterId, resource, x, y, width, height)`	Create a normal resource image.
`createChapterGif(chapterId, resource, x, y, width, height)`	Create a GIF canvas element.
`createChapterVideo(chapterId, videoPath, x, y, width, height)`	Create a video canvas element.
`createChapterText(chapterId, text, font, x, y, width, height)`	Create a text canvas element.
`createDecorativeAnchor(chapterId, x, y)`	Create a decorative anchor with a new stable key.

All creation methods return ChapterImage or null. Resource IDs must parse as Minecraft resource locations; coordinates and dimensions must be finite, with positive dimensions.

Native image fields

Method	Purpose
`setChapterImagePosition(image, x, y)`	Set position.
`setChapterImageSize(image, width, height)`	Set positive dimensions.
`setChapterImageRotation(image, rotation)`	Set rotation from -180 to 180 degrees.
`setChapterImageResource(image, resource)`	Set the resource location.
`setChapterImageColor(image, rgb)`	Set RGB tint.
`setChapterImageAlpha(image, alpha)`	Set alpha from 0 to 255.
`setChapterImageOrder(image, order)`	Set draw order.
`setChapterImageHover(image, ...lines)`	Replace hover lines.
`setChapterImageClick(image, click)`	Set or clear a click action.
`setChapterImageEditorsOnly(image, editorsOnly)`	Restrict visibility to editors.
`setChapterImageAlignToCorner(image, alignToCorner)`	Toggle corner alignment.
`setChapterImageDependency(image, questId)`	Attach a quest dependency.
`clearChapterImageDependency(image)`	Remove the dependency.

Specialized canvas fields

Method	Purpose
`setChapterGifResource(image, resource)`	Replace a GIF resource while keeping the GIF element type.
`setChapterVideoPath(image, videoPath)`	Replace a video path while keeping the video element type.
`setChapterText(image, text)`	Replace text while preserving its font.
`setChapterTextFont(image, font)`	Replace text font while preserving its text.

Specialized setters reject an element of the wrong type. This prevents a GIF, video, or text click payload from being silently replaced by another kind of element.

Canvas move, copy, and delete

Method	Purpose
`copyChapterImage(image, chapterId, x, y)`	Copy an element into a chapter and return the copy. Decorative anchors receive a new key.
`moveChapterImage(image, chapterId, x, y)`	Move within a chapter or across chapters and return the resulting element.
`deleteChapterImage(image)`	Delete a specific canvas element.
`deleteChapterImage(chapterId, index)`	Delete an element by chapter index.
`deleteObject(id)`	Delete a quest-book object by ID.
`moveQuest(questId, chapterId, x, y)`	Move a quest to a chapter and position.
`setQuestPosition(questId, x, y)`	Move a quest within its current chapter.
`moveTaskLeft(taskId)` / `moveTaskRight(taskId)`	Reorder a task inside its quest.

Use the returned ChapterImage with the mutators above; invalid or missing elements return false or null.

Opening the quest book

Method	Purpose
`open(id)`	Open the quest book on the client when called in a client context.
`open(player, id)`	Open the book for a specific player from a server event.

Use the player overload from a server event:

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

Navigation Menu

QuestUtils

QuestUtils API

Availability and execution

Return conventions

Object lookup and canvas inspection

Player and team state

Progress mutations

Prerequisites

Visibility and quest fields

Raw NBT data

Dynamic object creation

Description components

Canvas creation and editing

Creation

Native image fields

Specialized canvas fields

Canvas move, copy, and delete

Opening the quest book

Uh oh!

Uh oh!

Uh oh!

Quest Enhance

中文

Clone this wiki locally