🔩 Steel Target Simulator

📧 Email: admin@ballisticstoolkit.com
💻 GitHub: github.com/chasep255/BallisticsToolkit

Spotting Scope (Bottom-Left):
- WASD Pan camera (always active, no pointer lock needed)
- E/Q Zoom in/out (4× to 40× magnification)
- Movement scales with FOV (slower when zoomed in)
- Use to observe targets, wind flags, and shot impacts
- No reticle (clean view for observation)

Rifle Scope (Bottom-Right):
- Click inside the scope circle to enter scope mode (pointer lock activates)
- Move mouse to pan/aim the scope (reticle moves with cursor at 1:1 speed)
- Mouse Wheel or +/- Zoom in/out (4× to 40× magnification)
- Click to fire bullet from scope crosshair
- F refocus rifle scope at center crosshair distance (requires Experimental Optical Effects to be enabled)
- Shift+F refocus spotting scope at center distance (requires Experimental Optical Effects to be enabled)
- Esc to exit scope mode (releases pointer lock)
- FFP reticle scales with zoom (maintains MRAD subtensions)

Dial Controls:
- ArrowUp/ArrowDown dial elevation up/down (0.1 MRAD or 0.25 MOA per press; hold Shift for 1.0 MRAD or 1.0 MOA) - requires scope mode
- ArrowLeft/ArrowRight dial windage left/right (0.1 MRAD or 0.25 MOA per press; hold Shift for 1.0 MRAD or 1.0 MOA) - requires scope mode
- R reset both dials to zero (only when in rifle scope mode)
- On-screen dial buttons (U/D/L/R/⟲) next to HUD - click or hold to fast-dial, works anytime
- Dial position shown in HUD (upper-left) in the selected scope type units

Both Scopes:
- Single-finger drag: Pan the scope view
- Pinch: Zoom in/out (4× to 40× magnification)

Rifle Scope:
- Tap: Fire a shot (quick tap < 150ms)
- Long press (≈ 450ms) with minimal movement: Refocus scope at the point where you press (requires Experimental Optical Effects to be enabled)

Dial Buttons (on-screen, next to HUD):
- U/D: Adjust elevation up/down (0.1 MRAD or 0.25 MOA per tap, hold to fast-dial)
- L/R: Adjust windage left/right (0.1 MRAD or 0.25 MOA per tap, hold to fast-dial)
- ⟲: Reset both dials to zero
- Units depend on selected Scope Type (MRAD or MOA)

Fullscreen:
- Use the Fullscreen button for immersive mobile play
- Canvas automatically adapts to your screen's aspect ratio
- Only works in landscape orientations
- Note: Fullscreen may not work on all devices, especially iOS Safari. Desktop and Android work best.

- Start: Initialize the simulator and begin shooting
- Restart: Restart the simulator with current parameters
- Help: Show this help dialog
- Fullscreen: Enter fullscreen mode (also starts the game if not started). Canvas adapts to screen aspect ratio. May not work on iOS Safari.
- Settings are automatically saved and restored using cookies on reload

Target Racks: Multiple target racks positioned from 100 to 1760 yards (1 mile) with various target sizes and configurations. Targets include both rectangular and oval shapes with sizes ranging from ~2" chips up to large ~6‑ft gongs, roughly spanning 0.5–2+ MOA depending on distance and rack configuration.

Chain Mounting: Each target has two chains attached at the top, connecting to an overhead beam. Chains act as damped springs (10,000 N/m spring constant, 200 N·s/m damping) that dissipate energy to prevent bouncing.

Impact Physics: Bullet impacts transfer momentum to targets. Center hits cause mostly linear motion; edge hits create rotation. Smaller targets respond more dramatically than larger ones. Linear damping (75% velocity per second) and angular damping (10% angular velocity per second) simulate air resistance and friction.

Prairie Dogs: Scattered across the range from 100 to 600 yards, prairie dogs pop up from their burrows as hunting targets. Each prairie dog is approximately 16 inches tall and partially visible above its dirt mound when raised.

Behavior: Prairie dogs randomly pop up and down throughout the simulation, spending roughly 30% of their time raised and 70% lowered. Each state lasts between 5-90 seconds before changing.

Hit Effects: When hit, prairie dogs react with a quick upward jump before dropping back into their burrow, accompanied by a red mist effect. Killed prairie dogs respawn after approximately 1 minute.

Starting State: Each prairie dog starts in a random position (up or down) at the beginning of a session.

Bullet:
- MV: Muzzle velocity in fps (critical for trajectory and time-of-flight)
- BC: Ballistic coefficient (aerodynamic efficiency, higher = less drift/drop)
- Drag Function: G7 (modern boat-tail) or G1 (flat-base/older)
- Diameter: Bullet diameter in inches (affects spin calculations)
- Weight: Bullet weight in grains (for spin moment of inertia)
- Length: Bullet length in inches (for spin calculations)
- Twist: Barrel twist rate in inches per turn (e.g., 8 for 1:8 twist, calculates spin rate)

