react-native-games 0.3.0 → 0.5.0

package/README.md

@@ -6,11 +6,12 @@
 
 | Game | Description | Features |
 |------|-------------|----------|
-| **🐱 Cat Popper** | Classic whack-a-mole with cute cats | Multiple difficulty levels, customizable grid sizes, haptic feedback |
-| **🎈 Balloon Blaster** | Pop balloons rising from the bottom | Physics-based gameplay, particle effects, combo system |
-| **🍎 Fruit Slicer** | Slice fruits and avoid bombs | Physics-based gameplay, particle effects, combo system |
-| **🧩 Maze Runner** | Navigate through procedurally generated mazes | Dynamic maze generation, timer challenges, multiple difficulties |
-| **🚀 Space Traveller** | Dodge asteroids in space | 3D-style graphics, progressive difficulty, space physics |
+| **🐱 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 |
 
 ## 📦 Installation
 
@@ -25,17 +26,7 @@ yarn add react-native-games
 This library requires the following peer dependencies to be installed in your project:
 
 ```sh
-# Core React Native Skia for high-performance graphics
-npm install @shopify/react-native-skia
-
-# Reanimated for smooth animations
-npm install react-native-reanimated
-
-# Gesture Handler for touch interactions
-npm install react-native-gesture-handler
-
-# Worklets for performance (used by Reanimated)
-npm install react-native-worklets
+npm install @shopify/react-native-skia react-native-reanimated react-native-gesture-handler react-native-worklets expo-speech expo-haptics
 ```
 
 ### Platform Setup
