3.1 KiB
Native Editor extensions
Editor extensions are startup-loaded .so/.dll modules. They are trusted native
code inside the Editor process. Gameplay remains statically linked into the separate
Player; an Editor extension is never required by the exported game.
The initial SDK registers commands and small action panels. Inspector fields for runtime components come from the separate gameplay SchemaExporter. Rich custom widgets and a general marketplace/package manager are later work.
Example: Beacon
examples/extensions/beacon contains:
Beacon.hpp: a runtime component schema and rotating-object behavior.Editor.cpp: an Editor command and a panel that creates a Beacon in one transaction.
Include Beacon.hpp from your project's Scripts/Gameplay.cpp. Call
beacon::register_behavior(runtime) from registerGameplay, and append
beacon::schema() to the array returned by schema(). Build gameplay so the Editor
can load the new metadata. Read the first behavior tutorial
for the complete gameplay registration convention.
The normal engine build produces example-plugin/ inside its build directory.
Copy its beacon.faset-plugin.json and native library into your project's
Plugins/ directory, then restart the Editor. The Beacon tools panel offers
Add Beacon. Its command is also discoverable through MCP as
plugin_example_beacon_create and requires a document ID.
Disabling the Editor extension removes its panel and command after restart. It does not erase its saved component data. Removing the runtime registration leaves an unknown component preserved by authoring; exporting that scene fails until the runtime dependency is restored or the component is deliberately removed.
Compatibility and ownership
A manifest includes module ID/version, kind: editor, API version, native library,
build fingerprint and dependencies with exact versions. The loader validates the
complete graph for missing dependencies and cycles before calling entry points.
A failed dependency prevents loading its dependents.
The fingerprint includes the SDK sources, dependency lock, platform, architecture, compiler version, configuration and CRT settings. Rebuild a plugin for the exact Editor SDK. Compatibility across arbitrary C++ builds is not promised. Reloading an updated native module requires restarting the Editor.
include/faset/editor/plugin_api.h defines a small C interface. Borrowed UTF-8 JSON
strings are valid during a call; responses are copied through a receiving callback.
Each side frees its own allocations. Register only during startup and invoke the SDK
on the Editor thread. Commands must use their owning module's name prefix. Panels
can invoke owned commands; a $document argument resolves to the active authoring
document. No EnTT registry, live runtime world, or arbitrary C++ object pointer is
exposed as a scripting API.
The native plugin test loads the actual example module, creates a component, checks Undo, runs its separate runtime behavior, unloads command registrations, opens the saved scene without the package, and rejects incompatible/cyclic/missing plugin dependencies.