Canonicalizing Procedural Patterns in DungeonOPC

DungeonOPC already has the beginnings of a real pattern platform. It has a shared control surface, a show-state pipeline, procedural patterns that own their generated geometry, direct scene bindings under PatternOrchestrator, and focused EditMode tests. The next step is not simply adding more visuals. It is making the path from idea to production pattern explicit enough that every new visual behaves like a reliable part of the system.

That is what a pattern-authoring playbook should do: turn a collection of good conventions into one canonical contract.

The foundation is already there

Today, patterns such as Pixel Rain, Bass Bloom, Impact Rings, Heat Map, and Prism Scatter implement the same two key ideas. IPatternTarget provides the common operator controls—activation, trigger, intensity, palette, speed, blend, and audio reactivity—while IShowStatePatternTarget gives active patterns the merged realtime show state.

The scene already keeps direct roots beneath PatternOrchestrator, and selection metadata already captures useful ideas such as weight, intensity and BPM ranges, tags, coverage, and whether a pattern is suitable as a primary or accent. The audio documentation also establishes a valuable shared language: low energy should usually affect scale and impact; mids should move things; highs should add shimmer and detail; Tap should be a discrete event.

Those are the right primitives. What is missing is one place that says what “done” means for a new pattern.

Begin with a signal map, not geometry

The most useful rule in the proposed playbook is also the simplest: assign a visual job to every signal before building anything. Full-spectrum energy can govern confidence or density. Low energy can widen a ribbon, increase a bloom, or move a field. Mid energy can control flow, curvature, or phase. High energy can reveal sparks, edge detail, or fine structure. Tap should cause something that travels or decays visibly, while BPM supplies stable cyclic motion.

The point is not to use every input. The point is to avoid making every property pulse together. A pattern becomes musically legible when its inputs describe distinct visual dimensions. Someone should be able to look at it and feel the bass broaden the room, the mids steer the motion, and the highs sharpen the texture.

That also means designing silence on purpose. Audio streams vanish during transitions, device changes, sidecar restarts, and quiet passages. A pattern that becomes accidental darkness at zero input is not merely less interesting; it is operationally fragile. The quiet state should still look intentional.

Treat the runtime as a contract

A procedural pattern should live under the shared runtime pattern folder, implement the common interfaces, clamp its public controls at the boundary, and accept show state only while it is active. This keeps manual controls and API commands as a stable baseline while realtime audio modulates around them.

The existing helper approach is worth extending into a consistent toolkit. Shared handling for global brightness and palette overrides should remain mandatory. Per-band envelope followers should become the normal response layer, so bass-scale motion can decay slowly while high-frequency detail stays quick and crisp. Tap should remain an event with an explicit visual decay rather than being smoothed away into a vague flicker.

Generated geometry deserves the same discipline. The existing patterns already create their own emissive materials and clean up generated objects in Edit Mode and Play Mode. The canonical version should make that lifecycle non-negotiable: parent generated objects to the root, use local coordinates, remove colliders that offer no value, rebuild deterministically, and expose small diagnostics that tests can assert without scraping renderer internals.

Make the sample plane and catalog first-class

DungeonOPC’s procedural patterns already work around the OPC sample plane near local Y -4.75. That should be stated as a layout rule. Broad layers belong just beneath it, principal forms on it, and highlights slightly above it. This is a small convention with a large payoff: it prevents z-fighting and keeps the Unity scene aligned with what the low-resolution OPC output can actually show.

Likewise, pattern metadata should have one authoritative home. The current selection metadata is useful, but a PatternCatalog asset would give authoring, scene registration, and API consumers a single source of truth. A catalog entry can hold the display description, eligibility, ranges, tags, coverage, default controls, palette, accent policy, and guidance-plane position. The scene binding then only needs to connect its matching kebab-case ID to a root.

That separation matters. A pattern’s geometry is not its identity, and the scene should not be the only place where a consumer can discover what a pattern is for.

Tests should prove the visual promise

Existing EditMode pattern tests point in the right direction. Pixel Rain, for example, checks activation, clamping, trigger bursts, sample-plane placement, motion, and generated-material cleanup. The playbook generalizes that standard: every pattern should test its distinct behavior, its quiet state, independent band responses, global overrides, lifecycle cleanup, and any context input it uses.

The test suite should not just prove that a script compiles. It should prove that a pattern remains visually intelligible under the control system it will encounter in a live show.

An executable reference, not a style mandate

The planned Spectral Loom pattern is a good candidate for executable documentation. Its role would be to demonstrate the full contract in one readable implementation: full energy for field confidence, bass for wide slow ribbons, mids for weave motion, highs for sparks, BPM for a base clock, onset for a traveling pluck, context for pace and complexity, and a dim living state in silence.

It should be copied and simplified, not treated as the only correct aesthetic. The playbook is about interoperable behavior, not visual uniformity.

A new DungeonOPC pattern should be considered complete when it renders cleanly on the sample plane, responds honestly to its signals and shared controls, is registered in the scene and catalog, cleans up after itself, and is defended by focused tests. Once that becomes routine, adding a pattern stops being a fragile scene edit and becomes a dependable product operation.