@@ -45,161 +36,173 @@ 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
 - **[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
 
 ## 🚀 Usage
 
-### Basic Implementation
+### Simple Implementation
+
+For basic usage without settings persistence:
 
 ```tsx
 import React, { useState } from 'react';
-import { View, StyleSheet } from 'react-native';
-import { CatPopper, BalloonBlaster, FruitSlicer, MazeRunner, SpaceTraveller } from 'react-native-games';
+import { View } from 'react-native';
+import { DEFAULT_GAME_SETTINGS, BalloonBlaster } from 'react-native-games';
 
 export default function GameScreen() {
-  const [showSettings, setShowSettings] = useState(false);
+  const [settings, setSettings] = useState(DEFAULT_GAME_SETTINGS);
 
   return (
-    <View style={styles.container}>
-      {/* Cat Popper Game - Classic whack-a-mole with cats */}
-      <CatPopper
-        showSettingsModal={showSettings}
-        onToggleSettingsModal={() => setShowSettings(!showSettings)}
-      />
-
-      {/* Or choose any other game */}
-      {/* <BalloonBlaster /> */}
-      {/* <FruitSlicer /> */}
-      {/* <MazeRunner /> */}
-      {/* <SpaceTraveller /> */}
+    <View style={{ flex: 1 }}>
+      <BalloonBlaster settings={settings} onSettingsChange={setSettings} />
     </View>
   );
 }
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    backgroundColor: '#1a1a2e'
-  }
-});
 ```
 
-### Game-Specific Props & Default Settings
+### Advanced Implementation Example
+
+All games use the same props pattern for consistency. Here's a complete example with settings persistence and navigation integration:
 
-#### Cat Popper
 ```tsx
-<CatPopper
-  showSettingsModal={boolean}           // Control settings modal visibility
-  onToggleSettingsModal={() => void}    // Settings modal toggle callback
-/>
+import { View, TouchableOpacity } from 'react-native';
+import { useState, useLayoutEffect } from 'react';
+import { useNavigation, useTheme } from '@react-navigation/native';
+import { Ionicons } from '@expo/vector-icons';
+import { DEFAULT_GAME_SETTINGS, GAME_IDS, type GameSettings, FruitNinja } from 'react-native-games';
+import { StorageService } from '../services/StorageService';
+
+export default function FruitNinjaScreen() {
+  const { colors } = useTheme();
+  const storedSettings = StorageService.get(GAME_IDS.FRUIT_NINJA);
+  const [settings, setSettings] = useState(storedSettings || DEFAULT_GAME_SETTINGS);
+  const navigation = useNavigation();
+
+  const handleSettingsChange = (newSettings: GameSettings) => {
+    setSettings(newSettings);
+    StorageService.set(GAME_IDS.FRUIT_NINJA, newSettings);
+  };
+
+  const handleToggleSettingsModal = () => {
+    setSettings({...settings, isVisible: !settings.isVisible});
+  };
+
+  useLayoutEffect(() => {
+    navigation.setOptions({
+      headerRight: () => (
+        <TouchableOpacity
+          onPress={handleToggleSettingsModal}
+          className="p-2"
+        >
+          <Ionicons name="settings-outline" size={24} color={colors.text} />
+        </TouchableOpacity>
+      ),
+    });
+  }, [navigation, handleToggleSettingsModal]);
 
-// Default Settings:
-// {
-//   difficulty: 'medium',          // Balanced challenge
-//   soundEnabled: true,            // Audio feedback enabled
-//   hapticEnabled: true,           // Haptic feedback enabled
-//   gameDuration: 120              // Auto-set based on difficulty (Easy: 60s, Medium: 120s, Hard: 180s)
-// }
-// Available: difficulty ['easy','medium','hard']
-// 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
+  return (
+    <View className="flex-1 bg-background">
+      <FruitNinja settings={settings} onSettingsChange={handleSettingsChange} />
+    </View>
+  );
+}
 ```
 
-#### Balloon Blaster
-```tsx
-<BalloonBlaster
-  showSettingsModal={boolean}           // Control settings modal visibility
-  onToggleSettingsModal={() => void}    // Settings modal toggle callback
-/>
+### Available Games
 
-// Default Settings:
-// {
-//   difficulty: 'medium',          // Balanced challenge
-//   soundEnabled: true,            // Audio feedback enabled
-//   hapticEnabled: true,           // Haptic feedback enabled
-//   gameDuration: 120              // Auto-set based on difficulty (Easy: 60s, Medium: 120s, Hard: 180s)
-// }
-// Available: difficulty ['easy','medium','hard']
-// Balloons rise from bottom to top with physics-based movement
-// Spawn intervals and speeds adjust automatically with difficulty
-```
+All games use the same props interface:
 
-#### Fruit Slicer
 ```tsx
-<FruitSlicer
-  showSettingsModal={boolean}           // Control settings modal visibility
-  onToggleSettingsModal={() => void}    // Settings modal toggle callback
+// Import any game you want
+import { 
+  WhackAMole, 
+  PopitFidget, 
+  FruitNinja, 
+  MazeRunner, 
+  SpaceFighter, 
+  BalloonBlaster 
+} from 'react-native-games';
+
+// All games accept the same props:
+<GameComponent 
+  settings={settings} 
+  onSettingsChange={handleSettingsChange} 
 />
-
-// Default Settings:
-// {
-//   difficulty: 'medium',          // Balanced challenge
-//   soundEnabled: true,            // Audio feedback enabled
-//   hapticEnabled: true,           // Haptic feedback enabled
-//   gameDuration: 120              // Auto-set based on difficulty (Easy: 60s, Medium: 120s, Hard: 180s)
-// }
-// Available: difficulty ['easy','medium','hard']
-// Spawn intervals: easy 2000ms, medium 1500ms, hard 1000ms
 ```
 
-#### Maze Runner
-```tsx
-<MazeRunner
-  showSettingsModal={boolean}           // Control settings modal visibility
-  onToggleSettingsModal={() => void}    // Settings modal toggle callback
-/>
+### Game Settings & Configuration
 
-// Default Settings:
-// {
-//   difficulty: 'medium',          // Balanced challenge
-//   soundEnabled: true,            // Audio feedback enabled
-//   hapticEnabled: true,           // Haptic feedback enabled
-//   gameDuration: 120,             // Auto-set based on difficulty (Easy: 60s, Medium: 120s, Hard: 180s)
-//   gridSize: 10,                  // 10x10 maze grid (auto-adjusts with difficulty)
-//   showHints: false               // No hints by default
-// }
-// Available: difficulty ['easy','medium','hard']
-// Grid sizes: easy 8x8, medium 10x10, hard 12x12 (auto-adjusts with difficulty)
-// Procedurally generated mazes with intelligent pathfinding
-```
+All games use the unified `GameSettings` interface:
 
-#### Space Traveller
 ```tsx
-<SpaceTraveller
-  showSettingsModal={boolean}           // Control settings modal visibility
-  onToggleSettingsModal={() => void}    // Settings modal toggle callback
-/>
+interface GameSettings {
+  isVisible: boolean;        // Settings modal visibility
+  difficulty: 'easy' | 'medium' | 'hard';
+  enableSounds: boolean;     // Audio feedback
+  enableHaptics: boolean;    // Haptic feedback
+}
 
-// Default Settings:
-// {
-//   difficulty: 'medium',          // Balanced challenge
-//   soundEnabled: true,            // Audio feedback enabled
-//   hapticEnabled: true,           // Haptic feedback enabled
-//   gameDuration: 120,             // Auto-set based on difficulty (Easy: 60s, Medium: 120s, Hard: 180s)
-//   asteroidSpawnInterval: 3000,   // 3 seconds between asteroid pairs
-//   asteroidSpeed: 2               // Movement speed multiplier
-// }
-// Available: difficulty ['easy','medium','hard']
-// Horizontal drag controls with collision immunity system
-// Progressive difficulty with faster asteroids and shorter spawn intervals
+// Default settings for all games
+const DEFAULT_GAME_SETTINGS = {
+  isVisible: false,
+  difficulty: 'medium',
+  enableSounds: true,
+  enableHaptics: true,
+};
 ```
 
+#### Game-Specific Behaviors
+
+**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
+
+**Popit Fidget**
+- Relaxing bubble popping with satisfying sound effects
+- Different bubble shapes and colors for variety
+- Difficulty affects bubble responsiveness and patterns
+
+**Fruit Ninja**
+- Fixed 60-second gameplay sessions
+- Physics-based slicing with particle effects and combo system
+- Difficulty affects fruit spawn rate and bomb frequency
+
+**Space Fighter**
+- Progressive difficulty with asteroid spawn intervals
+- Horizontal drag controls with collision immunity system
+- Difficulty affects asteroid speed and spawn frequency
+
+**Maze Runner**
+- Grid sizes: easy 8x8, medium 10x10, hard 12x12
+- Procedurally generated mazes with intelligent pathfinding
+- Difficulty affects maze complexity and time limits
+
+**Balloon Blaster**
+- Fixed 60-second gameplay sessions
+- Balloon spawn interval: 1200ms, rise speed: 0.08
+- Physics-based balloon movement with particle effects
+
 ### Game Settings
 
 Each game includes built-in settings screens with a unified, simplified interface:
 
-- **Difficulty Levels**: Easy (60s), Medium (120s), Hard (180s) - automatically sets game duration
+- **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
 
-All games use a centralized settings system for consistency and ease of maintenance.
+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.
 
 ## 🎨 Features
 
 ### 🚀 **High Performance**
 - Built with React Native Skia for 60fps gameplay
-- Optimized animations using Reanimated 3
-- Efficient rendering and memory management
+- 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
 
 ### 🎵 **Rich Audio & Haptics**
 - Sound effects and speech synthesis
@@ -255,14 +258,15 @@ See the complete [LICENSE](LICENSE) file for detailed terms and definitions.
 
 - Built with [React Native Skia](https://shopify.github.io/react-native-skia/) for high-performance graphics
 - Powered by [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/) for smooth animations
-- State management with [Zustand](https://github.com/pmndrs/zustand)
+- Enhanced with [React Native Worklets](https://github.com/margelo/react-native-worklets) for high-performance JavaScript
+- State management with [Zustand](https://github.com/pmndrs/zustand) and [Immer](https://github.com/immerjs/immer)
 - Created with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)
 
 ## 📞 Support
 
 - 📧 **Email**: niranjan.devasani@gmail.com
-- 🐛 **Issues**: [GitHub Issues](https://github.com/ursnj/react-native-games/issues)
-- 💬 **Discussions**: [GitHub Discussions](https://github.com/ursnj/react-native-games/discussions)
+- 🐛 **Issues**: [GitHub Issues](https://github.com/ursnj/nayan-ui/issues)
+- 🌐 **Website**: [https://www.nayanui.com/games](https://www.nayanui.com/games)
 
 ---