Spinweb — Physics-Based Spinning Top Battler

Spinweb is a 2D side-view, physics-based spinning top battler with a retro pixel-art aesthetic. Built using Phaser 3 and Matter.js, the game integrates the Google Gemini API to generate real-time, context-aware pre-match rivalry trash-talk and post-match esports commentaries.

Developed for the DEV.to Weekend Challenge: Passion Edition.

📸 Game Previews

---

📖 Table of Contents

• Game Overview
• How the Passion Theme is Captured
• Core Features
• Physics & Mathematical Model
• Google AI & Gemini Integration
• Tech Stack
• Installation & Running
• Tuning Constants
• Credits

---

🎮 Game Overview

In Spinweb, players choose their arena and select a signature Beyblade-style behavior (Attack, Defense, or Stamina). Once selected, players release their slingshot launch vectors to shoot their tops into a high-speed clashing stadium, jockeying for center control and avoiding Ring Outs and Sleep Outs using real-time keyboard inputs.

---

🔥 How the Passion Theme is Captured

Spinweb captures the Passion theme through:

1. Intense Obsession/Rivalry: Pre-match trash talk generated dynamically by Gemini AI reflecting the competitive spirit of anime tournaments.
2. Esports Hype Commentary: Post-match comments tailored to the statistics of the match, bringing a high-energy broadcast feel to retro gaming.
3. Heavy Gyroscopic Impact: Sparks, camera shakes, and throttled collision sound effects simulating high-intensity metallic clashes.

---

✨ Core Features

• Pre-Game Setup: Interactive selection screen for Arena Shape (Circle/Rectangle) and Bey Style (Attack, Defense, Stamina).
• Specialized Enemy AI Behavior:
  • Attack (Aggressor): Aggressively pursues the player at $80%$ of player speed.
  • Defense (Tank): Holds coordinates at the absolute center of the arena, forcing you to engage them.
  • Stamina (Evader): Flees away from you, riding the stadium edges to conserve momentum.
• Active Keyboard Controls: WASD or Arrow Keys influence movement, adding active steering agency.
• Dynamic Arenas:
  • Circular Mode: 32-segment static boundary basin with concentric circular overlays and Pythagorean distance checks.
  • Rectangular Mode: Full-screen border colliders with bounding-box limit checks.
• Rich Retro Audio: Sound effects for match launches ("1-2-3-let-it-rip!"), clashing, and game over triggers, styled with rate/pitch randomization.
• Multi-Page Setup: Multi-page layout including the arcade viewport (index.html) and Tailwind CSS styled project documentation card (about.html).

---

📐 Physics & Mathematical Model

The game setting overrides standard gravity to simulate a 3D Beystadium basin on a 2D plane:

1. Gravity Well (Center Pull): Set world gravity to 0 and apply a centripetal force ($F_{well} = 0.0005$) pulling both tops directly toward the center coordinates (320, 180) in the update loop: $$\vec{F} = \text{normalize}(\vec{C} - \vec{P}) \cdot F_{well}$$
2. Exponential Angular Decay: Top stamina is represented by its spin speed ($\omega$). Spin velocity decays exponentially over time using: $$\omega(t) = \omega_0 \cdot e^{-\lambda \cdot dt}$$ where $\lambda$ depends on the selected style (Attack: 0.025, Defense: 0.015, Stamina: 0.008).
3. Kinetic Energy Transfer: Collisions transfer spin energy and apply elastic knockbacks calculated inside a custom resolver:
   • Spins drain upon clashing relative to impact force.
   • Spark particle count scales dynamically with collision magnitude.

---

🤖 Google AI & Gemini Integration

Spinweb integrates the official Google Gen AI SDK for client-side generation:

1. Pre-Match Trash-Talk: Utilizes the gemini-3.5-flash model inside SelectionScene.js to create a short, dramatic quote (max 15 words) before battle.
2. Post-Match Commentary: Queries Gemini on the matchOver event inside UIScene.js, analyzing winner, win method, match duration, and combatant styles. Renders the analysis with a retro character typewriter animation.
3. Graceful Fallbacks & Validation: Validates the API key formatting (ensuring it starts with AIzaSy and is not placeholder). If the key is invalid, the client bypasses the request and cleanly implements fallback text without throwing scary browser console red errors.

---

🛠 Tech Stack

• Phaser 3.87: Scene management, rendering, and graphics drawing.
• Matter.js: Rigid body physics, collision event loops, and velocity solvers.
• TailwindCSS: Aesthetic styling for the credits and documentation card page.
• Vite 6.4: Modern asset pipeline and multi-page entry configurations.
• Google Generative AI SDK: Dynamic commentary.
• ElevenLabs: High-quality retro audio sound effects.

---

🚀 Installation & Running

Prerequisites

• Node.js (v18+)

Steps

1. Clone the Repository:

   git clone https://github.com/Webrizen/spinweb.git
   cd spinweb

2. Install Dependencies:

   npm install

3. Configure API Key: Create a .env file at the root of the project:

   VITE_GEMINI_API_KEY=your_actual_google_api_key

   If left blank or placeholder, the game uses built-in fallback commentators automatically.
4. Run Development Server:

   npm run dev

   Open http://localhost:3000/ in your browser.
5. Build Production Build:

   npm run build

   Generates multi-page output (index.html & about.html) in the /dist directory.

---

⚙️ Tuning Constants

Tuning constants are centralized in src/physics/constants.js:

• OMEGA_INITIAL (40 rad/s): Initial launch spin speed.
• OMEGA_MIN (0.5 rad/s): Sleep Out threshold.
• ACTIVE_CONTROL_FORCE (0.002): Real-time player movement influence force.
• GRAVITY_WELL_FORCE (0.0005): Basins center-pull force scale.
• ARENA_RADIUS (160px): Circle arena radius boundary limit.

---

🏆 Credits

Developed for the DEV.to Weekend Challenge: Passion Edition by Arsh (Webrizen) and the Antigravity AI Pair Programmer.