占位符参考 / Placeholders Reference

定位 / Positioning

本章是兼容性参考，不是推荐写法。

This chapter is a compatibility reference, not a recommendation.

占位符是 HimDSL 早期提供的一种读取数据的方式，形如 $player(p, name)$。它的功能与引用字段（上一章）重叠。新写脚本时优先用引用，只有下面两种情况才需要占位符：

Placeholders are an early HimDSL way to read data, written as $player(p, name)$. Their role overlaps with reference fields (previous chapter). For new scripts, prefer references; use placeholders only in these two cases:

1. 软依赖功能：$player(p, atroom, "arena1")$、$boss(...)$ 这类依赖第三方插件的读取，引用上没有对应字段。

2. 维护既有脚本：老脚本用了占位符，改动时保持原风格。

3. Soft-dependency features: $player(p, atroom, "arena1")$, $boss(...)$ — third-party plugin reads not present on references.

4. Maintaining existing scripts: keep the original style when editing.

其他情况下，一句 p.name 更简洁、更安全。

In every other case, a single p.name is shorter and safer.

---

语法 / Syntax

$类型(参数...)$

$ 开头 $ 结尾，中间是类型名和括号里的参数。类型名来自固定的几种：

Wrapped in $...$, containing a type name and parenthesized arguments. Type names come from a fixed set:

类型	说明
player 或 p	玩家属性
world 或 w	世界属性
server 或 s	服务器属性
boss 或 b	HimDungeons Boss 属性（软依赖）
haveVar	检查变量是否存在

Type	Meaning
player or p	player property
world or w	world property
server or s	server property
boss or b	HimDungeons boss (soft dep)
haveVar	variable existence check

参数不写引号，即使是字符串：

Arguments are written without quotes, even for strings:

$player(p, name)$                // ✓
$player("p", "name")$            // ✗ 语法错

第一个参数通常是变量名（作为字符串传入，但不用引号）。这是占位符比较别扭的一点——你已经有 p 这个变量了，还得把它的名字 "p" 再写一遍。

The first argument is usually a variable name (passed as a string, but written without quotes). This is one of the awkward aspects of placeholders — you already have p in scope, yet must repeat its name "p".

---

为什么高级用法不推荐 / Why Advanced Users Avoid It

三个原因：

Three reasons:

原因一：字符串不是标识符

$player(p, name)$ 里 name 是字符串。拼成 naem 不会报错，只会返回 null。写 p.name 拼错，HimDSL 立刻报"字段不存在"。

Reason 1: Strings, not identifiers

In $player(p, name)$, name is a string. Typing naem silently returns null. With p.name, a typo immediately errors as "field not found".

原因二：变量名被重复

变量名出现在占位符里是字符串形式的。如果将来重命名变量，占位符不会跟着改，容易漏改。

Reason 2: Variable name duplication

The variable name appears as a string inside the placeholder. Renaming the variable later does not update the string, causing stale references.

原因三：信息分散

p.health 和 p.name 是同一套语法。占位符另开一套 $player(p, health)$、$player(p, name)$，读代码时要来回切换。

Reason 3: Split syntax

p.health and p.name share one syntax. Placeholders introduce a second: $player(p, health)$, $player(p, name)$ — readers bounce between styles.

---

常用占位符速查 / Quick Reference

下面的表仅供查漏补缺，新代码请优先用引用字段。

The tables below are lookup only; prefer reference fields for new code.

$player$ / $p$ —— 玩家

参数	返回	引用写法
name	玩家名	p.name
x、y、z	坐标	p.x、p.y、p.z
yaw、pitch	朝向	p.yaw、p.pitch
hp	生命值	p.health
hungry	饥饿值	p.hunger
world	世界名	p.world
uuid	UUID	p.uuid
gamemode	游戏模式	（无，需占位符）
explevel	经验等级	（无）
issneaking	是否潜行	（无）
issprinting	是否疾跑	（无）
mainhand	主手物品	（无）
offhand	副手物品	（无）
slot, N	指定槽位物品	（无）
opengui	是否打开 GUI	（无）
handlejoin	是否最近加入	（无）
atroom, "path"	HimDungeons 房间状态（软依赖）	（无）

$world$ / $w$ —— 世界

参数	返回
name	世界名
block, x, y, z	指定坐标方块类型
block, "worldName", x, y, z	指定世界的方块类型
iscontainer, x, y, z	是否是容器方块
contain, x, y, z, slot	容器第 N 槽物品
hasplayer, "worldName"	世界是否有玩家

$server$ / $s$ —— 服务器

参数	返回
tps	当前 TPS
mspt	每 tick 毫秒数
ping, "playerName"	玩家延迟
serverloadevent	是否触发过服务器加载事件
onpluginenable	是否触发过插件启用事件

$haveVar$ —— 变量存在检查

if ($haveVar(myVar)$) {
    // myVar 在当前作用域已定义
}

实际上 haveVar 用起来和直接用变量名判断等价：

if (myVar != null) {
    // 更直接
}

推荐用后者。

$boss$ / $b$ —— HimDungeons Boss（软依赖）

double x = $boss(x, @s)$;        // 玩家所在世界的 Boss 的 x 坐标
double hp = $boss(health, @s)$;

第二个参数可选，指定一个玩家来定位所在世界的 Boss。不传时返回第一个存活的 Boss。

Second argument is optional — a player used to locate the Boss in their world. Without it, returns the first living Boss.

---

参数求值 / Argument Evaluation

占位符的第一个参数总是当作字符串处理（变量名）。后续参数按普通表达式求值：

The first argument is always treated as a string (a variable name). Subsequent arguments evaluate as ordinary expressions:

$player(p, slot, 5)$              // 5 是数字
$player(p, atroom, "arena1")$     // "arena1" 是字符串

这也意味着第一个参数不能是复杂表达式。想让"选中的玩家"动态变化，只能先赋给变量再传名字：

This also means the first argument cannot be a complex expression. To make "the selected player" dynamic, assign it to a variable first:

player target = @p;
string name = $player(target, name)$;    // 传变量名 "target"

不能写 $player(@p, name)$。

$player(@p, name)$ is not valid.

---

小结 / Summary

• 占位符是兼容性写法，新代码优先用引用字段。

• 语法：$类型(参数...)$，参数不加引号。

• 五种类型：player、world、server、boss、haveVar。

• 第一个参数是变量名（作为字符串）。

• 拼写错误不会报错，返回 null。

• 只有软依赖功能（如 atroom、boss）占位符不可替代。

• 具体参数表见上方速查。

• Placeholders are legacy; prefer reference fields for new code.

• Syntax: $type(args...)$, arguments unquoted.

• Five types: player, world, server, boss, haveVar.

• First argument is a variable name (as a string).

• Typos do not error; they return null.

• Only soft-dependency features (atroom, boss) are irreplaceable.

• See the reference tables above for details.

---

下一步 / Next Steps

下一章 [PlaceholderAPI 桥接 / PAPI Bridge] 介绍如何读取其他插件提供的占位符。

Next, [PlaceholderAPI 桥接 / PAPI Bridge] covers reading other plugins' placeholders.

---