Get RAPTOR

Worked example: a bevel module

A module that uses all five Block extension points, explained step by step.

This module chamfers Block edges. Its settings are in an Edge bevel section in the Inspector, and it is off by default. The bevel renders from a display copy, and the sharp cage remains the collider.

Its code is in the RaptorEdgeFinish folder. It changes how Blocks are built, and RAPTOR's core does not reference it.

The bevel module ships separately

It will be released as an add-on. The code below is taken from its source.

Where each point is used

PointWhat the module does with itAPI
E1 BuildThe bevel modifierIRaptorBlockModifier
E2 InspectorThe Edge bevel sectionRaptorSuiteInspectorBlocks.Register
E3 EditsOne undo step per editRaptorBlockEdits.Transaction
E4 QueriesThe edges picked in Edge mode, and the two faces of each edgeRaptorMeshQueries.SelectedClosedEdges, EdgeFaces
E4 QueriesHotspot fits kept on the display copyRaptorHotspotLocks.CopyThrough
E4 QueriesA real material on the new stripsRaptorSpecialMaterials.PreferRealStrips
E5 DataReads a Block's settings, and adds them on the first editGetModifier, GetOrAddModifier

Two assemblies

The settings are saved in scenes, so they are in a runtime assembly. The modifiers and Inspector rows are in an Editor-only assembly that references it. Use your own root namespace. This one matches RAPTOR's because the module is first-party.

RaptorEdgeFinish/Editor/Raptor.EdgeFinish.Editor.asmdef
"name": "Raptor.EdgeFinish.Editor",
"rootNamespace": "Raptor.EditorTools",
"references": [
    "GUID:be077b987e64af8408d00913e39c042c",
    "GUID:38389940f44407c4c9afe23c03d52cef",
    "GUID:397ea669cfa6fc641bea09678decab17",
    "GUID:c7d7ffa20ed949ac8675f1aac4a14108"
],
"includePlatforms": [
    "Editor"
],

Per-Block data

The settings class derives from RaptorBlockModifierData. Its assembly, namespace and class name become saved keys.

RaptorEdgeFinish/Runtime/RaptorEdgeBevelData.cs
[Serializable]
public sealed class RaptorEdgeBevelData : RaptorBlockModifierData

Reading adds nothing to the Block. The entry is added on the first edit.

RaptorEdgeFinish/Runtime/RaptorEdgeFinish.cs
public static RaptorEdgeBevelData Bevel(RaptorMesh km)
{
    if (ReferenceEquals(km, null)) return null;
    return km.GetModifier<RaptorEdgeBevelData>() ?? BevelDefaults;
}

public static RaptorEdgeBevelData EditBevel(RaptorMesh km)
{
    if (ReferenceEquals(km, null)) throw new ArgumentNullException(nameof(km));
    return km.GetOrAddModifier<RaptorEdgeBevelData>();
}

The build

The modifier implements IRaptorBlockModifier and needs no registration call. Display returns the render-only copy.

RaptorEdgeFinish/Editor/RaptorEdgeFinishModifiers.cs
internal sealed class RaptorEdgeBevelModifier : IRaptorBlockModifier
{
    public string Id => RaptorEdgeFinishHash.BevelId;
    public int Order => RaptorEdgeFinishHash.BevelOrder;
    public int DisplayPriority => 100;

    public bool DisplayActive(RaptorMesh km) => RaptorMeshEdgeBevel.Active(km);

    public RaptorBlockDisplay Display(RaptorMesh km, PolygonMesh cage, int version) =>
        RaptorEdgeFinishDisplays.Of(RaptorMeshEdgeBevel.Display(km, cage, version));

    public void MixBakeHash(RaptorMesh km, Action<long> mix)
    {
        if (!RaptorEdgeFinish.Bevel(km).EdgeBevel) return; // mixed ONLY while on, so every other Block's persisted hash is unchanged
        mix(RaptorEdgeFinishHash.MeshEdgeBevel);
        foreach (long w in RaptorMeshEdgeBevel.HashWords(km)) mix(w);
    }

