Peraviz

Peraviz is an experimental, source-built real-time lighting visualizer. It loads MVR scenes, interprets fixture data from GDTF, receives live Art-Net DMX, and presents the resulting scene in Godot through a native C++ GDExtension. Peraviz is viewer-focused; Perastage remains the companion project for authoring and project-management workflows.

Peraviz is under active development and has no packaged release. GDTF coverage is intentionally incremental: consult the support matrix before relying on an attribute or renderer effect.

Current capabilities

• Native MVR/GDTF scene loading, fixture patching, and selected-mode runtime compilation.
• Live Art-Net input with native DMX evaluation and dirty, sectioned render updates.
• Native Dimmer, Pan, Tilt, Zoom, physical color, color-wheel, and bounded static seated-gobo paths for the verified scopes documented in the support matrix.
• Godot scene reconstruction, interaction, UI, and lightweight or volumetric beam presentation.
• Debug and regression tooling for transforms, runtime contracts, and renderer-facing updates.

Platforms and build

The repository targets Windows, Linux, and macOS source builds. Continuous integration currently verifies Linux Debug; Windows build and export instructions are maintained separately.

• Godot runtime/editor: 4.7.1 stable
• GDExtension API: Godot 4.7, using the pinned godot-cpp revision in native/cmake/GodotCompatibility.cmake
• Build tools: CMake and a compatible C++ compiler
• Native dependencies: managed by the native CMake/vcpkg configuration; see Native build

From the repository root:

cmake -S native -B native/build -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON
cmake --build native/build
ctest --test-dir native/build --output-on-failure

The build copies the extension into bin/. Open project.godot in the compatible Godot editor and run the main scene. See Native build and Windows export for complete platform instructions.

Documentation

These are the authoritative starting points:

• Runtime architecture: active native-to-Godot data flow and ownership boundaries.
• GDTF support matrix: supported, partial, parsed-only, and unsupported semantics.
• Gobo control: the current static seated-gobo contract and motion limitations.
• Uniform physical color pipeline: color evaluation and renderer approximation contracts.
• MVR-xchange: supported exchange behavior.
• Project data ownership and PVZ format: project-storage boundaries.
• Coordinate system, beam rendering modes, and performance guidelines: specialized renderer guidance.

Contributor rules are in AGENTS.md and CONTRIBUTING.md.

License

Peraviz is licensed under the GNU General Public License v3.0.