mirror of
https://github.com/BeamMP/Docs.git
synced 2026-02-16 10:30:56 +00:00
386 lines
9.8 KiB
Markdown
386 lines
9.8 KiB
Markdown
!!! 警告 "这个网站正在建设中！"
|
||
|
||
```
|
||
这个网站正在积极建设中。
|
||
|
||
觉得你能帮上忙吗？请用铅笔在右侧点击页面！
|
||
|
||
这也可以在任何页面上完成。
|
||
```
|
||
|
||
# 服务器脚本参考
|
||
|
||
## 服务器端版本 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 库来解析它，或者你也可以手动逐步解析字符串，提取所需的信息。
|