mirror of
https://github.com/BeamMP/Docs.git
synced 2026-05-19 08:10:50 +00:00
mt-gitlocalize
1503 lines
28 KiB
Markdown
1503 lines
28 KiB
Markdown
## 目录
|
||
|
||
### MPVehicleGE
|
||
|
||
- [Vehicle Functions（车辆函数）](#vehicle-functions)
|
||
- [Player Functions（玩家函数）](#player-functions)
|
||
- [Nametag Functions（昵称标签函数）](#nametag-functions)
|
||
- [Role Functions（角色函数）](#role-functions)
|
||
- [Navigation Functions（导航函数）](#navigation-functions)
|
||
- [Object Methods（对象方法）](#object-methods)
|
||
- [Event Hooks（事件钩子）](#event-hooks)
|
||
|
||
### MPConfig
|
||
|
||
- [MPConfig Functions（MPConfig函数）](#mpconfig-functions)
|
||
|
||
### MPCoreNetwork
|
||
|
||
- [MPCoreNetwork Functions](#mpcorenetwork-functions)
|
||
|
||
### MPGameNetwork
|
||
|
||
- [事件系统功能](#event-system-functions)
|
||
- [按键功能](#keypress-functions)
|
||
- [用户界面功能](#ui-functions)
|
||
- [MPGameNetwork 回调](#mpgamenetwork-callbacks)
|
||
|
||
### MPHelpers
|
||
|
||
- [编码函数](#encoding-functions)
|
||
- [颜色函数](#color-functions)
|
||
- [字符串函数](#string-functions)
|
||
- [表函数](#table-functions)
|
||
- [调试函数](#debug-functions)
|
||
|
||
---
|
||
|
||
## 车辆函数
|
||
|
||
### `getGameVehicleID(serverVehicleID)`
|
||
|
||
将 serverVehicleID 解析为 gameVehicleID
|
||
|
||
**参数：**
|
||
|
||
- `serverVehicleID` （字符串）- 格式：“X-Y”，其中 X 为玩家 ID，Y 为车辆 ID
|
||
|
||
**返回：**
|
||
|
||
- （数字）- 游戏内部车辆 ID
|
||
- （编号） `-1` - 如果车辆未知
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local gameID = extensions.MPVehicleGE.getGameVehicleID("0-0")
|
||
```
|
||
|
||
---
|
||
|
||
### `getServerVehicleID(gameVehicleID)`
|
||
|
||
将 gameVehicleID 解析为 serverVehicleID
|
||
|
||
**参数：**
|
||
|
||
- `gameVehicleID` （数字）- 游戏内部车辆 ID
|
||
|
||
**返回：**
|
||
|
||
- （字符串）- 服务器车辆 ID（例如，“0-0”）
|
||
- （nil）- 如果 gameVehicleID 未知
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local serverID = extensions.MPVehicleGE.getServerVehicleID(11171)
|
||
```
|
||
|
||
---
|
||
|
||
### `getVehicleByServerID(serverVehicleID)`
|
||
|
||
返回此车辆的完整车辆表
|
||
|
||
**参数：**
|
||
|
||
- `serverVehicleID` （字符串）- 格式：“X-Y”
|
||
|
||
**返回：**
|
||
|
||
- （表）- 车辆信息（名称、游戏车辆 ID、jbeam、所有者 ID、所有者名称、是否本地、是否已生成等）
|
||
- （nil）- 如果服务器车辆 ID 无效
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local vehicle = extensions.MPVehicleGE.getVehicleByServerID("0-0")
|
||
if vehicle then
|
||
print("Owner: " .. vehicle.ownerName)
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
### `getVehicleByGameID(gameVehicleID)`
|
||
|
||
返回此车辆的完整车辆表
|
||
|
||
**参数：**
|
||
|
||
- `gameVehicleID` （数字）- 游戏内部车辆 ID
|
||
|
||
**返回：**
|
||
|
||
- （表）- 车辆信息
|
||
- (nil) - 如果 gameVehicleID 无效
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local vehicle = extensions.MPVehicleGE.getVehicleByGameID(11171)
|
||
```
|
||
|
||
---
|
||
|
||
### `isOwn(gameVehicleID)`
|
||
|
||
检查给定车辆是否属于此客户端
|
||
|
||
**参数：**
|
||
|
||
- `gameVehicleID` （数字）- 游戏内部车辆 ID
|
||
|
||
**返回：**
|
||
|
||
- （boolean）- 如果车辆属于此客户端，则返回 true
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
if extensions.MPVehicleGE.isOwn(11171) then
|
||
print("This is my vehicle")
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
### `getOwnMap()`
|
||
|
||
返回一个包含此客户端拥有的所有车辆的表。
|
||
|
||
**参数：**
|
||
|
||
- 无
|
||
|
||
**返回：**
|
||
|
||
- （表）- 已拥有车辆地图`{[gameVehicleID] = vehicles_subtable}`
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local myVehicles = extensions.MPVehicleGE.getOwnMap()
|
||
```
|
||
|
||
---
|
||
|
||
### `getVehicleMap()`
|
||
|
||
返回一个包含所有已知多人游戏载具的表。
|
||
|
||
**参数：**
|
||
|
||
- 无
|
||
|
||
**返回：**
|
||
|
||
- （表）- 所有车辆的地图`{[serverVehicleID] = gameVehicleID}`
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local allVehicles = extensions.MPVehicleGE.getVehicleMap()
|
||
```
|
||
|
||
---
|
||
|
||
### `getDistanceMap()`
|
||
|
||
返回每个多人游戏载具到此客户端视角的距离
|
||
|
||
**参数：**
|
||
|
||
- 无
|
||
|
||
**返回：**
|
||
|
||
- （表）- 距离地图`{[gameVehicleID] = distanceInMeters}`
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local distances = extensions.MPVehicleGE.getDistanceMap()
|
||
```
|
||
|
||
---
|
||
|
||
### `getNicknameMap()`
|
||
|
||
返回所有多人游戏车辆 ID 及其所有者名称
|
||
|
||
**参数：**
|
||
|
||
- 无
|
||
|
||
**返回：**
|
||
|
||
- （表）- 昵称映射表`{[gameVehicleID] = ownerName}`
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local nicknameMap = extensions.MPVehicleGE.getNicknameMap()
|
||
```
|
||
|
||
---
|
||
|
||
### `getVehicles()`
|
||
|
||
返回完整的车辆表
|
||
|
||
**参数：**
|
||
|
||
- 无
|
||
|
||
**返回：**
|
||
|
||
- （表）- 所有车辆`{[serverVehicleID] = vehicles_subtable}`
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local vehicles = extensions.MPVehicleGE.getVehicles()
|
||
for serverID, vehicle in pairs(vehicles) do
|
||
print("Vehicle: " .. vehicle.jbeam)
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 玩家函数
|
||
|
||
### `getPlayerByName(name)`
|
||
|
||
返回该玩家的信息表和 ID
|
||
|
||
**参数：**
|
||
|
||
- `name` （字符串）- 玩家名称
|
||
|
||
**返回：**
|
||
|
||
- （表）- 玩家信息（姓名、玩家ID、角色、载具等）
|
||
- （数字）- 玩家 ID
|
||
- （nil）- 如果未找到玩家
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local player, playerID = extensions.MPVehicleGE.getPlayerByName("John")
|
||
if player then
|
||
print("Player ID: " .. playerID)
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
### `getPlayers()`
|
||
|
||
返回完整的玩家表
|
||
|
||
**参数：**
|
||
|
||
- 无
|
||
|
||
**返回：**
|
||
|
||
- （表）- 所有玩家`{[playerID] = players_subtable}`
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local players = extensions.MPVehicleGE.getPlayers()
|
||
for playerID, player in pairs(players) do
|
||
print("Player: " .. player.name)
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 昵称标签函数
|
||
|
||
### `setPlayerNickPrefix(targetName, tagSource, text)`
|
||
|
||
给玩家的名字标签添加前缀（显示在名字前面）
|
||
|
||
**参数：**
|
||
|
||
- `targetName` （字符串）- 玩家名称
|
||
- `tagSource` （字符串）- 此前缀的唯一标识符
|
||
- `text` （字符串）- 显示在名称之前的文本
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
extensions.MPVehicleGE.setPlayerNickPrefix("John", "RANK", "1st.")
|
||
-- Result: "1st. John"
|
||
```
|
||
|
||
---
|
||
|
||
### `setPlayerNickSuffix(targetName, tagSource, text)`
|
||
|
||
给玩家的名字标签添加后缀（显示在名字后面）
|
||
|
||
**参数：**
|
||
|
||
- `targetName` （字符串）- 玩家名称
|
||
- `tagSource` （字符串）- 此后缀的唯一标识符
|
||
- `text` （字符串）- 名称后显示的文本
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
extensions.MPVehicleGE.setPlayerNickSuffix("John", "STATUS", "[AFK]")
|
||
-- Result: "John [AFK]"
|
||
```
|
||
|
||
---
|
||
|
||
### `hideNicknames(hide)`
|
||
|
||
开启或关闭 BeamMP 的姓名标签绘制功能
|
||
|
||
**参数：**
|
||
|
||
- `hide` （boolean） - True 表示隐藏姓名标签，False 表示显示姓名标签
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
extensions.MPVehicleGE.hideNicknames(true) -- Hide
|
||
extensions.MPVehicleGE.hideNicknames(false) -- Show
|
||
```
|
||
|
||
---
|
||
|
||
### `toggleNicknames()`
|
||
|
||
切换显示姓名标签
|
||
|
||
**参数：**
|
||
|
||
- 无
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
extensions.MPVehicleGE.toggleNicknames()
|
||
```
|
||
|
||
---
|
||
|
||
## 角色函数
|
||
|
||
### `setPlayerRole(playerID, tag, shorttag, red, green, blue)`
|
||
|
||
为玩家设置自定义角色
|
||
|
||
**参数：**
|
||
|
||
- `playerID` （数字）- 玩家的ID
|
||
- `tag` （字符串）- 角色标签（例如，“VIP”）
|
||
- `shorttag` （字符串）- 简短版本（例如，“V”）
|
||
- `red` （数字）- 红色通道（0-255）
|
||
- `green` （数字）- 绿色通道（0-255）
|
||
- `blue` （数字）- 蓝色通道（0-255）
|
||
|
||
**返回：**
|
||
|
||
- （布尔值，字符串）- 如果玩家不存在`false, "player not found"`
|
||
- （布尔值，字符串）- 如果参数无效，则`false, error`
|
||
- （无）——关于成功无信息
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local success, error = extensions.MPVehicleGE.setPlayerRole(0, "VIP", "V", 255, 215, 0)
|
||
if success == false then
|
||
print("Error: " .. error)
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
### `clearPlayerRole(playerID)`
|
||
|
||
清除玩家的自定义角色
|
||
|
||
**参数：**
|
||
|
||
- `playerID` （数字）- 玩家的ID
|
||
|
||
**返回：**
|
||
|
||
- （布尔值）- 始终返回`false` （实现怪癖 - 用于检查玩家是否存在）
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
extensions.MPVehicleGE.clearPlayerRole(0)
|
||
```
|
||
|
||
---
|
||
|
||
### `setVehicleRole(playerIDVehicleID, tag, shorttag, red, green, blue)`
|
||
|
||
为特定车辆设置自定义角色
|
||
|
||
**参数：**
|
||
|
||
- `playerIDVehicleID` （字符串）- 车辆 ID（格式：“0-0”）
|
||
- `tag` （字符串）- 角色标签
|
||
- `shorttag` （字符串）- 短版本
|
||
- `red` （数字）- 红色（0-255）
|
||
- `green` （数字）- 绿色（0-255）
|
||
- `blue` （数字）- 蓝色（0-255）
|
||
|
||
**返回：**
|
||
|
||
- （布尔值，字符串）- 如果车辆不存在`false, "vehicle not found"`
|
||
- （布尔值，字符串）- 如果参数无效，则`false, error`
|
||
- （无）——关于成功无信息
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local success, error = extensions.MPVehicleGE.setVehicleRole("0-0", "Police", "POL", 0, 0, 255)
|
||
if success == false then
|
||
print("Error: " .. error)
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
### `clearVehicleRole(playerIDVehicleID)`
|
||
|
||
清除车辆的自定义角色
|
||
|
||
**参数：**
|
||
|
||
- `playerIDVehicleID` （字符串）- 车辆 ID（格式：“0-0”）
|
||
|
||
**返回：**
|
||
|
||
- （布尔值）- 始终返回`false` （实现特性 - 用于检查车辆是否存在）
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
extensions.MPVehicleGE.clearVehicleRole("0-0")
|
||
```
|
||
|
||
---
|
||
|
||
## 导航函数
|
||
|
||
### `groundmarkerToPlayer(targetName)`
|
||
|
||
设置一条通往目标玩家位置的地面标记路线（静态）
|
||
|
||
**参数：**
|
||
|
||
- `targetName` （字符串）- 玩家名称，如果为 nil 则清除
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
extensions.MPVehicleGE.groundmarkerToPlayer("John") -- Set
|
||
extensions.MPVehicleGE.groundmarkerToPlayer(nil) -- Clear
|
||
```
|
||
|
||
---
|
||
|
||
### `groundmarkerFollowPlayer(targetName, dontfollow)`
|
||
|
||
设置跟随目标玩家的地面标记路线
|
||
|
||
**参数：**
|
||
|
||
- `targetName` （字符串）- 玩家名称，如果为 nil 则停止
|
||
- `dontfollow` （布尔值）- 如果为true，则创建静态标记
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
extensions.MPVehicleGE.groundmarkerFollowPlayer("John") -- Follow
|
||
extensions.MPVehicleGE.groundmarkerFollowPlayer("John", true) -- Static
|
||
extensions.MPVehicleGE.groundmarkerFollowPlayer(nil) -- Stop
|
||
```
|
||
|
||
---
|
||
|
||
### `queryRoadNodeToPosition(targetPosition, owner)`
|
||
|
||
查找距离目标位置最近的道路节点
|
||
|
||
**参数：**
|
||
|
||
- `targetPosition` （vec3 或表）- 目标位置，包含 x、y、z 坐标
|
||
- `owner` （字符串）- 可选标识符（默认值：“target”）
|
||
|
||
**返回：**
|
||
|
||
- （布尔值）- 成功状态
|
||
- （数字）- 节点 ID（如果成功）
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local pos = vec3(100, 200, 50)
|
||
local success, nodeID = extensions.MPVehicleGE.queryRoadNodeToPosition(pos)
|
||
```
|
||
|
||
---
|
||
|
||
## 对象方法
|
||
|
||
### 玩家对象方法
|
||
|
||
#### `player:setNickPrefix(tagSource, text)`
|
||
|
||
设置该玩家名称标签的前缀
|
||
|
||
**参数：**
|
||
|
||
- `tagSource` （字符串）- 唯一标识符
|
||
- `text` （字符串）- 要显示的文本（或 nil 表示不显示）
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local player = extensions.MPVehicleGE.getPlayerByName("John")
|
||
if player then
|
||
player:setNickPrefix("STATUS", "[AFK]")
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
#### `player:setNickSuffix(tagSource, text)`
|
||
|
||
为该玩家的姓名标签设置后缀
|
||
|
||
**参数：**
|
||
|
||
- `tagSource` （字符串）- 唯一标识符
|
||
- `text` （字符串）- 要显示的文本（或 nil 表示不显示）
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local player = extensions.MPVehicleGE.getPlayerByName("John")
|
||
if player then
|
||
player:setNickSuffix("MISSION", "[In Mission]")
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
#### `player:setCustomRole(role)`
|
||
|
||
为该玩家设置自定义角色
|
||
|
||
**参数：**
|
||
|
||
- `role` （表）- 角色表： `{backcolor = {r, g, b}, tag = string, shorttag = string}`
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local player = extensions.MPVehicleGE.getPlayerByName("John")
|
||
if player then
|
||
player:setCustomRole({
|
||
backcolor = {r = 255, g = 0, b = 0},
|
||
tag = " [VIP]",
|
||
shorttag = " [V]"
|
||
})
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
#### `player:clearCustomRole()`
|
||
|
||
清除该玩家的自定义角色
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local player = extensions.MPVehicleGE.getPlayerByName("John")
|
||
if player then
|
||
player:clearCustomRole()
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
### 车辆对象方法
|
||
|
||
#### `vehicle:getOwner()`
|
||
|
||
返回此车辆的所有者
|
||
|
||
**返回：**
|
||
|
||
- （表）- 玩家对象
|
||
- （数字）- 玩家 ID
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local vehicle = extensions.MPVehicleGE.getVehicleByServerID("0-0")
|
||
if vehicle then
|
||
local owner, ownerID = vehicle:getOwner()
|
||
print("Owner: " .. owner.name)
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
#### `vehicle:setCustomRole(role)`
|
||
|
||
为这辆车设置自定义角色
|
||
|
||
**参数：**
|
||
|
||
- `role` （表）- 角色表： `{backcolor = {r, g, b}, tag = string, shorttag = string}`
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local vehicle = extensions.MPVehicleGE.getVehicleByServerID("0-0")
|
||
if vehicle then
|
||
vehicle:setCustomRole({
|
||
backcolor = {r = 0, g = 0, b = 255},
|
||
tag = " [Police]",
|
||
shorttag = " [POL]"
|
||
})
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
#### `vehicle:clearCustomRole()`
|
||
|
||
清除此车辆的自定义角色
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local vehicle = extensions.MPVehicleGE.getVehicleByServerID("0-0")
|
||
if vehicle then
|
||
vehicle:clearCustomRole()
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
#### `vehicle:setDisplayName(displayName)`
|
||
|
||
为这辆车设置自定义显示名称
|
||
|
||
**参数：**
|
||
|
||
- `displayName` （字符串）- 要显示的自定义名称
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local vehicle = extensions.MPVehicleGE.getVehicleByServerID("0-0")
|
||
if vehicle then
|
||
vehicle:setDisplayName("Patrol Car #1")
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 事件钩子
|
||
|
||
BeamMP 提供事件钩子，您可以重写这些钩子以在特定事件发生时执行自定义代码。**请勿直接调用这些函数**，而应在保留原始功能的前提下对其进行重写。
|
||
|
||
### 钩子模式
|
||
|
||
重写函数时，务必保留原函数：
|
||
|
||
```lua
|
||
-- Save the original function
|
||
local originalCallback = MPVehicleGE.onVehicleSpawned
|
||
|
||
-- Override with your custom logic
|
||
MPVehicleGE.onVehicleSpawned = function(gameVehicleID)
|
||
-- Call the original first
|
||
originalCallback(gameVehicleID)
|
||
|
||
-- Your custom code here
|
||
print("Vehicle spawned: " .. gameVehicleID)
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
### 可用的事件钩子
|
||
|
||
#### `onUpdate(dt)`
|
||
|
||
连接到多人游戏时，每一帧都会被调用
|
||
|
||
**参数：**
|
||
|
||
- `dt` （数值）- 自上一帧以来的时间间隔（秒）。
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local originalOnUpdate = MPVehicleGE.onUpdate
|
||
MPVehicleGE.onUpdate = function(dt)
|
||
originalOnUpdate(dt)
|
||
-- Your frame-by-frame logic here
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
#### `onPreRender(dt)`
|
||
|
||
在渲染每一帧之前调用
|
||
|
||
**参数：**
|
||
|
||
- `dt` （数值）- 时间差（秒）
|
||
|
||
**注意：**此功能在内部处理名称标签渲染、距离计算和地面标记。
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local originalOnPreRender = MPVehicleGE.onPreRender
|
||
MPVehicleGE.onPreRender = function(dt)
|
||
originalOnPreRender(dt)
|
||
-- Your pre-render logic here
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
#### `onVehicleSpawned(gameVehicleID)`
|
||
|
||
当车辆生成时调用（包括本地和远程车辆）
|
||
|
||
**参数：**
|
||
|
||
- `gameVehicleID` （数字）- 游戏内部车辆 ID
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local originalOnVehicleSpawned = MPVehicleGE.onVehicleSpawned
|
||
MPVehicleGE.onVehicleSpawned = function(gameVehicleID)
|
||
originalOnVehicleSpawned(gameVehicleID)
|
||
|
||
local vehicle = extensions.MPVehicleGE.getVehicleByGameID(gameVehicleID)
|
||
if vehicle then
|
||
print(vehicle.ownerName .. " spawned a " .. vehicle.jbeam)
|
||
end
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
#### `onVehicleDestroyed(gameVehicleID)`
|
||
|
||
车辆被销毁/移除时调用
|
||
|
||
**参数：**
|
||
|
||
- `gameVehicleID` （数字）- 游戏内部车辆 ID
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local originalOnVehicleDestroyed = MPVehicleGE.onVehicleDestroyed
|
||
MPVehicleGE.onVehicleDestroyed = function(gameVehicleID)
|
||
local vehicle = extensions.MPVehicleGE.getVehicleByGameID(gameVehicleID)
|
||
if vehicle then
|
||
print("Vehicle " .. vehicle.jbeam .. " was destroyed")
|
||
end
|
||
|
||
originalOnVehicleDestroyed(gameVehicleID)
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
#### `onVehicleSwitched(oldGameVehicleID, newGameVehicleID)`
|
||
|
||
当玩家切换车辆时调用
|
||
|
||
**参数：**
|
||
|
||
- `oldGameVehicleID` （数字）- 先前的车辆 ID（或 -1）
|
||
- `newGameVehicleID` （数字）- 新车辆 ID（或 -1）
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local originalOnVehicleSwitched = MPVehicleGE.onVehicleSwitched
|
||
MPVehicleGE.onVehicleSwitched = function(oldID, newID)
|
||
originalOnVehicleSwitched(oldID, newID)
|
||
|
||
print("Switched from vehicle " .. oldID .. " to " .. newID)
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
#### `onVehicleResetted(gameVehicleID)`
|
||
|
||
车辆重置时调用（仅限本地车辆）
|
||
|
||
**参数：**
|
||
|
||
- `gameVehicleID` （数字）- 游戏内部车辆 ID
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local originalOnVehicleResetted = MPVehicleGE.onVehicleResetted
|
||
MPVehicleGE.onVehicleResetted = function(gameVehicleID)
|
||
originalOnVehicleResetted(gameVehicleID)
|
||
|
||
print("Vehicle " .. gameVehicleID .. " was reset")
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
#### `onVehicleColorChanged(gameVehicleID, index, paint)`
|
||
|
||
当车辆的涂装颜色发生变化时调用
|
||
|
||
**参数：**
|
||
|
||
- `gameVehicleID` （数字）- 游戏内部车辆 ID
|
||
- `index` （数字）- 涂装槽索引（0、1 或 2）
|
||
- `paint` （表） - 包含颜色信息的油漆数据
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local originalOnVehicleColorChanged = MPVehicleGE.onVehicleColorChanged
|
||
MPVehicleGE.onVehicleColorChanged = function(gameVehicleID, index, paint)
|
||
originalOnVehicleColorChanged(gameVehicleID, index, paint)
|
||
|
||
print("Vehicle " .. gameVehicleID .. " changed paint slot " .. index)
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
#### `onVehicleReady(gameVehicleID)`
|
||
|
||
当车辆的扩展设备加载完毕且车辆完全准备就绪时，就会发出此通知。
|
||
|
||
**参数：**
|
||
|
||
- `gameVehicleID` （数字）- 游戏内部车辆 ID
|
||
|
||
**注意：**如果需要加载车辆扩展，请使用此方法代替`onVehicleSpawned` 。
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local originalOnVehicleReady = MPVehicleGE.onVehicleReady
|
||
MPVehicleGE.onVehicleReady = function(gameVehicleID)
|
||
originalOnVehicleReady(gameVehicleID)
|
||
|
||
-- Safe to interact with vehicle extensions here
|
||
local veh = be:getObjectByID(gameVehicleID)
|
||
if veh then
|
||
veh:queueLuaCommand("print('Vehicle is ready!')")
|
||
end
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
#### `onUIInitialised()`
|
||
|
||
在 BeamMP 用户界面初始化时调用
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local originalOnUIInitialised = MPVehicleGE.onUIInitialised
|
||
MPVehicleGE.onUIInitialised = function()
|
||
originalOnUIInitialised()
|
||
|
||
print("BeamMP UI initialized")
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
#### `onSettingsChanged()`
|
||
|
||
当 BeamMP 设置更改时调用
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local originalOnSettingsChanged = MPVehicleGE.onSettingsChanged
|
||
MPVehicleGE.onSettingsChanged = function()
|
||
originalOnSettingsChanged()
|
||
|
||
print("BeamMP settings changed")
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## MPConfig 函数
|
||
|
||
### `MPConfig.getPlayerServerID()`
|
||
|
||
返回本地玩家的服务器分配 ID
|
||
|
||
**返回：**
|
||
|
||
- （数字）- 玩家的服务器 ID（如果未设置则为 -1）
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local myID = extensions.MPConfig.getPlayerServerID()
|
||
```
|
||
|
||
---
|
||
|
||
### `MPConfig.getNickname()`
|
||
|
||
返回本地玩家的昵称
|
||
|
||
**返回：**
|
||
|
||
- （字符串）- 玩家当前的昵称
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local name = extensions.MPConfig.getNickname()
|
||
```
|
||
|
||
---
|
||
|
||
### `MPConfig.getConfig()`
|
||
|
||
返回 BeamMP 配置设置
|
||
|
||
**返回：**
|
||
|
||
- （表）- 包含所有 BeamMP 设置的配置表
|
||
- （nil）- 如果配置文件不存在
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local config = extensions.MPConfig.getConfig()
|
||
```
|
||
|
||
---
|
||
|
||
### `MPConfig.setConfig(settingName, settingVal)`
|
||
|
||
设置特定配置值
|
||
|
||
**参数：**
|
||
|
||
- `settingName` （字符串）- 设置的名称
|
||
- `settingVal` （任意值） - 要设置的值
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
extensions.MPConfig.setConfig("myCustomSetting", true)
|
||
```
|
||
|
||
---
|
||
|
||
## MPCoreNetwork 函数
|
||
|
||
### `MPCoreNetwork.getCurrentServer()`
|
||
|
||
返回有关当前连接服务器的信息
|
||
|
||
**返回：**
|
||
|
||
- （表）- 服务器数据（IP 地址、端口、名称、映射）
|
||
- （nil）- 如果未连接
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local server = extensions.MPCoreNetwork.getCurrentServer()
|
||
if server then
|
||
print("Server: " .. server.name)
|
||
print("IP: " .. server.ip .. ":" .. server.port)
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 事件系统功能
|
||
|
||
### `TriggerServerEvent(name, data)`
|
||
|
||
向服务器发送事件
|
||
|
||
**参数：**
|
||
|
||
- `name` （字符串）- 事件名称
|
||
- `data` （字符串）- 要发送的数据
|
||
|
||
**注意：**这是一个全局函数。服务器必须已注册此事件的处理程序。
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
TriggerServerEvent("playerReady", "ready")
|
||
|
||
-- With JSON
|
||
local data = {position = {x=100, y=200, z=50}}
|
||
TriggerServerEvent("updatePlayer", jsonEncode(data))
|
||
```
|
||
|
||
---
|
||
|
||
### `TriggerClientEvent(name, data)`
|
||
|
||
触发本地客户端事件
|
||
|
||
**参数：**
|
||
|
||
- `name` （字符串）- 事件名称
|
||
- `data` （字符串）- 要发送的数据
|
||
|
||
**注意：**全局函数。在本地触发，无需发送到服务器。
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
TriggerClientEvent("localUpdate", "data")
|
||
```
|
||
|
||
---
|
||
|
||
### `AddEventHandler(event_name, func, name)`
|
||
|
||
注册一个用于处理特定事件的函数
|
||
|
||
**参数：**
|
||
|
||
- `event_name` （字符串）- 要处理的事件的名称
|
||
- `func` （函数）- 处理函数（接收事件数据）
|
||
- `name` （字符串）- 可选的内部名称
|
||
|
||
**注意：**全局函数。
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
AddEventHandler("playerDamage", function(data)
|
||
print("Damage: " .. data)
|
||
end)
|
||
|
||
-- With JSON
|
||
AddEventHandler("vehicleSpawned", function(data)
|
||
local vehData = jsonDecode(data)
|
||
print("Spawned: " .. vehData.model)
|
||
end)
|
||
```
|
||
|
||
---
|
||
|
||
### `RemoveEventHandler(event_name, name)`
|
||
|
||
移除事件处理程序
|
||
|
||
**参数：**
|
||
|
||
- `event_name` （字符串）- 事件名称
|
||
- `name` （字符串）- 可选的内部名称
|
||
|
||
**注意：**全局函数。
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
RemoveEventHandler("playerDamage")
|
||
```
|
||
|
||
---
|
||
|
||
## 按键功能
|
||
|
||
### `onKeyPressed(keyname, func)`
|
||
|
||
注册一个按键按下时要调用的函数
|
||
|
||
**参数：**
|
||
|
||
- `keyname` （字符串）- 按键的名称（例如，“NUMPAD1”、“F1”）
|
||
- `func` （函数）- 要调用的函数（接收布尔值）
|
||
|
||
**注意：**全局函数。
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
onKeyPressed("NUMPAD1", function(state)
|
||
print("NUMPAD1 pressed!")
|
||
end)
|
||
```
|
||
|
||
---
|
||
|
||
### `onKeyReleased(keyname, func)`
|
||
|
||
注册一个在按键释放时要调用的函数
|
||
|
||
**参数：**
|
||
|
||
- `keyname` （字符串）- 键的名称
|
||
- `func` （函数）- 要调用的函数（接收布尔值）
|
||
|
||
**注意：**全局函数。
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
onKeyReleased("NUMPAD1", function(state)
|
||
print("NUMPAD1 released!")
|
||
end)
|
||
```
|
||
|
||
---
|
||
|
||
### `addKeyEventListener(keyname, func, type)`
|
||
|
||
注册一个具有可自定义触发类型的按键事件监听器
|
||
|
||
**参数：**
|
||
|
||
- `keyname` （字符串）- 键的名称
|
||
- `func` （函数）- 要调用的函数
|
||
- `type` （字符串）- 事件类型：“向下”、“向上”或“两者”（默认值：“两者”）
|
||
|
||
**注意：**全局函数。
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
addKeyEventListener("F1", function(isPressed)
|
||
if isPressed then
|
||
print("F1 pressed")
|
||
else
|
||
print("F1 released")
|
||
end
|
||
end, "both")
|
||
```
|
||
|
||
---
|
||
|
||
### `getKeyState(keyname)`
|
||
|
||
返回键的当前状态
|
||
|
||
**参数：**
|
||
|
||
- `keyname` （字符串）- 按键名称
|
||
|
||
**返回：**
|
||
|
||
- （布尔值）- 按下时为true，否则为false
|
||
|
||
**注意：**全局函数。仅适用于通过 addKeyEventListener 注册的键。
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local isPressed = getKeyState("NUMPAD1")
|
||
if isPressed then
|
||
print("NUMPAD1 is held down")
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## UI 函数
|
||
|
||
### `MPGameNetwork.spawnUiDialog(dialogInfo)`
|
||
|
||
创建自定义交互式对话框
|
||
|
||
**参数：**
|
||
|
||
- `dialogInfo` （表）- 对话框配置：
|
||
- `title` （字符串）- 对话框标题（可选）
|
||
- `body` （字符串）- 对话框消息（可选）
|
||
- `buttons` （表） - 按钮配置（可选）
|
||
- `class` （字符串）- “experimental” 用于危险警示线（可选）
|
||
- `interactionID` （字符串）- 交互标识符（可选）
|
||
- `reportToServer` （布尔值）- 发送到服务器（可选，默认值：false）
|
||
- `reportToExtensions` （布尔值）- 触发本地事件（可选，默认值：false）
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
-- Simple dialog
|
||
extensions.MPGameNetwork.spawnUiDialog({
|
||
title = "Welcome",
|
||
body = "Welcome to the server!"
|
||
})
|
||
|
||
-- Choice dialog
|
||
extensions.MPGameNetwork.spawnUiDialog({
|
||
title = "Choose Team",
|
||
body = "Which team?",
|
||
buttons = {
|
||
{label = "Red", key = "joinRed"},
|
||
{label = "Blue", key = "joinBlue"}
|
||
},
|
||
interactionID = "teamSelection",
|
||
reportToServer = true
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## MPGameNetwork 回调
|
||
|
||
### `MPGameNetwork.onUpdate(dt)`
|
||
|
||
连接到多人游戏时，每一帧都会被调用
|
||
|
||
**参数：**
|
||
|
||
- `dt` （数值）- 时间差（秒）
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local originalOnUpdate = MPGameNetwork.onUpdate
|
||
MPGameNetwork.onUpdate = function(dt)
|
||
originalOnUpdate(dt)
|
||
-- Your code here
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
### `MPGameNetwork.onVehicleReady(gameVehicleID)`
|
||
|
||
当车辆准备就绪且扩展设备已加载完毕时，会发出呼叫。
|
||
|
||
**参数：**
|
||
|
||
- `gameVehicleID` （数字）- 游戏内部车辆 ID
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local originalOnVehicleReady = MPGameNetwork.onVehicleReady
|
||
MPGameNetwork.onVehicleReady = function(gameVehicleID)
|
||
originalOnVehicleReady(gameVehicleID)
|
||
-- Your code here
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 编码函数
|
||
|
||
### `MPHelpers.b64encode(string)`
|
||
|
||
将字符串编码为 Base64（RFC 2045）
|
||
|
||
**参数：**
|
||
|
||
- `string` （字符串）- 要编码的字符串
|
||
|
||
**返回：**
|
||
|
||
- （字符串）- Base64 编码的字符串
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local encoded = extensions.MPHelpers.b64encode("Hello World")
|
||
|
||
-- Encoding JSON
|
||
local data = {name = "Player", score = 100}
|
||
local encoded = extensions.MPHelpers.b64encode(jsonEncode(data))
|
||
TriggerServerEvent("sendData", encoded)
|
||
```
|
||
|
||
---
|
||
|
||
### `MPHelpers.b64decode(string)`
|
||
|
||
解码 Base64 字符串（RFC 2045）
|
||
|
||
**参数：**
|
||
|
||
- `string` （string）- Base64 编码的字符串
|
||
|
||
**返回：**
|
||
|
||
- （字符串）- 解码后的字符串
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local decoded = extensions.MPHelpers.b64decode("SGVsbG8gV29ybGQ=")
|
||
|
||
-- Decoding JSON
|
||
AddEventHandler("receiveData", function(data)
|
||
local decoded = extensions.MPHelpers.b64decode(data)
|
||
local jsonData = jsonDecode(decoded)
|
||
end)
|
||
```
|
||
|
||
---
|
||
|
||
## 颜色函数
|
||
|
||
### `MPHelpers.hex2rgb(hex)`
|
||
|
||
将十六进制颜色代码转换为 RGB 值
|
||
|
||
**参数：**
|
||
|
||
- `hex` （字符串）- 十六进制颜色代码（例如，“#FF5733”或“#F57”）
|
||
|
||
**返回：**
|
||
|
||
- （表）- RGB 值`{r, g, b}`范围为 0-1
|
||
- （表）- 如果无效则为`{0, 0, 0}`
|
||
|
||
**注意：**支持 3 位和 6 位十六进制代码。
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local rgb = extensions.MPHelpers.hex2rgb("#FF5733")
|
||
print(rgb[1], rgb[2], rgb[3]) -- 1.0, 0.341, 0.2
|
||
|
||
-- Short format
|
||
local rgb = extensions.MPHelpers.hex2rgb("#F57")
|
||
```
|
||
|
||
---
|
||
|
||
## 字符串函数
|
||
|
||
### `MPHelpers.splitStringToTable(string, delimiter, convert_into)`
|
||
|
||
按分隔符拆分字符串，并可选择转换值
|
||
|
||
**参数：**
|
||
|
||
- `string` （字符串）- 要拆分的字符串
|
||
- `delimiter` （字符串） - 用于分割的分隔符
|
||
- `convert_into` (number) - 转换类型（可选）：
|
||
- `nil`或`0` - 保留为字符串（默认值）
|
||
- `1` - 转换为数字
|
||
- `2` - 转换为布尔值
|
||
|
||
**返回：**
|
||
|
||
- （表）- 分割值的数组
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
-- Strings
|
||
local parts = extensions.MPHelpers.splitStringToTable("Hello,World", ",")
|
||
-- {"Hello", "World"}
|
||
|
||
-- Numbers
|
||
local nums = extensions.MPHelpers.splitStringToTable("10,20,30", ",", 1)
|
||
-- {10, 20, 30}
|
||
|
||
-- Parse coordinates
|
||
local coords = extensions.MPHelpers.splitStringToTable("100,200,50", ",", 1)
|
||
local x, y, z = coords[1], coords[2], coords[3]
|
||
```
|
||
|
||
---
|
||
|
||
## 表函数
|
||
|
||
### `MPHelpers.tableDiff(old, new)`
|
||
|
||
比较两个表并返回它们的差异
|
||
|
||
**参数：**
|
||
|
||
- `old`表 - 要比较的第一个表
|
||
- `new` （表）——第二个用于比较的表
|
||
|
||
**返回：**
|
||
|
||
- （表） `diff` - 所有不同的键
|
||
- （表） `o` - 与旧值不同的值
|
||
- （表） `n` - 与新值不同的数值
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local oldConfig = {speed = 100, damage = 50, armor = 30}
|
||
local newConfig = {speed = 120, damage = 50, armor = 40}
|
||
|
||
local diff, oldVals, newVals = extensions.MPHelpers.tableDiff(oldConfig, newConfig)
|
||
-- diff = {speed = 120, armor = 40}
|
||
|
||
for key, value in pairs(diff) do
|
||
print(key .. " changed from " .. oldVals[key] .. " to " .. newVals[key])
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 调试函数
|
||
|
||
### `MPHelpers.simpletraces(level)`
|
||
|
||
返回格式化的调用者信息字符串。
|
||
|
||
**参数：**
|
||
|
||
- `level` （数字）- 堆栈层级（可选，默认值：2）
|
||
|
||
**返回：**
|
||
|
||
- （字符串）- 格式化字符串： `"source:line, namewhat name"`
|
||
- （字符串）- 如果信息不可用，则为`"unknown"`
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local function myFunction()
|
||
local caller = extensions.MPHelpers.simpletraces()
|
||
print("Called from: " .. caller)
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
### `MPHelpers.simpletrace(level)`
|
||
|
||
将调用者信息记录到控制台
|
||
|
||
**参数：**
|
||
|
||
- `level` （数字）- 堆栈层级（可选，默认值：1）
|
||
|
||
**注意：**将调用位置记录到控制台。
|
||
|
||
**用法：**
|
||
|
||
```lua
|
||
local function myFunction()
|
||
extensions.MPHelpers.simpletrace()
|
||
-- Logs: "Code was called from: lua/ge/extensions/mymod.lua:42"
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
*最后更新日期：2026年1月1日*
|