react-native-games 0.4.0 → 0.5.0

package/README.md

@@ -38,181 +38,171 @@ Follow the installation guides for each peer dependency:
 - **[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 { WhackAMole, PopitFidget, FruitNinja, MazeRunner, SpaceFighter, BalloonBlaster } 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}>
-      {/* Whack A Mole Game - Classic whack-a-mole with cats */}
-      <WhackAMole
-        showSettingsModal={showSettings}
-        onToggleSettingsModal={() => setShowSettings(!showSettings)}
-      />
-
-      {/* Or choose any other game */}
-      {/* <PopitFidget /> */}
-      {/* <FruitNinja /> */}
-      {/* <MazeRunner /> */}
-      {/* <SpaceFighter /> */}
-      {/* <BalloonBlaster /> */}
+    <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:
 
-#### Whack A Mole
 ```tsx
-<WhackAMole
-  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>
+  );
+}
 ```
 
-#### Popit Fidget
-```tsx
-<PopitFidget
-  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']
-// Relaxing bubble popping with satisfying sound effects
-// Different bubble shapes and colors for variety
-```
+All games use the same props interface:
 
-#### Fruit Ninja
 ```tsx
-<FruitNinja
-  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']
-// Balloons rise from bottom to top with physics-based movement
-// Spawn intervals and speeds adjust automatically with difficulty
 ```
 
-#### Space Fighter
-```tsx
-<SpaceFighter
-  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)
-// }
-// Available: difficulty ['easy','medium','hard']
-// Spawn intervals: easy 2000ms, medium 1500ms, hard 1000ms
-```
+All games use the unified `GameSettings` interface:
 
-#### Maze Runner
 ```tsx
-<MazeRunner
-  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)
-//   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
+// Default settings for all games
+const DEFAULT_GAME_SETTINGS = {
+  isVisible: false,
+  difficulty: 'medium',
+  enableSounds: true,
+  enableHaptics: true,
+};
 ```
 
-#### Balloon Blaster
-```tsx
-<BalloonBlaster
-  showSettingsModal={boolean}           // Control settings modal visibility
-  onToggleSettingsModal={() => void}    // Settings modal toggle callback
-/>
+#### Game-Specific Behaviors
 
-// 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
-```
+**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
@@ -268,7 +258,8 @@ 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