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.FlintErrorwith 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 addonslists every addon and what it registered./flint export <addon>writesplugins/Flint/flint-syntax-<addon>.jsonwith 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.syntaxFilesetting.
Names must be new: an addon cannot replace a built-in module, type, event or argument type.