Architecture

Architecture

Blockiverse VR is a Unity 6 C# project targeting Meta Quest 3 and Meta Quest 3S. The architecture favors testable pure-C# gameplay systems where practical, with Unity/XR integration at the runtime boundary.

Platform Stack

Concern	Project choice
Engine	Unity 6
Language	C#
Rendering	Universal Render Pipeline
XR runtime	OpenXR, Unity OpenXR: Meta, Meta XR SDK
Input	Unity Input System and Quest Touch controllers
Interaction	XR Interaction Toolkit where it fits
Multiplayer	Netcode for GameObjects + Unity Transport
Player representation	Meta Horizon avatars with original fallback proxies
Release path	Meta release channels / Meta Horizon Store, with signed APK fallback through GitHub Releases

Source Layout

Assets/
  Blockiverse/
    Art/             Original textures, sprites, branding, audio-facing visual assets
    Scenes/          Unity scenes
    Scripts/         Runtime and editor C# systems
    Settings/        Project and runtime settings
    Tests/           EditMode and PlayMode coverage
docs/
  adr/               Accepted architecture decisions
  architecture/      Branching and release docs
  roadmap/           Canonical execution plan
  rulesets/          Canonical game and implementation rulesets
  testing/           Repo-local test anchors and performance templates
scripts/
  art/               Deterministic art generation and validation helpers
  audio/             Deterministic audio cue generation and tests
  ci/                Repository safety checks
  store/             Store doc validation
  unity/             Local Unity test and build commands
website/
  Static GitHub Pages website for blockiversevr.com

Core Boundaries

• Pure gameplay models and registries should remain testable without VR hardware.
• World data, save/load, crafting, inventory, networking DTOs, resource harvests, and command validation should avoid scene-only assumptions where practical.
• Unity, XR, input, rendering, haptics, audio, and Meta integrations sit at runtime boundaries.
• Multiplayer follows host-authoritative commands for block edits, inventory changes, crafting, resource harvests, damage, weather-affecting world events, and structure edits.
• Backward compatibility belongs in migrations, not permanent preservation of temporary validation vocabularies.

Decisions

Accepted ADRs live in docs/adr/:

• 0001 - Engine and platform stack.
• 0002 - Runtime diagnostics logging.
• 0003 - Performance instrumentation and interaction feedback.

Release Model

The repository uses trunk-based development. main is protected and releasable. Feature work uses short-lived feature/*, fix/*, chore/*, spike/*, and hotfix/* branches. Releases are cut from main with v* tags. Validated engineering checkpoints use annotated kg/... tags and are not release tags.