Add Derived Velocity Tracking Support for Natural Locomotion #53

New Issue

MrUnknownDE · 2026-04-05T17:54:38+02:00

MrUnknownDE commented

2026-04-05 17:54:38 +02:00

Originally created by @M1DNYT3 on 2/16/2026

Add Derived Velocity Tracking Support for Natural Locomotion

Overview

This PR implements comprehensive velocity tracking functionality for SlimeVR trackers, enabling support for Natural Locomotion and similar locomotion systems that rely on velocity data. The implementation includes server-side velocity calculation, configurable scaling presets, role-based policies, and a complete GUI for configuration and real-time monitoring.

⚠️ Merge Order: This PR depends on the corresponding SolarXR Protocol PR being merged first. The protocol PR updates the submodule, and this PR contains the server implementation that uses the new protocol fields. Merging this PR before the protocol PR will break the build.

Key Features

Server-Side Implementation

Velocity Calculation System: Added derived velocity calculation for tracked positions with configurable update intervals and smoothing
Role-Based Policy Engine: Implemented VelocityRolePolicy to control which tracker roles can send velocity data, with implicit blacklisting of non-movement trackers (HMD, controllers, shoulders, neck, lower arms)
Configuration System: Added VelocityConfig with persistent settings for enable/disable state, role presets (ALL, HYBRID, CUSTOM), and scaling presets (UNSCALED, HYBRID, CUSTOM_UNIFIED, CUSTOM_PER_AXIS)
Per-Axis Scaling: Support for independent X/Y/Z velocity scaling with optional upscaling beyond 1.0 (experimental feature with warnings)
Hybrid Preset: Pre-tuned scaling values (X: 0.10, Y: 0.75, Z: 0.10) optimized for Natural Locomotion with FBT in VRChat

Protocol Integration

Updated ProtobufMessages: Regenerated from latest OpenVR Driver to support velocity transmission to SteamVR
SolarXR Protocol Extension: Added velocity data to tracker data feed with raw and scaled velocity vectors
RPC Settings Support: Full bidirectional communication for velocity settings between server and GUI

GUI Features

Comprehensive Settings Panel (Settings > General > Tracker Settings):
- Global velocity enable/disable toggle
- Tracker role preset selection (ALL/HYBRID/CUSTOM) with per-role checkboxes for CUSTOM mode
- Velocity scaling overrides with preset selection
- Advanced scaling controls with per-axis sliders (0.01-1.00 range, 0.01-5.00 with upscaling enabled)
- Context-aware tooltips and warnings
Real-Time Velocity Display: Added velocity monitoring to IMU Visualizer Widget showing both raw and scaled velocity with appropriate status messages
Instructions Modal: Comprehensive setup guide covering prerequisites, recommended Natural Locomotion settings, and common issues troubleshooting
Full Localization: All new UI strings added to English translation file with proper FTL formatting

Dynamic Behavior

Runtime Configuration: All settings can be changed on-the-fly without server restart
Intelligent Mapping: Automatic physical-to-synthetic tracker mapping with fallback logic for unmapped body parts
Status-Aware UI: Velocity fields show appropriate messages based on tracker state:
- Active velocity display when data is available
- "Supplied by HMD/controllers" for head and hands
- "Movement captured by other body parts" for implicitly disabled trackers
- "Disabled in settings" when explicitly disabled via configuration
- Greyed-out display when tracker is not allowed to send velocity

Technical Details

Modified Components

Core Server (server/core/):
- Tracker.kt: Added velocity calculation, scaling logic, and policy checks
- VelocityRolePolicy.kt: Role-to-group mappings and allowance logic
- VelocityConfig.kt: Configuration data classes and defaults
- HumanSkeleton.kt: Integration hook for velocity configuration
- ProtobufBridge.kt: Velocity data transmission to OpenVR Driver
- RPCSettingsBuilder.kt & RPCSettingsHandler.kt: RPC protocol handlers for settings
- DataFeedBuilder.kt: Tracker data feed with velocity information
GUI (gui/src/):
- GeneralSettings.tsx: Main velocity settings UI with dynamic rendering
- IMUVisualizerWidget.tsx: Real-time velocity display in tracker cards
- VelocityInstructionsModal.tsx: Setup instructions and troubleshooting guide
- tracker.ts & velocity-settings.ts: React hooks for data management
- datafeed-config.ts: Configuration types
Protocol (solarxr-protocol): Updated to include velocity schema and regenerated all language bindings

