Getting Started

Space Preparation

For the best experience, ensure you have:

• Good Lighting: Bright, even lighting helps the AI track the puck. Avoid harsh glares.
• Flat Surface: A smooth floor or shooting pad where the puck can slide freely.
• Contrast: A puck that stands out from your floor surface (e.g., black puck on white ice/pad).
• Clear Area: Remove obstacles and ensure you have enough space to move comfortably.

Device Setup

Position your device using a phone or tablet holder. Choose one of the following two setups:

Option A: Using a Mirror (Recommended)

This setup allows you to view the screen while the rear camera tracks your puck movement - perfect for extended training sessions. Follow these steps carefully:

Step-by-Step Mirror Setup:

1. Step 1 - Attach the Mirror: IMPORTANT: Loosely secure the wingnut - do not overtighten it at this stage. The clamp should be stable but allow for adjustment.

Step 1: Attach the mirror with the wingnut lightly snug (do not overtighten)
2. Step 2 - Position the Mirror: Place the mirror attachment so it sits securely on the bottom of the clamp. Verify that the mirror is properly seated and stable before proceeding.

Step 2: Mirror positioned on the bottom of the clamp
3. Step 3 - Mount Your Device: Place your phone or tablet onto the mount on top of the mirror's bar. CRITICAL: Ensure the rear camera is positioned to look directly at the mirror's reflective surface. This allows the camera to see the floor while the screen faces you.

Step 3: Device mounted with rear camera aligned to mirror surface
4. Step 4 - Final Adjustment: Make any final angle adjustments. The device screen should face you comfortably while the rear camera has a clear view of the floor through the mirror reflection.

Step 4: Complete setup - screen facing you, camera viewing floor via mirror

Option B: Direct View + TV Connection

• Position the device so the camera looks directly at the floor.
• Connect directly to TV via HDMI cable so you can see the targets while training.
• Preferred over casting to avoid slight millisecond delays.
• Works well for home setups with smart TVs.

First Launch

When you open VirtualDangle for the first time:

1. The app creates a "Guest" profile automatically
2. Guest profile provides limited time and game modes for trial
3. Unlock full features by activating your license (see Licensing & Activation below)
4. You can play immediately without activation to test the app

Platform Information

Android

• Android 7.0+ (API 24) with OpenGL ES 3.0
• Google Play Store
• Rear camera

iOS

• iOS 17.0+
• Apple App Store
• Rear camera, A11 Bionic+ recommended

Cross-Platform

• Same game modes and features
• Profiles, leaderboards, teams sync automatically
• License keys work on both platforms

Game Modes

Leaderboards

Time Filters

• Last 7 Days: Recent competition
• Last 30 Days: Medium-term tracking
• All Time: Ultimate leaderboards

Using Leaderboards

1. Navigate to Leaderboards tab
2. Select timeframe tab
3. Use horizontal chip selector for game mode
4. View Top 1 summary card at top
5. Scroll for Top 20 list

Teams

Teams Features

• Create teams (3-32 character names)
• Join teams with unique codes
• Team-only leaderboards
• Up to 20 members per team
• Each user can join 5 teams

Roles

Admin

• Reset join code
• Remove members
• Delete team

Member

• View leaderboards
• See member list

Profiles

Creating Profiles

The app will automatically prompt you to create your first profile after activation. Additional profiles can be created in Manage Profiles.

Username Requirements

• Must be globally unique across all VirtualDangle users
• Appears on all leaderboards
• Cannot be changed after creation

Profile Data

• High scores per game mode
• Recent scores
• Total playtime
• Session history

Deleting Profiles

• Tap and hold on profile
• Confirm deletion
• Local and cloud data removed (when online)

Licensing & Activation

License Key Format

16 characters: XXXX-XXXX-XXXX-XXXX (case-insensitive)

How to Activate

1. Go to Settings → License
2. Enter key
3. Tap Activate while online

