diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index bc009e154..fa5aad7d3 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -1,21 +1,27 @@ name: Documentation on: [push] -jobs: - build-and-publish-docfx: - runs-on: ubuntu-latest - if: github.repository == 'freezy/VisualPinball.Engine' && github.ref == 'refs/heads/master' - name: Build and publish documentation - steps: - - uses: actions/checkout@v4 - - uses: nunit/docfx-action@v3.4.2 - name: Build Documentation - with: - args: VisualPinball.Unity/Documentation~/docfx.json - - # Publish generated site using GitHub Pages - - uses: maxheld83/ghpages@master - name: Publish Documentation on GitHub Pages +jobs: + build-and-publish-docfx: + runs-on: ubuntu-latest + if: github.repository == 'freezy/VisualPinball.Engine' && github.ref == 'refs/heads/master' + name: Build and publish documentation + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-dotnet@v4 + name: Setup .NET SDK + with: + dotnet-version: 8.0.x + + - name: Install DocFX + run: dotnet tool install --global docfx --version 2.78.5 + + - name: Build Documentation + run: docfx VisualPinball.Unity/Documentation~/docfx.json + + # Publish generated site using GitHub Pages + - uses: maxheld83/ghpages@master + name: Publish Documentation on GitHub Pages env: BUILD_DIR: VisualPinball.Unity/Documentation~/_site # docfx's default output directory is _site GH_PAT: ${{ secrets.GH_PAT }} # See https://github.com/maxheld83/ghpages diff --git a/.gitignore b/.gitignore index 9950f251b..aca8b892d 100644 --- a/.gitignore +++ b/.gitignore @@ -21,10 +21,10 @@ mono_crash.* [Dd]ebugPublic/ [Rr]elease/ [Rr]eleases/ -x64/ -x86/ -[Aa][Rr][Mm]/ -[Aa][Rr][Mm]64/ +#x64/ +#x86/ +#[Aa][Rr][Mm]/ +#[Aa][Rr][Mm]64/ bld/ [Bb]in/ [Oo]bj/ @@ -367,7 +367,11 @@ MigrationBackup/ # Vi swap files *.swp -/VisualPinball.Unity/Plugins/** +/VisualPinball.Unity/Plugins/**/*.dll +/VisualPinball.Unity/Plugins/**/*.so +/VisualPinball.Unity/Plugins/**/*.dylib +libminiz.so.2.2.0 +libvips.so.42 obj.meta VisualPinball.Unity/VisualPinball.Unity.Test/TestProject~/*.vpx diff --git a/VisualPinball.Engine/Common/Constants.cs b/VisualPinball.Engine/Common/Constants.cs index 4bb1623e1..c003e00d0 100644 --- a/VisualPinball.Engine/Common/Constants.cs +++ b/VisualPinball.Engine/Common/Constants.cs @@ -66,7 +66,7 @@ public static class PhysicsConstants public const float DefaultStepTimeS = 0.01f; // DEFAULT_STEPTIME_S - public const double PhysFactor = PhysicsStepTimeS / DefaultStepTimeS; // PHYS_FACTOR + public const float PhysFactor = (float)(PhysicsStepTimeS / DefaultStepTimeS); // PHYS_FACTOR public const float LowNormVel = 0.0001f; // C_LOWNORMVEL @@ -113,10 +113,19 @@ public static class PhysicsConstants public const float ToleranceEndPoints = 0.0f; // C_TOL_ENDPNTS public const float ToleranceRadius = 0.005f; // C_TOL_RADIUS - /// - /// Precision level and cycles for interative calculations // acceptable contact time ... near zero time - /// - public const int Internations = 20; // C_INTERATIONS + /// + /// Precision level and cycles for interative calculations // acceptable contact time ... near zero time + /// + public const int Internations = 20; // C_INTERATIONS + + /// + /// Maximum number of physics sub-steps per frame. + /// If the physics loop falls behind (e.g. due to a frame hitch), it + /// will catch up for at most this many iterations before skipping + /// physics time forward. Prevents hitch cascades. + /// 200 iterations = 200ms of physics at 1kHz step rate. + /// + public const int MaxSubSteps = 200; // PHYSICS_MAX_LOOPS } public static class InputConstants diff --git a/VisualPinball.Engine/VisualPinball.Engine.csproj b/VisualPinball.Engine/VisualPinball.Engine.csproj index 0b54e984d..9d82bc04c 100644 --- a/VisualPinball.Engine/VisualPinball.Engine.csproj +++ b/VisualPinball.Engine/VisualPinball.Engine.csproj @@ -1,5 +1,5 @@  - + netstandard2.1 true @@ -12,10 +12,11 @@ 0.1.0.0 9.0 false - https://visualpinball.org - https://user-images.githubusercontent.com/70426/101756172-0965a200-3ad6-11eb-8c71-edb751f0f5d5.png - LICENSE - + https://visualpinball.org + icon.png + LICENSE + 0.0.2 + win-x64 @@ -34,9 +35,10 @@ - - - + + + + @@ -46,12 +48,16 @@ - - - - true - - + + + + true + + + + true + + @@ -65,20 +71,28 @@ - - - - - - + + + + + + + + + + + + - - - - - - - - - + + + + + + + + + + + diff --git a/VisualPinball.Resources/VisualPinball.Resources.csproj b/VisualPinball.Resources/VisualPinball.Resources.csproj index 070c859ed..fa6dbc034 100644 --- a/VisualPinball.Resources/VisualPinball.Resources.csproj +++ b/VisualPinball.Resources/VisualPinball.Resources.csproj @@ -11,7 +11,7 @@ 9.0 false https://visualpinball.org - https://user-images.githubusercontent.com/70426/101756172-0965a200-3ad6-11eb-8c71-edb751f0f5d5.png + icon.png LICENSE @@ -35,12 +35,16 @@ - - - - true - - + + + + true + + + + true + + diff --git a/VisualPinball.Unity/Assets/Resources/Prefabs/DefaultBall.prefab b/VisualPinball.Unity/Assets/Resources/Prefabs/DefaultBall.prefab index b0f27b09b..a5cdcea82 100644 --- a/VisualPinball.Unity/Assets/Resources/Prefabs/DefaultBall.prefab +++ b/VisualPinball.Unity/Assets/Resources/Prefabs/DefaultBall.prefab @@ -11,6 +11,7 @@ GameObject: - component: {fileID: 3881672604355561253} - component: {fileID: 6075728238804368159} - component: {fileID: 5180081487853661404} + - component: {fileID: 8313200498354517976} m_Layer: 0 m_Name: DefaultBall m_TagString: Untagged @@ -25,12 +26,13 @@ Transform: m_PrefabInstance: {fileID: 0} m_PrefabAsset: {fileID: 0} m_GameObject: {fileID: 8289283333368007096} + serializedVersion: 2 m_LocalRotation: {x: 0, y: 0, z: 0, w: 1} m_LocalPosition: {x: 0, y: 0, z: 0} m_LocalScale: {x: 1, y: 1, z: 1} + m_ConstrainProportionsScale: 0 m_Children: [] m_Father: {fileID: 0} - m_RootOrder: 0 m_LocalEulerAnglesHint: {x: 0, y: 0, z: 0} --- !u!33 &6075728238804368159 MeshFilter: @@ -51,11 +53,17 @@ MeshRenderer: m_CastShadows: 1 m_ReceiveShadows: 1 m_DynamicOccludee: 1 + m_StaticShadowCaster: 0 m_MotionVectors: 1 m_LightProbeUsage: 1 m_ReflectionProbeUsage: 1 m_RayTracingMode: 2 m_RayTraceProcedural: 0 + m_RayTracingAccelStructBuildFlagsOverride: 0 + m_RayTracingAccelStructBuildFlags: 1 + m_SmallMeshCulling: 1 + m_ForceMeshLod: -1 + m_MeshLodSelectionBias: 0 m_RenderingLayerMask: 1 m_RendererPriority: 0 m_Materials: @@ -77,7 +85,27 @@ MeshRenderer: m_AutoUVMaxDistance: 0.5 m_AutoUVMaxAngle: 89 m_LightmapParameters: {fileID: 0} + m_GlobalIlluminationMeshLod: 0 m_SortingLayerID: 0 m_SortingLayer: 0 m_SortingOrder: 0 m_AdditionalVertexStreams: {fileID: 0} +--- !u!114 &8313200498354517976 +MonoBehaviour: + m_ObjectHideFlags: 0 + m_CorrespondingSourceObject: {fileID: 0} + m_PrefabInstance: {fileID: 0} + m_PrefabAsset: {fileID: 0} + m_GameObject: {fileID: 8289283333368007096} + m_Enabled: 1 + m_EditorHideFlags: 0 + m_Script: {fileID: 11500000, guid: a04fca20ce2246b9abf456441b587efd, type: 3} + m_Name: + m_EditorClassIdentifier: VisualPinball.Unity::VisualPinball.Unity.BallComponent + Radius: 25 + Mass: 1 + Velocity: + x: 0 + y: 0 + z: 0 + IsFrozen: 0 diff --git a/VisualPinball.Unity/Documentation~/developer-guide/accelerometer-input-design.md b/VisualPinball.Unity/Documentation~/developer-guide/accelerometer-input-design.md new file mode 100644 index 000000000..076659190 --- /dev/null +++ b/VisualPinball.Unity/Documentation~/developer-guide/accelerometer-input-design.md @@ -0,0 +1,344 @@ +--- +uid: developer-guide-accelerometer-input-design +title: Accelerometer Input Design +description: Proposed architecture for adding accelerometer-based nudging to VPE, including Open Pinball Device support and calibration. +--- + +# Accelerometer Input Design + +This page describes the proposed design for adding accelerometer-based nudging to VPE. It covers the intended runtime architecture, where the work should land in the codebase, how Open Pinball Device support should fit into the plan, and how calibration should work for both velocity-capable and legacy-style devices. + +## Summary + +VPE does not yet have accelerometer or analog nudge support. The recommended design is to add it in three layers: + +1. Extend `VisualPinball.Unity.NativeInput` so it can poll analog HID/gamepad/Open Pinball Device inputs instead of only button edges. +2. Add a managed sensor and calibration layer in `VisualPinball.Unity` that turns raw axis samples into calibrated cabinet motion. +3. Feed calibrated cabinet motion into the physics simulation thread and apply it as cabinet velocity deltas before the main physics step. + +The key design choice is to make velocity-based nudge the primary internal model. Devices that already report integrated cabinet velocity should map directly into that model. Older devices that only report acceleration can be supported through a compatibility adapter. + +## Why velocity should be the primary model + +The upstream VPX accelerometer tech note argues that device-integrated velocity produces more stable and more realistic nudging than raw acceleration. The problem with raw acceleration is that the simulator only sees asynchronous USB samples, so it can over-sample, under-sample, or miss peaks entirely. A device that integrates the high-rate sensor stream locally can report the current cabinet velocity directly, which removes most of that resampling error. + +For VPE, this suggests a cleaner design than a straight port of the older VPX path: + +- Keep cabinet motion in physics state as the current X/Y cabinet velocity. +- On each simulation tick, compute `deltaVelocity = currentCabinetVelocity - previousCabinetVelocity`. +- Apply the opposite of that delta to each moving ball so the playfield remains the coordinate frame. + +This matches the physical model described in the VPX technical note while fitting naturally into VPE's simulation-thread architecture. + +## Existing integration points in VPE + +The work naturally splits across the existing packages: + +- `VisualPinball.Unity.NativeInput` + Polling layer for native user input. It already runs a dedicated high-frequency polling thread, but today it only supports keyboard bindings and still leaves gamepad support as future work. +- `VisualPinball.Unity/Simulation` + Managed bridge for the native polling library. `NativeInputManager` and `SimulationThread` already carry low-latency input into the simulation thread. +- `VisualPinball.Unity/Game` + Simulation-thread physics loop. `PhysicsUpdate.Execute()` is the best place to apply cabinet motion to balls before collision simulation. +- `VisualPinball.Unity/VPT/Ball` + `BallState` already stores per-ball linear velocity, so no structural change is needed to support cabinet-velocity deltas. + +## Existing reference points in VPX + +VPX already has most of the conceptual pieces, even though VPE has not ported them yet: + +- `InputManager` owns plunger and nudge sensors and combines multiple sensor pairs. +- `PhysicsSensor` supports mapping a source axis as position, velocity, or acceleration and inserts compatibility filters as needed. +- `OpenPinDevHandler` reads Open Pinball Device reports containing both acceleration and velocity fields for nudge, as well as plunger position and speed. +- `PhysicsEngine::UpdateNudge()` applies hardware-derived nudge state into the physics step. + +VPE should reuse the ideas, but it does not need to copy VPX's exact layering. + +## Proposed architecture + +### 1. Native analog polling + +`VisualPinball.Unity.NativeInput` should be extended from button polling to analog input polling. + +The current API is shaped around discrete actions: + +- `VpeInputAction` +- `VpeInputBinding` +- `VpeInputEvent` + +That works for flipper buttons, but it is too narrow for accelerometers and plungers. VPE should add a second API for analog channels with explicit device and axis identity. + +Recommended native additions: + +- Analog binding descriptor + Defines which device and element to watch. +- Analog sample callback + Returns timestamp, device id, element id, and float value. +- Device enumeration/metadata API + Lets managed code identify whether a source is a generic HID/gamepad path or an Open Pinball Device path. +- Open Pinball Device fast path + If a device exposes the OPD report format, decode the named fields directly instead of forcing the user to guess which generic axis is `RX`, `RY`, and so on. + +The native layer should support two acquisition modes: + +- Open Pinball Device mode + Preferred when the device exposes named fields such as `vxNudge`, `vyNudge`, `axNudge`, `ayNudge`, `plungerPos`, and `plungerSpeed`. +- Generic HID/gamepad axis mode + Fallback for older devices that still expose accelerometer or plunger data through joystick-style axes. + +### 2. Managed sensor abstraction + +On the managed side, VPE should introduce a small sensor abstraction rather than feeding raw analog events straight into physics. + +Recommended concepts: + +- `AnalogInputSample` + Timestamped sample from native input, with device id, element id, and value. +- `SensorInputType` + `Acceleration`, `Velocity`, or `Position`. +- `CalibratedAxisState` + Tracks bias, filtered value, noise window, and sample history for one axis. +- `NudgeInputSource` + Represents one X/Y pair for cabinet motion. +- `PlungerInputSource` + Represents plunger position or speed. +- `NudgeCalibrationProfile` + Persisted settings for a mapped source. + +This is the layer where VPE should: + +- subtract bias +- apply orientation/inversion +- apply a noise window or hysteresis filter +- apply gain and clamp +- optionally adapt the center slowly while the cabinet is idle + +### 3. Physics-facing nudge state + +VPE should keep a dedicated nudge state in the simulation-thread physics context. + +Recommended fields: + +- `CurrentCabinetVelocity` +- `PreviousCabinetVelocity` +- `CurrentCabinetAcceleration` + Optional, useful for diagnostics, tilt modeling, or compatibility mode. +- `CurrentCabinetDisplacement` + Optional, only needed later for visual shake or debugging. + +Recommended tick behavior: + +1. Read the latest calibrated nudge sample for the current simulation tick. +2. Convert it to the primary internal representation: + - velocity-capable devices: use directly + - acceleration-only devices: integrate into a compatibility velocity estimate +3. Compute `deltaVelocity = current - previous`. +4. Apply `-deltaVelocity` to each moving ball before the normal physics step. +5. Store `previous = current`. + +This should happen on the simulation thread before `PhysicsCycle.Simulate()` so collision detection and response see the updated ball velocities. + +### 4. Compatibility modes + +VPE should explicitly support two modes: + +- `Velocity` + Preferred mode. Uses cabinet velocity directly and should not use the old acceleration-oriented nudge filter. +- `Acceleration` + Compatibility mode for older joystick-style accelerometer devices. VPE can integrate these samples to a cabinet velocity estimate locally. + +If a source reports position instead of velocity, VPE can derive velocity in the managed sensor layer, just as VPX does for plunger and nudge compatibility paths. + +## Open Pinball Device handling + +Open Pinball Device is the best long-term target for VPE because it carries named pinball-specific inputs instead of pretending to be a generic joystick. + +For nudge support, OPD is especially useful because it can report: + +- raw nudge acceleration +- integrated nudge velocity +- plunger position +- plunger speed + +That means VPE should treat OPD as a first-class native input source rather than just another generic HID device. + +Recommended OPD behavior in VPE: + +- Automatically discover OPD devices in the native layer. +- Surface named channels in managed code instead of raw axis numbers. +- Prefer `vxNudge` and `vyNudge` over `axNudge` and `ayNudge` when both are present. +- Allow generic HID fallback for devices that do not implement OPD. + +VPE should still support mixed setups. For example: + +- plunger from OPD +- nudge from a joystick-style accelerometer +- buttons from keyboard or another controller + +## Calibration design + +Calibration should be split into separate responsibilities rather than treated as a single setting. + +The initial calibration step must be available outside the Unity editor. A future standalone player app will need to guide the user through at least the "cabinet is at rest, sample now" flow, so calibration logic should live in runtime-capable code with an editor UI layered on top, rather than being embedded only in editor inspectors. + +### 1. Orientation setup + +This is the structural setup step: + +- which physical axis maps to cabinet X +- which physical axis maps to cabinet Y +- invert X or Y +- optional rotation angle for boards mounted at 90, 180, or arbitrary angles + +This should be stored per input mapping. + +### 2. Manual zero calibration + +VPE should provide a calibration action equivalent to "read data now, I'm not moving." + +Recommended behavior: + +- user presses `Calibrate at Rest` +- VPE samples for a short fixed window, such as `0.5-2.0` seconds +- VPE computes the mean resting value for each axis +- that mean becomes the bias offset to subtract from future samples + +This is required for generic HID/gamepad accelerometer sources and should also be available as a fallback for OPD devices. + +This flow should be designed as a reusable runtime service: + +- callable from editor UI +- callable from a future player app or in-game settings UI +- able to return progress, sample counts, and success or failure state + +The editor and player-facing UIs can then share the same calibration implementation while presenting different workflows. + +### 3. Noise measurement and dead-zone setup + +Bias removal is not enough on its own because consumer accelerometers still jitter around zero. + +VPE should measure quiet-time noise during calibration and derive an initial noise window from it. Instead of a hard dead zone by default, the preferred behavior is a small hysteresis or jitter window because it avoids sudden jumps when the signal crosses the threshold. + +Recommended stored values: + +- `NoiseSigma` or another robust noise estimate +- `DeadZone` or `HysteresisWindow` +- optional `Clamp` + +Suggested behavior: + +- velocity-capable OPD sources: prefer a small hysteresis window +- generic acceleration sources: allow a slightly stronger dead zone or hysteresis filter + +### 4. Idle-time drift correction + +VPE should not rely only on a one-time calibration. Sensor centers drift over time because of temperature, cabinet settling, and mounting flex. + +Recommended behavior: + +- while the signal is inside a stillness window for some sustained interval, slowly adapt the stored zero point toward the live mean +- freeze that adaptation immediately when real motion starts + +This gives VPE both: + +- manual baseline calibration +- slow automatic recentering during idle periods + +For OPD velocity sources, this should be optional and conservative because the device may already be doing its own drift correction. For generic HID acceleration sources, VPE should enable it by default. + +### 5. Gain and clamp + +After centering and noise handling, VPE still needs: + +- X gain +- Y gain +- optional maximum output clamp + +These should stay explicit user settings. They control feel rather than sensor correctness. + +## Configuration model + +Recommended persisted settings for each nudge mapping: + +- input backend + `OpenPinDev` or `GenericHid` +- source X id +- source Y id +- input type + `Velocity` or `Acceleration` +- orientation angle +- invert X +- invert Y +- bias X +- bias Y +- idle recenter enabled +- idle recenter rate +- dead zone or hysteresis window +- X gain +- Y gain +- clamp + +If multiple nudge sources are allowed, VPE should average compatible active sources only when there is a clear reason to do so. Otherwise it should prefer one configured source pair. + +## Editor and player UX split + +The calibration system should be implemented in two layers: + +- runtime calibration service + Owns sample collection, bias estimation, noise estimation, stillness detection, and profile persistence +- host-specific UI + Editor inspectors, setup wizards, or a future player app can call into the runtime service + +Recommended responsibility split: + +- Unity editor + Full mapping UI, orientation setup, advanced gain and filter tuning, diagnostics +- future player app + Initial device discovery, initial rest calibration, simple gain adjustment, recalibration when cabinet conditions change + +This keeps setup possible for end users who never open the Unity project while still giving developers richer tooling inside the editor. + +## Recommended rollout + +### Milestone 1: Velocity path on Windows + +- extend `VisualPinball.Unity.NativeInput` with analog polling +- add managed analog sample handling in `VisualPinball.Unity` +- support one nudge X/Y source pair +- add calibration profile storage +- apply cabinet velocity deltas in the simulation thread + +This is the highest-value slice because it proves the architecture and covers modern velocity-capable devices. + +### Milestone 2: Generic acceleration compatibility + +- add acceleration-mode source type +- integrate acceleration into cabinet velocity in managed code +- add calibration UI for bias and dead zone or hysteresis +- document when to disable acceleration-style filtering for real velocity inputs + +### Milestone 3: OPD-first experience and tilt polish + +- add OPD device discovery and named channel mapping +- add plunger position and speed through the same analog stack +- add diagnostics UI +- add optional plumb tilt and visual cabinet displacement built on the same nudge state + +## Validation checklist + +The implementation should be considered correct when the following hold true: + +- repeated USB polls of the same velocity sample do not amplify a nudge +- missed USB polls do not weaken a velocity-based nudge beyond the actual cabinet motion represented by the latest sample +- the table remains stable at rest, with no gradual drift in ball motion +- left/right and front/back nudges move the ball in the expected directions after orientation setup +- idle-time recentering corrects slow drift without fighting real nudges +- velocity-based devices do not require the old acceleration-style nudge filter to feel stable + +## Open questions + +- Should VPE expose advanced calibration controls in both the editor and a future player app, or reserve the player app for initial setup and simple recalibration? +- Should OPD support live entirely in `VisualPinball.Unity.NativeInput`, or should VPE also keep a managed fallback parser for environments where a raw HID path is easier to ship? +- Should keyboard nudges be rewritten later to use the same cabinet-motion state so that all nudge sources share one physics path? + +The current recommendation is yes for the last question: VPE should eventually have one cabinet-motion model for keyboard, script, and hardware nudging, even if hardware support is implemented first. diff --git a/VisualPinball.Unity/Documentation~/developer-guide/b2s-integration-design.md b/VisualPinball.Unity/Documentation~/developer-guide/b2s-integration-design.md new file mode 100644 index 000000000..bc50d81f0 --- /dev/null +++ b/VisualPinball.Unity/Documentation~/developer-guide/b2s-integration-design.md @@ -0,0 +1,505 @@ +--- +uid: developer-guide-b2s-integration-design +title: B2S Integration Design +description: Proposed long-term architecture for integrating B2S into VPE by modernizing the upstream runtime into a cross-platform core, keeping a Windows COM shim for compatibility, and exposing native second-monitor and Unity texture outputs. +--- + +# B2S Integration Design + +This page describes the proposed design for integrating B2S into VPE. It covers how `.directb2s` assets should be loaded and rendered, how a future player app should drive a native second-monitor backglass window, which third-party libraries should be used, how the same renderer should also output a texture for VR or cabinet-style backglass meshes inside Unity, and why modernizing the upstream B2S runtime is the stronger long-term solution than building a separate VPE-native rewrite. + +## Summary + +VPE should integrate B2S by helping evolve the existing [B2S Backglass Server](https://github.com/vpinball/b2s-backglass) runtime into a host-agnostic, cross-platform managed core, then consume that core from VPE through a dedicated wrapper layer. + +The recommended long-term architecture is: + +1. extract or modernize the upstream B2S runtime into a cross-platform `b2s-core` +2. keep a thin Windows-only COM compatibility shim for `B2S.Server` +3. add a cross-platform desktop host for native second-monitor rendering +4. add a VPE-specific wrapper that consumes the same core directly and uploads frames into Unity textures when needed + +This is a better long-term solution than a VPE-native rewrite for three reasons: + +- it keeps B2S semantics anchored to the existing runtime instead of re-discovering them in a parallel implementation +- it gives the B2S maintainer and VPE a shared upgrade path instead of creating permanent drift between two runtimes +- it still gives VPE the outputs it needs: a native second-monitor backglass window and a Unity texture path for VR or in-world cabinet views + +Recommended library choices for the modernized runtime: + +- `SkiaSharp` + Shared offscreen 2D compositor, image decoding, dirty-region rendering, and frame export. +- `Avalonia` + Cross-platform desktop host for second-monitor output, monitor enumeration, and future player app UX around B2S. +- built-in `System.Xml.Linq` + `.directb2s` parsing. No extra XML library is needed. +- Unity `Texture2D` + Runtime upload target for the VR and in-world backglass path. Do not use a `RenderTexture` as the primary B2S surface because that implies a camera-driven render path. + +## Why this is the better long-term solution + +The first instinct for VPE is to build a dedicated B2S runtime that is shaped exactly around Unity and the future player app. That sounds attractive architecturally, but it is a worse long-term maintenance tradeoff. + +A VPE-native rewrite would still need to solve all of the hard problems: + +- `.directb2s` parsing and resource decoding +- backglass illumination behavior +- score reels, LEDs, and score displays +- animation behavior +- native second-window output +- Unity texture output +- compatibility validation across real backglasses + +And after doing all of that, VPE would still own a second implementation forever. Every upstream B2S fix, behavioral quirk, or compatibility improvement would need to be reinterpreted and ported again. + +By contrast, modernizing the upstream runtime keeps the semantic center of gravity in one place: + +- the B2S maintainer can continue to evolve the canonical runtime +- VPE gets a clean managed API and modern outputs without forking the behavior model +- Windows compatibility through COM can remain available without infecting the shared core + +That is why this page recommends a modernization and extraction effort, not a greenfield rewrite. + +## What has to change in upstream B2S + +The current runtime is not portable as-is because it is still tightly coupled to Windows-specific technologies such as WinForms, `System.Drawing`, `user32.dll`, COM activation, and registry-based runtime coordination. + +The good news is that the runtime is output-oriented and relatively light on interactive UI. That makes modernization much more realistic than for a full desktop application with deep user workflow dependencies. + +The work should be framed as "extract and re-host the runtime", not "keep patching the current Windows host until it compiles elsewhere". + +Recommended target split: + +- `b2s-core` + Cross-platform runtime containing `.directb2s` parsing, resource decoding, state model, animation logic, score and reel behavior, and a host-neutral rendering API. +- `b2s-rendering` + Shared `SkiaSharp` compositor that produces BGRA32 frames and owns dirty-region logic. +- `b2s-host-desktop` + Cross-platform desktop host using `Avalonia` for monitor enumeration and second-window output. +- `b2s-com-windows` + Windows-only COM wrapper that exposes `B2S.Server` for compatibility and forwards calls into the new core. +- `vpe-b2s` + VPE-specific wrapper or integration project that mounts B2S as a Git submodule and talks to the modern managed API directly, bypassing COM entirely. + +This split gives the B2S project a cleaner product architecture and gives VPE a stable integration boundary. + +## Existing integration points in VPE + +VPE already has the important runtime seams: + +- `DisplayPlayer` connects `IGamelogicEngine` display events to texture-backed display components. +- `DotMatrixDisplayComponent` and `SegmentDisplayComponent` already update textures from raw display frame data. +- `DisplayComponent` already renders a texture onto a mesh in Unity. +- `ScoreReelDisplayComponent` and `ScoreReelComponent` show that VPE already has EM-style score concepts in Unity. +- `Player`, `LampPlayer`, `CoilPlayer`, and `PinMameGamelogicEngine` already centralize switch, lamp, GI, coil, and display state that a B2S renderer would need. + +What VPE does not yet have is: + +- a B2S wrapper package or module +- a native second-window host wired into the future player app +- a Unity texture bridge for B2S frames +- player-owned backglass configuration UX + +That is a much smaller gap than writing a whole new B2S runtime from scratch. + +## Proposed architecture + +### 1. Modernize upstream B2S into a shared core + +The first phase should happen in or alongside the upstream B2S repository. + +Goals: + +- retarget the runtime to modern .NET +- separate runtime logic from WinForms forms and custom controls +- replace `System.Drawing` and control painting with a host-neutral compositor +- replace registry-driven runtime coordination with in-memory state and explicit host APIs +- keep Windows COM as an adapter around the new runtime rather than as the core programming model + +The important principle is that the runtime logic should stop depending on forms, screens, or the registry. + +### 2. Add a managed runtime API + +The shared core should expose a small managed host API that VPE and a desktop host can both consume. + +Recommended types: + +- `B2SSceneDefinition` + Static background art, grill art, image snippets, bulbs, reel definitions, score areas, DMD or segment cutouts, animation metadata, and layout bounds. +- `B2SSceneState` + Current values for lamps, solenoids, GI, mechs, scores, player-up, tilt, ball-in-play, and named animation state. +- `B2SDisplayState` + Current DMD and segment frame textures or raw frame buffers mapped by display id. +- `IB2SRuntime` + Runtime host API for loading scenes, updating state, advancing animations, and producing frames. +- `IB2SController` + High-level API for hosts that want to drive B2S state directly through familiar backglass concepts. + +Recommended `IB2SController` shape: + +- `SetData(id, value)` +- `PulseData(id)` +- `SetScore(player, value)` +- `SetCredits(value)` +- `SetBallInPlay(value)` +- `StartAnimation(name)` +- `StopAnimation(name)` +- `SetDisplayFrame(id, frame)` + +This is the API VPE should use. The COM wrapper should translate `B2S.Server` calls into this same core API on Windows. + +### 3. Add a shared offscreen compositor + +The heart of the integration should be a `SkiaSharp`-based compositor that belongs to the shared B2S runtime, not to VPE. + +Responsibilities: + +- rasterize the static backglass art +- apply illuminated bulb and overlay layers +- render score reels, LEDs, and text regions +- composite DMD and segment-display inputs into cutout regions +- advance time-based animations +- track dirty rectangles so only changed regions are redrawn when possible +- export the final frame as BGRA32 pixel data + +Recommended output model: + +- one BGRA32 pixel buffer per rendered B2S frame +- one logical frame size per backglass scene +- one shared render scheduler that can run at `30 Hz` when mostly static and up to `60 Hz` while animations or DMD changes are active + +This compositor should be the only place where B2S drawing rules live. + +### 4. Keep COM, but only as a compatibility shell + +Backwards compatibility still matters for the existing B2S ecosystem. The modernization path should preserve that by keeping a Windows-only COM wrapper. + +Important constraints: + +- COM should not be part of the shared runtime +- COM should forward into the managed runtime API +- COM should stay Windows-only +- VPE should never talk to COM directly + +This gives the B2S project a compatibility bridge without forcing VPE or cross-platform hosts to inherit old Windows host assumptions. + +### 5. Add a dedicated VPE integration project + +VPE should add a small integration project that mounts the modernized B2S repository as a Git module and exposes VPE-specific wrappers. + +Responsibilities of `vpe-b2s`: + +- resolve `.directb2s` assets for the active table +- map PinMAME, MPF, or original-game state into `IB2SController` +- own the Unity texture upload path +- coordinate with the future player app for second-monitor hosting and per-table settings + +This keeps the B2S runtime independent and reusable while still giving VPE a thin product-specific layer. + +## Third-party libraries + +### `SkiaSharp` + +Use `SkiaSharp` as the shared offscreen B2S compositor. + +Why it is the best fit: + +- mature cross-platform 2D raster API +- good image decoding support for the embedded backglass art path +- easy offscreen rendering into a shared pixel buffer +- reusable for both native windows and Unity textures + +This should replace `System.Drawing` and WinForms control painting in the runtime path. + +### `Avalonia` + +Use `Avalonia` for the desktop host and future player app UI around monitor selection, B2S enablement, and backglass diagnostics. + +Why it is the best fit: + +- cross-platform from the start +- first-class multi-window desktop UI +- good long-term fit if the future player app also wants to be cross-platform +- avoids building the backglass window around Windows-only UI frameworks + +`Avalonia` should be the window host, not the only renderer. Composition rules should stay in the shared `SkiaSharp` renderer so the same runtime also feeds Unity. + +### Built-in XML APIs + +Use `System.Xml.Linq` and the framework base64 APIs for `.directb2s` parsing and resource decoding. + +No additional XML stack is needed for v1. + +### Libraries not recommended for the core path + +- `WPF` or `WinUI 3` + Acceptable Windows-only UI stacks, but the wrong core abstraction if the goal is a shared cross-platform runtime. +- `System.Drawing` + Not suitable as the long-term renderer for a modern cross-platform runtime. +- a second Unity camera or multi-display-only path + Explicitly not the right solution for B2S because it adds a camera-driven render pipeline for what is fundamentally a 2D composition problem. + +## Second-monitor rendering + +### Window host design + +The second-monitor path should be owned by a `B2SMonitorHost` running in the future player app, or in a sidecar desktop host if the Unity runtime remains the main process. + +Responsibilities: + +- enumerate monitors +- persist the chosen backglass monitor id +- create a borderless window on the chosen monitor +- size the window to the monitor bounds or work area +- receive compositor frames and display them with minimal latency +- recover cleanly if the selected monitor disappears + +Recommended window behavior: + +- borderless and non-resizable by default +- optional topmost mode for cabinet setups +- one backglass window per active table +- recreate or reposition the window when monitor configuration changes + +### Rendering path + +The desktop host should not implement B2S drawing rules itself. It should display the latest compositor bitmap produced by the shared runtime. + +Recommended frame flow: + +1. `IB2SRuntime` renders through the shared `SkiaSharp` compositor into a BGRA32 buffer. +2. `B2SMonitorHost` copies or maps that buffer into an Avalonia `WriteableBitmap`. +3. The Avalonia window displays that bitmap through a lightweight image control. +4. Dirty-region redraw is handled by the compositor, not by a second scene graph. + +This keeps the host simple and ensures the Unity and native-window paths always look the same. + +### Data inputs for second-monitor mode + +The compositor should combine: + +- static `.directb2s` art and score regions +- lamp, solenoid, GI, and mech state from PinMAME or other game-logic engines +- DMD and segment display frames from existing VPE display sources +- direct `IB2SController` calls for original and EM-style tables + +## VR and in-world backglass texture rendering + +### Texture output design + +The VR path should use the same shared B2S compositor output and upload it into a Unity `Texture2D`. + +Recommended types: + +- `B2SUnityTextureOutput` + Receives the compositor frame buffer and uploads it into Unity. +- `B2SBackglassTextureComponent` + Applies the resulting texture to the backglass mesh or material in the scene. + +Recommended runtime behavior: + +- allocate one `Texture2D` matching the compositor output size +- upload BGRA or RGBA pixel data when a new frame is ready +- update only on the Unity main thread +- bind the texture to the cabinet backglass material +- use an emissive or unlit material setup in HDRP so the backglass remains readable in VR + +### VR priority and realism note + +VR is not the primary target for B2S. The expected usage is that the native second-monitor path serves the vast majority of users, while VR only needs a compatible fallback that works reliably. + +For that reason, the first VR implementation should simply embed the fully composited 2D B2S frame into the 3D backglass as a texture. It does not need to recreate the more realistic "light behind the translite" workflow used by hand-authored VPE backglasses. + +This is an intentional compromise: + +- `.directb2s` contains enough information to render a convincing 2D backglass +- `.directb2s` does not contain enough physical authoring data to reconstruct a truly realistic 3D backbox automatically +- using the raw B2S art and overlays as a texture in VR is acceptable because VR is a fallback use case, not the main product target + +If later needed, VPE can add a premium VR-specific path that maps B2S state onto authored Unity backglass assets and real light emitters, but that is explicitly out of scope for the first B2S integration. + +### Why this should use `Texture2D`, not `RenderTexture` + +`RenderTexture` is primarily useful when a camera or GPU pass is producing the image. B2S is not camera-driven in this architecture. It is a CPU-composited 2D surface. + +For that reason, the primary output should be a `Texture2D`. If a later HDRP effect or material workflow wants a `RenderTexture`, VPE can blit the `Texture2D` into one, but that should be an optional adapter, not the main rendering path. + +## State integration with PinMAME, MPF, and original games + +### PinMAME + +PinMAME is the highest-value first integration path. + +The B2S adapter should consume: + +- lamp changes +- GI changes +- coil and solenoid changes +- mech updates where the backglass expects them +- DMD and segment display frames already emitted through `IGamelogicEngine` + +This should be wired through a `B2SStatePublisher` that translates existing VPE state into `B2SSceneState` and `B2SDisplayState`. + +### MPF + +MPF should use the same `B2SStatePublisher` contract once it exposes equivalent lamp, segment, score, and display information. + +### Original games and EM-style logic + +Original games should drive B2S through `IB2SController`, not through COM emulation. + +This gives VPE a clean path for: + +- player-up indicators +- credits and ball-in-play +- reels and score windows +- scripted illumination and animation triggers + +## Resource resolution + +VPE should resolve B2S assets in this order: + +1. explicit backglass asset selected by the player app +2. packaged B2S asset embedded with the table package +3. loose sidecar `.directb2s` file next to the loaded table source or package + +The player app should also allow per-table overrides so cabinet owners can select alternative backglasses without changing authored content. + +## Scope boundaries + +V1 should include: + +- a modernized shared B2S runtime core +- `.directb2s` parsing and resource decoding +- static art and illuminated overlays +- score reels and basic score displays +- DMD and segment composition into backglass cutouts +- native second-monitor window output +- Unity texture output for VR and cabinet-room use +- a Windows COM shim for compatibility with existing B2S consumers +- a VPE wrapper project that uses the managed API directly + +V1 should not include: + +- porting the B2S editor and tools +- preserving WinForms or registry-driven runtime behavior internally +- a Unity multi-display camera-based implementation +- a physically reconstructed VR backbox generated automatically from `.directb2s` +- every legacy quirk before the shared runtime is stable + +Advanced legacy behavior can be added after the shared runtime, COM wrapper, and VPE integration layer are stable. + +## Recommended rollout + +### Milestone 1: Extract the shared runtime + +- identify and isolate parser, state, animation, score, and reel logic from the current Windows host +- retarget the runtime to modern .NET +- define `B2SSceneDefinition`, `B2SSceneState`, `B2SDisplayState`, `IB2SRuntime`, and `IB2SController` +- replace registry-driven runtime communication with explicit host APIs + +### Milestone 2: Replace the renderer + +- add a `SkiaSharp` compositor for static art, bulbs, score regions, and display slots +- replace `System.Drawing` and WinForms control painting in the runtime path +- establish a shared BGRA32 frame contract + +### Milestone 3: Restore desktop hosting and compatibility + +- add `B2SMonitorHost` using Avalonia +- add monitor selection and persistence +- add a Windows COM shim that forwards `B2S.Server` calls into the new runtime +- validate second-monitor rendering on Windows first + +### Milestone 4: Add VPE integration + +- add the dedicated VPE wrapper project +- map VPE DMD and segment display outputs into `B2SDisplayState` +- publish PinMAME lamp, GI, coil, and mech state into `IB2SController` +- validate ROM-driven tables in the player app + +### Milestone 5: Add Unity texture output + +- add `B2SUnityTextureOutput` +- bind the compositor output to a backglass mesh material +- validate HDRP material setup in VR and cabinet-room scenes +- keep VR as a compatibility path using the 2D composed frame, not as a physically reconstructed lighting system + +## Implementation estimate + +For the modernization path described on this page, the work is meaningful but still quite realistic, especially because the runtime is output-oriented and does not need its interactive editor or tools ported as part of v1. + +Estimated effort for a practical first version: + +- runtime extraction and project split: `3-5` implementation days +- modern managed host API and state model: `2-4` implementation days +- `SkiaSharp` compositor for static art, bulbs, score regions, and display slots: `4-7` implementation days +- Avalonia second-monitor host and monitor selection plumbing: `3-5` implementation days +- Windows COM compatibility shim over the new runtime: `2-4` implementation days +- VPE wrapper project, PinMAME state publication, and display-slot wiring: `3-5` implementation days +- Unity texture output and material hookup: `2-3` implementation days +- tests, failure handling, and documentation polish: `4-6` implementation days + +That puts a practical v1 at roughly: + +- `2-5 engineer-weeks` of work in conventional terms +- about `1-3 calendar weeks` for a strong AI coding agent working iteratively with human review, assuming the scope stays at the v1 boundaries defined on this page + +What would push the estimate up: + +- broad compatibility with legacy B2S quirks +- hidden coupling between runtime logic and the current Windows host +- large numbers of unusual score or animation behaviors +- support for legacy plugins or sound behaviors in the first pass + +If the goal changes from "practical first version" to "high confidence compatibility with a wide range of legacy backglasses," the effort rises to something closer to: + +- `4-8 engineer-weeks` +- about `2-4 calendar weeks` for an AI-agent-driven implementation with review and repeated validation + +## Why this should appeal to the B2S maintainer + +This plan is not asking the B2S maintainer to accept a VPE fork or a competing runtime. It is proposing a modernization that improves the upstream project itself. + +Benefits to upstream B2S: + +- cleaner project boundaries between runtime, host, and compatibility layers +- a path away from WinForms and `System.Drawing` in the runtime +- preserved Windows compatibility through a COM shim instead of through old host assumptions everywhere +- a reusable cross-platform runtime that can serve more than one host +- direct adoption in VPE without fragmenting the behavior model + +Benefits to VPE: + +- one canonical B2S runtime to integrate against +- better long-term compatibility with upstream fixes and behavior improvements +- a native second-monitor solution and Unity texture output without inventing a second implementation + +That alignment is why this modernization path is the better long-term solution. + +## Validation checklist + +The implementation should be considered correct when: + +- the same B2S scene renders identically in the second-monitor window and on the Unity backglass texture +- rendering B2S does not require a second Unity camera or a second 3D scene +- the native backglass window can be assigned to a chosen monitor and survives table reloads +- DMD and segment displays composite into the correct B2S regions +- VR backglass presentation stays readable without introducing frame spikes from texture uploads +- the Windows COM layer can still satisfy compatibility expectations for `B2S.Server` +- missing or malformed `.directb2s` assets fail gracefully and do not break gameplay + +## Open questions + +- Should the first modernization phase happen directly in the upstream repository, or in a temporary companion repository that is merged back once the architecture settles? +- How much of the current `B2S.Server` surface should the Windows COM shim preserve in v1? +- Should the desktop host live in-process with the future VPE player app, or start as a sidecar process that later gets embedded without changing the runtime API? +- Should the first VPE import path package `.directb2s` assets into the table, or should v1 focus on loose sidecar files and add packaging later? + +The current recommendation is: + +- modernize upstream B2S into a shared runtime +- keep COM as a compatibility adapter +- let VPE consume the managed API directly +- treat second-monitor output as the primary product target +- treat VR as a functional texture-based fallback, not a premium physical backglass solution diff --git a/VisualPinball.Unity/Documentation~/developer-guide/dependencies.svg b/VisualPinball.Unity/Documentation~/developer-guide/dependencies.svg new file mode 100644 index 000000000..1f2702702 --- /dev/null +++ b/VisualPinball.Unity/Documentation~/developer-guide/dependencies.svg @@ -0,0 +1,549 @@ + + + + + + + + VPE HDRP Project + Your HDRP Table Project + Settings + + Assets + + + VPE URP Project + Your URP Table Project + Settings + + Assets + + + + vpe.hdrp + org.visualpinball.engine.unity.hdrp + VisualPinball.Unity.Hdrp + + + + + + VisualPinball.Unity.Hdrp + + + + + + + + VisualPinball.Unity.Hdrp.Editor + + + + + + + + Assets + + + + + + + + + + vpe.assets + org.visualpinball.unity.assets + VisualPinball.Unity.Assets + + + AssetPath + + + + Assets + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + main + org.visualpinball.engine.unity + VisualPinball.Engine + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + VisualPinball.Engine + + + + + + + + VisualPinball.Unity + + + + + + + + VisualPinball.Unity.Editor + + + + + + + + VisualPinball.Unity.Patcher + + + + + + + + VisualPinball.Unity.Test + + + + + + + + + + + + + + + + IPatcher + + + + + + + + vpe.urp + org.visualpinball.engine.unity.urp + VisualPinball.Unity.Urp + + + + + + VisualPinball.Unity.Urp + + + + + + + + VisualPinball.Unity.Urp.Editor + + + + + + + Assets + + + + + + + + + + + + + + + + + IRenderPipeline + IRenderPipeline + + + + + + + + + + + + + + + + vpe.visualscripting + org.visualpinball.engine.unity.visualscripting + VisualPinball.Unity.VisualScripting + + + vpe.pinmame + org.visualpinball.engine.pinmame + VisualPinball.Engine.PinMAME + + + vpe.mpf + org.visualpinball.engine.missionpinball + VisualPinball.Engine.Mpf + + + + + + + + UPM PackageC# ProjectC# ClassUnity Related + Legend + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/VisualPinball.Unity/Documentation~/developer-guide/dof-integration-design.md b/VisualPinball.Unity/Documentation~/developer-guide/dof-integration-design.md new file mode 100644 index 000000000..1f238ce83 --- /dev/null +++ b/VisualPinball.Unity/Documentation~/developer-guide/dof-integration-design.md @@ -0,0 +1,256 @@ +--- +uid: developer-guide-dof-integration-design +title: DOF Integration Design +description: Proposed architecture for integrating DOF into VPE with a Windows-first path and a later hybrid cross-platform backend model. +--- + +# DOF Integration Design + +This page describes the proposed design for integrating the DirectOutput Framework (DOF) into VPE. It covers the recommended runtime architecture, where the work should land in the codebase, how a future player app should own configuration, and how a later cross-platform backend should fit into the same design. + +## Summary + +VPE should integrate DOF in two steps: + +1. Add a Windows-first, compatibility-first backend that bundles upstream `DirectOutput` with the VPE player app and hosts it through a thin VPE-owned adapter. +2. Keep the VPE-facing feedback API backend-neutral from the start, then add a second backend based on `libdof` for cross-platform support and eventual parity testing on Windows. + +The key design choice is to keep DOF itself out of the Unity gameplay core. VPE should publish switch, coil, lamp, and GI state through a neutral feedback service, while the player app owns backend selection, cabinet configuration, diagnostics, and output testing. + +## Why the first step should target Windows + +Compatibility with existing DOF behavior matters slightly more than immediate cross-platform reach. + +Classic `DirectOutput` is still the most compatibility-oriented runtime, but it is effectively Windows-only today. It is also designed around desktop .NET and Windows-era hardware assumptions, so VPE should not bake it directly into the shared runtime layer. + +`libdof` is the right long-term portability direction, and VPX already uses it for the new plugin-based DOF integration, but it is still a port with some compatibility gaps compared with classic DOF. That makes it a better second step than a v1 default. + +This leads to a hybrid plan: + +- Windows player builds use bundled `DirectOutput` first. +- The shared VPE feedback contract stays cross-platform. +- A later `libdof` backend can be added without changing table content or game-logic integration. + +## Existing integration points in VPE + +The current VPE runtime already has the seams needed for a feedback host: + +- `IGamelogicEngine` publishes switches, coils, lamps, GI, and displays. +- `Player` owns the game-logic engine, runtime lifecycle, and table mapping state. +- `CoilPlayer` and `LampPlayer` already maintain live output state for mapped playfield devices. +- `PinMameGamelogicEngine` already keeps shared coil, lamp, and GI state snapshots for low-latency playback. +- `MappingConfig` already represents the machine-facing identity of switches, coils, lamps, and wires. + +What VPE does not yet have is: + +- a backend-neutral feedback API +- a player-owned feedback coordinator +- a standalone cabinet configuration and diagnostics UX +- a portable backend boundary for `DirectOutput` and `libdof` + +## Proposed architecture + +### 1. Add a backend-neutral feedback service + +VPE should add a runtime-facing feedback service in `VisualPinball.Unity` that is independent of any specific DOF implementation. + +Recommended concepts: + +- `IFeedbackHost` + The lifecycle and capability surface exposed to the runtime. +- `FeedbackSessionDescriptor` + Table path, table id, ROM id, game-logic engine name, display name, and other metadata used when starting a feedback session. +- `FeedbackSnapshot` + The current normalized switch, coil, lamp, and GI state. +- `FeedbackEvent` + Optional delta form for backends that need immediate edge-triggered updates. +- `FeedbackBackendKind` + `None`, `DirectOutput`, or `LibDof`. +- `FeedbackHostStatus` + Health, initialization state, detected devices, backend version, and last error. + +Recommended `IFeedbackHost` shape: + +- `Initialize(profile)` +- `StartSession(sessionDescriptor)` +- `PublishSnapshot(snapshot)` +- `PublishEvent(feedbackEvent)` +- `StopSession()` +- `GetStatus()` +- `RunOutputTest(testDescriptor)` + +The important rule is that VPE publishes machine outputs, not DOF-specific toy instructions. The backend remains responsible for translating those outputs into hardware behavior according to its own config. + +### 2. Add a player-owned feedback coordinator + +The future player app should own a `FeedbackCoordinator` that sits above the Unity table runtime and below the selected backend. + +Responsibilities: + +- choose a backend for the current platform +- own backend startup and shutdown +- subscribe to VPE output state +- aggregate high-frequency output changes into a single state cache +- publish snapshots at a fixed host cadence +- expose logs, health, and device detection to the player UI +- reset outputs safely on table exit, reload, or backend failure + +Cadence rules: + +- do not call DOF directly from the 1000 Hz simulation loop +- publish snapshots at a stable host rate such as `60-120 Hz` +- allow urgent coil-edge delivery as optional immediate deltas +- keep backend calls off any latency-sensitive gameplay path + +### 3. Publish output state from existing VPE seams + +VPE should use the output state it already has instead of introducing a second gameplay or cabinet model. + +Recommended publication sources: + +- switches from `SwitchPlayer` and `IGamelogicEngine.OnSwitchChanged` +- coils from `CoilPlayer`, `IGamelogicEngine.OnCoilChanged`, and shared PinMAME coil state +- lamps and GI from `LampPlayer`, `IGamelogicEngine.OnLampChanged`, `OnLampsChanged`, and shared PinMAME lamp and GI state +- table metadata from the loaded package plus player-selected overrides + +Recommended publication behavior: + +1. Maintain one in-memory `FeedbackSnapshot` cache in the coordinator. +2. Update that cache from engine and player events. +3. Publish full snapshots on a fixed cadence. +4. Optionally send immediate deltas for pulse-sensitive coil edges. +5. Send a full baseline snapshot when a session starts. +6. Send a backend-native reset or an all-off state when a session stops. + +### 4. Keep table mappings and cabinet config separate + +`MappingConfig` should remain table-side mapping data. It should not grow DOF toy names, output controller assignments, or cabinet wiring. + +Recommended split: + +- `MappingConfig` + Table-side identity and playfield device mapping only. +- `FeedbackProfile` + Player-owned settings such as backend choice, enabled flag, config root, logging level, and optional ROM or table overrides. +- backend-native config + The actual `DirectOutput` or `libdof` configuration files and generated artifacts. + +This keeps authored table content portable and prevents one cabinet's hardware layout from leaking into reusable packages. + +## Windows-first implementation + +### Runtime model + +The Windows-first backend should bundle upstream `DirectOutput` with the VPE player app and host it through a thin `WindowsDirectOutputHost`. + +Recommended boundaries: + +- upstream `DirectOutput` stays as close to unmodified as possible +- VPE integrates it as a pinned git submodule +- the player app owns config editing, output testing, and diagnostics +- the Unity runtime talks only to `IFeedbackHost` + +This allows VPE to reuse the most compatible DOF implementation without requiring users to install DOF separately. + +### Configuration model + +The player app should fully own DOF setup. + +Required player features: + +- enable or disable DOF +- choose the active backend +- choose, create, import, or reset the config root +- edit global config and per-table or per-ROM overrides +- detect available controllers and surface backend health +- run output tests without launching a table +- expose backend logs and validation errors + +Compatibility-first rule: + +- use the real DOF config files as the canonical storage +- do not invent a separate VPE-only DOF format +- store only a small VPE-owned profile around backend selection and install paths + +### Upstream changes + +No upstream DOF changes are strictly required for the first working Windows integration if VPE bundles the runtime and calls the lower-level setup APIs directly. + +Additive upstream changes that would still be useful later: + +- explicit host and config-path options +- structured logging callbacks +- a cleaner headless packaging split between runtime and tools + +These should remain optional and must not change current DOF behavior for existing users. + +### Acceptance criteria + +The Windows-first path is complete when: + +- the VPE player can start DOF without any separate installation +- a bundled config root can be created from scratch or imported from an existing setup +- PinMAME tables can drive coils, lamps, and GI through DOF +- outputs reset safely on table exit, reload, or crash +- the player app can run output tests and expose actionable diagnostics + +## Hybrid second step with libdof + +The second step is to add a `LibDofFeedbackHost` that implements the same `IFeedbackHost` interface. + +Recommended selection policy: + +- Windows defaults to `DirectOutput` until parity is proven +- Linux and macOS use `libdof` when available +- unsupported platforms use `NullFeedbackHost` +- Windows can later expose `libdof` as an advanced backend option for comparison and validation + +Cross-platform rules: + +- the shared feedback API must stay free of Windows-only types +- the player-owned settings stay backend-neutral except for backend-specific option bags +- health, logs, and device detection flow through `FeedbackHostStatus` +- table content and `MappingConfig` remain unchanged regardless of backend + +The `libdof` step should be treated as an explicit parity project, not as a drop-in assumption. It needs platform-by-platform controller validation and side-by-side comparison with the Windows `DirectOutput` path on real tables. + +## Recommended rollout + +### Milestone 1: Shared feedback contract + +- add `IFeedbackHost`, `FeedbackSnapshot`, `FeedbackSessionDescriptor`, and `FeedbackHostStatus` +- add a runtime-owned state cache and publication path +- add `NullFeedbackHost` + +### Milestone 2: Windows-first DirectOutput backend + +- bundle `DirectOutput` with the player app +- add `WindowsDirectOutputHost` +- wire player-owned configuration, logs, and output testing +- validate PinMAME-driven coils, lamps, and GI + +### Milestone 3: Hybrid backend support + +- add `LibDofFeedbackHost` +- keep Windows on `DirectOutput` by default +- validate Linux and macOS controller support +- add parity testing and optional Windows backend selection + +## Validation checklist + +The implementation should be considered correct when: + +- feedback publication never blocks the simulation thread +- switching tables repeatedly does not leave outputs active +- missing or malformed config files produce actionable diagnostics +- the player app can test outputs without entering gameplay +- Windows `DirectOutput` remains the compatibility reference backend +- `libdof` can be added later without changing the shared runtime contract + +## Open questions + +- Should the future player app expose all backend-specific advanced settings directly, or keep the UI focused on the most common cabinet workflows and leave advanced file edits to external tools? +- Should VPE publish only snapshots to the backend, or preserve a mixed model with snapshots plus immediate coil-edge deltas for pulse-sensitive toys? +- Once `libdof` is integrated, should Windows keep `DirectOutput` as the long-term default, or only until parity is measured across the most common hardware configurations? + +The current recommendation is to answer yes to the second question. VPE should keep snapshots as the primary synchronization model, but it should preserve an immediate path for short-lived coil pulses that would be easy to miss at a pure fixed publish cadence. diff --git a/VisualPinball.Unity/Documentation~/developer-guide/index.md b/VisualPinball.Unity/Documentation~/developer-guide/index.md new file mode 100644 index 000000000..0998d8f01 --- /dev/null +++ b/VisualPinball.Unity/Documentation~/developer-guide/index.md @@ -0,0 +1,72 @@ +--- +uid: developer-guide-overview +title: Overview +description: How the Visual Pinball Engine repositories fit together. +--- + +# Overview + +The Visual Pinball Engine ecosystem is split across multiple repositories. The main reasons for this are: + +- The base engine can stay focused on simulation, file I/O, and Unity integration. +- Render-pipeline support can move at the pace of Unity graphics updates. +- Game-logic integrations can ship native binaries and external runtime dependencies without bloating the core package. +- Large asset libraries can live separately from code-heavy repositories. +- Each package can be versioned and published independently to [registry.visualpinball.org](https://registry.visualpinball.org/). + +> [!WARNING] +> VPE is still very much a work in progress. Things are still changing, and we're still far from a state where authors can start building tables. + +## Repository map + +With that out of the way, here's a quick overview: + +![VPE Dependencies](dependencies.svg) + +The center of gravity is `VisualPinball.Engine`. It contains the simulation core, the main Unity integration package, editor tooling, tests, and this documentation site. The other repositories extend that base package for rendering, game logic, scripting, or content. + + +### VisualPinball.Engine + +This is the main repository and the one most contributors touch first. It contains the platform-independent engine (`VisualPinball.Engine`), the Unity runtime bridge (`VisualPinball.Unity`), the editor package (`VisualPinball.Unity.Editor`), test projects, and the DocFX project under `VisualPinball.Unity/Documentation~`. + +If you are changing physics, VPX parsing, table import, common component behavior, or the authoring experience inside Unity, this is usually the right place. + +### VisualPinball.Unity.Hdrp + +This repository adds the render-pipeline-specific layer on top of the base Unity package. It depends on `VisualPinball.Engine` for the runtime/editor integration and on `VisualPinball.Unity.Assets` for common art content. + +Use it for changes that are specific to HDRP rendering, materials, shaders, or package-level graphics setup. + +### VisualPinball.Unity.VisualScripting + +This package extends Unity's Visual Scripting so tables can drive VPE behavior through graphs instead of handwritten C# code. It is especially relevant for original games, EM-style logic, and hybrid projects where scripting needs to stay accessible to non-programmers. + +Use it for node definitions, graph-facing wrappers, or workflow improvements around Unity Visual Scripting. + +### VisualPinball.Engine.Mpf + +This repository integrates VPE with the Mission Pinball Framework, which runs as a separate Python process and communicates with VPE over gRPC. It is the configuration-heavy option for teams who want to reuse MPF's machine-control model inside a simulator. + +Use it when the work involves MPF connectivity, Unity-side MPF components, bridge protocols, or setup around the external Python runtime. + +### VisualPinball.Engine.PinMAME + +This repository covers ROM-based game logic. It wraps `pinmame-dotnet`, packages native binaries for supported platforms, and exposes the Unity-side integration used by VPE tables that emulate existing solid-state machines. + +Use it for PinMAME-specific metadata, plugin deployment, native wrapper work, or Unity integration around ROM-driven tables. + +### VisualPinball.Unity.Assets + +This is the shared asset library. It keeps reusable content out of the engine repositories and provides meshes, materials, and prefabs that render packages and table projects can consume without duplicating large binary files. + +Use it for reusable art content rather than engine or gameplay code. + + +## Future integrations + +The developer guide also tracks design work for integrations that are not yet fully implemented in VPE. These pages are intended to capture architectural direction early, so implementation work across native input, runtime systems, and tooling can converge on the same design. + +- [Accelerometer Input Design](xref:developer-guide-accelerometer-input-design) covers analog nudge input, Open Pinball Device support, calibration, and how a future player app should participate in initial setup. +- [B2S Integration Design](xref:developer-guide-b2s-integration-design) proposes modernizing the upstream B2S runtime into a shared cross-platform core with a Windows COM shim, a native second-monitor host, and a Unity texture output for VR backglasses. +- [DOF Integration Design](xref:developer-guide-dof-integration-design) covers a Windows-first `DirectOutput` integration for the future player app and the later hybrid path toward a `libdof` backend. \ No newline at end of file diff --git a/VisualPinball.Unity/Documentation~/developer-guide/removed-meta-files.png b/VisualPinball.Unity/Documentation~/developer-guide/removed-meta-files.png new file mode 100644 index 000000000..3f4099dce Binary files /dev/null and b/VisualPinball.Unity/Documentation~/developer-guide/removed-meta-files.png differ diff --git a/VisualPinball.Unity/Documentation~/developer-guide/setup.md b/VisualPinball.Unity/Documentation~/developer-guide/setup.md new file mode 100644 index 000000000..165217b54 --- /dev/null +++ b/VisualPinball.Unity/Documentation~/developer-guide/setup.md @@ -0,0 +1,168 @@ +--- +uid: development-setup +title: Development Setup +description: So, you want to contribute and set this up locally? Here's how! +--- + +# Development Setup + +VPE uses Unity's [Package Manager](https://docs.unity3d.com/Manual/upm-ui.html) to fetch its code. For users, that's great because they get updates without having to deal with git, and the actual project to work with is very small because the heavy dependencies get pulled in by UPM. We use our [own scoped registry](https://registry.visualpinball.org/). Packages get published automatically when something gets merged or pushed to `master`. + +However, packages are immutable in Unity, meaning code can't be updated and thus they are not suitable for local development. For that, you need to clone each package locally and manually add them to the project. + +## Order of Setup + +If you already have a project that references VPE through our registry, remove it. Then, clone all the repos: + +```bash +git clone git@github.com:VisualPinball/VisualPinball.Unity.Assets.git +git clone git@github.com:freezy/VisualPinball.Engine.git +git clone git@github.com:VisualPinball/VisualPinball.Unity.Hdrp.git +git clone git@github.com:VisualPinball/VisualPinball.Unity.Urp.git +git clone git@github.com:VisualPinball/VisualPinball.Engine.PinMAME.git +``` + +If you receive authentication errors, you will need to add an [SSH key to your GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). + +Lastly, you'll need to compile some non-Unity dependencies: + +```bash +cd VisualPinball.Engine +dotnet build -c Release + +cd .. + +cd VisualPinball.Engine.PinMAME +dotnet build -c Release +``` + +### HDRP + +In your Unity project, add the repositories as packages from disk in the following order: + +1. [VisualPinball.Unity.Assets](https://github.com/VisualPinball/VisualPinball.Unity.Assets) +2. [VisualPinball.Engine](https://github.com/freezy/VisualPinball.Engine) +3. [VisualPinball.Unity.Hdrp](https://github.com/VisualPinball/VisualPinball.Unity.Hdrp) +4. [VisualPinball.Engine.PinMAME](https://github.com/VisualPinball/VisualPinball.Engine.PinMAME) + +### URP + +When working with URP, use these repositories in this order: + +1. [VisualPinball.Engine](https://github.com/freezy/VisualPinball.Engine) +2. [VisualPinball.Unity.Urp](https://github.com/VisualPinball/VisualPinball.Unity.Urp) +3. [VisualPinball.Engine.PinMAME](https://github.com/VisualPinball/VisualPinball.Engine.PinMAME) + +## Releasing + +One advantage of UPM is that it makes it easy for users to upgrade: + +![Unity Package Manager](unity-package-manager.png) + +In order for that to work, we use GitHub Actions to increase the package version on each merge to master, publish the package to our registry, and update the dependents. For example, if you commit to `vpe.assets`, GitHub will: + +- Increase the version of `vpe.assets` and publish a new package to our package registry +- Update `vpe.assets.hdrp`, `vpe.assets.urp` and `main` to use the new version +- Since they got updated, the three repos in the last step will also increase their version and publish themselves + +Summary: Committing to master on any repo will automatically release itself and its dependents. So avoid committing to master directly and use PRs! + +## Cross-Repo Features + +Sometimes you'll be working on features that span multiple repositories. We recommend branching each repository to the same branch name so it's clear which branches belong together when testing the feature. + +## .meta Files + +Unity automatically creates a `.meta` file for every file and directory it indexes. It also does a somewhat decent job cleaning them up if the original file is missing. The `.meta` files are particularly important for native binaries, because they tell Unity to which platform they belong and thus avoid conflicts. + +The thing is, in the main repo there are a few native dependencies that we don't include directly. Instead, we reference them through NuGet and copy them to Unity's Plugin folder when compiling for the first time. That means that in the repo, we have the `.meta` files for those dependencies, but not the actual files, which results in Unity cleaning the `.meta` files for all platforms when compiling. + +Long story short, you'll end up with something like this very soon: + +![Delete .meta files in git](removed-meta-files.png) + +You don't want to commit this because it will break CI and package publishing. We also can't put them into `.gitignore` because that only applies to files that exist and you don't want to commit (here it's the other way around - you deleted files you don't want to commit). + +The workaround is to tell git to explicitly ignore those files. You only do that once after cloning: + +
+Show all assume-unchanged commands + +```bash +git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/FluentAssertions.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/JeremyAnsel.Media.WavefrontObj.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/NLog.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/NetMiniZ.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/NetVips.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/OpenMcdf.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/System.Buffers.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/VisualPinball.Resources.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/libminiz.so.2.2.0.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/libvips.so.42.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/ICSharpCode.SharpZipLib.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/OpenMcdf.Extensions.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/arm64/libvips.42.dylib.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/x64/libvips.42.dylib.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/FluentAssertions.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/JeremyAnsel.Media.WavefrontObj.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/NLog.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/NetMiniZ.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/NetVips.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/OpenMcdf.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/System.Buffers.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/VisualPinball.Resources.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/libminiz.2.2.0.dylib.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/libvips.42.dylib.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/ICSharpCode.SharpZipLib.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/OpenMcdf.Extensions.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/FluentAssertions.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/JeremyAnsel.Media.WavefrontObj.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/NLog.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/NetMiniZ.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/NetVips.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/OpenMcdf.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/System.Buffers.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/VisualPinball.Resources.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/libglib-2.0-0.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/libgobject-2.0-0.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/libminiz-2.2.0.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/libvips-42.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/ICSharpCode.SharpZipLib.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/OpenMcdf.Extensions.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/FluentAssertions.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/JeremyAnsel.Media.WavefrontObj.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/NLog.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/NetMiniZ.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/NetVips.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/OpenMcdf.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/System.Buffers.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/VisualPinball.Resources.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/libglib-2.0-0.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/libgobject-2.0-0.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/libminiz-2.2.0.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/libvips-42.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/ICSharpCode.SharpZipLib.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/OpenMcdf.Extensions.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/FluentAssertions.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/JeremyAnsel.Media.WavefrontObj.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/NLog.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/NetMiniZ.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/NetVips.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/OpenMcdf.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/System.Buffers.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/VisualPinball.Resources.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/ICSharpCode.SharpZipLib.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/OpenMcdf.Extensions.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/FluentAssertions.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/JeremyAnsel.Media.WavefrontObj.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/NLog.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/NetMiniZ.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/NetVips.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/OpenMcdf.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/System.Buffers.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/VisualPinball.Resources.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/ICSharpCode.SharpZipLib.dll.meta +git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/OpenMcdf.Extensions.dll.meta +``` +Yeah, we know... +
\ No newline at end of file diff --git a/VisualPinball.Unity/Documentation~/developer-guide/threading-model.md b/VisualPinball.Unity/Documentation~/developer-guide/threading-model.md new file mode 100644 index 000000000..adefc2403 --- /dev/null +++ b/VisualPinball.Unity/Documentation~/developer-guide/threading-model.md @@ -0,0 +1,170 @@ +--- +uid: developer-guide-threading-model +title: Threading Model +description: How Unity, the simulation thread, PinMAME, and input polling interact at runtime. +--- + +# Threading Model + +VPE's low-latency runtime is intentionally split across several execution domains. The important point is that rendering and `GameObject` mutation stay on Unity's main thread, while physics simulation and time-sensitive game logic can run independently at a higher rate. + +The current runtime architecture is built around four domains: + +| Domain | Main code | What it does | +| --- | --- | --- | +| Unity main thread | `PhysicsEngine.Update()`, `SimulationThreadComponent.Update()`, `PinMameGamelogicEngine.Update()` | Applies visuals, drains queued callbacks, polls some PinMAME outputs, runs Unity APIs | +| Simulation thread | `SimulationThread`, `PhysicsEngineThreading.ExecuteTick()` | Runs the 1 kHz physics simulation loop, dispatches low-latency inputs, advances physics, publishes snapshots | +| Native input polling thread | `NativeInputManager`, `VisualPinball.Unity.NativeInput` | Polls keyboard input outside Unity's frame loop and forwards events into a lock-free ring buffer | +| PinMAME native callback thread(s) | `pinmame-dotnet` callbacks, `PinMameGamelogicEngine` handlers | Raises ROM-driven outputs such as coils, displays, mechs, audio, and state changes | + +## High-level flow + +```mermaid +flowchart TD + Input["Native input polling thread
500 us poll default
1000 us in editor"] -->|Lock-free ring buffer| Sim["Simulation thread
1000 Hz / 1 ms tick"] + UnityInput["Unity Input System
main-thread fallback"] -->|Queued external switches| Sim + Sim -->|Direct switch dispatch| PM["PinMAME emulation
Native callback thread(s)"] + PM -->|Coil events for low-latency consumers| Sim + PM -->|Display/mech/coil UI callbacks| Main["Unity main thread
Update()"] + PM -->|Lamp/GI deltas polled per frame| Main + Sim -->|Triple-buffer snapshot publish
once per tick| Snapshot["SimulationState"] + Snapshot -->|Read once per frame| Main + Main -->|Apply GameObject motion
and shared PinMAME state| Visuals["Visible table state"] + + Latency["Best visible input path:
poll interval + <=1 ms sim tick + up to one render frame"] + Visuals --- Latency +``` + +## What each thread is responsible for + +VPE supports two timing modes because the engine needs to serve two different runtime shapes. Internal timing is the simpler mode: Unity's main thread calls into physics directly, which keeps everything in one place and is easier to debug, integrate, and reason about when low latency is not the primary goal. External timing exists for the threaded runtime: it disables the normal `PhysicsEngine.Update()`-driven simulation step so a dedicated simulation thread can own the 1 kHz clock, feed PinMAME with tighter time fences, and react to inputs without waiting for the next frame. In short, internal timing optimizes for simplicity and compatibility, while external timing optimizes for determinism and lower end-to-end input latency. + +### Unity main thread + +The main thread remains the only place where Unity objects are touched directly. + +- `PhysicsEngine.Update()` switches between single-threaded physics and external-timing mode. +- In external-timing mode it does **not** run physics. Instead it drains deferred callbacks, stages kinematic transform changes, and applies the latest published snapshot. +- `SimulationThreadComponent.Update()` keeps the simulation clock aligned with Unity time scaling, flushes any input dispatchers that require main-thread delivery, reads the latest snapshot, and applies shared PinMAME state such as lamps and GI. +- `PinMameGamelogicEngine.Update()` drains a main-thread dispatch queue for callbacks that cannot safely touch Unity from a native thread, then polls `GetChangedLamps()` and `GetChangedGIs()` once per frame. + +This means that all visible motion is still frame-bound even when the simulation itself is running faster than the render loop. + +### Simulation thread + +`SimulationThread` creates a dedicated `Thread` named `VPE Simulation Thread` and runs it at `AboveNormal` priority. Its target cadence is 1000 Hz, or one tick every 1000 microseconds. + +Each tick runs in this order: + +1. Consume switch events that originated on the Unity main thread. +2. Consume native input events from the lock-free `InputEventBuffer`. +3. Dispatch low-latency coil outputs that PinMAME queued for simulation-side consumers. +4. Execute one physics tick through `PhysicsEngineThreading.ExecuteTick()`. +5. Advance the PinMAME time fence with `SetTimeFence()`. +6. Copy the current animation and shared-output state into `SimulationState` and publish the next snapshot. + +Physics itself runs under `PhysicsLock`, but the published animation data crosses back to Unity through a triple-buffered `SimulationState` so the main thread can read it without taking that lock. + +### Native input polling thread + +When `SimulationThreadComponent` enables native input, `NativeInputManager` starts a native polling thread through `VisualPinball.Unity.NativeInput`. + +- On Windows, the native code uses `GetAsyncKeyState()` in a dedicated highest-priority polling thread. +- The default poll interval is 500 microseconds, but the editor clamps it to 1000 microseconds to avoid destabilizing stop/start behavior. +- The native callback calls back into `NativeInputManager.OnInputEvent()`, which forwards the event straight into `SimulationThread.EnqueueInputEvent()`. + +That path avoids waiting for Unity's next `Update()` before a flipper press becomes visible to the simulation. + +Native polling does not replace Unity's Input System; the two paths coexist. `InputManager` still loads the Unity `InputActionAsset`, `SwitchPlayer` still listens to `InputSystem.onActionChange`, and those events still reach `Player.DispatchSwitch()` on the main thread. Native polling is the lower-latency path used when `SimulationThreadComponent` enables it, but it works with its own native binding table rather than reading Unity's `.inputactions` asset directly. The bridge between the two systems is the logical action name: `NativeInputManager` emits `NativeInputApi.InputAction` values such as `LeftFlipper` or `Start`, and `SimulationThread.BuildInputMappings()` maps those actions to actual game switches by scanning `IGamelogicEngine.RequestedSwitches` and matching each switch's `InputActionHint` against the same `InputConstants` names used by the Unity bindings. In other words, Unity and native input share the same action vocabulary, but they are configured through separate binding layers. That is why the native defaults in `NativeInputManager.SetupDefaultBindings()` are kept roughly aligned with the Unity defaults in `InputManager.GetDefaultInputActionAsset()`, and why the first switch advertising a given `InputActionHint` becomes the switch that native polling drives. + +### PinMAME callback thread(s) + +`pinmame-dotnet` registers managed callbacks in `PinMameApi.Config`. Those callbacks immediately invoke managed events from whichever native thread PinMAME uses for that callback. + +VPE therefore treats PinMAME callbacks as **off-main-thread** work: + +- display and mech updates are queued onto `_dispatchQueue` and drained later in `PinMameGamelogicEngine.Update()`. +- solenoid updates also enqueue normal Unity-facing callbacks onto `_dispatchQueue`. +- solenoid updates additionally enqueue low-latency coil events into `_simulationCoilDispatchQueue` when a coil can be handled safely from the simulation thread. +- lamp and GI changes are not delivered through the callback queue. They are polled on the Unity main thread once per frame with `GetChangedLamps()` and `GetChangedGIs()`. + +This split is deliberate: coils can affect physics latency, while lamps and displays are primarily visual. + +## Crossing thread boundaries + +The runtime uses different mechanisms depending on how latency-sensitive the data is. + +| From | To | Mechanism | Why | +| --- | --- | --- | --- | +| Native input thread | Simulation thread | `InputEventBuffer` lock-free SPSC ring buffer | Lowest-latency input path, no lock on the hot path | +| Unity main thread | Simulation thread | `SimulationThread` external switch queue | Lets Unity-driven switches join the 1 kHz simulation loop | +| Any thread | Physics thread/domain | `PhysicsEngine.InputActions` queue under `InputActionsLock` | Safe mutation requests into the physics state | +| Unity main thread | Simulation thread | `PendingKinematicTransforms` under `PendingKinematicLock` | Main thread observes transforms; sim thread consumes them | +| Simulation thread | Unity main thread | triple-buffered `SimulationState` | Lock-free animation/state handoff | +| Simulation thread | Unity main thread | physics `EventQueue` drained with `Monitor.TryEnter(PhysicsLock)` | Avoids stalling the main thread if simulation is mid-tick | +| PinMAME callback thread | Unity main thread | `_dispatchQueue` | Keeps Unity API usage on the main thread | +| PinMAME callback thread | Simulation thread | `_simulationCoilDispatchQueue` | Fast coil-to-physics path for flippers and similar devices | +| PinMAME shared output state | Snapshot / main thread | `_outputStateLock` + snapshot copy | Consistent lamp/GI/coil state across threads | + +## Why the latency is lower than a frame-bound design + +The key optimization is that the fastest input path does not wait for the next Unity frame. + +```mermaid +sequenceDiagram + autonumber + participant NI as Native input thread + participant ST as Simulation thread + participant PM as PinMAME callback thread + participant MT as Unity main thread + + NI->>ST: Input event enqueued
after 0-500 us poll delay + ST->>PM: Switch dispatched in same 1 ms sim tick + PM-->>ST: Coil event queued for simulation-side consumers + ST->>ST: Physics tick updates flipper state + ST->>MT: Publish snapshot + MT->>MT: Next Update() applies visuals + + Note over NI,MT: Best visible path is roughly poll interval + <=1 ms simulation tick + up to one render frame. + Note over PM,MT: Lamps, GI, displays, and mech visuals stay frame-bound
because Unity-facing work drains in Update(). +``` + +In practice this creates two different latency classes. + +### Low-latency path + +This is the path for native input and simulation-thread-safe coil effects: + +- Input can be detected by the native polling thread in well under a frame. +- The simulation thread sees it on the next 1 ms tick. +- PinMAME can emit a coil callback back into the simulation-side queue. +- Physics changes are published immediately into the next snapshot. + +The remaining user-visible delay is usually waiting for Unity's next rendered frame to apply that snapshot. + +### Frame-bound path + +This is the path for visual-only and Unity-only work: + +- Unity Input System input arrives on the main thread and then has to be queued into the simulation thread. +- Display, mech, and normal coil callbacks are drained on the next `PinMameGamelogicEngine.Update()`. +- Lamp and GI changes are only observed when the main thread polls PinMAME in `Update()`. + +That work is still correct, but it is fundamentally tied to frame cadence rather than the 1 kHz simulation cadence. + +## Important consequences and limits + +- **Physics is Burst-compiled, not Job System-driven at runtime** - `PhysicsUpdate.Execute()` is Burst-compiled, but the runtime physics loop is called directly from the simulation thread or the Unity main thread. The live simulation path is not scheduled onto Unity worker threads through `IJob` or `IJobParallelFor`. + That matters because the main concurrency boundary is *main thread vs dedicated simulation thread*, not Unity's runtime job scheduler. +- **Visible motion still waits for a frame** - Even with a 1 ms simulation tick, Unity transforms are only updated when the main thread applies the latest snapshot. Faster simulation reduces the time spent waiting for physics and ROM logic, but it does not bypass the render frame. +- **Some main-thread work is intentionally non-blocking** - `DrainExternalThreadCallbacks()` uses `Monitor.TryEnter(PhysicsLock)` instead of blocking. If the simulation thread is currently inside a physics tick, the main thread skips the drain and tries again next frame. That avoids hitches on the render thread, but it can delay callback delivery by one frame. +- **Catch-up is bounded** - `PhysicsUpdate.Execute()` caps catch-up work through `PhysicsConstants.MaxSubSteps`. Under heavy load, VPE prefers dropping excess catch-up rather than letting a long stall cascade into even worse latency. +- **PinMAME shutdown avoids blocking Unity** - PinMAME stop can block while the native emulator thread joins, so `PinMameGamelogicEngine` pushes shutdown work onto `Task.Run()` instead of doing it on Unity's main thread. + +## Practical guidance for contributors + +- If code touches `GameObject`, `Transform`, or other Unity APIs, keep it on the main thread. +- If code changes the authoritative simulation state, decide whether it belongs in the simulation thread or should be queued into physics through `PhysicsEngine.Schedule()`. +- If a PinMAME callback must influence physics immediately, prefer the simulation-thread coil path instead of a main-thread callback. +- If a feature is visual-only, it is usually acceptable for it to stay frame-bound. +- If you add another game logic engine, implement `IGamelogicInputThreading`, `IGamelogicTimeFence`, `IGamelogicCoilOutputFeed`, or shared-state interfaces only when the engine is actually safe to use from those domains. diff --git a/VisualPinball.Unity/Documentation~/developer-guide/toc.yml b/VisualPinball.Unity/Documentation~/developer-guide/toc.yml new file mode 100644 index 000000000..edd7d45ef --- /dev/null +++ b/VisualPinball.Unity/Documentation~/developer-guide/toc.yml @@ -0,0 +1,14 @@ +- name: Overview + href: index.md +- name: Setup + href: setup.md +- name: Threading Model + href: threading-model.md +- name: Future Integrations + items: + - name: Accelerometer Input Design + href: accelerometer-input-design.md + - name: B2S Integration Design + href: b2s-integration-design.md + - name: DOF Integration Design + href: dof-integration-design.md \ No newline at end of file diff --git a/VisualPinball.Unity/Documentation~/developer-guide/unity-package-manager.png b/VisualPinball.Unity/Documentation~/developer-guide/unity-package-manager.png new file mode 100644 index 000000000..27551e3f5 Binary files /dev/null and b/VisualPinball.Unity/Documentation~/developer-guide/unity-package-manager.png differ diff --git a/VisualPinball.Unity/Documentation~/docfx.json b/VisualPinball.Unity/Documentation~/docfx.json index 9f0efa589..fbe3d67a3 100644 --- a/VisualPinball.Unity/Documentation~/docfx.json +++ b/VisualPinball.Unity/Documentation~/docfx.json @@ -7,6 +7,8 @@ "creators-guide/**.md", "plugins/**/toc.yml", "plugins/**.md", + "developer-guide/**/toc.yml", + "developer-guide/**.md", "toc.yml", "*.md" ] @@ -42,7 +44,7 @@ "postProcessors": [ "ExtractSearchIndex" ], "globalMetadata": { "_appTitle": "VPE Documentation", - "_appFooter": "Copyright © 2025 VPE Team", + "_appFooter": "Copyright © 2026 VPE Team", "_appFaviconPath": "favicon.png", "_gitContribute": { "branch": "master" @@ -60,4 +62,4 @@ "cleanupCacheHistory": false, "disableGitFeatures": false } -} +} diff --git a/VisualPinball.Unity/Documentation~/template/vpe/layout/_master.tmpl b/VisualPinball.Unity/Documentation~/template/vpe/layout/_master.tmpl index 10fcf194c..67a770ab1 100644 --- a/VisualPinball.Unity/Documentation~/template/vpe/layout/_master.tmpl +++ b/VisualPinball.Unity/Documentation~/template/vpe/layout/_master.tmpl @@ -40,6 +40,7 @@ +