Translate v2-server-reference.md via GitLocalize

2026-02-16 10:30:56 +00:00 · 2025-12-20 19:35:38 +00:00
parent 1b3088a920
commit bbc8905084
1 changed files with 385 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 库来解析它，或者你也可以手动逐步解析字符串，提取所需的信息。