License Statuses

• Active: Online with valid license
• Full version until [date]: Offline grace period
• Guest Mode: Limited trial features

Device Limits

• Each license has max device activations
• Deactivate old devices before new ones
• One activation per device (any OS)

Model Benchmarking

Why Benchmark?

• Different devices have vastly different capabilities
• Optimal settings vary significantly by hardware
• Customized settings give best experience
• Ensures smooth, responsive gameplay
• The staggering number of different devices requires testing multiple models to find the best fit

Performance Targets

• Recommended: 30fps+ for smooth, responsive gameplay
• Minimum: 25fps+ acceptable, may feel slightly less smooth
• Below 25fps: Not recommended, consider using simpler model

Model Types (Low to High Accuracy)

Models are organized from fastest/least accurate to slowest/most accurate:

By Model Tier (Speed vs Accuracy):

• Lite: Fastest performance, good for older devices (Lite Ultra Low, Lite Low, Lite Med)
• Base: Balanced performance and accuracy (Base models)
• Max: Best accuracy, requires powerful device (Max models)

Within Each Tier (Accuracy Levels):

• Ultra Low: Lowest accuracy, fastest speed
• Low: Low accuracy, good speed
• Med: Medium accuracy, medium speed
• High: High accuracy, slower speed

Type1 vs Type2:

• Type1: Standard model
• Type2: Improved model - better than Type1 at same FPS

Delegate Options:

• GPU First: Fastest acceleration for most Android devices
• NNAPI First: Balanced performance on Android
• CPU Only: Most compatible, slower but reliable
• iOS Neural Engine: Optimized delegate for Apple devices (iOS equivalent to GPU First)

How to Run Benchmark

1. Go to Settings → Advanced
2. Tap "Benchmark Models"
3. Tap "Start Benchmark"
4. Wait for benchmark to complete (takes a few minutes)

Understanding Results

After benchmarking completes, you'll see a list of all models with their real FPS results. Higher fps = better performance.

Selecting the Best Model

1. Look at the FPS results for each model
2. Start with the highest-accuracy model (Max High Type2)
3. Work down through accuracy levels: High → Med → Low → Ultra Low
4. Then try different model tiers: Max → Base → Lite
5. Find a model that meets your target (30fps+ recommended, 25fps+ minimum)
6. Prefer Type2 over Type1 when performance is similar
7. Try different delegates if needed - best balance varies by device
8. Tap to select that model in Settings

The app will use this model for all games.

Settings Guide

Core Gameplay

Enable Autofocus (Default: On)

Camera auto-focuses. Turn off only for fixed setups with drifting focus.

Puck Detection Confidence (Default: 60)

Range 10-90. Lower = more sensitive, Higher = fewer false positives.

Enable Sound / Master Volume

Toggle game sounds and adjust volume level.

Model Strength (Default: Base Med Type1)

Select ML model. Lite = fastest, Base = balanced, Max = most accurate. Type2 is better than Type1.

Delegate Preference (Default: NNAPI First)

GPU First = fastest acceleration, NNAPI First = balanced, CPU Only = most compatible. iOS uses Neural Engine automatically.

Shield Mode (Default: Off)

Hides camera feed, shows only puck indicator. Forces reliance on peripheral vision and puck "feel".

Ghost Mode (Default: Off, requires Shield Mode)

Faint, blinking puck indicator. Forces reliance on prediction and muscle memory. Very challenging!

Visual & Display

Use Mirror Mode (Default: On)

Enable when using mirror attachment. Disable for direct camera view.

Show Puck Indicator (Default: Off)

Shows circle on detected puck. Used for troubleshooting only.

Show Playable Area Outline (Default: Off)

Shows border of game area. Used for camera setup.

Debug Overlay (Default: Off)

Shows detection internals. Advanced troubleshooting only.

Detection Upgrades

