Translate v2-server-reference.md via GitLocalize

2026-02-16 02:20:44 +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 库来解析它，或者你也可以手动逐步解析字符串，提取所需的信息。