-
Notifications
You must be signed in to change notification settings - Fork 2
/
Scripting.html
251 lines (250 loc) · 11.2 KB
/
Scripting.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
<!--
title: Scripting in BeamMP
description: This will briefly introduce you to the concept of scripting for BeamMP.
published: true
date: 2022-12-22T09:22:38.585Z
tags: scripting
editor: ckeditor
dateCreated: 2020-06-17T19:31:24.640Z
-->
<p>BeamMP allows server-owners to extend the functionality of their server via custom <a href="lua.org">lua</a> scripts/plugins.</p>
<h1>Plugin Folder</h1>
<p>all lua files live inside of their respective plugin folder, the plugin folder should look like this: <u>Resources\Server\<pluginName></u> every lua file within a plugin folder has its own dedicated lua environment; under normal circumstances, separate lua files cannot interact with each-other beyond triggering events.</p>
<h1>Events</h1>
<p> in BeamMP, events must be registered using <u>RegisterEvent(<EventName>,<functionName>)</u> otherwise they will not be triggered, the 'EventName' parameter is the title of the desired event to be registered as a string, 'FunctionName' is the name of the <strong>global</strong> function as a <strong>string</strong> that you want to be called when the event is triggered. </p>
<h2>Vanilla BeamMP events</h2>
<p>Vanilla BeamMP servers ship with various pre-existing events which correspond to various in-game actions. can be cancelled by returning 1 in the function.</p>
<figure class="table">
<table>
<thead>
<tr>
<th>Event Name</th>
<th>Parameters</th>
<th>When is it triggered?</th>
<th>When cancelled</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>onInit</td>
<td>nothing</td>
<td>When the lua file is loaded</td>
<td>Does nothing</td>
<td> </td>
</tr>
<tr>
<td>onPlayerConnecting</td>
<td>PlayerID</td>
<td>When the player presses 'Connect'</td>
<td>Not recomended, use DropPlayer(PlayerID, reason)</td>
<td> </td>
</tr>
<tr>
<td>onPlayerJoining</td>
<td>PlayerID</td>
<td>When the player begins loading</td>
<td>Not recomended, use DropPlayer(PlayerID, reason)</td>
<td> </td>
</tr>
<tr>
<td>onPlayerJoin</td>
<td>PlayerID</td>
<td>When the player is done loading</td>
<td>Not recomended, use DropPlayer(PlayerID, reason)</td>
<td> </td>
</tr>
<tr>
<td>onPlayerDisconnect</td>
<td>PlayerID</td>
<td>When the player leaves the server</td>
<td>Does Nothing</td>
<td> </td>
</tr>
<tr>
<td>onChatMessage</td>
<td>PlayerID, name, message</td>
<td>When a player sends a chat message</td>
<td>Message does not display in chatbox</td>
<td> </td>
</tr>
<tr>
<td>onVehicleSpawn</td>
<td>PlayerID, vehicleID, data</td>
<td>When a player spawns a vehicle</td>
<td>Deletes vehicle, does not trigger onVehicleDeleted</td>
<td>data is raw JSON</td>
</tr>
<tr>
<td>onVehicleEdited</td>
<td>PlayerID, vehicleID, data</td>
<td>When a player applies their edits to the server</td>
<td>Deletes vehicle, does not trigger onVehicleDeleted</td>
<td>data is raw JSON</td>
</tr>
<tr>
<td>onVehicleDeleted</td>
<td>PlayerID, vehicleID</td>
<td>When a player deletes their vehicle</td>
<td>Does Nothing</td>
<td> </td>
</tr>
</tbody>
</table>
</figure>
<h2>User-defined events</h2>
<p>Users may also define their own Events beyond the pre-existing BeamMP events, they are registered the same way as normal events, the difference being that user-defined events are not tied to a specific event on the server and instead have to be triggered manually.</p>
<p>User-defined events can be triggered using two functions, <u>TriggerLocalEvent(<EventName>, ...)</u> or <u>TriggerGlobalEvent(<EventName>, ...)</u> String, EventName is the name that users will register their events under, any parameters after EventName, will be passed to the function the event points to. <u>TriggerLocalEvent(<EventName>, ...)</u> will execute any registered instances of EventName within the <strong>plugin folder</strong>, whereas <u>TriggerGlobalEvent(<EventName>, ...)</u> will execute <strong>any</strong> registered instance of EventName regardless of plugin folder.</p>
<p>Under normal circumstances, user-defined events are the only way that separate lua files will be able to communicate with each other.</p>
<h1>Functions</h1>
<p>BeamMP also has a set of predefined global functions you may use.</p>
<figure class="table">
<table>
<thead>
<tr>
<th>Function</th>
<th>Description</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>GetPlayerName(<serverID>)</td>
<td>Returns the players discord name as a string</td>
<td> </td>
</tr>
<tr>
<td>GetPlayerDiscordID(<serverID>)</td>
<td>Deprecated, for compatibility, currently returns the player's name as a string.</td>
<td>Deprecated, do not use this.</td>
</tr>
<tr>
<td>GetPlayerHWID(<serverID>)</td>
<td>Returns the players hardware id as a string.</td>
<td>hardware ID is not<br>implemented yet.</td>
</tr>
<tr>
<td>GetPlayerVehicles(<serverID>)</td>
<td>Returns the players vehicles as a table of IDs and Data (nil if no cars were found)</td>
<td>Doesn't work/inconsistent.</td>
</tr>
<tr>
<td>DropPlayer(<serverID>, <Reason>)</td>
<td>Drops the connection for a specific player. Essentially Kicking them</td>
<td> </td>
</tr>
<tr>
<td>SendChatMessage(<serverID>,<Message>)</td>
<td>Sends a message over the network as the server to a player use -1 to broadcast</td>
<td>use -1 to broadcast</td>
</tr>
<tr>
<td>RegisterEvent(<EventName>,<functionName>)</td>
<td>Register a function to be triggered by EventName. <br>functionName is a string representing a global function.</td>
<td> </td>
</tr>
<tr>
<td>TriggerLocalEvent(<EventName>, ...)</td>
<td>Trigger any Event registered under <EventName> within the plugin folder.<br>Any further args after <EventName> will be passed through as args.</td>
<td> </td>
</tr>
<tr>
<td>TriggerGlobalEvent(<EventName>, ...)</td>
<td>Trigger any Event registered under <EventName> regardless of the plugin folder.<br>Any further args after <EventName> will be passed through as args.</td>
<td> </td>
</tr>
<tr>
<td>CreateThread(<funcName>, <times per sec>)</td>
<td>funcName is a string representing the global name of a function.<br>A new thread will be created, on which, function is called x times per sec</td>
<td>cannot pass args<br>use this instead of infinite loops<br>times/sec is between 1 and 500</td>
</tr>
<tr>
<td>StopThread()</td>
<td>Will stop trying to call the thread function of the current script</td>
<td>if there is no thread, <br>nothing happens</td>
</tr>
<tr>
<td>GetPlayerCount()</td>
<td>Returns the number of players on the server.</td>
<td> </td>
</tr>
<tr>
<td>Sleep(<millisecs>)</td>
<td>pauses <strong>ALL</strong> operations for milliseconds. It is recommended that you only use Sleep inside of a thread.</td>
<td> </td>
</tr>
<tr>
<td>RemoveVehicle(<serverID>,<VehicleID>)</td>
<td>Deletes a player's vehicle.</td>
<td> </td>
</tr>
<tr>
<td>GetPlayers()</td>
<td>Returns a table of serverID's and their names. </td>
<td>nil if there is no players connected</td>
</tr>
<tr>
<td>TriggerClientEvent(<serverID>,<function name>,<Data>)</td>
<td>Will send a trigger request to the client lua.</td>
<td> </td>
</tr>
<tr>
<td>Set(<configID>, <new value>)</td>
<td>Will change the running-config of the server depending on the ID.</td>
<td>
<p>0 for the debug config,</p>
<p>1 for the private config,</p>
<p>2 for the CarCount Config,</p>
<p>3 for the MaxPlayers config,</p>
<p>4 for the Map,</p>
<p>5 for the Name,</p>
<p>6 for the Description,</p>
<p>any other ID will result in a console warning.</p>
</td>
</tr>
<tr>
<td>exit</td>
<td>will close the server.</td>
<td> </td>
</tr>
</tbody>
</table>
</figure>
<h1>Players</h1>
<p>When a player connects to your server, they are assigned a serverID starting from 0 and counting upwards. serverIDs are reused; if a player leaves and re-joins they will not be assigned a new serverID, they will simply get another available one. When the server restarts, serverIDs will be reset.</p>
<h2>Static Identifiers</h2>
<p>Players in BeamMP have 3 static identifiers which can be obtained from their serverID being their name, discordID, and their hardwareID or HWID. (though the latter of the aforementioned isn't implemented, we will act as if it is) Each of the three ID types has their own origins and strength's/weaknesses to using them for player identification.</p>
<figure class="table">
<table>
<thead>
<tr>
<th>ID TYPE</th>
<th>PROS</th>
<th>CONS</th>
<th>FUNCTION TO OBTAIN</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>easy to obtain, straightforward</td>
<td>not secure</td>
<td>GetPlayerName(<serverID>)</td>
</tr>
<tr>
<td>discordID</td>
<td>fairly secure</td>
<td>inconvenient</td>
<td>GetPlayerDiscordID(<serverID>)</td>
</tr>
<tr>
<td>HWID</td>
<td>extremely secure</td>
<td>hard to obtain</td>
<td>GetPlayerHWID(<serverID>)</td>
</tr>
</tbody>
</table>
</figure>
<h1>Vehicles</h1>
<p>Vehicles in beamMP have 3 attributes that the server pays attention to, the owner's serverID, the vehicles vehicleID and it's data. The the Owner's serverID is straight forward, it is the serverID, every vehicle also has an ID, vehicle IDs are not unique to the vehicle; two vehicles may have the same ID, assuming they're from different owners. Unlike serverIDs, vehicleIDs <strong>are reused</strong>, for example, if I have 4 vehicles, their IDs are 0, 1, 2 and, 3 if I delete the vehicle in vehicleID 2, I will have 0, 1 and, 3, when I spawn a new vehicle, the new vehicle will slot into ID 2. Lastly, the last attribute vehicles have is data, data contains a vehicle, name, parts, and other data; as the name implies. data is stored as a raw JSON string, so you will need a <a href="https://gist.github.com/tylerneylon/59f4bcf316be525b30ab">JSON library</a> alternatively, you can manually step through the string and dig out the information you need.</p>