react-native-games 0.7.0 → 1.0.0

package/README.md

@@ -1,17 +1,369 @@
 # 🎮 react-native-games
 
-**react-native-games** is a collection of free, high-performance games for your React Native projects. Built with modern React Native technologies including Skia, Reanimated, and TypeScript for smooth 60fps gameplay.
+**react-native-games** is a collection of 14 high-performance games for your React Native projects. Built with modern React Native technologies including Skia, Reanimated, Gesture Handler and TypeScript for smooth 60fps gameplay across iOS, Android, and Web platforms.
+
+<table style="border: none;">
+<tr style="border: none;">
+<td width="33%" style="border: none; vertical-align: top;">
+
+### 🚀 High Performance
+- 60fps gameplay with React Native Skia
+- Optimized animations using Reanimated 3
+- Delta time physics loops
+- React.memo optimizations
+- Minimal re-renders with direct store subscriptions
+
+</td>
+<td width="33%" style="border: none; vertical-align: top;">
+
+### 📱 Cross-Platform
+- iOS, Android, and Web support
+- Consistent performance across platforms
+- Responsive design for all screen sizes
+- Dynamic offset handling for notches
+- Adaptive UI components
+
+</td>
+<td width="33%" style="border: none; vertical-align: top;">
+
+### 🎵 Rich Audio & Haptics
+- Sound effects and speech synthesis
+- Haptic feedback for immersive experience
+- Configurable audio settings
+- Per-game sound customization
+
+</td>
+</tr>
+<tr style="border: none;">
+<td width="33%" style="border: none; vertical-align: top;">
+
+### 🎯 Customizable
+- Multiple difficulty levels
+- Adjustable game parameters
+- Persistent settings storage
+- Unified settings interface
+
+</td>
+<td width="33%" style="border: none; vertical-align: top;">
+
+### 🎮 Game Features
+- Physics simulation and collisions
+- Particle systems and visual effects
+- Procedural generation (mazes, obstacles)
+- Score systems and achievements
+- Progressive difficulty scaling
+
+</td>
+<td width="33%" style="border: none; vertical-align: top;">
+
+### 🛠️ Developer Friendly
+- TypeScript support throughout
+- Shared components (GameControlButton, ScoreBoard)
+- Consistent API across all games
+- Easy integration and customization
+- Comprehensive documentation
+
+</td>
+</tr>
+</table>
 
 ## 🎯 Available Games
 
