59 lines
3.1 KiB
Markdown
59 lines
3.1 KiB
Markdown
# 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](../scripting/first-behavior.md)
|
|
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.
|