Skip to content
Flint
Dokumentation
Going further

Writing addons

Adding modules, types, events and argument types to Flint from a Java plugin.

An addon is an ordinary Paper or Velocity plugin that registers new things with Flint when it is enabled. Scripts then use them like built-ins. A complete example that adds a warps module is in examples/addon of the Flint sources.

Set up

Add the Flint API to your build (provided: the Flint plugin supplies it on the server, so do not shade it):

<dependency>
    <groupId>dev.flint</groupId>
    <artifactId>flint-core</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
</dependency>

Make Flint a dependency so it is enabled first: depend: [Flint] in plugin.yml on Paper, or @Plugin(dependencies = @Dependency(id = "flint")) on Velocity.

import dev.flint.api.Addon;
import dev.flint.api.FlintApi;

public final class MyAddon extends JavaPlugin {
    private Addon addon;

    @Override
    public void onEnable() {
        addon = FlintApi.get().addon(getName());
        // register modules, types, events and argument types here
    }

    @Override
    public void onDisable() {
        addon.unregister();      // removes everything this addon added
    }
}

Flint loads scripts after every plugin is enabled, so your registrations are there in time. If an addon registers later, Flint reloads its scripts by itself.

Modules

addon.module("greetings", "Friendly messages.", m -> m
        .fn("hello", "(name, [times])", "Greets a name.", (fiber, args) -> {
            int times = args.length > 1 ? ((Double) args[1]).intValue() : 1;
            return ("Hello, " + args[0] + "! ").repeat(times).trim();
        })
        .constant("DEFAULT", "Hello!", "The plain greeting."));
import greetings
print(greetings.hello("Kim", 2))

The signature string is shown in the editor and checked on every call: (a, b) takes exactly two arguments, (a, [b]) one or two, (a, ...rest) one or more.

In a script In Java
number Double
text String
true / false Boolean
none null
list List<Object>
map Map<String, Object>
duration java.time.Duration
player, block… the server’s own object
  • Return any of these. Other numbers, enums, UUIDs and collections are converted for you.
  • Throw dev.flint.vm.FlintError with a message for the script author; scripts can catch it.
  • For slow work (web, disk, databases), return fiber.await(() -> result): the script pauses, the task runs off the server thread, and the script continues with the result.
  • m.onReset(...) runs on every reload: remove what scripts created through your module.

Types

addon.type("warp", Warp.class, "A named teleport destination.", t -> t
        .prop("name", "text", "Name of the warp.", w -> w.name)
        .prop("uses", "number", "Times used.", w -> w.uses, (w, v) -> w.uses = ((Double) v).intValue())
        .method("distance", "(player)", "Blocks to the warp.", (w, fiber, args) -> ...));

Events

AddonEvent use = addon.event("warp.use", "A player is about to use a warp.", true, "player:player", "warp:warp");

if (use.fire(player, player, warp)) return;     // true: a script cancelled it
on warp.use:
    if warp.name == "vip" and not player.has_permission("warps.vip"):
        cancel

The first argument of fire is what the event is about (a player, entity or location); after a wait, the handler continues on that object’s thread (important on Folia). use.inUse() is false while no script listens.

Command argument types

addon.argType("warp", new ArgType() {
    public Object parse(Object sender, String raw) {
        Warp w = warps.get(raw);
        if (w == null) throw new FlintError("There is no warp called '" + raw + "'");
        return w;
    }
    public List<String> complete(Object sender, String prefix) {
        return new ArrayList<>(warps.keySet());
    }
});

Checking and publishing

  • /flint addons lists every addon and what it registered.
  • /flint export <addon> writes plugins/Flint/flint-syntax-<addon>.json with only your addon’s modules, types and events.
  • Upload your jar and that JSON on the addons page (you need an invitation for now). The site shows your addon’s reference in the same style as Flint’s own, and the VS Code extension can use the file through the flint.syntaxFile setting.

Names must be new: an addon cannot replace a built-in module, type, event or argument type.