    public void MixSessionHash(RaptorMesh km, Action<ulong> mix)
    {
        if (!RaptorEdgeFinish.Bevel(km).EdgeBevel) return; // mixed ONLY while on; an undo / redo of a setting rebuilds the model
        mix(RaptorEdgeFinishHash.SessionEdgeBevel);
        foreach (long w in RaptorMeshEdgeBevel.HashWords(km)) mix(unchecked((ulong)w));
    }

    public string InspectorLine(IReadOnlyList<RaptorMesh> meshes) => RaptorMeshEdgeBevel.SettingsText(meshes);
}

Do not copy the hash marker

MeshEdgeBevel is 1010, and numbers below 2000 are reserved for RAPTOR. Mix a hash of your modifier's Id first instead. Keep the early return, so unchanged Blocks keep their hash and are not rebuilt.

Inspector rows

With Section = typeof(RaptorMesh), the rows draw inside the Block's section, after RAPTOR's rows.

RaptorEdgeFinish/Editor/RaptorEdgeFinishSections.cs
static RaptorEdgeFinishSections()
{
    RaptorSuiteInspectorBlocks.Register(new RaptorSuiteInspectorBlock
    { Id = BevelBlockId, Section = typeof(RaptorMesh), Order = RaptorEdgeFinishHash.BevelOrder, DrawSection = DrawEdgeBevel });
}

The rows use RaptorPropertiesUI. Commit runs the edit outside the drawing pass.

RaptorEdgeFinish/Editor/RaptorEdgeFinishSections.cs
static void DrawEdgeBevel(Component[] components, RaptorPropertiesUI ui)
{
    RaptorMesh[] meshes = components?.OfType<RaptorMesh>().Where(m => m != null).ToArray();
    if (meshes == null || meshes.Length == 0) return;
    if (!ui.Header("edgebevel", "Edge bevel", "op-bevel")) return;
    RaptorMesh first = meshes[0];

    bool mixedOn = meshes.Any(m => RaptorEdgeFinish.Bevel(m).EdgeBevel != RaptorEdgeFinish.Bevel(first).EdgeBevel);
    bool on = RaptorEdgeFinish.Bevel(first).EdgeBevel && !mixedOn;
    Rect onField = ui.LabelledRow("Bevel", "op-bevel");
    bool next = ui.Switch(onField, on, 34, 20, mixedOn);
    if (next != on || (mixedOn && next))
    {
        bool chosen = next;
        ui.Commit(() => RaptorEdgeFinishEdits.SetEdgeBevel(meshes, chosen, null, null, null, null, chosen ? "Edge Bevel On" : "Edge Bevel Off"));
    }
    // ... the width, segments and angle rows
}

Edits

Transaction records the Blocks, runs the write and rebuilds their models as one undo step.

RaptorEdgeFinish/Editor/RaptorEdgeFinishEdits.cs
var models = RaptorBlockEdits.OwningModels(changed);
return RaptorBlockEdits.Transaction(changed.Cast<Object>().ToArray(), models, undoName, () =>
{
    foreach (RaptorMesh km in changed)
        RaptorEdgeFinish.EditBevel(km).SetEdgeBevel(
            on ?? RaptorEdgeFinish.Bevel(km).EdgeBevel,
            width ?? RaptorEdgeFinish.Bevel(km).EdgeBevelWidth,
            segments ?? RaptorEdgeFinish.Bevel(km).EdgeBevelSegments,
            angle ?? RaptorEdgeFinish.Bevel(km).EdgeBevelAngle,
            inside ?? RaptorEdgeFinish.Bevel(km).EdgeBevelInside);
});

What it leaves out

The module has no settings section, data folder or credit. For those, see the Module template.

Its geometry code also calls a few members that are not in this reference. Do not use them in your module, as they can change without notice.

Removing it

After the folder is deleted:

  • Blocks build from their sharp cage. Bevelled rooms show Not built and need one rebuild, because their hash no longer includes the bevel.
  • Saved entries load as empty and stay in the file. Adding the folder back restores the bevel. Back up those scenes before saving them without the module.
  • Unity logs a missing-type warning for each Block with an entry.