App Documentation

VirtualDangle App Documentation

On-device ML puck tracking for stickhandling drills and mini‑games.

Audience: players, parents, coaches.

Quick Start

  1. Requirements
    • Android 7.0+ with OpenGL ES 3.0
    • Rear camera
    • Well‑lit space and a flat surface
  2. Install
    Download and install VirtualDangle from your internal test link or Google Play (when available).
  3. First Launch
    The app creates a “Guest” profile for a quick trial if you haven’t activated a license yet (limited time/modes).
  4. Activate (to unlock full features)
    Settings → License → enter your 4×4 key (e.g., XXXX‑XXXX‑XXXX‑XXXX) → Activate. Online shows “Active”; offline shows “Full version until: ”.
  5. Create a Profile
    Menu → Manage Profiles → Add user (activation required). Profiles track scores and leaderboards.
  6. Start a Game
    Pick a mode → Start. Puck tracking runs on‑device (no internet needed).
  7. Leaderboards (online)
    When activated and online, your sessions and high scores sync automatically.
  8. Basic Tips
    Good lighting, clear surface, steady framing. Adjust Settings if detection/performance needs tuning.
  9. Safety: Be aware of surroundings. Train at your own risk.

Leaderboards

The Leaderboards screen now uses a modern, touch‑friendly horizontal chip selector (Material 3) to choose a game. Above the selector, a summary card shows the “Top 1 per game” for the selected timeframe (Last 7, Last 30, All Time). Below, you’ll see the Top 20 for the selected game. Offline mode falls back to local data.

How to Use

  1. Tap a timeframe tab (Last 7 / Last 30 / All Time).
  2. Select a game via the chips; the selected chip stays highlighted.
  3. Review the “Top 1 per game” summary card, then the Top 20 list for the selected game.

Notes

  • Online: Top lists come from cloud leaderboards and include all users.
  • Offline: Lists come from on‑device history and may be limited to your local data.

Teams

Teams let you view team‑only leaderboards and manage membership. The Teams tab is in the bottom navigation. The initial Teams screen shows your teams (as Material cards) and a Create/Join card at the bottom. Tapping a team opens a detail page with a header card, admin controls (if applicable), timeframe tabs, and a chip selector for games.

Teams List

  • Each team appears as a Material card with its name, member count, and a role chip (“admin” or “member”).
  • Tap a card to open the team’s detail page.

Create / Join

  • Create Team: Provide a name (3–32 chars). You’ll be the admin.
  • Join Team: Enter a join code you’ve received from an admin.

Team Detail

  • Header card shows team name, your role, and join code (admins).
  • Admin actions: reset join code, remove member, or delete team.
  • Leaderboard: time‑range tabs and a game chip selector; list shows Top 20 for the team.

Tips

  • When on multiple teams, the app opens the team you tapped and preserves that selection during navigation.
  • Reselecting the Teams tab (while viewing a team detail) returns to the Teams list.

Detailed Guide

Overview

VirtualDangle uses on‑device machine learning (TensorFlow Lite) to detect your puck in real time, powering drills and mini‑games. It works offline; when online and activated, results sync to cloud leaderboards. Multiple profiles can share one device.

Key Features

  • On‑device ML puck tracking (fast, private, offline)
  • Multiple game modes (reaction, precision, agility)
  • Profiles and local progress
  • Cloud sync + leaderboards (when activated and online)
  • Privacy‑minded design; diagnostics toggle

Supported Devices

  • Android 7.0+ with OpenGL ES 3.0
  • Rear camera required
  • Works best on modern devices with good lighting

Licensing & Activation

  1. Settings → License → enter 4×4 license key → Activate.
  2. Online status: Active. Offline shows: “Full version until: ”.
  3. Screen shows Plan, Max users/device, Device ID, Activation ID.
  4. Check‑in: Tap when you want to refresh entitlement (e.g., after network changes).
  5. Deactivate: Use when moving to a new device.

Profiles

  • Menu → Manage Profiles → add a unique username (requires activation).
  • Switch profiles from the top bar/profile menu.
  • Deleting a profile removes local data and (when online/activated) cloud data; offline deletions are queued.

Game Modes (examples)

  • Basic Light Chase / Fast Light Chase: reaction drills at different paces
  • Light Rain / Dodge Rain: agility under pressure
  • Puck Pong Challenge: precision timing and control
  • Puck Chaser Snake: guide the snake without trapping yourself
  • Stick Handle Short / Long: compact vs extended reach patterns
  • Game Timer: structured session timer

Playing a Game

  1. Select a mode.
  2. Frame the playable area (puck and surface visible).
  3. Press Start; the app detects, tracks, and scores.
  4. Results save locally and sync online if activated and connected.

Settings (Device‑Wide)

Menu → Settings. Defaults shown here reflect current release defaults.

General

