Get RAPTOR

Block extension points

Change how a Block is built, add rows to its Inspector section and store settings on it.

A Block in Mesh mode is a RaptorMesh. The faces, edges and vertices you select and move form its cage. When a model is built, each Block's cage becomes its render mesh and collider.

The five extension points below let a module change the build without changing the cage. The examples use a fictional "Rounded corners" module with the id studio.rounded-corners.

PointWhat it doesTypes
E1 BuildBuilds a render-only copy of the Block, such as one with bevelled edgesIRaptorBlockModifier, RaptorBlockModifiers, RaptorBlockDisplay
E2 InspectorAdds rows inside the Block's section of the InspectorRaptorSuiteInspectorBlock, RaptorPropertiesUI, RaptorStepRule
E3 EditsChanges Blocks as one undo step, then rebuilds themRaptorBlockEdits
E4 QueriesReads a Block's faces and edges, and the current selectionRaptorMeshQueries, RaptorHotspotLocks, RaptorSpecialMaterials
E5 DataStores your settings on each Block, saved with the sceneRaptorBlockModifierData, RaptorMesh

E1 to E4 are in Raptor.Editor. E5 is in Raptor.Components. For a module that uses all five, see Worked example: a bevel module.

E1 Build: a Block modifier

Implement IRaptorBlockModifier in a class with a public parameterless constructor. RAPTOR finds it without a registration call. The class can be internal.

MemberWhat it is
string IdA permanent id, such as studio.rounded-corners. One modifier per id.
int OrderPosition among modifiers. Lower runs first.
int DisplayPriorityWhen several modifiers want to build a Block's copy, the highest priority builds it.
bool DisplayActive(RaptorMesh km)true when this modifier wants to build this Block's copy.
RaptorBlockDisplay Display(RaptorMesh km, PolygonMesh cage, int version)Returns the render-only copy, or null to render the cage. The cage is always the collider.
void MixBakeHash(RaptorMesh km, Action<long> mix)Adds your settings to the saved build hash, which decides when the Block needs a rebuild.
void MixSessionHash(RaptorMesh km, Action<ulong> mix)Adds your settings to the editor's session rebuild check. Not saved.
string InspectorLine(IReadOnlyList<RaptorMesh> meshes)A line for Unity's Inspector, or null.

Mix nothing for a Block you leave unchanged

The hash decides which Blocks rebuild. Mixing words for a Block you do not change makes it rebuild and re-bake. Return early when your setting is off. Mix a hash of your Id first. Numbers below 2000 are reserved for RAPTOR.

  • A modifier that throws is reported once for that Block, and the Block builds from its cage.
  • RaptorBlockModifiers.Register and Unregister exist for tests and tools. Modules do not need them.

E2 Inspector: rows in the Block's section

Register a RaptorSuiteInspectorBlock with Section = typeof(RaptorMesh). Its rows draw inside the Block's section, after RAPTOR's rows.

[InitializeOnLoad]
static class RoundedCornersSection
{
    static RoundedCornersSection()
    {
        RaptorSuiteInspectorBlocks.Register(new RaptorSuiteInspectorBlock
        {
            Id = "studio.rounded-corners.properties",
            Section = typeof(RaptorMesh),
            Order = 100,
            DrawSection = Draw,
        });
    }

    static void Draw(Component[] targets, RaptorPropertiesUI ui)
    {
        if (!ui.Header("roundedcorners", "Rounded corners", "op-bevel")) return;
        // ui.LabelledRow, ui.DragFloat, ui.Switch ... then ui.Commit(() => your edit)
    }
}

RaptorPropertiesUI draws rows in RAPTOR's style with Header, Row, LabelledRow, DragFloat, DragInt, Switch, SegmentCell, Subheading and ReadoutLine. Run every edit through ui.Commit, which runs it outside the drawing pass.

With Section = null, the block draws after every section, for the whole selection.

E3 Edits: one undo step

MemberWhat it does
CanEdit(targets)true when every target is editable: outside Play mode, not generated output and not read-only.
OwningModels(components)The models the components belong to.
Transaction(touched, models, undoName, write)Records touched, runs write, rebuilds the models and marks them changed, as one undo step. If write throws, the change is undone.
ManipulationActivetrue while a handle is being dragged. Edits wait until it ends.

E4 Queries

  • RaptorMeshQueries reads a Block: the two faces of an edge (EdgeFaces), a face's material, corner normals, triangles, the mesh being edited (LiveMeshOf) and the edges selected in Edge mode (SelectedClosedEdges).
  • RaptorHotspotLocks copies each face's hotspot fit to your copy, keeping hotspot textures in place.
  • RaptorSpecialMaterials.PreferRealStrips gives new strips a real material when their neighbouring faces use a special one, such as NoDraw or Skybox.

E5 Data: your settings on each Block

Make a data class

Derive a [Serializable] class from RaptorBlockModifierData. Put it in an assembly for all platforms, so built games can load scenes that contain it.

[Serializable]
public sealed class RoundedCornersData : RaptorBlockModifierData
{
    public float radius = 0.05f;
}

Read it

km.GetModifier<RoundedCornersData>() returns null when the Block has none. Reading adds nothing to the Block.

Write it inside a transaction

km.GetOrAddModifier<RoundedCornersData>() adds the entry with its defaults on the first edit. Call it inside RaptorBlockEdits.Transaction. RemoveModifier<T>() removes it.

The class name is saved into scenes

The data is serialized by reference, so its assembly, namespace and class name are written into every scene and prefab that uses it. Do not change them. To move or rename the class, add [MovedFrom(true, ns, asm, class)] with the old names.

If your module is removed, its entries load as empty and stay in the file. Adding the module back restores them.