BASIC引擎 - 编程指南

以下为 BASIC引擎 的所有内置函数，供 BASIC 程序调用。每个函数在执行后可通过 ERR$ 函数获取最近的错误信息（若无错误则返回空字符串）。

---

1. 错误与时间

ERR$

• 功能：获取最近一次调用其他内置函数时产生的错误信息，并清除内部错误记录。
• 参数：无
• 返回值：字符串，错误描述；若无错误则返回空字符串。
• 示例：E$ = ERR$()

TIMESTAMP

• 功能：获取当前系统时间戳（秒级浮点数）。
• 参数：无
• 返回值：浮点数，Unix 时间戳（1970-01-01 至今的秒数）。
• 示例：T = TIMESTAMP()

---

2. 类型转换

TRY_INT(obj)

• 功能：尝试将对象转换为整型。
• 参数：obj - 任意值（通常为字符串或数字）。
• 返回值：成功时返回整数，失败时返回 0 并设置 ERR$。
• 示例：I = TRY_INT("114514")
• 错误："传入值无法转换为整型"

TRY_FLOAT(obj)

• 功能：尝试将对象转换为浮点型。
• 参数：obj - 任意值。
• 返回值：成功时返回浮点数，失败时返回 0.0 并设置 ERR$。
• 示例：I = TRY_FLOAT("114514.1919810")
• 错误："传入值无法转换为浮点型"

---

3. 程序控制

EXIT(msg)

• 功能：立即终止当前 BASIC 程序的执行，并可附带退出信息。
• 参数：msg - 字符串，退出时的提示信息（可选）。
• 返回值：无（程序终止）。
• 示例：EXIT("程序正常结束")

TIMER(wait_time, book_handle, data)

• 功能：设置一个定时器，在指定延迟后执行另一个 BASIC 程序（从书本中读取）。
• 参数：
• wait_time - 浮点数，延迟秒数。
• book_handle - 由 ITEM_HANDLE 生成的书本句柄。
• data - 字符串，传递给新程序的自定义数据，可通过 DATA$ 变量获取（可选）。
• 返回值：无（异步执行）。
• 示例：TIMER(1.0, BOOK$, DATA$)
• 注意：被调用的程序会获得初始变量 DATA$ 设置为传入的 data。

---

4. 消息与命令

SAY(msg, color)

• 功能：向所有玩家发送一条屏幕通知消息。
• 参数：
• msg - 字符串，要发送的消息。
• color - 字符串，颜色名称（如 "WHITE"、"RED"），可选，默认为 "WHITE"。
• 返回值：整数 0。

CMD(cmd, entity_id, show_output)

• 功能：执行一条游戏命令（类似 / 开头的指令）。
• 参数：
• cmd - 字符串，要执行的命令（不含前导斜杠）。
• entity_id - 字符串，执行命令的实体 ID（可选，默认为控制台）。
• show_output - 布尔值或整数（0/1），是否显示命令输出给执行者（可选，默认为 0）。
• 返回值：整数，1 表示命令成功发送，0 表示失败。

---

5. 玩家与实体信息

OWNER_UID

• 功能：获取房主的玩家 UID（唯一标识符）。
• 参数：无
• 返回值：字符串，房主的 UID；若房主不存在则返回空字符串并设置 ERR$。
• 错误："只有我的山头可用该接口"

HOST_EID

• 功能：获取房主的实体 ID（EID）。
• 参数：无
• 返回值：字符串，房主的 EID；若房主不存在或未上线则返回空字符串并设置 ERR$。
• 错误："房主不存在或暂未上线"

NAME_TO_EID(name)

• 功能：通过玩家名字获取对应的实体 ID。
• 参数：name - 字符串，玩家名。
• 返回值：字符串，对应的 EID；若未找到则返回空字符串并设置 ERR$。
• 错误："玩家名所对应的玩家暂不存在"

UID_TO_EID(uid)

• 功能：通过玩家 UID 获取对应的实体 ID。
• 参数：uid - 字符串，玩家 UID。
• 返回值：字符串，对应的 EID；若未找到则返回空字符串。
• 错误：无（未找到时不设置错误）。

OP_LV(eid)

• 功能：获取玩家的管理员权限等级。
• 参数：eid - 字符串，实体 ID。
• 返回值：整数，权限等级（通常 0=普通玩家，1=管理员，具体值由服务器定义）。

ETT_NAME(eid)

• 功能：获取实体的名称。
• 参数：eid - 字符串，实体 ID。
• 返回值：字符串，实体名称；若不存在则返回空字符串。

ETT_POS(eid)

• 功能：获取实体的位置坐标。
• 参数：eid - 字符串，实体 ID。
• 返回值：JSON 字符串，格式为 [x, y, z]（浮点数列表）。

ETT_ROT(eid)

• 功能：获取实体的旋转角度。
• 参数：eid - 字符串，实体 ID。
• 返回值：JSON 字符串，格式为 [pitch, yaw]（浮点数列表）。

ETT_ALIVE(eid)

• 功能：判断实体是否存活。
• 参数：eid - 字符串，实体 ID。
• 返回值：整数，1 表示存活，0 表示死亡或不存在。