• Anti-Jitter: Consistent detection across frames (keep On)
• Weighted Selection: Prioritizes near last position (keep On)
• Geometric Filtering: Filters by shape/size (keep On)
• Edge Filtering: Stricter edge checks (keep On)
• Kalman Filter: Physics-based smoothing (try for smoother motion)

Performance

Frame Skipping (Default: 1)

1 = smoothest, 4 = best performance. Increase only if experiencing lag.

System

Share Crash Reports and Diagnostics (Default: On)

Anonymous error logs to help improve app. No personal data.

Reset All Settings

Restores defaults. Preserves profiles, scores, license.

Wipe App Data

Deletes everything. App restarts as fresh install. Cannot be undone!

Troubleshooting

Puck Detection Issues

Puck Not Detected

• Check lighting (bright, even, no glare)
• Improve contrast between puck and surface
• Lower detection threshold
• Enable puck indicator to see what app detects

Inconsistent Detection

• Reduce glare and shadows
• Stabilize device position
• Keep all detection upgrades On
• Try Kalman filter

False Detections

• Raise detection threshold
• Clear area of other objects
• Improve lighting
• Keep edge and geometric filtering On

Performance Issues

App Crashes

• Run benchmark to find compatible model
• Try CPU Only delegate
• Increase frame skipping
• Switch to simpler model
• Restart device
• Check storage space

Laggy Performance

• Run benchmark to find better model
• Increase frame skipping
• Use simpler model
• Try CPU Only delegate
• Close other apps
• Disable power-saving mode

High Battery Drain

• Increase frame skipping
• Use CPU Only delegate
• Shorter training sessions
• Use simpler models

Online Features

Leaderboards Not Updating

• Check internet connection
• Verify license is Active
• Check In to refresh status
• Wait a moment after game completion

Scores Not Syncing

• Check internet connection
• Verify license is activated
• Check In to refresh
• Offline data syncs when online

Profile Issues

Cannot Create Profile

• Check license is activated for named profiles
• Choose globally unique username
• Check internet connection for validation
• Try different username if taken

FAQ

General Questions

Does the app stream video to the internet?

No. All puck detection happens entirely on your device. No camera frames are ever uploaded.

Do I need internet to use the app?

For playing games and tracking progress locally, no internet required. Internet is needed for activation, cloud sync, and leaderboards.

Can multiple players use one device?

Yes! Create separate profiles for each player. Each profile tracks its own scores and stats independently.

Is VirtualDangle available on iOS?

Yes! VirtualDangle is available on both Android and iOS with full feature parity.

Technical Questions

What device do I need?

Android 7.0+ with OpenGL ES 3.0 or iOS 17.0+ with rear camera. Older devices may struggle with performance.

How do I set up my device?

Use a mirror attachment (available at virtualdangle.com) so the camera sees the floor while the screen faces you. Enable "Mirror Mode" in Settings. Alternatively, connect directly to TV via HDMI for direct view setup.

Licensing Questions

How do I activate my license?

Go to Settings → License, enter your 16-character license key, and tap Activate while connected to the internet.

Can I switch my account between devices?

No. Accounts are tied to devices. If you remove your account from a device, all users and data on that device are permanently deleted.

Privacy & Safety

Privacy

• All puck detection happens entirely on your device
• No camera frames are ever uploaded to the internet
• Diagnostics are anonymous and contain no personal data
• You can delete all your data at any time

Safety

• Clear your training area of obstacles
• Secure your device properly to prevent falls
• Take breaks to avoid fatigue and eye strain
• Use proper stickhandling technique

Support

Getting Help

• Read through this documentation thoroughly
• Check the Troubleshooting section
• Review the FAQ section

Contacting Support

When contacting support, include:

• Device ID: Found in Settings → License
• Activation ID: Found in Settings → License
• App Version: Found in Settings → About
• Issue Description: Detailed description of the problem

Support Channels

• Email: virtualdangle@gmail.com
• Website: virtualdangle.com