Skip to content
Flint
Documentation
Writing scripts

Events

Reacting to what happens on the server, cancelling events, waiting and timers.

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)