JavaScript 脚本基础

本文档介绍 QueDP JavaScript 脚本的核心概念和语法。

1. 选择器 (Selectors)

选择器用于指定动作的目标玩家。

选择器	英文别名	说明
@所有玩家	@all, @a	地牢中的所有玩家
@触发者	@trigger, @p	触发当前事件的玩家
@队伍	@party	触发者的队伍成员
@随机	@random	随机选择一个玩家
@最近	@nearest	距离触发位置最近的玩家

使用示例：

action.message('@所有玩家', '大家好');
action.heal('@触发者');
action.give_item('@随机', 'diamond', 1);

2. 变量系统

QueDP 提供了灵活的变量系统，用于存储和传递数据。

内置对象

对象	说明	访问方式
player	触发者玩家对象 (Bukkit Player)	player.getName()
trigger	同 player	trigger.getName()
dungeon	地牢实例对象	dungeon.getPlayers()

IMPORTANT

QueDP 使用 GraalJS 引擎，访问 Java 对象需要使用方法调用而不是属性访问：

• 正确: player.getName()
• 错误: player.name (会返回函数引用)

常用 Player 方法：

player.getName()        // 获取玩家名
player.getHealth()      // 获取当前血量
player.getMaxHealth()   // 获取最大血量
player.getLocation()    // 获取位置
player.getWorld()       // 获取世界
player.getLevel()       // 获取等级
player.getGameMode()    // 获取游戏模式

自定义变量 (读写)

使用 setVar 和 getVar 在整个地牢实例中共享数据。

// 设置变量
setVar('总击杀', 0);
setVar('BossDead', true);

// 读取变量 (建议提供默认值)
var kills = getVar('总击杀') || 0;

// 变量运算
setVar('总击杀', kills + 1);

TIP

变量在整个地牢实例的生命周期内有效，可以在不同的脚本文件（如 monsters.yml 和 tasks.yml）之间共享。

WARNING

使用 action.wait() 时，wait 之后的代码会在新的上下文中执行，局部变量不会保留。 需要跨 wait 使用的数据请用 setVar/getVar 保存。

3. 等待与延迟

使用 action.wait() 可以暂停脚本执行：

action.message('@all', '3秒后开始...')
action.wait('3秒')
action.message('@all', '开始！')

支持的时间格式：

• '5秒' 或 '5s' - 秒
• '100tick' 或 '100t' - tick (1秒=20tick)
• '2分钟' 或 '2min' - 分钟

IMPORTANT

action.wait() 后面的代码会在延迟后的新上下文中执行，局部变量会丢失。 如果需要在 wait 前后传递数据，请使用 setVar/getVar：

var playerName = player.getName()
setVar('_playerName', playerName)  // 保存到持久变量

action.wait('5秒')

var name = getVar('_playerName')   // 从持久变量读取
action.message('@all', name + ' 完成了任务')

4. 随机数生成

使用 JavaScript Math

// 随机整数 0-99
var rand = Math.floor(Math.random() * 100);

// 50% 概率
if (Math.random() < 0.5) {
    action.message('@all', '运气不错！');
}

使用占位符 (推荐)

在字符串参数中，可以直接使用 {random:...} 占位符：

• 范围随机: {random:1-100}
• 列表随机: {random:金,木,水,火,土}

action.message('@all', '本次幸运数字: {random:1-100}');

随机怪物函数

• action.random_monster_group('组A', '组B'): 从多个组中随机选一个ID返回
• action.random_spawn_group('组A', '组B'): 从多个组中随机选一个并立即生成

5. 常用语法速查

QueDP 使用 GraalJS 引擎，支持 ES6+ 语法。

条件判断

var score = getVar('分数') || 0;

if (score >= 100) {
    action.reward('大奖');
} else if (score >= 60) {
    action.reward('小奖');
} else {
    action.message('@p', '继续努力');
}

循环

// for 循环 - 支持 action.wait
for (var i = 5; i > 0; i--) {
    action.title('@all', '&c' + i, '')
    action.sound('@all', 'BLOCK_NOTE_BLOCK_PLING', 1.0, 1.0)
    action.wait('1秒')
}
action.message('@all', '开始！')

// while 循环 - 变量修改必须放在 wait 之前
setVar('_count', 3)
while (getVar('_count') > 0) {
    action.message('@all', '倒计时: ' + getVar('_count'))
    setVar('_count', getVar('_count') - 1)  // 必须在 wait 之前
    action.wait('1秒')
}

TIP

循环内的 action.wait() 会自动转换为递归调用，无需手动处理。

WARNING

while 循环注意事项：

• 循环变量必须使用 setVar/getVar 存储（局部变量在 wait 后会丢失）
• 变量修改代码必须放在 action.wait() 之前
• action.wait() 后面的代码会被截断，不会执行

调试技巧

// 输出到服务器控制台
log('当前分数: ' + getVar('分数'));

// 输出给玩家
action.message('@p', '调试信息: ' + someVar);

6. 注释

GraalJS 支持标准 JavaScript 注释：

// 单行注释

/* 
   多行注释
   可以跨越多行
*/