KILL_ETT(eid)

• 功能：杀死指定实体。
• 参数：eid - 字符串，实体 ID。
• 返回值：整数，1 表示成功，0 表示失败。

SELECTOR(selector, eid)

• 功能：通过目标选择器获取符合条件的实体 ID 列表。
• 参数：
• selector - 字符串，目标选择器（如 @a、@e[type=!player]）。
• eid - 字符串，执行选择器的实体 ID（用于上下文）。
• 返回值：JSON 字符串，实体 ID 列表（数组形式）；若选择器无效或没有匹配，返回空列表 []。
• 错误：当选择器解析出错时设置 ERR$（内容由底层决定）。

---

6. 计分板操作

GET_SCORE(eid, scoreboard_name)

• 功能：获取指定玩家在某个计分板上的分数。
• 参数：
• eid - 字符串，玩家实体 ID。
• scoreboard_name - 字符串，计分板名称。
• 返回值：整数，分数值；若玩家或计分板不存在则返回 0。

SET_SCORE(eid, scoreboard_name, value)

• 功能：设置指定实体在某个计分板上的分数（通过命令实现）。
• 参数：
• eid - 字符串，实体 ID。
• scoreboard_name - 字符串，计分板名称。
• value - 整数，要设置的分数。
• 返回值：整数，1 表示命令执行成功，0 表示失败（例如名称包含空格）。
• 注意：计分板名称和值中不能包含空格，否则返回 0。

---

7. 物品与书本操作

ITEM_HANDLE(x, y, z, dm, slot)

• 功能：创建一个物品句柄，用于定位容器中的某个槽位。
• 参数：
• x, y, z - 整数或浮点数，容器的世界坐标。
• dm - 整数，维度 ID（例如 0 为主世界）。
• slot - 整数，槽位索引（从 0 开始）。
• 返回值：JSON 字符串，格式为 [x, y, z, dm, slot]。
• 示例：LET HANDLE = ITEM_HANDLE(100, 64, 200, 0, 0)

BOOK_GET(book_handle)

• 功能：从书本句柄指定的容器槽位中读取成书的内容。
• 参数：book_handle - 物品句柄（由 ITEM_HANDLE 生成）。
• 返回值：字符串，书本的页面文本（多页内容拼接）；若读取失败则返回空字符串并设置 ERR$。
• 抛出异常：
• "Book handle is not in correct JSON format"
• "Book handle data type must be JSON list"
• "Book handle data type must be JSON list of length 5"
• 或其他底层错误信息。

BOOK_SET(book_handle, content)

• 功能：将内容写入到书本句柄指定的容器槽位中的成书。
• 参数：
• book_handle - 物品句柄（由 ITEM_HANDLE 生成）。
• content - 字符串，要写入的文本。
• 返回值：空字符串（成功时无返回值）；失败时抛出运行时错误（程序终止）。
• 抛出异常：同 BOOK_GET。

---

8. 客户端信息（需玩家同意）

以下函数获取玩家客户端的各类信息，部分功能需要玩家在客户端配置中明确同意（通过 basic_clients_conf 设置）。

EG_VER(eid)

• 功能：获取玩家客户端的引擎版本。
• 参数：eid - 字符串，玩家实体 ID。
• 返回值：字符串，引擎版本号；若信息不存在则返回空字符串并设置 ERR$。
• 错误："客户端信息不存在" 或 "客户端引擎版本信息不存在"

MC_VER(eid)

• 功能：获取玩家客户端的 Minecraft 版本。
• 参数：eid - 字符串，玩家实体 ID。
• 返回值：字符串，MC 版本号；若不存在则返回空字符串并设置 ERR$。
• 错误："客户端信息不存在" 或 "客户端MC版本信息不存在"

UID(eid)

• 功能：获取玩家客户端的 UID。
• 参数：eid - 字符串，玩家实体 ID。
• 返回值：字符串，UID；若不存在则返回空字符串并设置 ERR$。
• 错误："客户端信息不存在" 或 "客户端UID信息不存在"

IP(eid)

• 功能：获取玩家客户端的 IP 地址。
• 参数：eid - 字符串，玩家实体 ID。
• 返回值：字符串，IP 地址；若不存在则返回空字符串并设置 ERR$。
• 错误："客户端信息不存在" 或 "客户端IP信息不存在"

PLATFORM(eid)

• 功能：获取玩家客户端的运行平台。
• 参数：eid - 字符串，玩家实体 ID。
• 返回值：整型，运行平台枚举值；若玩家拒绝或信息缺失则返回 -2 并设置 ERR$。
• 枚举值：
• 0: Windows
• 1: IOS
• 2: Android
• -1: 其他
• 错误：
• "客户端配置信息不存在"
• "客户端没有明确同意运行平台信息被访问"
• "客户端明确拒绝运行平台信息被访问"
• "客户端信息不存在"
• "客户端运行平台信息不存在"

FPS(eid)

• 功能：获取玩家客户端的当前帧率（FPS）。
• 参数：eid - 字符串，玩家实体 ID。
• 返回值：浮点数，FPS 值；若信息不存在则返回 -1.0 并设置 ERR$。
• 错误："客户端信息不存在" 或 "客户端FPS信息不存在"

