You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: structures/expressions/variables.md
+208Lines changed: 208 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -14,6 +14,8 @@ Some types of variable have special behaviour in certain situations, detailed be
14
14
15
15
Most variables are **value** variables: these store a raw value. Value variables have the standard `{variable}` name pattern.
16
16
17
+
Normal (value) variables are local to the current `trigger` section.
18
+
17
19
Variables can be set and retrieved like a normal expression.
18
20
19
21
```clike
@@ -167,3 +169,209 @@ This would allow an atomic variable to be returned from a function secretly, but
167
169
{% hint style="danger" %}
168
170
This will be an `AtomicVariable` object and may be difficult to manipulate.
169
171
{% endhint %}
172
+
173
+
### Thread-Local Variables
174
+
175
+
Thread-local variables use the `{_variable}` name pattern. They are **reference** variables.
176
+
177
+
Thread-local variables are accessible **anywhere** on the current process (thread). This includes other functions and lambdas. Thread-local variables are **not** accessible from other threads.
178
+
179
+
{% hint style="info" %}
180
+
A thread/process is like a queue of instructions, executed in order. Using the `wait` or `sleep`effect will pause the thread.
181
+
182
+
The `run ... in the background` effect can be used to create a different, branching process that will run at the same time as the current one.
183
+
{% endhint %}
184
+
185
+
In normal code, thread-local variables function exactly the same as regular value variables.
186
+
187
+
```clike
188
+
set {_var} to 100
189
+
set {_var} to {_var} - 1
190
+
print {_var}
191
+
if {_var} is 6:
192
+
set {_var} to 20
193
+
```
194
+
195
+
Remember: a variable named `{_var}` is **different** from a variable named `{var}`.
196
+
197
+
```clike
198
+
set {_var} to 1 // thread-local
199
+
set {var} to 2 // normal
200
+
assert {var} is not {_var}
201
+
```
202
+
203
+
Thread-local variables make it easy to pass data between triggers that are guaranteed to be executed in the same process.
204
+
205
+
```clike
206
+
function first:
207
+
trigger:
208
+
set {_var} to 10 // thread-local
209
+
set {var} to 5 // normal (local to this trigger)
210
+
run second()
211
+
212
+
function second:
213
+
trigger:
214
+
assert {var} is null
215
+
assert {_var} is 10 // value is kept from before call
216
+
```
217
+
218
+
Thread-local variables are **atomic**, and any use alters the same copy of the variable.
219
+
220
+
```clike
221
+
function first:
222
+
trigger:
223
+
set {_var} to 10 // thread-local
224
+
assert {_var} is 10
225
+
run second() // value is changed in this function
226
+
assert {_var} is 5
227
+
228
+
function second:
229
+
trigger:
230
+
assert {_var} is 10
231
+
set {_var} to 5
232
+
assert {_var} is 5
233
+
```
234
+
235
+
Thread-local variables can be accessed and changed from lambdas, unlike regular variables.
236
+
237
+
```clike
238
+
function my_function:
239
+
trigger:
240
+
set {_var} to 10 // thread-local
241
+
set {thing} to a new runnable:
242
+
assert {_var} is 10
243
+
set {_var} to 5
244
+
assert {_var} is 5
245
+
assert {_var} is 10
246
+
run {thing} // value is changed by the runnable
247
+
assert {_var} is 5
248
+
```
249
+
250
+
However, lambdas or functions run in the background will **not** be able to access the value.
251
+
252
+
This is because background processes are run on a **different** thread, so their thread-local `{_variables}` are different.
253
+
254
+
```clike
255
+
function my_function:
256
+
trigger:
257
+
set {_var} to 10 // thread-local
258
+
set {thing} to a new runnable:
259
+
assert {_var} is null
260
+
set {_var} to 5 // does NOT update the other _var
261
+
assert {_var} is 5
262
+
assert {_var} is 10
263
+
run {thing} in the background // run on a DIFFERENT thread
264
+
wait 10 milliseconds // wait for other thread to finish
265
+
assert {_var} is 10 // _var is unchanged
266
+
```
267
+
268
+
Events and other entry-points are triggered on a new thread, so there is no cross-contamination between processes.
269
+
270
+
```clike
271
+
on load:
272
+
trigger:
273
+
assert {_var} is null // not set yet
274
+
set {_var} to 10 // thread-local
275
+
assert {_var} is 10
276
+
277
+
on load: // different event trigger, so run on different thread
278
+
trigger:
279
+
assert {_var} is null // not set on THIS thread
280
+
set {_var} to 10 // thread-local
281
+
assert {_var} is 10
282
+
```
283
+
284
+
The [skript namespace ](../../namespaces/skript.md#generic)has a special function to transfer thread-local variables to a different thread.
285
+
286
+
Transferring these will **copy** the variables, so the original copy will not be updated by changes.
287
+
288
+
```clike
289
+
function my_function:
290
+
trigger:
291
+
set {thread} to the current process
292
+
set {_var} to 10 // thread-local
293
+
set {thing} to a new runnable:
294
+
run copy_threadlocals_from({thread})
295
+
assert {_var} is 10 // copied from other _var
296
+
set {_var} to 5 // does NOT update the other _var
297
+
assert {_var} is 5
298
+
assert {_var} is 10
299
+
run {thing} in the background // run on a DIFFERENT thread
300
+
assert {_var} is 10 // _var is unchanged, the COPY was changed
301
+
```
302
+
303
+
### Global Variables
304
+
305
+
Global variables use the `{!variable}` name pattern. They are **reference** variables. These are most similar to the normal variables from [original Skript](https://github.com/SkriptLang/Skipt).
306
+
307
+
Any copy of a global `{!variable}` anywhere on any process will access the same value.
308
+
309
+
{% hint style="info" %}
310
+
Unlike in original Skript, global variables are not persistent across restarts (by default.)
311
+
{% endhint %}
312
+
313
+
In normal code, globals variables function exactly the same as regular value variables.
314
+
315
+
```clike
316
+
set {!var} to 100
317
+
set {!var} to {!var} - 1
318
+
print {!var}
319
+
if {!var} is 6:
320
+
set {!var} to 20
321
+
```
322
+
323
+
Remember: a variable named `{!var}` is **different** from a variable named `{var}`.
324
+
325
+
```clike
326
+
set {!var} to 1 // global
327
+
set {var} to 2 // normal
328
+
assert {var} is not {!var}
329
+
```
330
+
331
+
Global variables make it easy to pass data between triggers and entire scripts.
332
+
333
+
```clike
334
+
function first:
335
+
trigger:
336
+
set {!var} to 10 // thread-local
337
+
set {var} to 5 // normal (local to this trigger)
338
+
run second()
339
+
340
+
function second:
341
+
trigger:
342
+
assert {var} is null
343
+
assert {!var} is 10 // value is kept from before call
344
+
```
345
+
346
+
Global variables are **atomic** and can be accessed and changed from other triggers, lambdas and different threads, unlike regular variables.
347
+
348
+
```clike
349
+
function my_function:
350
+
trigger:
351
+
set {!var} to 10 // thread-local
352
+
set {thing} to a new runnable:
353
+
assert {!var} is 10
354
+
set {!var} to 5
355
+
assert {!var} is 5
356
+
assert {!var} is 10
357
+
run {thing} in the background // value is changed by the runnable
358
+
wait 10 milliseconds // wait for other thread to finish
359
+
assert {!var} is 5
360
+
```
361
+
362
+
Global variables are accessible from **any** process.
363
+
364
+
```clike
365
+
on load:
366
+
trigger:
367
+
assert {!var} is null // not set yet
368
+
set {!var} to 10 // global
369
+
assert {!var} is 10
370
+
371
+
on load: // different event trigger, so run on different thread
372
+
trigger:
373
+
wait 10 milliseconds // wait for previous trigger to finish
0 commit comments