-| Game | Description | Features |
-|------|-------------|----------|
-| **🐱 Whack A Mole** | Whack cute cats popping from holes - fast reflexes needed! | Multiple difficulty levels, customizable grid sizes, haptic feedback |
-| **🫧 Popit Fidget** | Pop satisfying bubbles in this relaxing fidget toy game | Relaxing gameplay, colorful bubbles, different shapes |
-| **🍎 Fruit Ninja** | Slice flying fruits with finger swipes - avoid the bombs! | Physics-based slicing, particle effects, combo system |
-| **🧩 Maze Runner** | Navigate ball through mazes using tilt and physics controls | Dynamic maze generation, physics controls, multiple difficulties |
-| **🚀 Space Fighter** | Pilot spaceship through asteroid fields in endless space | 3D-style graphics, progressive difficulty, space physics |
-| **🎈 Balloon Blaster** | Pop rising balloons before they escape - quick taps win! | Physics-based gameplay, particle effects, combo system |
+<table>
+<tr>
+<td width="50%" style="vertical-align: top;">
+<table style="border: none;">
+<tr style="border: none;">
+<td width="120" style="vertical-align: top; border: none;">
+<img src="https://cdn.worklage.com/playtura/screenshots/fruit-ninja.png" alt="Fruit Ninja" width="100"/>
+</td>
+<td style="vertical-align: top; border: none;">
+
+**🍎 Fruit Ninja**  
+Slice flying fruits with finger swipes - avoid the bombs!
+
+• Fixed 60-second gameplay sessions  
+• Physics-based slicing with particle effects and combo system  
+• Difficulty affects fruit spawn rate and bomb frequency
+
+</td>
+</tr>
+</table>
+</td>
+<td width="50%" style="vertical-align: top;">
+<table style="border: none;">
+<tr style="border: none;">
+<td width="120" style="vertical-align: top; border: none;">
+<img src="https://cdn.worklage.com/playtura/screenshots/candy-crush.png" alt="Candy Crush" width="100"/>
+</td>
+<td style="vertical-align: top; border: none;">
+
+**🍬 Candy Crush**  
+Match colorful candies in this puzzle game
+
+• Match-3 puzzle with colorful candies  
+• Create special candies with 4+ matches  
+• Cascading combos and satisfying animations  
+• Difficulty affects level objectives and move limits
+
+</td>
+</tr>
+</table>
+</td>
+</tr>
+<tr>
+<td width="50%" style="vertical-align: top;">
+<table style="border: none;">
+<tr style="border: none;">
+<td width="120" style="vertical-align: top; border: none;">
+<img src="https://cdn.worklage.com/playtura/screenshots/flappy-bird.png" alt="Flappy Bird" width="100"/>
+</td>
+<td style="vertical-align: top; border: none;">
+
+**🐦 Flappy Bird**  
+Navigate bird through pipes with precise timing
+
+• Classic tap-to-flap mechanics with gravity physics  
+• Navigate through pipes with pixel-perfect collision  
+• Progressive difficulty with increasing pipe speed  
+• Difficulty affects pipe gap size and spawn frequency
+
+</td>
+</tr>
+</table>
+</td>
+<td width="50%" style="vertical-align: top;">
+<table style="border: none;">
+<tr style="border: none;">
+<td width="120" style="vertical-align: top; border: none;">
+<img src="https://cdn.worklage.com/playtura/screenshots/colors-sort.png" alt="Colors Sort" width="100"/>
+</td>
+<td style="vertical-align: top; border: none;">
+
+**🎨 Colors Sort**  
+Sort colored liquids into matching tubes
+
+• Sort colored liquids into matching tubes  
+• Logic puzzle with increasing complexity  
+• Satisfying pour animations and sound effects  
+• Difficulty affects number of tubes and colors
+
+</td>
+</tr>
+</table>
+</td>
+</tr>
+<tr>
+<td width="50%" style="vertical-align: top;">
+<table style="border: none;">
+<tr style="border: none;">
+<td width="120" style="vertical-align: top; border: none;">
+<img src="https://cdn.worklage.com/playtura/screenshots/dino-jump.png" alt="Dino Jump" width="100"/>
+</td>
+<td style="vertical-align: top; border: none;">
+
+**🦖 Dino Jump**  
+Chrome offline dino game - jump to avoid obstacles!
+
+• Endless runner with tap-to-jump mechanics  
+• Collect stars for extra lives (max 3 lives)  
+• Game durations: easy 2 mins, medium 3 mins, hard 5 mins  
+• Dynamic ground height based on device offset (150px or 250px)  
+• Difficulty affects obstacle spawn rate and game speed
+
+</td>
+</tr>
+</table>
+</td>
+<td width="50%" style="vertical-align: top;">
+<table style="border: none;">
+<tr style="border: none;">
+<td width="120" style="vertical-align: top; border: none;">
+<img src="https://cdn.worklage.com/playtura/screenshots/popit-fidget.png" alt="Popit Fidget" width="100"/>
+</td>
+<td style="vertical-align: top; border: none;">
+
+**🫧 Popit Fidget**  
+Pop satisfying bubbles in this relaxing fidget toy game
+
+• Relaxing bubble popping with satisfying sound effects  
+• Different bubble shapes and colors for variety  
+• Difficulty affects bubble responsiveness and patterns
+
+</td>
+</tr>
+</table>
+</td>
+</tr>
+<tr>
+<td width="50%" style="vertical-align: top;">
+<table style="border: none;">
+<tr style="border: none;">
+<td width="120" style="vertical-align: top; border: none;">
+<img src="https://cdn.worklage.com/playtura/screenshots/whack-a-mole.png" alt="Whack A Mole" width="100"/>
+</td>
+<td style="vertical-align: top; border: none;">
+
+**🐱 Whack A Mole**  
+Whack cute cats popping from holes - fast reflexes needed!
+
+• Cat spawn intervals: easy 2000ms, medium 1500ms, hard 1000ms  
+• Cat visible duration: easy 2500ms, medium 2000ms, hard 1500ms  
+• Grid sizes: easy/medium 3x3, hard 4x4
+
+</td>
+</tr>
+</table>
+</td>
+<td width="50%" style="vertical-align: top;">
+<table style="border: none;">
+<tr style="border: none;">
+<td width="120" style="vertical-align: top; border: none;">
+<img src="https://cdn.worklage.com/playtura/screenshots/balloon-blaster.png" alt="Balloon Blaster" width="100"/>
+</td>
+<td style="vertical-align: top; border: none;">
+
+**🎈 Balloon Blaster**  
+Pop rising balloons before they escape - quick taps win!
+
+• Fixed 60-second gameplay sessions  
+• Balloon spawn interval: 1200ms, rise speed: 0.08  
+• Physics-based balloon movement with particle effects
+
+</td>
+</tr>
+</table>
+</td>
+</tr>
+<tr>
+<td width="50%" style="vertical-align: top;">
+<table style="border: none;">
+<tr style="border: none;">
+<td width="120" style="vertical-align: top; border: none;">
+<img src="https://cdn.worklage.com/playtura/screenshots/space-fighter.png" alt="Space Fighter" width="100"/>
+</td>
+<td style="vertical-align: top; border: none;">
+
+**🚀 Space Fighter**  
+Pilot spaceship through asteroid fields in endless space
+
+• Horizontal drag controls with smooth spacecraft movement  
+• Dynamic spacecraft positioning based on device offset  
+• Progressive difficulty with asteroid spawn intervals  
+• 1-second collision immunity after each hit  
+• Difficulty affects asteroid speed and spawn frequency
+
+</td>
+</tr>
+</table>
+</td>
+<td width="50%" style="vertical-align: top;">
+<table style="border: none;">
+<tr style="border: none;">
+<td width="120" style="vertical-align: top; border: none;">
+<img src="https://cdn.worklage.com/playtura/screenshots/maze-runner.png" alt="Maze Runner" width="100"/>
+</td>
+<td style="vertical-align: top; border: none;">
+
+**🧩 Maze Runner**  
+Navigate ball through mazes using tilt and physics controls
+
+• Grid sizes: easy 8x8, medium 10x10, hard 12x12  
+• Procedurally generated mazes with intelligent pathfinding  
+• Game over modal only appears on maze completion (not on stop)  
+• White time display for better visibility  
+• Difficulty affects maze complexity and time limits
+
+</td>
+</tr>
+</table>
+</td>
+</tr>
+<tr>
+<td width="50%" style="vertical-align: top;">
+<table style="border: none;">
+<tr style="border: none;">
+<td width="120" style="vertical-align: top; border: none;">
+<img src="https://cdn.worklage.com/playtura/screenshots/sliding-numbers.png" alt="Sliding Numbers" width="100"/>
+</td>
+<td style="vertical-align: top; border: none;">
+
+**🔢 Sliding Numbers**  
+Solve the classic 15-puzzle with numbers
+
+• Classic 15-puzzle with numbered tiles  
+• Grid sizes: easy 3x3, medium 4x4, hard 5x5  
+• Timer challenge to solve as fast as possible  
+• Smooth tile sliding animations
+
+</td>
+</tr>
+</table>
+</td>
+<td width="50%" style="vertical-align: top;">
+<table style="border: none;">
+<tr style="border: none;">
+<td width="120" style="vertical-align: top; border: none;">
+<img src="https://cdn.worklage.com/playtura/screenshots/game-2048.png" alt="2048 Game" width="100"/>
+</td>
+<td style="vertical-align: top; border: none;">
+
+**🎮 2048 Game**  
+Merge tiles to reach 2048 and beyond
+
+• Swipe to merge tiles with same numbers  
+• Reach 2048 tile to win, continue for higher scores  
+• Undo moves feature for strategic gameplay  
+• Difficulty affects starting tile values and spawn rate
+
+</td>
+</tr>
+</table>
+</td>
+</tr>
+<tr>
+<td width="50%" style="vertical-align: top;">
+<table style="border: none;">
+<tr style="border: none;">
+<td width="120" style="vertical-align: top; border: none;">
+<img src="https://cdn.worklage.com/playtura/screenshots/fruit-merger.png" alt="Fruit Merger" width="100"/>
+</td>
+<td style="vertical-align: top; border: none;">
+
+**🍉 Fruit Merger**  
+Merge fruits to create bigger ones
+
+• Merge fruits to create bigger ones (watermelon evolution)  
+• Physics-based dropping and merging mechanics  
+• Combo system for multiple merges  
+• Difficulty affects merge requirements and spawn rate
+
+</td>
+</tr>
+</table>
+</td>
+<td width="50%" style="vertical-align: top;">
+<table style="border: none;">
+<tr style="border: none;">
+<td width="120" style="vertical-align: top; border: none;">
+<img src="https://cdn.worklage.com/playtura/screenshots/snake.png" alt="Snake & Eggs" width="100"/>
+</td>
+<td style="vertical-align: top; border: none;">
+
+**🐍 Snake & Eggs**  
+Classic snake game with modern touch controls
+
+• Classic snake gameplay with modern touch controls  
+• Swipe or tap to change direction  
+• Grow by eating food, avoid walls and yourself  
+• Difficulty affects snake speed and grid size
+
+</td>
+</tr>
+</table>
+</td>
+</tr>
+</table>
 
 ## 📦 Installation
 