Rifle:
- MV σ: Muzzle velocity standard deviation in fps (lower = more consistent, typical values: 5-15 fps)
- Accuracy: Rifle+shooter precision in MOA (1 MOA ≈ 1" at 100 yards)
- Zero Distance: Distance at which the rifle is zeroed in yards (commonly 100 yards; a dedicated 100‑yard rack is included)
- Scope Height: Height of the scope above the bore in inches

Spin Effects:
- Spin drift and crosswind jump are modeled based on bullet spin rate calculated from barrel twist and muzzle velocity
- Spin rate is recomputed for each shot based on actual muzzle velocity (accounting for MV variation)

Variability:
- Each shot has slightly different muzzle velocity (from MV σ) and accuracy errors (from rifle accuracy setting)
- These simulate real-world shot-to-shot variability

Zeroing:
- Rifle is zeroed at the configured distance with scope height compensation
- Zeroing calculates the initial launch angle needed to hit the target point-of-aim at zero distance

Wind:
- Wind presets (selected in the UI) control atmospheric conditions affecting bullet trajectory throughout the full 3D flight path
- Wind flags along the range show wind direction and intensity at multiple distances
- Wind affects bullet trajectory, not just dust particles

Impact Marks: Bullet impacts appear as splatter marks on the target texture, with metal showing through the red paint on the side that was hit.

Dust Effects: Metallic dust particles (silver-gray) fly back when hitting targets. Brown dust clouds appear when missing and hitting the ground. Particles fade out over time.

Audio: Shot sounds play immediately on fire. Impact sounds (ping) play with distance-based delay and volume attenuation (full volume at 100 yards, fading to 10% at max range).

Experimental Optical Effects:
- Toggle via the \"Experimental Optical Effects\" checkbox in the settings bar (off by default).
- Enables physically-inspired depth-of-field blur and scope optics (56mm objective, zoom-dependent DOF).
- Desktop: Use F/Shift+F to refocus rifle/spotting scopes at the center crosshair distance.
- Mobile: Long-press inside a scope (≈ 450ms, minimal movement) to refocus at the point where you press.
- Increases GPU load; turn off on low-power or thermally constrained devices.

Technical Details:
- Uses a thin-lens circle of confusion (CoC) model for physically accurate depth-of-field blur.
- Lens parameters: 56mm objective diameter, focal length and f-number derived from scope FOV/zoom.
- Blur radius calculated from CoC using: CoC = |(F²/(N·(df-F)))·((d-df)/d)| where F=focal length, N=f-number, df=focus distance, d=object distance.
- Implements separable Gaussian blur (horizontal then vertical passes) for performance (O(2n) vs O(n²)).
- Depth texture captured from scene render, decoded using THREE.js perspective depth reconstruction.
- Default focal distance: 100 yards. Blur strength scales with zoom level (higher zoom = stronger blur).
- Resolution-independent blur calculation ensures consistent appearance across different screen sizes.

HUD Text:
- Elevation: Current elevation dial setting (U = up, D = down)
- Windage: Current windage dial setting (R = right, L = left)
- Impact Status: Shows "IMPACT" (green) when hitting targets, "MISS" (red) when missing
- Units displayed depend on selected Scope Type (MRAD or MOA)

Dial Buttons (next to HUD):
- U/D elevation, L/R windage, ⟲ reset
- Tap for single adjustment (0.1 MRAD or 0.25 MOA), hold for fast-dial
- Shift+arrow keys move 1.0 MRAD or 1.0 MOA increments

Physics Engine:
- Custom rigid body physics in C++ (WebAssembly) with quaternion-based orientation for stable rotations
- Targets use momentum transfer with linear and angular damping

Rendering:
- 3-pass composition system: background scene renders to texture, scope renders independently with zoom, then composited with reticle overlay
- Three.js WebGL with 4× MSAA anti-aliasing
- Vertex positions computed in C++ and transferred via typed memory views

Scope Reticle:
- Geometry-based reticle using Three.js meshes
- FFP behavior scales with zoom, maintaining angular subtensions
- Scope Type: Select MRAD or MOA in the settings bar to change reticle tick spacing and dial units
- MRAD mode: 0.5 MRAD minor ticks, 1.0 MRAD major ticks
- MOA mode: 2.0 MOA minor ticks, 4.0 MOA major ticks
- Dial click values and HUD display units match the selected scope type

Impact Detection:
- Spatial binning system (10m bins) for efficient collision detection
- Raycasting from trajectory path detects target intersections
- Impact points converted to local target coordinates for physics and texture drawing
- No collision detection between targets (simplified physics)

Texture System:
- Targets use double-width texture buffer: front face UVs map to left half (0-0.5), back face to right half (0.5-1.0)
- Allows impacts to appear on the correct side

Chain Model:
- Chains modeled as damped springs without mass or realistic chain link physics
- Cannot go slack or wrap around objects

- Start with the 100-yard rack to confirm your zero
- Use wind flags at multiple distances to read wind gradients
- Watch target movement after impacts to understand hit location (center vs edge)
- Make small dial adjustments (0.1 MRAD or 0.25 MOA increments) for precise corrections
- Use Shift+Arrow keys for larger adjustments (1.0 MRAD or 1.0 MOA) when needed
- Select your preferred Scope Type (MRAD or MOA) in the settings bar - affects reticle spacing and dial units
- Higher BC bullets drift less in the wind
- Lower MV σ = more consistent impacts
- Practice at shorter distances before attempting 1760 yards (1 mile)
- Use the HUD to track your dial settings and impact status