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
| Point | What the module does with it | API |
|---|---|---|
| E1 Build | The bevel modifier | IRaptorBlockModifier |
| E2 Inspector | The Edge bevel section | RaptorSuiteInspectorBlocks.Register |
| E3 Edits | One undo step per edit | RaptorBlockEdits.Transaction |
| E4 Queries | The edges picked in Edge mode, and the two faces of each edge | RaptorMeshQueries.SelectedClosedEdges, EdgeFaces |
| E4 Queries | Hotspot fits kept on the display copy | RaptorHotspotLocks.CopyThrough |
| E4 Queries | A real material on the new strips | RaptorSpecialMaterials.PreferRealStrips |
| E5 Data | Reads a Block's settings, and adds them on the first edit | GetModifier, 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.
"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.
[Serializable]
public sealed class RaptorEdgeBevelData : RaptorBlockModifierDataReading adds nothing to the Block. The entry is added on the first edit.
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.
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.
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.
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.
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.