Configuration File Changes

The feature adds the following to vrconfig.yml:

velocityConfig:
  sendDerivedVelocity: false  # Global enable/disable
  preset: ALL                 # Role preset: ALL, HYBRID, or CUSTOM
  enabledGroups: []           # Array of role groups for CUSTOM mode (e.g., ["CHEST", "WAIST", "FEET"])
  overrideScalingPreset: false # Enable custom scaling
  scalingPreset: UNSCALED     # Scaling preset selection
  enableUpscaling: false      # Allow values > 1.0 (experimental)
  scale:
    scaleX: 0.5
    scaleY: 0.5
    scaleZ: 0.5

Use Cases

Primary: Natural Locomotion with FBT

Recommended settings: HYBRID role preset + HYBRID scaling preset
Provides lower body + waist velocity while maintaining FBT stability
Requires "walk-in-place" activation in NaLo to prevent constant walking

Secondary: Natural Locomotion without FBT

Can use ALL tracker preset with custom scaling as needed
Greater flexibility for experimentation with scaling values

Warning: Not Recommended for FBT-Only Setups

Velocity calculation adds minor jitter due to SteamVR position prediction
Should be disabled entirely if not using Natural Locomotion or similar systems

Testing Recommendations

Verify proper floor level and boundary setup in the VR headset
Test with HYBRID preset first for known-good baseline
Monitor jitter in VRChat/Beat Saber while moving trackers
Validate Natural Locomotion detects tracker movement correctly
Test runtime configuration changes apply immediately

Breaking Changes

None - feature is disabled by default and opt-in.

Dependencies

SolarXR Protocol PR (must be merged first): https://github.com/SlimeVR/SolarXR-Protocol/pull/197
- This PR updates the solarxr-protocol submodule reference to include velocity support
- The protocol PR can be merged independently, but this server PR requires it to be merged first
Regenerated ProtobufMessages from the latest OpenVR Driver main branch

Implements support for Natural Locomotion integration while maintaining FBT compatibility: https://github.com/SlimeVR/SlimeVR-Server/issues/25

