TQ 插件文档

成就、进度与任务 ​

这一页是 AchieveMaster 脚本动作里最核心的一页。它同时覆盖两类东西：

  • AST 原生语句：直接写在脚本里的 增加进度、返回、延迟执行 这类结构
  • 成就动作函数：显式操作别的成就、读状态、接任务、提任务

先记住这四条 ​

1. trigger.script 会消费当前成就 AST 结果 ​

增加进度、设置进度、增加目标进度、设置目标进度 这些 AST 语句不会立刻自己写库，而是先写进当前 ScriptResult，再由 TriggerManager 在 trigger.script 流程里统一消费。

2. rewards.script 当前不会额外消费这一套 AST 结果 ​

奖励脚本会执行，但不会像触发脚本那样再专门把“当前成就 AST 进度结果”吃进去。所以奖励脚本里不要把 设置进度 这一类语句当主推进手段。

3. 延迟执行 会在后续 tick 再落结果 ​

延迟执行 会复制当前上下文，然后在延迟回调里单独执行。延迟块里的进度和目标进度结果会正常落正式结果，但它不是当前调用栈的同步继续执行。

4. 任务动作的失败结果可能是字符串 ​

接取成就任务、提交成就任务、取消成就任务 成功通常返回 true，失败时可能直接返回错误文本，不要只按布尔值处理。

AST 当前成就进度语句 ​

增加进度 ​

  • 用法：增加进度 数值
  • 参数：1 个可计算表达式
  • 返回值：无
  • 补充说明：只作用于当前成就。旧写法 进度增加 1、增加进度(1) 会被兼容层自动归一化。
text
增加进度 1

减少进度 ​

  • 用法：减少进度 数值
  • 参数：1 个可计算表达式
  • 返回值：无
  • 补充说明：实现上等价于给当前成就追加一个负进度变更。它不会自己额外做语义判断。
text
减少进度 2

设置进度 ​

  • 用法：设置进度 数值
  • 参数：1 个可计算表达式
  • 返回值：无
  • 补充说明：会把当前脚本上下文里的 progress 临时值一起更新，所以同一段 AST 里后续读取可以看到新值。
text
设置进度 10

增加目标进度 ​

  • 用法：增加目标进度 目标ID 数值
  • 参数：目标 ID、可计算数值
  • 返回值：无
  • 补充说明：作用于当前成就的指定目标。旧写法 目标进度增加 dragon 1、目标进度增加("dragon", 1) 会被兼容层归一化。
text
增加目标进度 "dragon" 1

设置目标进度 ​

  • 用法：设置目标进度 目标ID 数值
  • 参数：目标 ID、可计算数值
  • 返回值：无
  • 补充说明：会把当前上下文里的 目标进度_<目标ID> 临时值一起更新，所以紧接着调用 获取目标进度("目标ID") 能读到新的待提交值。
text
设置目标进度 "dragon" 3

AST 控制流语句 ​

返回 ​

  • 用法：返回 或 返回 表达式
  • 参数：可选返回表达式
  • 返回值：无
  • 补充说明：会结束当前 AST 代码块，并把值写进 ScriptResult.returnValue。在成就 trigger.script / rewards.script 里，外层流程通常只把它当成“提前结束当前脚本块”；真正会取这个返回值的是 AST 自定义加载函数之类需要函数返回值的场景。
text
判断 (是否有药水效果("隐身")) {
  返回 "already_hidden"
}
返回 true

跳出 ​

  • 用法：跳出
  • 参数：无
  • 返回值：无
  • 补充说明：用于 循环、遍历、当 这类循环结构里，立即结束当前循环。
text
循环 10 次 {
  判断 (获取目标进度("dragon") >= 3) {
    跳出
  }
}

继续 ​

  • 用法：继续
  • 参数：无
  • 返回值：无
  • 补充说明：用于循环结构里，直接进入下一轮。
text
遍历 item 在 items {
  判断 (item == null) {
    继续
  }
  发送消息("&7处理: " + item)
}

停止脚本 ​

  • 用法：停止脚本
  • 参数：无
  • 返回值：无
  • 补充说明：会把当前结果标记成 shouldContinue = false，并停止当前脚本块继续执行。在允许取消的触发器流程里，它还可能让外层事件按“已拦截”处理；这取决于具体触发器是否允许取消。
