Get RAPTOR

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

WhereWhatAPI
ToolbarA tool button, with options in the context barRaptorSuiteExternalTools
InspectorRows for the selection or inside a component's sectionRaptorSuiteInspectorBlocks
ViewsDrawing in the 3D view and a row in a view's menuRaptorSuiteViewportOverlays
PanelsA panel, as a side tab or in the DockRaptorSuiteRegistry
Project SettingsA section under Edit → Project Settings → RAPTORRaptorProjectSettings
SettingsA row on Settings → Modules, and rows on Settings → CreditsRaptorModules, RaptorCredits
BlocksA step in building a BlockBlock 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).

MyModule.Editor.asmdef
{
    "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.

MyTool.cs
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

RuleWhy
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 seeWhere
A puzzle button named TemplateToolbar
A Size field while the tool is onContext bar
The selection's name and a Write note buttonInspector
A Module template sectionEdit → Project Settings → RAPTOR
A Module template rowSettings → Credits
Selection.txt, after Write noteAssets/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

  1. Rename the asmdef, its name and rootNamespace, and the namespace in both scripts.
  2. Change the ids at the top of ModuleTemplateTool. Ids must be unique across modules. The module id also names your data folder.
  3. Replace the credit with one row per third-party part you ship.
  4. Replace the Size field and Write note button with your tool. Choose an IconGlyph from Editor/Suite/Icons/Raptor/icons.json in the RAPTOR folder.
  5. Update or delete ModuleTemplateSmoke.cs.

The template registers everything in one static constructor:

Samples/ModuleTemplate/ModuleTemplateTool.cs
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:

Samples/ModuleTemplate/ModuleTemplateTool.cs
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

Copy the project

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.