Block Jam

Inspiration

I was inspired by classic sliding block puzzles like Rush Hour and the satisfaction of mobile matching games. I wanted to combine the logic of spatial puzzles with the visceral satisfaction of "cleaning up" a board. I also saw an opportunity to use Generative AI not just for text, but to create game logic and level design, making a puzzle game that theoretically never runs out of content.

What it does

Color Block Jam is a grid-based puzzle game.

• Core Loop: Players drag multi-cell blocks (1x1, 1x2, 2x2, etc.) along their specific axes (horizontal or vertical) to navigate them towards walls of the matching color.
• Mechanics: When a block hits a matching wall, it gets "shredded" and removed from the board. The goal is to clear specific blocks or the whole board before the timer runs out.
• AI Levels: It uses the Google Gemini API to generate valid, solvable JSON level structures on the fly, ensuring infinite replayability.
• Level Editor: Players can build their own puzzles using a drag-to-paint interface and save them locally.
• Economy: A complete game loop with coins, heart regeneration, and unlockable power-ups (Rocket, Hammer, Vacuum, Freeze) to help solve difficult layouts.

How I built it

I built the application using React and TypeScript for the core logic and component structure.

• UI/UX: I used Tailwind CSS for rapid styling and a modern, dark-mode aesthetic. Framer Motion handles all the complex animations, including the smooth block dragging physics, the "shredding" exit effects, and UI transitions.
• AI Integration: I integrated the Google Gemini API (gemini-3-flash-preview) to act as a level designer. I engineered specific prompts to force the AI to return strictly typed JSON that adheres to the game's physics rules (e.g., ensuring blocks fit through exits and puzzles are enclosed).
• State Management: I utilized React hooks and LocalStorage to persist player progress, inventory, currency, and custom levels without a backend database.

Challenges I ran into

• AI Hallucinations: Initially, Gemini would generate levels with blocks trapped inside walls or grids that were mathematically impossible to solve. I had to refine the system instructions and implement a client-side validation layer (ensureExits) to sanitize the AI's output.
• Collision Detection: Implementing grid-based collision detection while allowing for smooth, pixel-based dragging via Framer Motion was tricky. I had to calculate "snap points" and look-ahead logic to prevent blocks from phasing through each other during rapid movements.
• Responsive Design: Making the grid scale correctly across different mobile and desktop screen sizes while keeping the touch targets accessible required careful CSS calculations.

Accomplishments that I'm proud of

• The "Feel": I'm really proud of the tactile feel of the game. The sound effects, the haptic-like animations, and the "shredding" visual when a block exits make the gameplay loop very satisfying.
• The Level Editor: Building a fully functional editor where users can "paint" walls and drag to create blocks was a complex UI challenge that turned out very intuitive.
• Seamless AI: The transition between levels feels magic; the game generates a new complex puzzle in seconds, making it feel like a professionally curated endless mode.

What I learned

• Prompt Engineering for Logic: I learned that asking an LLM for "JSON" isn't enough; you have to define the "physics" of the desired output in the prompt to get playable game levels.
• Advanced React Patterns: I deepened my understanding of useRef for tracking drag deltas and optimizing rendering performance in a game loop.
• Game Juice: I learned how crucial "juice" (particles, screen shake, sounds) is to turning a dry logic puzzle into an engaging game.

What's next for Block Jam

• Global Leaderboards: Moving from local mock data to a real database (Firebase/Supabase) to track daily/weekly high scores.
• Social Sharing: Generating shareable codes for user-created levels so friends can challenge each other.
• New Mechanics: Adding teleporters, color-changing tiles, and multi-color blocks to increase difficulty.

Built With

• canvas-confetti
• framer-motion
• google-gemini-api
• lucide-react
• react
• tailwind-css
• typescript
• vite