First Script

第一个脚本 / Your First Script

本章目标 / What You Will Build

上一章的脚本只会发一条固定消息。这一章我们写一个真正会"看情况"的脚本：找出所有在线玩家，检查谁的血量低于安全线，给这些玩家发一条警告，并让他们回到出生点。

The previous chapter's script only sent a fixed message. This chapter we write one that actually "looks at the situation": find all online players, check whose health is below a safe line, warn them, and send them back to spawn.

---

找到玩家 / Finding Players

HimDSL 用选择器来指向游戏里的实体，写法参考原版命令。常用的有五种：

• @p —— 距离最近的玩家
• @a —— 所有在线玩家
• @r —— 随机一名在线玩家
• @s —— 当前触发事件的那个玩家
• @e —— 所有实体

HimDSL uses selectors to point at entities in the game, borrowing the syntax from vanilla commands. Five are commonly used:

• @p — nearest player
• @a — all online players
• @r — a random online player
• @s — the player who triggered the current event
• @e — all entities

本章先只用到 @p 和 @a。@s 只在事件里有效，我们后面再讲。

This chapter only uses @p and @a. @s works only inside events; we'll cover it later.

---

把玩家存进变量 / Storing a Player in a Variable

选择器本身只是"一个指向"，你需要把它存起来才能反复使用。HimDSL 用 player 关键字声明玩家变量：

A selector is just a "pointer"; you need to store it to reuse it. HimDSL uses the player keyword to declare a player variable:

player p = @p;

这样变量 p 就代表了最近的那名玩家。接下来就可以读取他的信息，或者让他执行命令。

Now p stands for the nearest player. You can read their info or make them run commands.

---

读取玩家信息 / Reading Player Info

读取玩家属性用占位符，写法是 $player(变量名, 属性名)$。常用的属性有：

• name —— 玩家名
• hp —— 当前生命值
• x、y、z —— 坐标
• world —— 所在世界
• gamemode —— 游戏模式
• explevel —— 经验等级

Read player attributes with a placeholder, written as $player(varName, property)$. Common properties:

• name — player name
• hp — current health
• x, y, z — coordinates
• world — the world they are in
• gamemode — game mode
• explevel — experience level

例如：

For example:

player p = @p;
string name = $player(p, name)$;
double hp = $player(p, hp)$;
runcmd("CONSOLE", "say 玩家 " + name + " 当前血量 " + hp);

字符串拼接直接用 +，跟 Java 一样。

String concatenation uses +, just like Java.

---

做判断 / Making Decisions

if 的写法和 Java 一样，支持 else if 和 else：

if looks just like Java, with support for else if and else:

player p = @p;
double hp = $player(p, hp)$;

if (hp < 10) {
    runcmd("CONSOLE", "say 血量告急！");
} else {
    runcmd("CONSOLE", "say 状态良好。");
}

比较运算符有 ==、!=、<、>、<=、>=；逻辑运算符有 &&、||、!。

Comparison operators: ==, !=, <, >, <=, >=. Logical operators: &&, ||, !.

---

遍历所有玩家 / Looping Over All Players

@a 返回的是"所有玩家"，你要遍历它。HimDSL 没有 for-each，用普通的索引循环：

@a returns "all players", and you need to iterate. HimDSL has no for-each, so use an index loop:

var players = @a;
int total = players.size();
for (int i = 0; i < total; i = i + 1) {
    var p = players.get(i);
    string name = $player(p, name)$;
    runcmd("CONSOLE", "say 玩家 " + name + " 在线");
}

几个要点：

• var 是通用变量声明，类型自动推断。
• players.size() 取列表长度。
• players.get(i) 取第 i 个元素。
• for 的三个部分都要写全，尤其是最后那个 i = i + 1，不能省。

A few things to note:

• var is a generic declaration with inferred type.
• players.size() returns the list length.
• players.get(i) returns the i-th element.
• All three sections of for must be present, especially i = i + 1.

---

派出命令 / Running Commands

用 runcmd(执行者, 命令) 执行 Minecraft 命令。执行者写 "CONSOLE" 表示由控制台执行，写玩家名表示由该玩家执行。命令文本不带前导斜杠。

Use runcmd(executor, command) to run a Minecraft command. "CONSOLE" means run as the console; a player name means run as that player. Command text has no leading slash.

runcmd("CONSOLE", "say 服务器将在 5 分钟后重启");
runcmd("Steve", "spawn");

---

小结 / Summary

本章用到了六个构件：选择器、player 变量、var 变量、占位符、if 判断、for 循环。这六个是 HimDSL 日常写脚本的基本零件，后面的章节都会围绕它们展开。

This chapter used six building blocks: selectors, player variables, var variables, placeholders, if, and for. These six form the basic toolkit of everyday HimDSL scripting, and the rest of the documentation builds on them.

---

下一步 / Next Steps

下一章 [命令速查 / Commands] 会把 /himdsl 的三个子命令讲清楚，包括参数传递和调试开关。之后我们会正式进入语言基础部分，从**[词法结构 / Lexical-Structure]**开始。

The next chapter [命令速查 / Commands] explains the three /himdsl subcommands, including argument passing and debug switches. Then we enter the language basics, starting with [词法结构 / Lexical-Structure].

---