text
判断 (成就是否已解锁("first_boss")) {
  发送消息("&7你已经完成过这个挑战")
  停止脚本
}

延迟执行 ​

  • 用法：延迟执行 tick数 { ... }
  • 参数：1 个可计算 tick 数，外加一个代码块
  • 返回值：无
  • 补充说明：会复制当前 ScriptContext，在后续 tick 再执行。玩家延迟期间离线时，延迟块会直接跳过。延迟块里的进度和目标进度结果会单独落库，但 返回、停止脚本、跳出、继续 不会同步回流到当前调用栈。
text
延迟执行 20 {
  增加进度 1
  发送消息("&a1 秒后补了一点进度")
}

旧写法兼容 ​

下面这些旧写法当前仍会被兼容层自动改写成 AST 正式语法：

  • 进度增加 1 -> 增加进度 1
  • 进度减少 1 -> 减少进度 1
  • 进度设置 10 -> 设置进度 10
  • 增加进度(1) -> 增加进度 1
  • 目标进度增加 dragon 1 -> 增加目标进度 dragon 1
  • 设置目标进度("dragon", 3) -> 设置目标进度 "dragon" 3

新脚本建议直接写正式 AST 语法，不要继续堆旧写法。

跨成就进度动作 ​

设置成就进度 ​

  • 用法：设置成就进度("成就ID", 数值[, "玩家名"])
  • 别名：setAchievementProgress、成就进度设置
  • 参数：成就 ID、目标数值、可选玩家名
  • 返回值：Boolean
  • 补充说明：可选玩家名通过 Bukkit.getPlayer(...) 解析，只支持在线玩家。
text
设置成就进度("daily_sign", 10)

增加成就进度 ​

  • 用法：增加成就进度("成就ID", 数值[, "玩家名"])
  • 别名：addAchievementProgress、成就进度增加
  • 参数：成就 ID、增量、可选玩家名
  • 返回值：Boolean
  • 补充说明：适合推进“不是当前这条”的其它成就。
text
增加成就进度("daily_sign", 1)

设置成就目标进度 ​

  • 用法：设置成就目标进度("成就ID", "目标ID", 数值[, "玩家名"])
  • 别名：setObjectiveProgress、目标进度设置
  • 参数：成就 ID、目标 ID、数值、可选玩家名
  • 返回值：Boolean
  • 补充说明：针对多目标成就的显式覆盖写法。
text
设置成就目标进度("boss_line", "dragon", 3)

增加成就目标进度 ​

  • 用法：增加成就目标进度("成就ID", "目标ID", 数值[, "玩家名"])
  • 别名：addObjectiveProgress、目标进度增加
  • 参数：成就 ID、目标 ID、增量、可选玩家名
  • 返回值：Boolean
  • 补充说明：同样只解析在线玩家名。
text
增加成就目标进度("boss_line", "dragon", 1)

读取与判断 ​

获取成就进度 ​

  • 用法：获取成就进度("成就ID"[, "玩家名"])
  • 别名：getAchievementProgress、成就进度
  • 参数：成就 ID、可选玩家名
  • 返回值：Number
  • 补充说明：解析不到目标玩家时返回 0。
text
赋值 value = 获取成就进度("daily_sign")

获取目标进度 ​

  • 用法：获取目标进度("目标ID")
  • 别名：getCurrentObjectiveProgress、currentObjectiveProgress
  • 参数：当前成就里的目标 ID
  • 返回值：Number
  • 补充说明：优先读取当前脚本上下文里待提交的 目标进度_<目标ID>，没有时再读当前成就正式进度。所以它能看到本段 AST 里尚未写库的临时结果。
text
设置目标进度 "dragon" 3
发送消息("&e当前脚本看到的目标值: " + 获取目标进度("dragon"))

