Merge pull request #266 from BeamMP/gitlocalize-36289

Update zh translations by Ace06-suzhou
2026-02-16 02:20:44 +00:00 · 2025-12-27 21:15:05 +01:00
parent 53d2a8fc31 13e58053fd
commit c0aa622fb2
3 changed files with 492 additions and 0 deletions
--- a/docs/zh/scripting/server/v2-server-reference.md
+++ 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))`将返回服务器上第一个玩家的名字。
+
+`<PlayersServerID>` 从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。<br>serverID 会被重复利用；如果玩家离开后再次加入，他们不会获得新的 serverID，而是会被分配一个当前可用的 serverID。<br>当服务器重新启动时，serverID 会被重置。
+
+#### 静态标识符
+
+BeamMP 中的玩家拥有 3 个可通过其 serverID 获取的静态标识符，分别是他们的名称、discordID，以及硬件ID（HWID）。<br>（尽管最后一个尚未实现，但在此处我们将假设它已实现。）<br>这三种 ID 类型各自具有不同的来源，以及在玩家识别用途上的优点和缺点。
+
+ID 类型 | 优点 | 缺点 | 获取的函数
+--- | --- | --- | :-:
+name | 容易获得，直截了当 | 不安全 | GetPlayerName()
+discordID | 非常安全 | 不方便 | GetPlayerDiscordID()
+HWID | 超级安全 | 难获得 | GetPlayerHWID()
+
+### 车辆
+
+BeamMP 中的车辆有 3 个服务器会关注的属性：车辆所属者的 serverID、车辆的 vehicleID 以及车辆的数据。<br>所属者的 serverID 很简单，它就是玩家的 serverID。每辆车也有一个 vehicleID，但 vehicleID 并不是车辆唯一的；来自不同玩家的两辆车可能拥有相同的 vehicleID。<br>与 serverID 不同，vehicleID 会被重复使用。例如，如果我有 4 辆车，它们的 ID 分别是 0、1、2 和 3。如果我删除 vehicleID 为 2 的车辆，我就只剩下 0、1 和 3。当我生成一辆新车时，这辆新车会占用 ID 2。<br>最后，车辆的第三个属性是 data。data 包含车辆名称、部件以及其他数据，顾名思义。data 是以原始 JSON 字符串存储的，因此你需要使用 JSON 库来解析它，或者你也可以手动逐步解析字符串，提取所需的信息。
--- a/docs/zh/server/error-codes.md
+++ 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)。
--- a/docs/zh/server/manual.md
+++ b/docs/zh/server/manual.md
@@ -0,0 +1,87 @@
+# 服务器手册
+
+# 环境
+
+服务器受各种外部参数状态的影响：
+
+-  "Resources" 文件夹
+- ENV（进程环境）
+- 命令行参数
+- ServerConfig.toml 文件
+- 工作目录
+
+## Resources 文件夹
+
+resources 文件夹会在服务器启动时创建，同时会生成“Client”和“Server”子目录。“Server”子目录可以包含多个文件夹，每个文件夹至少包含一个 `.lua` 文件。位于插件顶层目录的 `.lua` 文件在修改时会被热加载。“Client”子目录仅接受 *&nbsp;`.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 个字符