skLambda 1.3.0

Supports: Paper 1.21.1+ · Skript 2.15+

This release is about async. A lambda can run off the main thread, a trigger can wait for something without freezing the server, and a new watcher polls values and conditions for you so you don't have to write a loop.

New sections

• Wait for a future: wait for %future% [within %timespan%]: suspends the trigger until the future resolves, then runs the body, where result of %future% is ready to read. The server keeps ticking while it waits, it doesn't block. Use wait for all of %futures% to join several (when-all) or wait for any of %futures% for the first to finish. An optional on timeout: block runs instead if the time runs out, and locals from either branch carry on to the code after the block.
• Wait for the next event: wait for next <event> [where <condition>] [within %timespan%]: pauses a trigger until that event fires, with the event's values in scope in the body (so message works for chat). Filter with a trailing where, cap the wait with within, and handle the no-show with on timeout:. The event has already dispatched by the time the body runs, so you can't cancel or change it there.
• Watch a value: watch %value% every %timespan%: re-reads the expression on a timer and runs on change: only when it differs from last time, with old value and new value in scope. Pass within %timespan% for an on timeout:, add on end: for teardown, and tie it to an owner: so it stops itself when the owner goes away. It's a normal listener, so pause, resume, unregister and /sklambda listeners all work on it.
• Watch a condition: watch when <condition> every %timespan%: is edge-triggered. on rising: fires the moment the condition goes false to true, on falling: fires on true to false. The state at the first poll is the baseline, so a condition that's already true won't fire on rising until it goes false and back. This is "do X the first time Y becomes true" without a poll loop.

New expressions

• Future of a lambda: future of calling lambda %lambda% [with %objects%] starts the lambda on a background thread right away and hands you a future for its result. The body must be pure computation or I/O with no Bukkit API (no blocks, entities, inventories, or players), since touching the server off-thread will throw. Arguments are read on the main thread before it starts.
• New future: a new future is an empty promise you resolve yourself later with complete. Good for bridging a callback or another thread back into a waiting trigger.
• Future result: result of %future% is the resolved value, or nothing for a future that isn't done yet or that failed. Read it after a wait for, when the future is guaranteed resolved.
• Old and new value: old value and new value hold the previous and current readings inside a watcher's on change: block.

New condition

• Future state: %future% is done (also resolved or completed), %future% is pending, and %future% has failed, each with a negated form. Check a future before reading its result, or branch on whether a background job blew up.

New effect

• Complete a future: complete %future% with %object% resolves one or more futures with a value and wakes any trigger waiting on them. complete %future% with no value resolves it with nothing. A future that's already resolved is left alone.