r3f-state-management

R3F State Management

When to Use

Use this skill when:

• Managing global game state in R3F
• Sharing state between 3D and UI components
• Implementing player state, inventory, score
• Coordinating multiple 3D objects
• Optimizing state updates for performance

Core Principles

1. Zustand for Global State: Fast, minimal re-renders
2. React Context for Scoped State: Component trees
3. Local State for Component-Only: useState
4. Immutable Updates: Never mutate state directly
5. Selectors for Performance: Subscribe to slices
6. Avoid Props Drilling: Use stores or context

Implementation

1. Zustand Store Setup

// stores/gameStore.ts
import { create } from 'zustand';
import { devtools, persist } from 'zustand/middleware';

interface GameState {
  // Player state
  playerPosition: [number, number, number];
  playerHealth: number;
  playerScore: number;

  // Game state
  isPaused: boolean;
  gameLevel: number;
  enemies: Array<{ id: string; position: [number, number, number] }>;

  // Actions
  setPlayerPosition: (position: [number, number, number]) => void;
  damagePlayer: (amount: number) => void;
  addScore: (points: number) => void;
  togglePause: () => void;
  nextLevel: () => void;
  spawnEnemy: (id: string, position: [number, number, number]) => void;
  removeEnemy: (id: string) => void;
  reset: () => void;
}

const initialState = {
  playerPosition: [0, 1, 0] as [number, number, number],
  playerHealth: 100,
  playerScore: 0,
  isPaused: false,
  gameLevel: 1,
  enemies: [],
};

export const useGameStore = create<GameState>()(
  devtools(
    persist(
      (set) => ({
        ...initialState,

        setPlayerPosition: (position) =>
          set({ playerPosition: position }),

        damagePlayer: (amount) =>
          set((state) => ({
            playerHealth: Math.max(0, state.playerHealth - amount),
          })),

        addScore: (points) =>
          set((state) => ({ playerScore: state.playerScore + points })),

        togglePause: () =>
          set((state) => ({ isPaused: !state.isPaused })),

        nextLevel: () =>
          set((state) => ({
            gameLevel: state.gameLevel + 1,
            enemies: [],
          })),

        spawnEnemy: (id, position) =>
          set((state) => ({
            enemies: [...state.enemies, { id, position }],
          })),

        removeEnemy: (id) =>
          set((state) => ({
            enemies: state.enemies.filter((e) => e.id !== id),
          })),

        reset: () => set(initialState),
      }),
      {
        name: 'game-storage',
        partialize: (state) => ({
          playerScore: state.playerScore,
          gameLevel: state.gameLevel,
        }),
      }
    )
  )
);