State Management Best Practices

React state management in the RMMZ/RPGReact context has unique challenges due to the integration with game engine observables, animation loops, and event-driven architecture.

Core Principles

1. Choose the Right State Type

Use useState for:

• UI-only state (modal open/closed, selected tab, form inputs)

• State that triggers re-renders when changed

• Values that change infrequently

const [isModalOpen, setIsModalOpen] = useState(false);
const [selectedTab, setSelectedTab] = useState('items');

Use useRef for:

• Values that change frequently but don't need to trigger re-renders

• Animation frame IDs

• Timers and intervals

• Tracking previous values

• Avoiding stale closures in callbacks

const frameRef = useRef<number>(0);
const previousValueRef = useRef<number>(0);

Use MobX observables for:

• Game data that comes from RMMZ (already observable)

• Computed values derived from game state

• Cross-component reactive state

import { observer } from 'mobx-react-lite';

const PartyDisplay = observer(() => {
  const party = pageData.runtime.gameParty.members();
  // Component automatically re-renders when party changes
  return <div>{party.map(m => m.name())}</div>;
});

2. Avoid Stale Closures

Problem: Closures in animation loops, event handlers, and setTimeout capture state at creation time.

// ❌ BAD: Animation loop sees stale targetValue
const [targetValue, setTargetValue] = useState(100);

useEffect(() => {
  const animate = () => {
    if (currentValue < targetValue) { // Stale!
      setCurrentValue(v => v + 1);
      requestAnimationFrame(animate);
    }
  };
  requestAnimationFrame(animate);
}, []);

Solution 1: Use refs to track latest values

// ✅ GOOD: Use ref for values accessed in animation loop
const [targetValue, setTargetValue] = useState(100);
const targetRef = useRef(100);

useEffect(() => {
  targetRef.current = targetValue;
}, [targetValue]);

useEffect(() => {
  const animate = () => {
    if (currentValue < targetRef.current) { // Fresh!
      setCurrentValue(v => v + 1);
      requestAnimationFrame(animate);
    }
  };
  requestAnimationFrame(animate);
}, []);

Solution 2: Depend on the animation state, not external state

// ✅ GOOD: Self-contained animation with dependencies
useEffect(() => {
  const startTime = Date.now();
  const duration = 1000;
  const startValue = currentXp.current;
  const endValue = targetXp.current;

  const animate = () => {
    const elapsed = Date.now() - startTime;
    const progress = Math.min(elapsed / duration, 1);
    const value = startValue + (endValue - startValue) * progress;

    setDisplayValue(value);

    if (progress < 1) {
      requestAnimationFrame(animate);
    }
  };

  requestAnimationFrame(animate);
}, [animationKey]); // Trigger new animation by incrementing key

3. Memoize Expensive Computations

Problem: Recreating arrays/objects on every render causes child components to re-render unnecessarily.

// ❌ BAD: sellItems array is recreated every render
const sellItems = (() => {
  const gp = props.pageData.runtime.gameParty;
  return [
    ...gp.items(),
    ...gp.weapons(),
    ...gp.armors(),
  ].filter((it: any) => (gp.numItems(it) || 0) > 0);
})();

return <ItemList items={sellItems} />; // Re-renders constantly!

Solution: Use useMemo

// ✅ GOOD: sellItems only recreated when dependencies change
const sellItems = useMemo(() => {
  const gp = props.pageData.runtime.gameParty;
  return [
    ...gp.items(),
    ...gp.weapons(),
    ...gp.armors(),
  ].filter((it: any) => (gp.numItems(it) || 0) > 0);
}, [props.pageData.runtime.gameParty, goldData]);

return <ItemList items={sellItems} />;

When to use useMemo:

• Filtering/mapping large arrays

• Creating configuration objects passed to children

• Expensive calculations

• When passing arrays/objects as props to components using React.memo()

When NOT to use useMemo:

• Simple calculations (useMemo overhead > calculation cost)

• Values only used once in the component

• Primitives (numbers, strings, booleans)

4. Clean Up Side Effects

Problem: Animation frames, timers, and event listeners can leak if not cleaned up.

// ❌ BAD: Animation continues after unmount
useEffect(() => {
  const animate = () => {
    setFrame(f => f + 1);
    requestAnimationFrame(animate);
  };
  requestAnimationFrame(animate);
}, []);

Solution: Return cleanup function

// ✅ GOOD: Cancel animation on unmount
useEffect(() => {
  let frameId: number;
  const animate = () => {
    setFrame(f => f + 1);
    frameId = requestAnimationFrame(animate);
  };
  frameId = requestAnimationFrame(animate);

  return () => {
    if (frameId) cancelAnimationFrame(frameId);
  };
}, []);

5. Batch State Updates

Problem: Multiple setState calls in quick succession cause multiple re-renders.

// ❌ BAD: 3 re-renders
const handleSelection = (item) => {
  setSelectedItem(item);      // Re-render 1
  setQuantity(1);              // Re-render 2
  setShowDetails(true);        // Re-render 3
};

Solution: Combine into single state object

// ✅ GOOD: 1 re-render
const [selection, setSelection] = useState({
  item: null,
  quantity: 1,
  showDetails: false
});

const handleSelection = (item) => {
  setSelection({
    item,
    quantity: 1,
    showDetails: true
  });
};

Or use React's automatic batching (React 18+):

// ✅ GOOD: React 18 automatically batches these
const handleSelection = (item) => {
  setSelectedItem(item);
  setQuantity(1);
  setShowDetails(true);
  // All batched into one re-render
};

6. Functional Updates for Dependent State

Problem: setState using current state can be stale in rapid updates.

// ❌ BAD: May skip increments if called rapidly
const increment = () => {
  setCount(count + 1);
};