@@ -33,12 +385,11 @@ npm install @shopify/react-native-skia react-native-reanimated react-native-gest
 
 Follow the installation guides for each peer dependency:
 
-- **[@shopify/react-native-skia](https://shopify.github.io/react-native-skia/docs/getting-started/installation)** - Graphics rendering
+- **[@shopify/react-native-skia](https://shopify.github.io/react-native-skia/docs/getting-started/installation)** - Graphics
 - **[react-native-reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started)** - Animations
 - **[react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/installation)** - Gestures
-- **[expo-speech](https://docs.expo.dev/versions/latest/sdk/speech/)** - Text-to-speech functionality
-- **[expo-haptics](https://docs.expo.dev/versions/latest/sdk/haptics/)** - Haptic feedback
-- **[react-native-worklets](https://github.com/margelo/react-native-worklets)** - JavaScript worklets for high-performance animations
+- **[expo-speech](https://docs.expo.dev/versions/latest/sdk/speech/)** - Sounds
+- **[expo-haptics](https://docs.expo.dev/versions/latest/sdk/haptics/)** - Haptic
 
 ## 🚀 Usage
 
@@ -92,10 +443,7 @@ export default function FruitNinjaScreen() {
   useLayoutEffect(() => {
     navigation.setOptions({
       headerRight: () => (
-        <TouchableOpacity
-          onPress={handleToggleSettingsModal}
-          className="p-2"
-        >
+        <TouchableOpacity className="p-2" onPress={handleToggleSettingsModal}>
           <Ionicons name="settings-outline" size={24} color={colors.text} />
         </TouchableOpacity>
       ),
@@ -116,19 +464,27 @@ All games use the same props interface:
 
 ```tsx
 // Import any game you want
-import { 
-  WhackAMole, 
-  PopitFidget, 
-  FruitNinja, 
-  MazeRunner, 
-  SpaceFighter, 
-  BalloonBlaster 
+import {
+  FruitNinja,
+  CandyCrush,
+  FlappyBird,
+  ColorsSort,
+  DinoJump,
+  PopitFidget,
+  WhackAMole,
+  BalloonBlaster,
+  SpaceFighter,
+  MazeRunner,
+  SlidingNumbers,
+  Game2048,
+  FruitMerger,
+  Snake
 } from 'react-native-games';
 
 // All games accept the same props:
-<GameComponent 
-  settings={settings} 
-  onSettingsChange={handleSettingsChange} 
+<GameComponent
+  settings={settings}
+  onSettingsChange={handleSettingsChange}
 />
 ```
 
@@ -150,81 +506,148 @@ const DEFAULT_GAME_SETTINGS = {
   difficulty: 'medium',
   enableSounds: true,
   enableHaptics: true,
+  offset: 0,
 };
 ```
 
-#### Game-Specific Behaviors
+### Game Settings
 
-**Whack A Mole**
-- Cat spawn intervals: easy 2000ms, medium 1500ms, hard 1000ms
-- Cat visible duration: easy 2500ms, medium 2000ms, hard 1500ms
-- Grid sizes: easy/medium 3x3, hard 4x4
+Each game includes built-in settings screens with a unified, simplified interface:
 
-**Popit Fidget**
-- Relaxing bubble popping with satisfying sound effects
-- Different bubble shapes and colors for variety
-- Difficulty affects bubble responsiveness and patterns
+- **Difficulty Levels**: Easy, Medium, Hard - each game has custom difficulty descriptions and behaviors
+- **Sound Effects**: Toggle audio feedback on/off
+- **Haptic Feedback**: Toggle vibration feedback on/off
 
-**Fruit Ninja**
-- Fixed 60-second gameplay sessions
-- Physics-based slicing with particle effects and combo system
-- Difficulty affects fruit spawn rate and bomb frequency
+All games use a centralized settings system for consistency and ease of maintenance. Game durations and difficulty behaviors are customized per game for optimal gameplay experience.
 
-**Space Fighter**
-- Progressive difficulty with asteroid spawn intervals
-- Horizontal drag controls with collision immunity system
-- Difficulty affects asteroid speed and spawn frequency
+## 📚 API Reference
 
-**Maze Runner**
-- Grid sizes: easy 8x8, medium 10x10, hard 12x12
-- Procedurally generated mazes with intelligent pathfinding
-- Difficulty affects maze complexity and time limits
+### Exported Constants & Types
 
-**Balloon Blaster**
-- Fixed 60-second gameplay sessions
-- Balloon spawn interval: 1200ms, rise speed: 0.08
-- Physics-based balloon movement with particle effects
+```tsx
+import {
+  // Game IDs Enum
+  GAME_IDS,
+  
+  // Default Settings
+  DEFAULT_GAME_SETTINGS,
+  
+  // Games List & Mapping
+  GAMES_LIST,
+  GAMES_MAPPING,
+  
+  // TypeScript Types
+  type GameSettings,
+  type GameProps,
+  type GameDefinition,
+  type GameComponent,
+  
+  // All Game Components
+  FruitNinja,
+  CandyCrush,
+  FlappyBird,
+  ColorsSort,
+  DinoJump,
+  PopitFidget,
+  WhackAMole,
+  BalloonBlaster,
+  SpaceFighter,
+  MazeRunner,
+  SlidingNumbers,
+  Game2048,
+  FruitMerger,
+  Snake
+} from 'react-native-games';
+```
 
-### Game Settings
+### GAME_IDS Enum
 
-Each game includes built-in settings screens with a unified, simplified interface:
+All available game identifiers:
 
-- **Difficulty Levels**: Easy, Medium, Hard - each game has custom difficulty descriptions and behaviors
-- **Sound Effects**: Toggle audio feedback on/off
-- **Haptic Feedback**: Toggle vibration feedback on/off
+```tsx
+GAME_IDS.FRUIT_NINJA      // 'fruit-ninja'
+GAME_IDS.CANDY_CRUSH      // 'candy-crush'
+GAME_IDS.FLAPPY_BIRD      // 'flappy-bird'
+GAME_IDS.COLORS_SORT      // 'colors-sort'
+GAME_IDS.DINO_JUMP        // 'dino-jump'
+GAME_IDS.POPIT_FIDGET     // 'popit-fidget'
+GAME_IDS.WHACK_A_MOLE     // 'whack-a-mole'
+GAME_IDS.BALLOON_BLASTER  // 'balloon-blaster'
+GAME_IDS.SPACE_FIGHTER    // 'space-fighter'
+GAME_IDS.MAZE_RUNNER      // 'maze-runner'
+GAME_IDS.SLIDING_NUMBERS  // 'sliding-numbers'
+GAME_IDS.GAME_2048        // 'game-2048'
+GAME_IDS.FRUIT_MERGER     // 'fruit-merger'
+GAME_IDS.SNAKE            // 'snake'
+```
 
-All games use a centralized settings system for consistency and ease of maintenance. Game durations and difficulty behaviors are customized per game for optimal gameplay experience.
+### DEFAULT_GAME_SETTINGS
 
-## 🎨 Features
+Default configuration for all games:
 
-### 🚀 **High Performance**
-- Built with React Native Skia for 60fps gameplay
-- Optimized animations using Reanimated 3 with worklets
-- Delta time physics loops for consistent performance
-- React.memo optimizations and efficient state management
-- Minimal re-renders with direct store subscriptions
+```tsx
+const DEFAULT_GAME_SETTINGS = {
+  isVisible: false,      // Settings modal visibility
+  difficulty: 'medium',  // Game difficulty level
+  enableSounds: true,    // Audio feedback enabled
+  enableHaptics: true,   // Haptic feedback enabled
+  offset: 0,            // Top offset for notch/status bar
+};
 
-### 🎵 **Rich Audio & Haptics**
-- Sound effects and speech synthesis
-- Haptic feedback for immersive experience
-- Configurable audio settings
+// Example: Custom settings with offset
+const customSettings = {
+  ...DEFAULT_GAME_SETTINGS,
+  offset: 50,  // Moves game elements 50px down from top
+};
+```
 
-### 🎯 **Customizable**
-- Multiple difficulty levels
-- Adjustable game parameters
-- Persistent settings storage
+### GAMES_LIST
+
+Array of all game definitions with metadata:
+
+```tsx
+// GAMES_LIST is an array of GameDefinition objects
+GAMES_LIST.forEach(game => {
+  console.log(game.id);          // GAME_IDS enum value
+  console.log(game.title);       // Display title
+  console.log(game.description); // Game description
+  console.log(game.component);   // React component
+});
+
+// Example: Find a specific game
+const fruitNinja = GAMES_LIST.find(g => g.id === GAME_IDS.FRUIT_NINJA);
+```
 
-### 📱 **Cross-Platform**
-- iOS and Android support
-- Consistent performance across devices
-- Responsive design for different screen sizes
-
-### 🎮 **Game Features**
-- **Physics Simulation**: Realistic movement and collisions
-- **Particle Systems**: Visual effects and animations
-- **Procedural Generation**: Dynamic content (mazes, obstacles)
-- **Score Systems**: Leaderboards and achievements
-- **Progressive Difficulty**: Adaptive challenge levels
+### GAMES_MAPPING
+
+Object mapping game IDs to their components:
+
+```tsx
+// Access game component by ID
+const GameComponent = GAMES_MAPPING[GAME_IDS.FRUIT_NINJA];
+
+// Render dynamically
+<GameComponent settings={settings} onSettingsChange={handleChange} />
+```
+
+### TypeScript Types
+
+```tsx
+// Game settings interface
+interface GameSettings {
+  isVisible: boolean;        // Settings modal visibility
+  difficulty: 'easy' | 'medium' | 'hard';
+  enableSounds: boolean;     // Audio feedback
+  enableHaptics: boolean;    // Haptic feedback
+  offset?: number;           // Optional padding from top (default: 0)
+}
+
+// Game component props
+interface GameProps {
+  settings?: GameSettings;
+  onSettingsChange?: (settings: GameSettings) => void;
+}
+```
 
 ## 📄 License