Block Puzzle 10x10

A premium, fully offline, single-player block puzzle game built with React Native and Expo. Designed for performance, aesthetics, and pure gameplay focus without the distractions of ads or monetization.

---

🎮 Gameplay & Features

The Goal: Drag and drop blocks onto the 10x10 grid to create full rows or columns. Cleared lines score points and free up space. The game ends when no available pieces fit on the board.

Key Features

• Arcade Aesthetic: Polished visual theme with selectable Dark/Light modes.
• Improved UX: Pieces center under your finger automatically with a vertical offset for visibility, accompanied by a precise "ghost" shadow on the grid.
• Sensory Feedback: Rich haptic feedback patterns (via expo-haptics) and custom sound effects for satisfying interaction.
• State Persistence: Your game is saved instantly. Close the app and resume exactly where you left off.

🚀 Power-Ups

Strategize with 5 unique game-changing abilities:

1. Undo: Made a mistake? Revert your last move instantly.
2. Rotate: Rotate all current pieces in the tray 90° clockwise.
3. Discard: Remove a difficult piece from your tray to get a new set sooner.
4. Force Place: Smash a piece onto the board, overwriting any existing blocks.
5. Add Single: Spawn a flexible 1x1 block to fill tight gaps.

---

🛠 Tech Stack

Built with a focus on Clean Architecture and Performance.

Layer	Technology	Description
Core	Expo (SDK 54)	Managed workflow for cross-platform stability.
Logic	TypeScript	Pure, dependency-free game engine (src/engine).
State	Zustand	Lightweight store for reactive state and actions.
UI	NativeWind	Utility-first styling (Tailwind CSS) for React Native.
Motion	Reanimated 3	60fps+ animations running on the UI thread.
Gestures	Gesture Handler	Native-driven drag-and-drop interactions.
Storage	AsyncStorage	robust local persistence for game state.
Testing	Jest + RNTL	Comprehensive Unit and Integration testing (>90% coverage).

---

📂 Project Structure

src/
├── components/         # Atomic UI components
│   ├── Grid/           # Board rendering (Memoized)
│   ├── Piece/          # Draggable and Ghost pieces
│   ├── PieceTray/      # Selection area
│   └── UI/             # HUD, Modals, Score
├── engine/             # PURE LOGIC (No React deps)
│   ├── board.ts        # Grid validation & clearing
│   ├── pieces.ts       # Canonical shapes
│   └── scoring.ts      # Score calculation
├── hooks/              # Reusable React logic (Sensory, Theme)
├── screens/            # Route controllers (Game, Settings)
├── store/              # Zustand state & persistence
├── styles/             # Global theme tokens
└── utils/              # Haptics, Audio, Math helpers

---

⚡️ Getting Started

Prerequisites

• Bun (Recommended) or Node.js
• Expo Go app on your mobile device

Installation

1. Clone the repository:

   git clone <repo-url>
   cd block-puzzle

2. Install dependencies:

   bun install

3. Start the development server:

   bun start

   Scan the QR code with your iPhone (Camera) or Android (Expo Go).

---

🧪 Testing

This project follows a strict Test-Driven Development (TDD) workflow.

Running Tests

Run all unit and integration tests

bun x jest

or

npm run test

Run tests in watch mode

bun x jest --watch

or

npm run test:watch

Generate coverage report

bun x jest --coverage

or

npm run test:coverage

Coverage Targets

• Global: >80% (Currently ~96%)
• Critical Paths: 100% (Engine logic, State management)

---

📄 License

Private & Confidential All rights reserved. Unauthorized copying or distribution is strictly prohibited.