Falcon plugins

Pick a runtime

Native C++ Available

Header-only C++ classes over a stable C ABI. Build with any compiler and the plugin loads on every server with the same API major version.

One .dll, .so or .dylib per plugin
Survives server updates without a rebuild
"runtime": "native"

Internal C++ Available

Full access to the server's own classes: subclass blocks, items, mobs, AI goals and commands, and override vanilla ones.

Built against one release with its SDK archive
Rebuilt for every server update
"runtime": "internal"

C# Available

.NET class libraries loaded in-process, with the same events, commands and content as C++.

Needs the .NET runtime
"runtime": "dotnet"

Java Available

Jar files running in one embedded JVM, calling the server through the foreign function API.

Needs Java 22 or newer
"runtime": "java"

What a plugin can do

Events

Listen with priorities from lowest to monitor, cancel, and change what happens next.

Players: join, quit, chat, move, death, respawn, commands, game mode, dimension, drop and pickup
Blocks: break, place, interact, fire spread, burn
Entities: damage, death, interact, projectile hit, explosion with editable blocks
Inventories: open, close, every click, crafting
Server: tick, console commands, raw packets in and out

Commands

Register commands with a description, usage and permission. They show up in the player's command list.

Custom content

New items, blocks and entities with their own behaviour, sent to players automatically.

World

Read and set blocks, spawn entities, drop items, change time and weather, strike lightning and create explosions.

Players and items

Inventories, armor, offhand, health, food, experience, titles, game modes, lore and enchantments.

Scheduler

Delayed and repeating tasks on the main thread, and async work that reports back safely.

Permissions and config

Permission nodes with defaults, per-player grants, and a config.yml per plugin.

Raw packets

Send any packet to a player, and read, rewrite or drop every packet going in and out.

Your first plugin

Pick a language and follow the three steps.

1. Add the SDK

The SDK is a CMake project. falcon_add_plugin builds the shared library with the right settings for your platform.

include(FetchContent)

FetchContent_Declare(
    falcon_plugin_api
    GIT_REPOSITORY https://github.com/Falcon-MC/PluginAPI.git
    GIT_TAG main
)
FetchContent_MakeAvailable(falcon_plugin_api)

falcon_add_plugin(MyPlugin MyPlugin.cpp)

2. Write the plugin

Subclass falcon::Plugin, subscribe to events and register commands in onEnable. A plugin can be split into as many classes and folders as you like.

#include <falcon/Falcon.hpp>

class MyPlugin : public falcon::Plugin {
public:
    bool onEnable() override {
        events().on<falcon::PlayerJoinEvent>(
            [](falcon::PlayerJoinEvent &event) {
                event.player().sendMessage("Welcome!");
            });
        return true;
    }
};

FALCON_PLUGIN(MyPlugin)

3. Install it

Put the library next to a plugin.json in plugins/MyPlugin/ and start the server. Dependencies between plugins are declared here and load in the right order.

{
  "name": "MyPlugin",
  "version": "1.0.0",
  "api-version": "1.2",
  "main": "MyPlugin",
  "depend": [],
  "softdepend": []
}

Talk to other plugins

Services

A plugin provides a named service and any other plugin calls it, whatever language either of them is written in. Requests and responses are text, usually JSON.

Custom events

Fire your own events and let other plugins listen, cancel them or change their data, with the same priorities as the server's events.

services().provide("economy:balance", [](const std::string &request) {
    return std::string("{\"balance\":250}");
});

auto balance = services().call("economy:balance", "{\"player\":\"Steve\"}");

services().on("quests:completed", [](falcon::CustomEvent &event) {
    event.setData(event.data() + " rewarded");
});

services().fire("quests:completed", "{\"quest\":\"miner\"}", true);

Internal plugins

Every release ships a FalconSDK-<platform>.tar.gz with the server's headers. Extract it next to your project and build against it with the compiler named in its README.txt.

cmake -B build -DFALCON_SDK_DIR=/path/to/FalconSDK-linux
cmake --build build

Plugins for Falcon