获取成就目标进度 ​

  • 用法：获取成就目标进度("成就ID", "目标ID"[, "字段"])
  • 别名：getAchievementObjProgress、achObjProgress、成就目标进度
  • 参数：成就 ID、目标 ID、可选字段
  • 返回值：Any
  • 补充说明：当前真正生效的是 IntegrationBuiltins 版本，不是旧的 ActionBuiltins 版本。也就是说第三个参数现在是“字段”，不是“玩家名”。支持的字段有 progress、target、percent、complete、name。没有玩家上下文或目标不存在时，可能返回 null。
text
赋值 percent = 获取成就目标进度("boss_line", "dragon", "percent")

成就是否已解锁 ​

  • 用法：成就是否已解锁("成就ID"[, "玩家名"])
  • 别名：isAchievementUnlocked、已解锁成就
  • 参数：成就 ID、可选玩家名
  • 返回值：Boolean
  • 补充说明：玩家名同样只解析在线玩家。
text
判断 (成就是否已解锁("first_boss")) {
  发送消息("&7该成就已完成")
}

成就任务是否已接取 ​

  • 用法：成就任务是否已接取("成就ID"[, "玩家名"])
  • 别名：isQuestAccepted、已接取任务
  • 参数：成就 ID、可选玩家名
  • 返回值：Boolean
text
判断 (成就任务是否已接取("daily_collect")) {
  发送消息("&e你已经接过这个任务")
}

成就状态动作 ​

解锁成就 ​

  • 用法：解锁成就("成就ID"[, "玩家名"])
  • 别名：unlockAchievement、完成成就
  • 参数：成就 ID、可选玩家名
  • 返回值：Boolean
  • 补充说明：这是直接改状态，不经过当前成就 AST 进度累计。
text
解锁成就("first_boss")

重置成就进度 ​

  • 用法：重置成就进度("成就ID"[, "玩家名"])
  • 别名：resetAchievementProgress、成就重置
  • 参数：成就 ID、可选玩家名
  • 返回值：Boolean
  • 补充说明：常用于每日、每周或赛季类内容。
text
重置成就进度("daily_sign")

撤销成就 ​

  • 用法：撤销成就("成就ID"[, "玩家名"])
  • 别名：revokeAchievement、成就撤销
  • 参数：成就 ID、可选玩家名
  • 返回值：Boolean
  • 补充说明：它针对的是已解锁状态，不是简单的“减一点进度”。
text
撤销成就("first_boss")

任务动作 ​

接取成就任务 ​

  • 用法：接取成就任务("成就ID"[, "玩家名"])
  • 别名：acceptQuest、任务接取
  • 参数：成就 ID、可选玩家名
  • 返回值：Boolean | String
  • 补充说明：成功时一般返回 true，失败时可能直接返回错误消息字符串。
text
赋值 result = 接取成就任务("daily_collect")
判断 (result != true) {
  发送消息("&c" + 转文本(result))
}

提交成就任务 ​

  • 用法：提交成就任务("成就ID"[, "玩家名"])
  • 别名：submitQuest、任务提交
  • 参数：成就 ID、可选玩家名
  • 返回值：Boolean | String
text
赋值 result = 提交成就任务("daily_collect")
判断 (result != true) {
  发送消息("&c提交失败: " + 转文本(result))
}

取消成就任务 ​

  • 用法：取消成就任务("成就ID"[, "玩家名"])
  • 别名：cancelQuest、任务取消
  • 参数：成就 ID、可选玩家名
  • 返回值：Boolean | String
text
赋值 result = 取消成就任务("daily_collect")
判断 (result != true) {
  发送消息("&c取消失败: " + 转文本(result))
}

实战建议 ​

  • 推当前这条成就时，优先用 AST 原生语句，不要绕一圈去改 progress 变量。
  • 推别的成就时，优先用显式的 设置成就进度 / 增加成就进度，不要靠上下文猜“当前成就是谁”。
  • 多目标成就优先围绕目标 ID 写逻辑，不要把所有判断糊成一条总进度。
  • 返回 适合做 AST 自定义函数返回，不适合把触发脚本当普通函数来写。
  • 停止脚本 适合做快速拦截，但它和“外层事件是否取消”不是一回事。
  • 延迟执行 里如果要做正式推进，可以做；如果你指望延迟块里的 返回 false 立刻阻止当前触发器，那是做不到的。

TQ Minecraft Server Plugin Docs

Copyright © 2026 TQ