*Originally created by @M1DNYT3 on 2/16/2026* # Add Derived Velocity Tracking Support for Natural Locomotion ## Overview This PR implements comprehensive velocity tracking functionality for SlimeVR trackers, enabling support for Natural Locomotion and similar locomotion systems that rely on velocity data. The implementation includes server-side velocity calculation, configurable scaling presets, role-based policies, and a complete GUI for configuration and real-time monitoring. **⚠️ Merge Order**: This PR depends on the corresponding SolarXR Protocol PR being merged first. The protocol PR updates the submodule, and this PR contains the server implementation that uses the new protocol fields. Merging this PR before the protocol PR will break the build. ## Key Features ### Server-Side Implementation - **Velocity Calculation System**: Added derived velocity calculation for tracked positions with configurable update intervals and smoothing - **Role-Based Policy Engine**: Implemented `VelocityRolePolicy` to control which tracker roles can send velocity data, with implicit blacklisting of non-movement trackers (HMD, controllers, shoulders, neck, lower arms) - **Configuration System**: Added `VelocityConfig` with persistent settings for enable/disable state, role presets (ALL, HYBRID, CUSTOM), and scaling presets (UNSCALED, HYBRID, CUSTOM_UNIFIED, CUSTOM_PER_AXIS) - **Per-Axis Scaling**: Support for independent X/Y/Z velocity scaling with optional upscaling beyond 1.0 (experimental feature with warnings) - **Hybrid Preset**: Pre-tuned scaling values (X: 0.10, Y: 0.75, Z: 0.10) optimized for Natural Locomotion with FBT in VRChat ### Protocol Integration - **Updated ProtobufMessages**: Regenerated from latest OpenVR Driver to support velocity transmission to SteamVR - **SolarXR Protocol Extension**: Added velocity data to tracker data feed with raw and scaled velocity vectors - **RPC Settings Support**: Full bidirectional communication for velocity settings between server and GUI ### GUI Features - **Comprehensive Settings Panel** (Settings > General > Tracker Settings): - Global velocity enable/disable toggle - Tracker role preset selection (ALL/HYBRID/CUSTOM) with per-role checkboxes for CUSTOM mode - Velocity scaling overrides with preset selection - Advanced scaling controls with per-axis sliders (0.01-1.00 range, 0.01-5.00 with upscaling enabled) - Context-aware tooltips and warnings - **Real-Time Velocity Display**: Added velocity monitoring to IMU Visualizer Widget showing both raw and scaled velocity with appropriate status messages - **Instructions Modal**: Comprehensive setup guide covering prerequisites, recommended Natural Locomotion settings, and common issues troubleshooting - **Full Localization**: All new UI strings added to English translation file with proper FTL formatting ### Dynamic Behavior - **Runtime Configuration**: All settings can be changed on-the-fly without server restart - **Intelligent Mapping**: Automatic physical-to-synthetic tracker mapping with fallback logic for unmapped body parts - **Status-Aware UI**: Velocity fields show appropriate messages based on tracker state: - Active velocity display when data is available - "Supplied by HMD/controllers" for head and hands - "Movement captured by other body parts" for implicitly disabled trackers - "Disabled in settings" when explicitly disabled via configuration - Greyed-out display when tracker is not allowed to send velocity ## Technical Details ### Modified Components - **Core Server** (`server/core/`): - `Tracker.kt`: Added velocity calculation, scaling logic, and policy checks - `VelocityRolePolicy.kt`: Role-to-group mappings and allowance logic - `VelocityConfig.kt`: Configuration data classes and defaults - `HumanSkeleton.kt`: Integration hook for velocity configuration - `ProtobufBridge.kt`: Velocity data transmission to OpenVR Driver - `RPCSettingsBuilder.kt` & `RPCSettingsHandler.kt`: RPC protocol handlers for settings - `DataFeedBuilder.kt`: Tracker data feed with velocity information - **GUI** (`gui/src/`): - `GeneralSettings.tsx`: Main velocity settings UI with dynamic rendering - `IMUVisualizerWidget.tsx`: Real-time velocity display in tracker cards - `VelocityInstructionsModal.tsx`: Setup instructions and troubleshooting guide - `tracker.ts` & `velocity-settings.ts`: React hooks for data management - `datafeed-config.ts`: Configuration types - **Protocol** (`solarxr-protocol`): Updated to include velocity schema and regenerated all language bindings ### Configuration File Changes The feature adds the following to `vrconfig.yml`: ```yaml velocityConfig: sendDerivedVelocity: false # Global enable/disable preset: ALL # Role preset: ALL, HYBRID, or CUSTOM enabledGroups: [] # Array of role groups for CUSTOM mode (e.g., ["CHEST", "WAIST", "FEET"]) overrideScalingPreset: false # Enable custom scaling scalingPreset: UNSCALED # Scaling preset selection enableUpscaling: false # Allow values > 1.0 (experimental) scale: scaleX: 0.5 scaleY: 0.5 scaleZ: 0.5 ``` ## Use Cases ### Primary: Natural Locomotion with FBT - Recommended settings: **HYBRID** role preset + **HYBRID** scaling preset - Provides lower body + waist velocity while maintaining FBT stability - Requires "walk-in-place" activation in NaLo to prevent constant walking ### Secondary: Natural Locomotion without FBT - Can use **ALL** tracker preset with custom scaling as needed - Greater flexibility for experimentation with scaling values ### Warning: Not Recommended for FBT-Only Setups - Velocity calculation adds minor jitter due to SteamVR position prediction - Should be disabled entirely if not using Natural Locomotion or similar systems ## Testing Recommendations 1. Verify proper floor level and boundary setup in the VR headset 2. Test with HYBRID preset first for known-good baseline 3. Monitor jitter in VRChat/Beat Saber while moving trackers 4. Validate Natural Locomotion detects tracker movement correctly 5. Test runtime configuration changes apply immediately ## Breaking Changes None - feature is disabled by default and opt-in. ## Dependencies - **SolarXR Protocol PR** (must be merged first): https://github.com/SlimeVR/SolarXR-Protocol/pull/197 - This PR updates the `solarxr-protocol` submodule reference to include velocity support - The protocol PR can be merged independently, but this server PR requires it to be merged first - Regenerated ProtobufMessages from the latest OpenVR Driver main branch ## Related Issues Implements support for Natural Locomotion integration while maintaining FBT compatibility: https://github.com/SlimeVR/SlimeVR-Server/issues/25

