Skip to content

BASIC引擎 - 函数

以下为 BASIC引擎 官方提供的所有内置函数，供 BASIC 程序调用。

每个函数在执行后可通过 ERR$ 函数获取最近的错误信息（若无错误则返回空字符串）。

使用第三方模组提供的 BASIC 解释能力时，如果对方对函数列表作出了修改，请查阅对方的文档。

1. 错误与时间

ERR$()

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

TIMESTAMP()

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

2. 类型转换

TRY_INT(obj)

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

TRY_FLOAT(obj)

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

3. 程序控制

EXIT([msg])

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

TIMER(wait_time, book_handle[, data])

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

4. 消息与命令

SAY(msg[, color])

  • 功能：向所有玩家发送一条屏幕通知消息。
  • 参数：
  • msg - 字符串，要发送的消息。
  • color - 字符串，颜色名称（如 "WHITE"、"RED"），可选，默认为 "WHITE"。
  • 返回值：整数 0。
  • 示例：
10 SAY("你好，世界！")
20 SAY("世界不太好。。。", "BLUE")

TELL(eid, msg[, color])

  • 功能：向指定玩家发送一条屏幕通知消息。
  • 参数：
  • eid - 字符串，目标玩家的实体 ID。
  • msg - 字符串，要发送的消息。
  • color - 字符串，颜色名称（如 "WHITE"、"RED"），可选，默认为 "WHITE"。
  • 返回值：整数 0。
  • 示例：
10 EID$ = HOST_EID()
20 TELL(EID$, "你好，房主！")

CMD(cmd[, entity_id, show_output])

  • 功能：执行一条游戏命令（游戏中 / 开头的指令）。
  • 参数：
  • cmd - 字符串，要执行的命令（可不含前导斜杠）。
  • entity_id - 字符串，执行命令的实体 ID（可选，默认为随机一位幸运玩家）。
  • show_output - 布尔值或整数（0/1），是否显示命令输出给执行者（可选，默认为 0）。
  • 返回值：整数，1 表示命令成功发送，0 表示失败。
  • 示例：
10 CMD("kill @e[type=item]")

5. 玩家与实体信息

OWNER_UID()

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

HOST_EID()

  • 功能：获取房主的实体 ID（EID）。
  • 参数：无
  • 返回值：字符串，房主的 EID；若房主不存在或未上线则返回空字符串并设置 ERR$。
  • 示例：
10 H$ = HOST_EID()
  • 错误："房主不存在或暂未上线"
  • 注意：只有联机房可用该接口。

NAME_TO_EID(name)

  • 功能：通过玩家名字获取对应的实体 ID。
  • 参数：name - 字符串，玩家名。
  • 返回值：字符串，对应的 EID；若未找到则返回空字符串并设置 ERR$。
  • 示例：
10 N$ = NAME_TO_EID("狂笑的蛇将写散文")
  • 错误："玩家名所对应的玩家暂不存在"

UID_TO_EID(uid)

  • 功能：通过玩家 UID 获取对应的实体 ID。
  • 参数：uid - 字符串，玩家 UID。
  • 返回值：字符串，对应的 EID；若未找到则返回空字符串。
  • 示例：
10 N$ = NAME_TO_EID("狂笑的蛇将写散文")
20 U$ = UID(N$)
20 E$ = UID_TO_EID(U$)
  • 错误：无（未找到时不设置错误）。

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 - 字符串，要写入的文本。
  • 返回值：整数，1 表示写入成功，0 表示失败。错误信息将通过 ERR$ 获取。
  • 错误：错误信息通过 ERR$ 返回，可能包括格式错误、容器不存在等。

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 字符串，数组形式。
  • 示例：
L$ = JSON_LIST(1, "a", TRUE)  ' 返回 "[1, \"a\", 1]"

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

  • 功能：创建一个 JSON 对象（字典）。
  • 参数：键值对依次排列，必须成对出现。
  • 返回值：JSON 字符串，对象形式。
  • 错误：若参数个数为奇数，抛出运行时错误 "The number of parameters must be even"。
  • 示例：
D$ = 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 字符串。
  • 字典：合并两个字典，第二个覆盖第一个的同名键。
  • 数组：拼接两个数组。
  • 错误：格式错误、类型不同或非数组/字典时抛出异常。

10. 后处理特效

POSTPROCESS(eid, effect_name, enable, ...)

  • 功能：应用后处理特效（需要“后处理引擎”模组支持）。
  • 参数：可变参数，具体参数个数和含义取决于所调用的特效。详见 后处理引擎 文档。
  • 返回值：整数，1 表示特效应用成功，0 表示失败（如模组未装载、参数错误等）。
  • 错误：若模组“后处理引擎”未装载，则设置 ERR$ 为 "模组 '后处理引擎' 未装载"。
  • 示例：
10 SUCCESS = POSTPROCESS(E$, "sharp", TRUE, 10)

附注

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