Writing a module
Add tools, Inspector rows or build steps to RAPTOR from a separate assembly.
A module is your own assembly that references RAPTOR. RAPTOR does not reference it, so deleting the module leaves the project working.
Logic is a module that ships inside the package.
What a module can add
| Where | What | API |
|---|---|---|
| Toolbar | A tool button, with options in the context bar | RaptorSuiteExternalTools |
| Inspector | Rows for the selection or inside a component's section | RaptorSuiteInspectorBlocks |
| Views | Drawing in the 3D view and a row in a view's menu | RaptorSuiteViewportOverlays |
| Panels | A panel, as a side tab or in the Dock | RaptorSuiteRegistry |
| Project Settings | A section under Edit → Project Settings → RAPTOR | RaptorProjectSettings |
| Settings | A row on Settings → Modules, and rows on Settings → Credits | RaptorModules, RaptorCredits |
| Blocks | A step in building a Block | Block extension points |
The full list is in Extension points.
Set up the assembly
Make a folder for the module
Put it anywhere under Assets except Assets/RAPTOR, which is replaced when you update RAPTOR.
Add an Editor-only assembly definition
In the folder, choose Create → Scripting → Assembly Definition. Under Platforms, tick only Editor.
Reference RAPTOR by GUID
Add Raptor.Editor to its references with Use GUIDs enabled. Add other assemblies as needed (see Assemblies).
{
"name": "MyModule.Editor",
"rootNamespace": "MyModule",
"references": [
"GUID:be077b987e64af8408d00913e39c042c"
],
"includePlatforms": [
"Editor"
]
}Add a runtime assembly for saved data
If the module saves data in scenes or prefabs, put those types in a second assembly with all platforms ticked, so they load in a built game. Reference it from the editor assembly.
Compiled builds
In compiled builds of RAPTOR, Raptor.Editor and Raptor.MeshCore are DLLs without assembly definitions. Their GUID references resolve to nothing, but Unity references the DLLs automatically, so your code still compiles. If your assembly definition uses Override References, add the package's four .dll files under Assembly References.
Register your parts
Put all registrations in the static constructor of an [InitializeOnLoad] class, and call registries on the main thread. Unity runs the constructor when the editor loads and after every script reload.
using Raptor.EditorTools;
using UnityEditor;
[InitializeOnLoad]
static class MyTool
{
const string ModuleId = "studio.my-tool";
static MyTool()
{
RaptorSuiteExternalTools.Register(new RaptorSuiteExternalTool
{
Id = ModuleId,
Name = "My tool",
IconGlyph = "lg-module",
RailOrder = 600, // after RAPTOR's own tools
IsActive = () => active,
Activate = () => active = true,
Deactivate = () => active = false,
});
RaptorModules.Register(ModuleId, "My tool", RaptorModuleKind.Module);
}
static bool active;
}Registering the same id again adds nothing, so script reloads are safe. A registered callback that throws is logged once and left out.
Rules
| Rule | Why |
|---|---|
| Read registries when drawing or acting, not in your static constructor. | Modules load in any order, so another module may not be registered yet. |
| Write nothing while loading. Create folders and files on the first action that needs them. | Opening a project should not change it. |
Keep your data under RaptorPaths.Data(module, path) and create the folder with RaptorPaths.EnsureDataFolder. Do not write under Packages/. | The data goes to Assets/RAPTOR Data/<module>, which survives RAPTOR updates. |
Find your shipped files with RaptorPaths.RegisterModuleRoot and RaptorPaths.Install. | Users can then move your folder anywhere. |
Store per-user choices in RaptorPrefs, named RAPTOR.<Module>.<name>. | They are stored for the current user on the local machine. |
Store shared choices in RaptorProjectSettings, prefixing each key with your module's name. | They apply to everyone who opens the project. |
Make project-wide changes (defines, tags, layers, Graphics, Quality, Player) only through RaptorProjectChanges. | The user approves each change on Settings → Modules before it runs. |
Register every third-party part you ship with RaptorCredits. | Each one is listed on Settings → Credits. |
| Show a state as an icon and a short word, not by colour alone. Keep instructions out of bars and rows. | This matches the rest of RAPTOR. |
| Treat ids, keys and the names of saved data types as permanent. | They are written into users' projects. See the Persistence contract. |
When Play does not reload scripts
With domain reload turned off for Play mode, static fields keep their values between Play sessions. Registrations persist and need no change. Reset runtime values in a method marked [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)] on the same class.
Start from the template
The Module template sample is a minimal working module that uses only supported API.
Turn it on
The sample in Assets/RAPTOR/Samples/ModuleTemplate compiles only when RAPTOR_MODULE_TEMPLATE is defined. Add the symbol under Edit → Project Settings → Player → Scripting Define Symbols.
Or copy the folder out of Assets/RAPTOR, then remove the symbol from the asmdef's Define Constraints.
See what it adds
| You see | Where |
|---|---|
| A puzzle button named Template | Toolbar |
| A Size field while the tool is on | Context bar |
| The selection's name and a Write note button | Inspector |
| A Module template section | Edit → Project Settings → RAPTOR |
| A Module template row | Settings → Credits |
Selection.txt, after Write note | Assets/RAPTOR Data/ModuleTemplate/Notes |
Check it
ModuleTemplateSmoke.Run() returns an empty string if every registration is in place, or else the first problem it finds.
Make it yours
- Rename the asmdef, its
nameandrootNamespace, and the namespace in both scripts. - Change the ids at the top of
ModuleTemplateTool. Ids must be unique across modules. The module id also names your data folder. - Replace the credit with one row per third-party part you ship.
- Replace the Size field and Write note button with your tool. Choose an
IconGlyphfromEditor/Suite/Icons/Raptor/icons.jsonin the RAPTOR folder. - Update or delete
ModuleTemplateSmoke.cs.
The template registers everything in one static constructor:
static ModuleTemplateTool()
{
RaptorPaths.RegisterModuleRoot(ModuleId, FindRoot);
RaptorSuiteExternalTools.Register(new RaptorSuiteExternalTool
{
Id = ToolId,
Name = "Template",
IconGlyph = RailIcon,
RailOrder = RailPosition,
IsActive = () => Active,
Activate = () => Active = true,
Deactivate = () => Active = false,
KeepsSuiteView = () => true, // the Suite keeps picking under this tool, so a click still selects
DrawOptions = DrawOptions,
OwnsSelection = targets => Active && targets.Length > 0,
DrawProperties = DrawProperties,
});
RaptorProjectSettings.RegisterSection(new RaptorSettingsSection(SectionId, "Module template", DrawSettings,
order: 900, keywords: new[] { "Module template", "Size" }));
RaptorCredits.Register(new RaptorCredit(CreditId, "Module template", "Example component", "LicenseRef-Example",
() => RaptorPaths.Install(ModuleId, "README.md")));
}The data folder is created the first time Write note is pressed:
static void WriteNote(GameObject[] targets)
{
var lines = new List<string> { "size " + Size };
foreach (GameObject target in targets) lines.Add(target.name);
string path = RaptorPaths.EnsureDataFolder(ModuleId, NotesFolder) + "/Selection.txt";
File.WriteAllLines(path, lines);
AssetDatabase.ImportAsset(path);
}Test that it can be removed
Open RAPTOR
The project should compile without errors and show none of the module's tools or rows. The module's saved data stays in the scenes as empty entries and loads again when you restore the folder.