Setting Key Default Description / Tips
Enable Autofocus device_enable_autofocus On Camera focuses automatically. For fixed setups, tap preview (where available) to lock focus before a game.
Puck Detection Confidence setting_confidence_threshold 60 Minimum confidence (10–90 → roughly 0.1–0.9). Increase to reduce false positives; decrease if detection is too strict.
Top Playable Area Margin (dp) setting_playable_area_top_margin_dp 10 Adjust the top boundary of the game area to match your surface/camera framing.
Bottom Playable Area Margin (dp) setting_playable_area_bottom_margin_dp 10 Adjust the bottom boundary of the game area.

Audio

Setting Key Default Description / Tips
Enable Sound device_enable_sound On Toggle in‑game sounds.
Master Volume device_master_volume 80 Overall volume level for app sounds.

Performance & Quality

Setting Key Default Description / Tips
Delegate Preference device_delegate_preference nnapi Compute backend. Try NNAPI (default) first. GPU can be faster on high‑end devices; CPU is most compatible.
Model Strength device_model_strength 2 Higher values generally improve accuracy at potential performance cost. Suggested range: 1 (low) to 3 (high).
Analysis Quality device_analysis_quality 2 Balances detection quality vs performance. 1=low, 2=medium, 3=high (device dependent).
Frame Skipping device_frame_skipping 1 Skips frames to reduce CPU/GPU load on slower devices. Higher values lower resource use but reduce responsiveness.

Camera & Display

Setting Key Default Description / Tips
Use Mirror Mode device_use_mirror_mode On Mirrors the view for a more natural perspective in many setups.
Process Inverted Image device_process_inverted_image_directly Off Enable if your camera feed is inverted due to your mounting/orientation.
Show Puck Indicator device_show_puck_indicator Off Displays a visual marker on the detected puck for training clarity.
Show Playable Area Outline device_show_playable_area_debug Off Outlines the area used by the game logic; helpful for setup and camera framing.
Debug Overlay device_enable_debug_overlay Off Advanced visualization of detection internals. Keep off during normal play.
Tip: If detection flickers, try lowering Puck Detection Confidence, increase Model Strength, or raise Analysis Quality. For older devices, increase Frame Skipping.

Troubleshooting

Navigation / Bottom Bar Highlight

  • If the bottom bar doesn’t highlight or seems “stuck” on a tab, update to the latest build (navigation handlers were improved to avoid re‑entrant loops).
  • Reselecting a tab pops to its root (e.g., Teams detail → reselect Teams → Teams list).

Leaderboards chips don’t highlight

  • Update to the latest build. The chip row now recomposes after selection and stays highlighted.

No puck detected / inconsistent detection

  • Improve lighting and reduce glare.
  • Ensure puck contrasts with the surface.
  • Lower Confidence threshold slightly.
  • Increase Model Strength or Analysis Quality if device can handle it.
  • Temporarily enable Debug Overlay to visualize detection.

High battery drain / device gets warm

  • Lower Analysis Quality or increase Frame Skipping.
  • Use NNAPI delegate (default) if GPU causes heat.

Online features not working

  • Check License: Settings → License.
  • Verify internet connectivity.
  • Offline results store locally and sync later when online.

Cannot create a profile

  • Activation is required for non‑Guest profiles.
  • Pick a globally unique username.

“License required or check‑in needed”

  • Settings → License → Check‑in (online).

Reinstall brings back old data

  • The app disables backup restore for prefs/DB to prevent unintended returns after a Wipe. If you previously had device backups, uninstall and delete the old backup once, then reinstall.

FAQ

Does the app stream video?
No. All detection runs on‑device; no camera frames are uploaded.

Do I need internet?
No for playing and local logging. Yes for activation, cloud sync, leaderboards.

Can multiple players use one device?
Yes. Create profiles and switch between them.

What happens if I delete a profile?
Local data is removed. If online/activated, cloud data is removed too. Offline deletes are queued for later.

What does the diagnostics toggle do?
Enables anonymized crash/error reporting; you can turn it off in Settings → Advanced.

Is there a trial?
Yes. A short “Guest” trial is available prior to activation (limited time/modes).

Privacy & Safety

  • Detection is on‑device; no video is uploaded.
  • Only minimal technical data is sent for licensing/sync when online.
  • Diagnostics (if enabled) do not include secrets/PII.
  • Be mindful of surroundings; train at your own risk.

Support

  • Check Troubleshooting above.
  • From the License screen, you can copy Device ID / Activation ID if requested by support.
  • Include your app version (shown during activation/check‑in).
  • Contact: use the support contact listed on the website or in‑app.

Release Notes (October 2025)

  • Leaderboards: Added Material 3 chip selector and “Top 1 per game” summary card for timeframe.
  • Teams: Material card rows; Create/Join panel redesigned as a card; Team detail header card + chip selector.
  • Navigation: Fixed bottom nav highlight and recursion crash; reselect pops to root destinations.
  • Stability: Improved handling when a user is on multiple teams; preserves selected team across navigation.
© VirtualDangle. All rights reserved.