From bbc89050849268d11944b357cae2c2fca729c282 Mon Sep 17 00:00:00 2001 From: Ace06_10010 Date: Sat, 20 Dec 2025 19:35:38 +0000 Subject: [PATCH 1/3] Translate v2-server-reference.md via GitLocalize --- .../scripting/server/v2-server-reference.md | 385 ++++++++++++++++++ 1 file changed, 385 insertions(+) create mode 100644 docs/zh/scripting/server/v2-server-reference.md diff --git a/docs/zh/scripting/server/v2-server-reference.md b/docs/zh/scripting/server/v2-server-reference.md new file mode 100644 index 00000000..2d64f1e3 --- /dev/null +++ b/docs/zh/scripting/server/v2-server-reference.md @@ -0,0 +1,385 @@ +!!! 警告 "这个网站正在建设中！" + +``` +这个网站正在积极建设中。 + +觉得你能帮上忙吗？请用铅笔在右侧点击页面！ + +这也可以在任何页面上完成。 +``` + +# 服务器脚本参考 + +## 服务器端版本 2.X + +!!! 警告 + +``` +BeamMP 服务器版本 2.X 已不再提供支持。 +本文档仅供参考。 +请更新到最新版本以进行维护和支持。 +``` + +--- + +> 这是 2.x 的脚本，仅当你的服务器端版本是老的/过时的(version 2.x.x)， 时才能使用此方法，有关最新文档，请参见 [这里](https://docs.beammp.com/scripting/server/latest-server-reference)。 {.is-warning} + +### 说明 + +要在服务器控制台中获得函数的输出，必须将其包装在`print()`语句中。例如：`print(GetPlayerName(0))`将返回服务器上第一个玩家的名字。 + +`` 从0开始。 + +### 用于编写脚本的可用函数列表 + +#### GetPlayerName(playersServerID) + +以字符串形式返回玩家的Discord名称 + +```lua +function onPlayerJoin(playerID) + local name = GetPlayerName(playerID) + -- Do something +end +``` + +#### GetPlayerDiscordID(playersServerID) + +以字符串形式返回玩家的Discord名称 + +```lua +function onPlayerJoin(playerID) + local name = GetPlayerDiscordID(playerID) + -- Do something +end +``` + +#### GetPlayerHWID(playersServerID) + +以字符串形式返回玩家的Discord ID + +```lua +function onPlayerJoin(playerID) + local name = GetPlayerHWID(playerID) + -- Do something +end +``` + +#### GetPlayerVehicles(playersServerID) + +返回玩家的车辆作为一个对象/数组 + +```lua +function onChatMessage(playerID, senderName, message) + local vehicleList = GetPlayerVehicles(playerID) + for vehicleID, vehicleData in pairs(vehicleList) do + -- Do something + -- Could also be used to check how many vehicles a player have + end +end +``` + +#### DropPlayer(playersServerID) + +断开特定玩家的连接。“其实就是踢出玩家” + +```lua +function onVehicleSpawn(playerID, vehicleID, vehicleData) + -- Do something + DropPlayer(playerID) +end +``` + +#### SendChatMessage(playersServerID, message) + +通过网络向指定的用户发送消息。每个人都用-1 + +```lua +function onPlayerJoin(playerID) + SendChatMessage(-1, "Someone just joined!") +end +``` + +#### CancelEvent() -- DEPRECIATED + +取消事件的发生。这可能很快就会发生。使用`return 1`来取消事件。 + +#### onInit() + +如果在lua文件中声明，它将在c++成功加载当前lua文件后被调用 + +```lua +function onInit() + print("Server ready") +end +``` + +#### exit() + +将关闭服务器 + +```lua +function onInit() + print("Server Ready. But who needs a server which is running") + exit() -- Stops the server +end +``` + +#### CreateThread(functionName, callInterval) + +将在专用线程上执行该函数，它将每秒运行callInterval数次。它每秒钟都会跑一次。 + +```lua +function yourFunction() + for i = 1,10 do + SendChatMessage(-1, "Countdown: "..i) + Sleep(1000) + end +end +CreateThread("yourFunction", 30) +``` + +已弃用示例：将在专用线程上执行该函数 + +```lua +function yourFunction() + for i = 1,10 do + SendChatMessage(-1, "Countdown: "..i) + Sleep(1000) + end +end +CreateThread("yourFunction", 30) +``` + +#### StopThread(functionName) + +将停止尝试调用当前脚本的线程函数 + +```lua +function yourFunction() + delayExpired = false + Sleep(10000) + delayExpired = true +end +CreateThread("yourFunction", 30) +-- Do something +if not delayExpired then + StopThread("yourFunction") +else + -- Do something +end + +``` + +#### Sleep(millisecs) - DEPRECIATED + +将暂停执行指定的时间（警告，如果没有创建线程，将暂停整个服务器） + +```lua +function countdown() + for i = 1,10 do + SendChatMessage(-1, "Countdown: "..i) + Sleep(1000) + end +end +CreateThread("countdown", 10) +``` + +#### GetPlayerCount() + +将返回多少玩家连接 + +```lua +function onPlayerJoin(playerID) + SendChatMessage(playerID, "You are the "..GetPlayerCount().."th player!" +end +``` + +#### RemoveVehicle(playerServerID, VehicleID) + +这会导致一辆载具消失。 + +```lua +function onVehicleSpawn(playerID, vehicleID, vehicleData) + if --[[ Vehicle data equal something it shouldn't be ]] then + RemoveVehicle(playerID, vehicleIID) + end +end +``` + +#### GetPlayers() + +将返回一个带有name的id表 + +```lua +local function onPlayerJoin(joinedPlayerID) + local players = GetPlayers() + for playerID, playerName in pairs(players) do + if playerID == joinedPlayerID then + -- Do something + end + end +end +``` + +#### RegisterEvent(eventName, functionName) + +将该函数注册到指定的事件，都必须是字符串。 + +```lua + function anyEvent() + -- Do something + end + RegisterEvent("onAnyEventHappen", "anyEvent") + -- Do something + TriggerLocalEvent("onAnyEventHappen") +``` + +#### TriggerLocalEvent(eventName) + +将调用同一插件文件夹中的每个注册函数。 + +```lua + function anyEvent() + -- Do something + end + RegisterEvent("onAnyEventHappen", "anyEvent") + -- Do something + TriggerLocalEvent("onAnyEventHappen") +``` + +#### TriggerGlobalEvent(eventName) + +将使用此事件名称调用每个已注册的函数。 + +```lua + -- File A + function anyEvent() + -- Do something + end + RegisterEvent("onAnyEventHappen", "anyEvent") +``` + +```lua + -- File B + TriggerGlobalEvent("onAnyEventHappen") +``` + +#### TriggerClientEvent(playerServerID, eventName, data) + +将使用给定的数据在指定的客户端（-1 表示广播）上触发该事件。 + +```lua + function onPlayerJoin(playerServerID) + TriggerClientEvent(playerServerID, "anyEvent", "You just joined the server") + end + RegisterEvent("onAnyEventHappen", "anyEvent") +``` + +#### Set(configID, newValue) + +会将配置设置修改为下方表格中指定的新值。 + +```lua + function onChatMessage(playerID, senderName, message) + if playerID == adminPlayer then + if message == --[[ anything ]] then + Set(3, 10) + end + end + end +``` + +#### 可用于 `Set()` 命令的配置项列表 + +> Note that these will not save to the config file. + +Config ID | 名称 | 只接受以下内容 +--- | --- | --- +`0` | 调试设置 | true 或 false +`1` | 私人设置 | true 或 false +`2` | 每个玩家的最大车辆数 | 数字 +`3` | 最大玩家数 | 数字 +`4` | 地图 | 字符串 +`5` | 名称 | 字符串 +`6` | 描述 | 字符串 +任何其他ID都会导致控制台警告 | | + +### 用于编写脚本的可用事件列表 + +#### 默认事件 + +如何使用事件的示例: + +```lua + function onInit() + RegisterEvent("onPlayerJoin", "onPlayerJoin") + end + + function onPlayerJoin(playerServerID) + -- Do something + end +``` + +如果你不希望访客进入你的服务器： + +```lua + function onInit() + print("noGuests Ready") + RegisterEvent("onPlayerAuth","onPlayerAuth") + end + + function onPlayerAuth(name, role, isGuest) + if isGuest then + return "You must be signed in to join this server!" + end + end +``` + +事件 | 参数 | 描述 +--- | --- | --- +`onPlayerAuth` | 玩家的名称、论坛角色、是否为访客账号（布尔值） | 有一名玩家已通过验证并正在请求加入。 +`onPlayerConnecting` | 玩家的ID | 玩家正在加载（在加载地图之前） +`onPlayerJoining` | 玩家的ID | 玩家正在加载地图，很快就会加入 +`onPlayerJoin` | 玩家的ID | 玩家已加入并加载 +`onPlayerDisconnect` | 玩家的ID | 玩家退出了游戏 +`onChatMessage` | 发消息的玩家的ID、昵称和聊天消息 | 发送了一条聊天消息。这对于创建命令系统非常有用 +`onVehicleSpawn` | 玩家ID，车辆ID和车辆数据 | 当有人刷出一辆车时输出 +`onVehicleEdited` | 玩家ID，车辆ID和车辆数据 | 当有人编辑车辆或替换现有车辆时，就会调用此操作 +`onVehicleDeleted` | 玩家的ID和车辆ID | 当某人删除自己拥有的车辆时，就会调用此操作 + +#### 自定义事件 + +可以创建自定义事件以供自己使用。这与默认值的处理方式非常相似。 + +如何使用自定义事件的范例: + +```lua + function onInit() + RegisterEvent("myCustomEvent", "myCustomEvent") + end + + function myCustomEvent(playerServerID, customData) + -- Do something + end +``` + +接着可以使用各自的函数从客户端或服务器端调用该函数。 + +### 玩家 + +当玩家连接到你的服务器时，他们会被分配一个从 0 开始递增的 serverID。
serverID 会被重复利用；如果玩家离开后再次加入，他们不会获得新的 serverID，而是会被分配一个当前可用的 serverID。
当服务器重新启动时，serverID 会被重置。 + +#### 静态标识符 + +BeamMP 中的玩家拥有 3 个可通过其 serverID 获取的静态标识符，分别是他们的名称、discordID，以及硬件ID（HWID）。
（尽管最后一个尚未实现，但在此处我们将假设它已实现。）
这三种 ID 类型各自具有不同的来源，以及在玩家识别用途上的优点和缺点。 + +ID 类型 | 优点 | 缺点 | 获取的函数 +--- | --- | --- | :-: +name | 容易获得，直截了当 | 不安全 | GetPlayerName() +discordID | 非常安全 | 不方便 | GetPlayerDiscordID() +HWID | 超级安全 | 难获得 | GetPlayerHWID() + +### 车辆 + +BeamMP 中的车辆有 3 个服务器会关注的属性：车辆所属者的 serverID、车辆的 vehicleID 以及车辆的数据。
所属者的 serverID 很简单，它就是玩家的 serverID。每辆车也有一个 vehicleID，但 vehicleID 并不是车辆唯一的；来自不同玩家的两辆车可能拥有相同的 vehicleID。
与 serverID 不同，vehicleID 会被重复使用。例如，如果我有 4 辆车，它们的 ID 分别是 0、1、2 和 3。如果我删除 vehicleID 为 2 的车辆，我就只剩下 0、1 和 3。当我生成一辆新车时，这辆新车会占用 ID 2。
最后，车辆的第三个属性是 data。data 包含车辆名称、部件以及其他数据，顾名思义。data 是以原始 JSON 字符串存储的，因此你需要使用 JSON 库来解析它，或者你也可以手动逐步解析字符串，提取所需的信息。 From 94c11cf4fab3c0a0a407c46e1ee4a9b8ef0fc699 Mon Sep 17 00:00:00 2001 From: Ace06_10010 Date: Sat, 20 Dec 2025 19:35:43 +0000 Subject: [PATCH 2/3] Translate error-codes.md via GitLocalize --- docs/zh/server/error-codes.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 docs/zh/server/error-codes.md diff --git a/docs/zh/server/error-codes.md b/docs/zh/server/error-codes.md new file mode 100644 index 00000000..41d68b34 --- /dev/null +++ b/docs/zh/server/error-codes.md @@ -0,0 +1,20 @@ +# 错误代码 + +此页面包含服务器可能显示的所有错误代码。 + +--- + +错误代码 | 描述 | 可能的解决方案 +--- | --- | --- +10022 | 绑定端口时出现问题 | 检查该端口是否已被其他服务占用，如果是，请更换为其他端口。 +10048 | 地址已被占用 | 有另一个 BeamMP 服务器或程序正在使用该端口，请更换为其他端口。 +10051 | 网络不可达 | 端口转发配置错误或类似问题，请确认所有设置均已正确配置。 +10052 | 网络重置 | 当网络在建立连接过程中断开时会发生此情况。请重试连接。 +10053 | 连接已中止 | 由于超时或网络错误导致，请重试连接。 +10054 | 连接被对端重置。 | 有客户端已从你的服务器断开连接。 +10060 | 连接超时 | 你的端口转发存在问题，请参考 [指南步骤](create-a-server.md#1-port-forwarding)。 +10061 | 连接被拒绝 | 你的端口转发存在问题，请参照 [指南步骤](create-a-server.md#1-port-forwarding)。 +10064 | 主机宕机 | 罕见错误，但表示主机已宕机，可能是因为主机已关闭或端口被关闭。 +10065 | 无法访问主机 | 无网络或端口转发错误，请参考 [指南步骤](create-a-server.md#1-port-forwarding)。 + +!!! note “对于本列表中未包含的任何其他错误代码，如果你对网络/套接字有一定了解，可以参考 [https://learn.microsoft.com/en-us/windows/win32/winsock/windows-sockets-error-codes-2](https://learn.microsoft.com/en-us/windows/win32/winsock/windows-sockets-error-codes-2)。 From 13e58053fd277a213e0bfbfc5cd90c223349f22f Mon Sep 17 00:00:00 2001 From: Ace06_10010 Date: Sat, 20 Dec 2025 19:35:46 +0000 Subject: [PATCH 3/3] Translate manual.md via GitLocalize --- docs/zh/server/manual.md | 87 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/zh/server/manual.md diff --git a/docs/zh/server/manual.md b/docs/zh/server/manual.md new file mode 100644 index 00000000..2c826b34 --- /dev/null +++ b/docs/zh/server/manual.md @@ -0,0 +1,87 @@ +# 服务器手册 + +# 环境 + +服务器受各种外部参数状态的影响： + +- "Resources" 文件夹 +- ENV（进程环境） +- 命令行参数 +- ServerConfig.toml 文件 +- 工作目录 + +## Resources 文件夹 + +resources 文件夹会在服务器启动时创建，同时会生成“Client”和“Server”子目录。“Server”子目录可以包含多个文件夹，每个文件夹至少包含一个 `.lua` 文件。位于插件顶层目录的 `.lua` 文件在修改时会被热加载。“Client”子目录仅接受 * `.zip` 文件，这些文件在服务器启动时加载，并假设在运行时不会发生变化。* + +## ENV + +### 一般设置 + +从服务器 v3.2.0 版本开始，BeamMP 服务器支持环境变量，这些变量会 **覆盖** ServerConfig.toml 中的设置。所有位于“General”类别/部分的 ServerConfig 变量都是 PascalCase，而环境变量则为 ALL_CAPS，并以 `BEAMMP_` 为前缀。例如，`MaxPlayers` 设置转换为全大写为 `MAX_PLAYERS`（注意每个新单词前的 `_`），加上前缀后变为 `BEAMMP_MAX_PLAYERS`。所有“General”设置都遵循此格式。现有的 ENV 变量如下： + +- `BEAMMP_DEBUG` +- `BEAMMP_PRIVATE` +- `BEAMMP_PORT` +- `BEAMMP_MAX_CARS` +- `BEAMMP_MAX_PLAYERS` +- `BEAMMP_MAP` +- `BEAMMP_NAME` +- `BEAMMP_DESCRIPTION` +- `BEAMMP_TAGS` +- `BEAMMP_RESOURCE_FOLDER` +- `BEAMMP_AUTH_KEY` +- `BEAMMP_LOG_CHAT` + +任何对应于配置参数的环境变量，如果参数类型为字符串或数字，则环境变量必须为字符串，例如 `BEAMMP_NAME="Cool Server"`、`BEAMMP_NAME=Server1`、`BEAMMP_PORT=12345`。对应于布尔类型（true/false、on/off）的配置参数的环境变量必须为 `true` 或 `1`（都表示开启），其他任意值表示关闭。 + +### 服务器提供者或服务提供相关的设置 + +这些环境变量允许托管提供者（以及拥有更多服务器的其他用户，此处称为‘提供者’）覆盖某些特定于提供者的设置。 + +#### `BEAMMP_PROVIDER_PORT_ENV` (在v3.3.0版本) + +当设置为非空字符串时，这会用另一个变量替换 `BEAMMP_PORT` 变量，以便从现有的 ENV 中读取该变量。例如，Pterodactyl 可能会将 `SERVER_PORT` 作为 ENV 暴露。要在 BeamMP-Server 中使用它，你需要这样设置 `BEAMMP_PORT=${SERVER_PORT}`，这有点繁琐。 + +现在，你可以使用 `BEAMMP_PROVIDER_PORT_ENV="SERVER_PORT"`，这样 BeamMP-Server 就会从 `SERVER_PORT` ENV 变量中读取端口。 + +#### `BEAMMP_PROVIDER_DISABLE_CONFIG` (在v3.3.0版本) + +如果设置为 `1` 或 `true`，则 `ServerConfig.toml` 将 **不被生成**，如果存在也 **不会被读取**。服务器必须设置 `BEAMMP_AUTH_KEY` 才能正常运行。 + +#### `BEAMMP_PROVIDER_UPDATE_MESSAGE` (在v3.2.2版本) + +当设置为非空字符串时，这会替换整个更新消息，默认消息为“NEW VERSION IS OUT! Please update to the new...” 等。你提供的更新消息中 **必须**包含 `{}`，服务器会将其替换为新版本号。例如，你的更新消息可以如下所示： + +```sh +BEAMMP_PROVIDER_UPDATE_MESSAGE="BeamMP-Server 的新版本已发布：{}！请按照此更新指南操作：https://example.com/update-guide" +``` + +这将生成如下更新消息 + +``` +BeamMP-Server 的新版本已发布：v5.0.2！请按照此更新指南操作：https://example.com/update-guide +``` + +请务必向用户明确说明他们需要更新，并解释如何进行更新。 + +## 命令行参数 + +使用 `--help` 参数运行 BeamMP 服务器以了解更多信息。例如：`./BeamMP-Server --help`。 + +## ServerConfig.toml + +该文件会在首次启动时生成。文件内的注释是了解每个设置作用的最新方式。 + +## 工作目录 + +服务器的工作目录，而不是服务器可执行文件的位置，决定了 ServerConfig.toml、服务器日志文件和 Resources 文件夹的生成位置。 + +# 限制 + +以下限制在 BeamMP 后端中被强制执行，这会影响服务器： + +- Name 的长度限制为 250 个字符 +- 描述限制为 1000 个字符 +- 地图名称限制为 100 个字符 +- 标签限制为 100 个字符