DMD Studio authoring and runtime

[freezy]

Overview

This introduces DMD Studio, an integrated workflow for authoring, previewing, simulating, and playing dot-matrix display content in VPE. It covers the complete functional path from reusable DMD project assets and visual cue authoring through deterministic runtime playback, cue scheduling, GLE control, and display output.

The goal is to let table authors build rich DMD experiences inside the Unity project, preview what will actually ship, exercise cue behavior without running a complete table, and use the same authored content from game logic at runtime.

Authoring workflow

• DMD projects define the target display, canvas dimensions, color mode, frame rate, preview tint, cue library, reusable sprites, fonts, palettes, parameters, and representative sample states.
• The DMD Studio window provides a project and asset browser, a live canvas, a cue timeline, property editing, sample-state controls, validation, and playback controls in one authoring workspace.
• Authors can assemble cues from bitmap, text, numeric, geometric, and masking layers, then position and animate those layers over time.
• The timeline supports keyframed movement, opacity, rotation, scale, palette changes, numeric progression, sprite playback, and marquee-style content.
• Project sample states let authors preview parameter-bound content such as scores, player numbers, modes, awards, and messages without starting a game.
• The cue simulator exposes scheduler state and allows cues to be played, stopped, updated, queued, preempted, and resumed while inspecting which cue is visible and why.
• Scene mirroring can send the current preview to a selected DMD display so content can be checked in table context.

Asset creation and import

• PNG images can be imported as individual sprites, sprite sheets, or numbered image sequences.
• Sprite animation supports per-frame timing as well as a project-level frame rate.
• BMFont definitions and atlas pages can be imported for bitmap text rendering, including opaque atlas images commonly exported as white-on-black pages.
• Starter bitmap fonts are included for immediate use and carry their corresponding license information.
• A pixel and glyph editor supports direct touch-up of sprite frames and bitmap-font glyphs, including undo/redo and safe texture replacement.
• Numbered image sequences use natural ordering, so names such as frame2 and frame10 appear in the expected playback order.

Runtime rendering

• Cues render as layered compositions with bitmap, text, numeric, shape, and mask content.
• Projects can target 4-shade monochrome, 16-shade monochrome, or full RGB output.
• Monochrome previews use the same quantization behavior as runtime output, so the number and placement of visible intensity bands match what is sent to the display.
• Layers support masking, tint and palette selection, multiple blend behaviors, animated transforms, opacity, and time-based effects.
• Text and number layers can resolve project parameters at playback time, format values, and update active cues without restarting them.
• Sprite animation, count-up content, and marquee motion use normalized playback timing and remain consistent with the player's supported frame-rate range.
• A missing or malformed referenced sprite, font, palette, or mask suppresses only the affected layer and produces a diagnostic; the rest of the cue remains playable.
• Newly played cues emit their first content frame immediately. One-frame cues are therefore visible, and finite cues display the intended number of frames.

Cue scheduling and transitions

• Game logic can play cues with explicit priority, interruption, queueing, replacement, and coalescing behavior.
• Non-interruptible cues can defer incoming work, while interruptible cues can be replaced or suspended according to their configured policy.
• Suspended cues can resume from the prior point, restart, or be discarded.
• Queued cues retain priority ordering and first-in/first-out behavior within the same priority.
• Active cue parameters can be updated through a playback handle, and cues can be stopped explicitly.
• Enter and exit transitions include deterministic timing and preserve the outgoing visual when a transition is interrupted.
• Finite, looping, and held cues follow consistent natural-end behavior, including the configured relationship between exit transitions and the next cue.

GLE and display integration

• Game logic can start, update, and stop authored DMD cues through the DMD Studio runtime player.
• The player targets a selected display, emits the project's chosen output format, and periodically re-announces display configuration for consumers that attach or recover after playback begins.
• Display negotiation accepts the supported monochrome formats for monochrome projects and native RGB frames for RGB projects.
• Runtime output works with scene DMD components and the native display bridge while preserving the existing display-routing model.
• The associated DMD pipeline change prevents an incompatible colorization configuration from turning authored RGB output into a blank display.

Validation and diagnostics

• Project validation reports invalid dimensions, color modes, timing, duplicate identifiers, malformed layer data, missing assets, incompatible sprite or font data, and transition errors before runtime.
• Validation distinguishes between cue-level errors and recoverable asset-reference errors so authors can continue previewing and playing the valid parts of a cue.
• Runtime diagnostics are rate-limited where appropriate to avoid flooding logs while preserving actionable information.
• Editor import and editing paths normalize asset metadata so saved assets reproduce the same timing and appearance in preview and runtime.

Performance and reliability

• The compositor reuses rendering buffers and caches formatted content used by animated cues.
• A 300-frame animated benchmark covers a five-layer composition at both supported reference resolutions and verifies zero managed allocations during steady-state playback.
• Measured reference results:
  • 128×32, five layers: 0.0707 ms per frame against a 0.25 ms target.
  • 192×64, five layers: 0.1839 ms per frame against a 1.0 ms target.
• Runtime and editor lifecycle handling covers texture replacement, undo/redo, scene reload, and domain reload behavior.

Verification

• 165 DMD Studio runtime and editor tests pass, covering asset validation, compositing, animation, transitions, scheduling, formatting, import behavior, preview parity, display negotiation, deterministic rendering, and performance.
• The companion DMD repository test suite passes 18 tests covering format bypass and recovery behavior.

Related change

The companion display-pipeline change is VisualPinball.Engine.DMD#1. It provides the safe colorization bypass and recovery behavior required by authored RGB output.

[greptile-apps]

Too many files changed for review. (174 files found, 100 file limit)

Bypass the limit by tagging @greptile-apps to review.

[freezy]

Too many files changed for review. (174 files found, 100 file limit)

Bypass the limit by tagging @greptile-apps to review.

@greptile-apps