Solution: Use functional update form

// ✅ GOOD: Always uses latest value
const increment = () => {
  setCount(prev => prev + 1);
};

7. Separate Concerns: Refs for Animation, State for UI

Pattern for animations:

const XPBar = ({ startExp, targetExp, onComplete }) => {
  // State: triggers re-renders for UI updates
  const [displayExp, setDisplayExp] = useState(startExp);
  const [displayLevel, setDisplayLevel] = useState(1);

  // Refs: track animation state without re-renders
  const frameRef = useRef<number>(0);
  const currentExp = useRef(startExp);
  const targetExpRef = useRef(targetExp);

  useEffect(() => {
    currentExp.current = startExp;
    targetExpRef.current = targetExp;

    const animate = () => {
      // Update ref
      currentExp.current += speedPerFrame;

      // Update UI state periodically (not every frame)
      setDisplayExp(currentExp.current);

      // Check for level-up using ref
      if (currentExp.current >= nextLevelExp) {
        setDisplayLevel(prev => prev + 1);
      }

      if (currentExp.current < targetExpRef.current) {
        frameRef.current = requestAnimationFrame(animate);
      } else {
        onComplete();
      }
    };

    frameRef.current = requestAnimationFrame(animate);

    return () => {
      if (frameRef.current) cancelAnimationFrame(frameRef.current);
    };
  }, [startExp, targetExp]);

  return <ProgressBar value={displayExp} level={displayLevel} />;
};

Common Patterns

Pattern: Animation Controller with Skip

const AnimatedComponent = ({ onComplete }) => {
  const [isAnimating, setIsAnimating] = useState(false);
  const frameRef = useRef<number>(0);
  const targetRef = useRef<number>(0);

  const skip = useCallback(() => {
    if (frameRef.current) {
      cancelAnimationFrame(frameRef.current);
      frameRef.current = 0;
    }
    // Set to final state immediately
    setDisplayValue(targetRef.current);
    setIsAnimating(false);
    onComplete?.();
  }, [onComplete]);

  useImperativeHandle(ref, () => ({ skip }), [skip]);

  // ... animation logic
};

Pattern: Tracking Selection in Lists

const SelectableList = ({ items, onSelect }) => {
  const [selectedIndex, setSelectedIndex] = useState(0);
  const selectedRef = useRef(0);

  // Keep ref in sync
  useEffect(() => {
    selectedRef.current = selectedIndex;
  }, [selectedIndex]);

  // Reset when items change
  useEffect(() => {
    if (items.length > 0 && selectedIndex >= items.length) {
      setSelectedIndex(0);
      selectedRef.current = 0;
    }
  }, [items]);

  return (
    <div>
      {items.map((item, i) => (
        <div
          key={i}
          className={i === selectedIndex ? 'selected' : ''}
          onClick={() => setSelectedIndex(i)}
        >
          {item.name}
        </div>
      ))}
    </div>
  );
};

Pattern: Conditional State Updates

// ❌ BAD: Always updates, even when unchanged
useEffect(() => {
  setSelectedItem(items[0]);
}, [items]);

// ✅ GOOD: Only updates when actually changing
useEffect(() => {
  setSelectedItem(prev => {
    if (!prev || !items.includes(prev)) {
      return items[0] || null;
    }
    return prev;
  });
}, [items]);

Debugging Tips

1. Track why components re-render

import { useEffect, useRef } from 'react';

const useWhyDidYouUpdate = (name, props) => {
  const previousProps = useRef();

  useEffect(() => {
    if (previousProps.current) {
      const allKeys = Object.keys({ ...previousProps.current, ...props });
      const changedProps = {};
      allKeys.forEach(key => {
        if (previousProps.current[key] !== props[key]) {
          changedProps[key] = {
            from: previousProps.current[key],
            to: props[key]
          };
        }
      });

      if (Object.keys(changedProps).length > 0) {
        console.log('[why-did-you-update]', name, changedProps);
      }
    }

    previousProps.current = props;
  });
};

// Usage
const MyComponent = (props) => {
  useWhyDidYouUpdate('MyComponent', props);
  // ...
};

2. Detect stale closures

// Add timestamp to closures for debugging
const handleClick = useCallback(() => {
  const timestamp = Date.now();
  console.log('Created at:', timestamp);

  setTimeout(() => {
    console.log('Executing at:', Date.now());
    console.log('Captured value:', someState); // If stale, you'll see old value
    console.log('Age:', Date.now() - timestamp, 'ms');
  }, 1000);
}, [someState]);

3. Verify ref updates

useEffect(() => {
  console.log('Ref updated:', myRef.current);
}, [myValue]); // Re-log when state changes

useEffect(() => {
  myRef.current = myValue;
  console.log('Synced ref to state:', myValue);
}, [myValue]);

Performance Optimization

Use React.memo for expensive components

const ExpensiveComponent = React.memo(({ data }) => {
  // Only re-renders if data changes
  return <div>{/* complex rendering */}</div>;
}, (prevProps, nextProps) => {
  // Custom comparison: return true to skip re-render
  return prevProps.data.id === nextProps.data.id;
});

Avoid inline function creation in render

// ❌ BAD: Creates new function every render
<Button onClick={() => handleClick(item)} />

// ✅ GOOD: Stable callback
const onClick = useCallback(() => handleClick(item), [item]);
<Button onClick={onClick} />

Use keys properly in lists

// ❌ BAD: Index as key causes issues when reordering
{items.map((item, index) => <Item key={index} {...item} />)}

// ✅ GOOD: Stable unique identifier
{items.map((item) => <Item key={item.id} {...item} />)}

See Also

• MobX React Lite Documentation

• React Hooks API Reference

• Battle System Architecture - Real-world state management examples