1. Executive Summary
Velocity Vault is a high-precision physics puzzle game for Android. The player controls the trajectory of a ball on a flat board, aiming to bounce it into a designated hole. The core loop revolves around "Catching" the ball at the bottom paddle and "Launching" it with variable force and curvature.
Note for AI Agent: Prioritize high-fidelity physics (collision, friction, restitution) and responsive touch input. The game must run smoothly at 60fps on Android devices using a web-based wrapper or native JS engine.
2. Core Gameplay Mechanics
2.1 The Launch Sequence
- Starting Position: The ball rests on a paddle located at the bottom center of the screen.
- Trajectory Swipe: Players touch the ball and swipe upward.
- Vectoring: The angle of the swipe determines the initial direction.
- Force/Pressure: Velocity of the swipe (pixels per millisecond) and total distance dragged determine the launch speed.
- Curvature: If the player curves their finger during the swipe, a "curve force" is applied to the ball's trajectory upon release.
2.2 The "Magnetic Catch" System
- Catch Zone: A thin horizontal strip at the bottom of the board (around the paddle area).
- Interaction: When the ball enters this zone, it does not immediately bounce off the bottom wall. Instead, if the player is touching the screen and moving their finger along the X-axis, the ball becomes "magnetized" to their touch.
- Re-Launch: Once caught, the player can immediately perform another Launch Sequence from their current horizontal position.
2.3 Win/Loss Conditions
- Win (Goal): The ball enters the hole. Reward: +5 Points and progression to next level.
- Loss (Death): The ball exits the screen via the bottom edge (missing the paddle/catch zone).
- Result: Level resets or Game Over depending on life count.
3. Level Progression & Difficulty
| Level Range |
Hole Behavior |
Ball Physics |
Challenge Level |
| 1 - 20 |
Static position. |
Standard speed/friction. |
Introductory |
| 21 - 40 |
Moves once upon the player catching a missed ball. |
Standard speed. |
Intermediate |
| 41 - 60 |
Moves multiple times during the ball's flight/catch cycle. |
Slightly increased velocity. |
Advanced |
| 61+ |
Rapid, erratic positioning; smaller hole radius. |
Ramped up speed; lower friction (slippery). |
Expert
4. UI & User Experience
4.1 Screen Flow
- Splash Screen: Logo, Developer Name, "Loading" bar.
- Main Menu:
- Play (Start/Resume)
- Options (Sound, Theme, Sensitivity)
- Leaderboard (High Scores)
- Exit
- Game Screen: HUD showing Current Level, Score, and a Pause button.
- Pause Menu: Resume, Restart Level, Main Menu.
- Level Complete/Fail: Summary of points earned, "Next Level" or "Try Again" buttons.
4.2 Themes & Visuals
The game should support Themes that change the colors of the board, ball, and hole (e.g., Neon Night, Minimalist White, Deep Sea). These are selectable in the Options menu.
5. Technical Specifications
5.1 Audio Requirements
- Music:
- Menu Theme: Calm, looping ambient track.
- Gameplay Theme: High-energy, rhythmic track that increases in tempo/intensity after Level 60.
- Sound Effects (SFX):
sfx_launch: A "woosh" or spring sound.sfx_bounce: a crisp, metallic "clink."sfx_catch: A magnetic "snap" or suction sound.sfx_goal: A satisfying chime/celebratory sound.sfx_death: A low-frequency thud or glass break.
5.2 Development Stack Recommendation
- Language: HTML5, CSS3, JavaScript (ES6+).
- Physics Engine: Matter.js or P2.js for realistic collisions and restitution.
- Rendering: Canvas API or Phaser 3 Framework.
- Android Packaging: Capacitor or Cordova to wrap the HTML/JS into an APK.
- Offline Capability: Use a Service Worker (PWA) or local asset bundling for offline play.
6. Refined Function List for AI Implementation
The AI Agent should implement the following specific functions:
calculateTrajectory(touchStart, touchEnd, velocity): Converts swipe data into a physics vector.checkMagneticCatch(ballPosition, playerTouchX): Determines if the ball is within the catch zone and aligned with the finger.updateHolePosition(level, state): Handles the logic for hole movement based on the level brackets defined in Section 3.applyTheme(themeConfig): Updates CSS variables and Canvas colors dynamically.saveProgress()`: LocalStorage implementation to save current level and high score.