MrUnknownDE closed this issue

2026-04-05 17:54:38 +02:00

Sign in to join this conversation.

Branches Tags

main

sapphire/diy-fw-tool-version-sort

aed/grammar-police

battery-0

bscotch/server-rewrite-temp

hannah/steam

pontoon

hannah/keybinds

server-rewrite

bscotch/accel-mount

dependabot/github_actions/gradle/actions-6

dependabot/github_actions/pnpm/action-setup-5

dependabot/github_actions/actions/upload-artifact-7

dependabot/github_actions/actions/download-artifact-8

FloorClipSteamLinkInteractionFix

sapphire/trim-vrm-json

llelievr/trackers-udp-tests

sapphire/linux-bridge-kotlin

sapphire/linux-vrchat-compatdata-path

smol-sleep-state

sapphire/stay-aligned-setup-no-step-skip

sapphire/steamvr-hands-warning

sapphire/proportions-import-skeleton-request

sapphire/bone-mask-update

llelievr/settings-profiles

bscotch/proguard

bscotch/bvh-fix

mitten

bscotch/reset-proof-tests

hannah/install-from-server

smol-buttons

TheButlah-patch-1

sapphire/update-solarxr

sapphire/kotlin-flatbuffers

csv-data-export

feat_flashmode

bscotch/remove-drift-compensation

llelievr/kotlin-config

bscotch/fix-osc-duplication

llelievr/keep-battery-value

rest-calibration-support

tracker-graph

fingertracking

update-eslint

tauri-android

hide-new-resets

height-config

snap-serial

feat/new-updater

support-inches

vrc-fix-ik-key

llelievr/3dmodel-preview

accel-mapping-fixes

llelievr/manual-proportions-rework

llelievr/put-automatic-steamvr-tracker-assigment-first

llelievr/remove-manual-mounting-onboarding

onboarding-usage-step

oldflex

motion-compensation

kotlin-warnings-fix

accessories

tpose

foxvr

No Label Area: Application Protocol Area: Application Protocol Area: Application Protocol Area: Application Protocol Area: Application Protocol Area: Application Protocol Area: Application Protocol Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: GUI Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Skeletal Model Area: Skeletal Model Area: Skeletal Model Area: Skeletal Model Area: Skeletal Model Area: Skeletal Model Area: Skeletal Model Area: Skeletal Model Area: Skeletal Model Area: SteamVR Driver Area: SteamVR Driver Area: SteamVR Driver Area: SteamVR Driver Area: SteamVR Driver Area: SteamVR Driver Area: SteamVR Driver Area: SteamVR Driver Area: SteamVR Driver Area: SteamVR Driver Area: Translation Area: Translation Area: Translation Area: Translation Area: Translation Area: Translation Area: Translation Area: Translation

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github/SlimeVR-Server#53