How ovi-lab/hpui-core works
Main Components
• Editor Components: Located in the “Editor” directory. These include custom inspectors, property drawers, and assembly definitions (asmdef files) that group editor-specific code. Their role is to provide a customized editing experience to configure HPUI properties and interactables.
• Runtime Components: Found in the “Runtime” directory. This contains several submodules:
• Assets (including HPUI UI prefabs for interactables and continuous user interfaces),
• Interaction logic (under “Runtime/Interaction” with scripts for interactables, gesture logic, detection, and handling ray-cast or sphere-cast based interactions),
• Tracking (located in “Runtime/Tracking” with hand skeleton drivers, joint follower scripts, etc.),
• Components and Utils that provide supporting functionality (e.g., UI behavior, event handling, helper classes, filter functions).
• Legacy Assets and Scripts: The “Assets_Legacy” directories in both Editor and Runtime hold older or backward-compatible versions that may be integrated or maintained for legacy projects.
• Resources: Under “Runtime/Resources” where default joint data and configurable assets reside (used for hand joint definitions).
• Samples: Sample scenes and scripts in the “Samples~” directory illustrate usage scenarios (e.g., creating sample HPUI interaction scenes).
• Tests: The “Tests” directory includes assembly definitions and test scripts that ensure the proper behavior of components like gesture logic, interactable definitions, and interactor behavior.
• Documentation: Contains usage, developer guides, and Doxygen configuration files. It is key for understanding module functions and design guidelines.
Component Relationships and Data Flow
• At the core, runtime modules manage the actual hand interaction behavior:
• Tracking gathers data from head-mounted display sensors and hand tracking systems.
• The Interaction module uses this tracking data to detect and process gestures (using scripts in “Runtime/Interaction” and “Runtime/Interaction/Logic”).
• The UI module (under “Runtime/UI”) contains and manages HPUI visual representations, linking with Interaction components to update based on hand inputs.
• Some utility modules (“Runtime/Utils”) and Resources provide supporting functions (e.g., filtering, data defaults).
• The Editor layer works as a complementary development experience by providing custom property drawers, inspectors, and type selectors (as found in the “Editor” directory). This allows developers to configure HPUI assets properly within Unity.
• Samples demonstrate how these layers coordinate in a real scene, showing the integration between custom editor configurations, runtime behavior, and component interactions.
• Testing components ensure that critical parts of the transformation from hand tracking to UI response behave as expected.
Architectural Patterns and Design Principles
• Modular Organization: Clear division between Editor and Runtime, as well as further separation within Runtime into Interaction, Tracking, UI, and Utils. This modular division (supported by the use of .asmdef files) makes the system maintainable and independent.
• Event-Driven and Component-Based Architecture: In Unity, using components attached to game objects means systems like “HPUI Events”, “Gesture Logic”, etc., trigger and respond to events, promoting loose coupling.
• Extensibility and Maintainability: Custom inspectors and property drawers in the Editor allow flexibility in defining new interactable types without changing the core runtime modules.
• Legacy Support: The presence of legacy directories suggests that backward compatibility is maintained for earlier assets and scripts.
Incorporate Relevant Technologies and Frameworks
• Unity: The entire structure is based on the Unity engine with a dedicated focus on XR/VR interactions.
• C# and Unity Assembly Definitions (.asmdef files) to modularize code.
• Doxygen for documentation generation, visible in the Documentation directories and Doxyfile.
• GitHub Actions workflows (in the .github directory) used for continuous integration, for example, static analysis.
Specific Elements
• Clear Labels: Each main block should be clearly labeled such as “Editor Tools”, “Runtime Interaction / UI”, “Tracking Engine”, “Legacy Support”, “Testing Framework”, “Sample Application”.
• Layered Architecture: Consider a layered design where the lowest layer is the hardware/sensors (external XR input), above which sits the Tracking module, then the Interaction/Logic layer, and finally the UI and Presentation layer.