GET_CLIPBOARD(eid)

• 功能：获取玩家客户端的剪切板内容（需玩家同意）。
• 参数：eid - 字符串，玩家实体 ID。
• 返回值：字符串，剪切板内容；若玩家拒绝或信息缺失则返回空字符串并设置 ERR$。
• 错误：
• "客户端配置信息不存在"
• "客户端没有明确同意剪切板被访问"
• "客户端明确拒绝剪切板被访问"
• "客户端信息不存在"
• "客户端剪切板信息不存在"

VIBRATE(eid)

• 功能：触发玩家客户端的设备振动（仅支持移动端）。
• 参数：eid - 字符串，玩家实体 ID。
• 返回值：整数，1 表示振动指令已发送。

SET_CLIPBOARD(eid, content)

• 功能：设置玩家客户端的剪切板内容（需玩家同意）。
• 参数：
• eid - 字符串，玩家实体 ID。
• content - 字符串，要写入剪切板的文本。
• 返回值：整数，1 表示成功，0 表示失败（如玩家拒绝）。
• 错误：同 GET_CLIPBOARD 的相关错误。

---

9. JSON 操作

以下函数用于创建和操作 JSON 对象（字符串形式）。

JSON_LIST(arg1, arg2, ...)

• 功能：创建一个 JSON 数组。
• 参数：任意数量的参数，将作为数组元素。
• 返回值：JSON 字符串，数组形式。
• 示例：basic LET LIST = JSON_LIST(1, "a", TRUE) ' 返回 "[1, \"a\", 1]"

JSON_DICT(key1, value1, key2, value2, ...)

• 功能：创建一个 JSON 对象（字典）。
• 参数：键值对依次排列，必须成对出现。
• 返回值：JSON 字符串，对象形式。
• 错误：若参数个数为奇数，抛出运行时错误 "The number of parameters must be even"。
• 示例： basic LET DICT = JSON_DICT("name", "张三", "age", 18) ' 返回 "{\"name\": \"张三\", \"age\": 18}"

JSON_GET(json_data, key_or_idx, default)

• 功能：从 JSON 对象中获取指定键或索引的值。
• 参数：
• json_data - JSON 字符串。
• key_or_idx - 字符串（键名）或整数（数组索引）。
• default - 默认值，当键/索引不存在时返回此值。
• 返回值：对应值（类型根据 JSON 内容自动转换）；若 JSON 格式错误则抛出异常。
• 错误："The string is not in correct JSON format" 或 "The json data type must be list or dict"

JSON_SET(json_data, key_or_idx, value)

• 功能：设置 JSON 对象中指定键或索引的值，并返回新 JSON 字符串。
• 参数：
• json_data - JSON 字符串。
• key_or_idx - 键名或索引。
• value - 新值。
• 返回值：修改后的 JSON 字符串。
• 错误：同 JSON_GET。

JSON_LEN(json_data)

• 功能：获取 JSON 对象（数组、字典或字符串）的长度。
• 参数：json_data - JSON 字符串。
• 返回值：整数，数组元素个数、字典键值对数量或字符串字符数。
• 错误：格式错误或类型不符时抛出异常。

JSON_KEYS(json_data)

• 功能：获取 JSON 字典的所有键名。
• 参数：json_data - JSON 字符串（必须是字典）。
• 返回值：JSON 字符串，键名数组。
• 错误：格式错误或类型不是字典时抛出异常。

JSON_HAS(json_data, key_or_item)

• 功能：判断 JSON 对象中是否包含指定键（字典）或元素（数组）。
• 参数：
• json_data - JSON 字符串。
• key_or_item - 要检查的键名或元素值。
• 返回值：整数，1 表示存在，0 表示不存在。
• 错误：格式错误或类型不是数组/字典时抛出异常。

JSON_DEL(json_data, key_or_idx)

• 功能：从 JSON 对象中删除指定键或索引的元素。
• 参数：
• json_data - JSON 字符串。
• key_or_idx - 键名或索引。
• 返回值：删除后的新 JSON 字符串；若键/索引不存在，则返回原字符串并设置 ERR$。
• 错误："索引错误" 或 "键错误"，格式错误也会抛出异常。

JSON_MERGE(json_obj_1, json_obj_2)

• 功能：合并两个 JSON 对象（必须同为数组或同为字典）。
• 参数：
• json_obj_1 - JSON 字符串。
• json_obj_2 - JSON 字符串。
• 返回值：合并后的 JSON 字符串。
• 字典：合并两个字典，第二个覆盖第一个的同名键。
• 数组：拼接两个数组。
• 错误：格式错误、类型不同或非数组/字典时抛出异常。

---

附注

• 所有函数返回值若为字符串，在 BASIC 中可直接赋值给字符串变量；数字返回值可直接用于数值运算。
• 函数执行后可通过 ERR$ 获取错误详情，该函数调用后会清空错误记录，因此建议在每次可能出错的内置函数调用后立即检查。
• 涉及客户端信息的函数需要玩家在 basic_clients_conf 中明确授权，否则会返回默认值或错误。