Handling an event
on block.break:
if block.type == "diamond_ore":
cancel
send "<red>Not here." to player
Each event gives the handler some variables (player, block, entity…) plus event, the raw server event. Only the variables a handler actually uses are read, so unused ones cost nothing. Every event and its variables are listed in the reference.
A file can have several handlers for the same event; they all run.
Cancelling
cancel stops the event (the block is not broken, the message is not sent…). It must run before any wait, because by then the server has already moved on.
on player.chat:
if message.contains("badword"):
cancel
Waiting
on player.join:
wait 2 seconds # pauses this handler only
if player.online:
player.title("<gold>Welcome!")
wait accepts any duration, including one computed at runtime: wait time.seconds(n). While a handler waits, the player may leave, so check player.online before doing something with them.
player.chat runs off the main thread on Paper. You can read the message and cancel there, but wait 1 tick before changing the world.
Timers
every 5 minutes:
broadcast "<gray>Remember to vote!"
every needs a fixed duration (at least one tick). Timers start when the script loads and stop when it is reloaded.
Load and unload
on load:
print("ready")
on unload:
print("saving...")
Any other event
Flint has names for the common events. For anything else, use the Java class name of the event (Paper only):
on event "PlayerBedLeaveEvent":
send "Good morning! Your bed is at {event.bed.x}, {event.bed.z}" to player
player, entity, block and world are filled in when the event has them. Everything else is read from event in snake_case: event.bed calls getBed(), event.set_cancelled(true) calls setCancelled(true). For events of other plugins, give the full class name, for example on event "com.example.SomeEvent":. See Java access.
Folia
On Folia every region of the world has its own thread. Flint handles this for you: after a wait, a handler continues on the thread that owns its player, entity or block. every blocks and on load run on the global region; to act on a player from there, hop to the player’s thread with run:
import players
fn heal(p):
p.heal()
every 1 minute:
for p in players.all():
p.run(heal, p)