Troubleshooting

Tips and techniques for debugging RPGReact games during development.

Browser DevTools

Accessing DevTools

In NW.js (desktop):

// Add to package.json
{
  "chromium-args": "--remote-debugging-port=9222"
}

Then open Chrome and navigate to chrome://inspect or press F12 in-game (if enabled).

In browser (web build): Press F12 or right-click → Inspect

Console Logging

Add debug logs to your components:

useEffect(() => {
  console.log('[MyComponent] Mounted', props);
  return () => console.log('[MyComponent] Unmounted');
}, []);

useEffect(() => {
  console.log('[MyComponent] Props changed', props);
}, [props]);

Common Console Errors

"Cannot read property 'X' of undefined"

• Game data not loaded yet

• MobX observable accessed before initialization

• Check if RPGBridge.IsInitialized() is true

"Maximum update depth exceeded"

• Infinite render loop

• State update in render function

• Fix: Move state updates to useEffect or event handlers

"Warning: Can't perform a React state update on an unmounted component"

• Async operation completes after unmount

• Fix: Cancel async operations in useEffect cleanup

React DevTools

Install React DevTools extension for Chrome/Firefox.

Features:

• Inspect component tree

• View props and state

• Track component re-renders

• Profile performance

Highlight renders: Settings → Highlight updates when components render

MobX DevTools

Spy on observables

import { spy } from 'mobx';

// Log all observable changes
spy((event) => {
  if (event.type === 'update') {
    console.log('[MobX]', event.name, event.oldValue, '→', event.newValue);
  }
});

Track reactions

import { trace } from 'mobx';

const MyComponent = observer(() => {
  trace(); // Logs what observables this component depends on
  return <div>{someObservable.value}</div>;
});

Common Issues & Solutions

Issue: Stale State in Callbacks

Symptom: Values in setTimeout/animation loops are outdated

Debug:

const [count, setCount] = useState(0);

useEffect(() => {
  console.log('Effect setup, count=', count);
  const id = setInterval(() => {
    console.log('Interval callback, count=', count); // Always 0!
  }, 1000);
  return () => clearInterval(id);
}, []); // Empty deps = stale closure

Solution: Use refs or functional updates

const countRef = useRef(count);
useEffect(() => { countRef.current = count; }, [count]);

// Or
setCount(prev => prev + 1); // Always uses latest

Issue: Component Not Re-rendering

Debug: Check if using MobX observer:

// ❌ Won't react to observable changes
const MyComponent = () => {
  const value = observableObject.value;
  return <div>{value}</div>;
};

// ✅ Reacts to changes
const MyComponent = observer(() => {
  const value = observableObject.value;
  return <div>{value}</div>;
});

Issue: Memory Leaks

Detect:

1. Open Chrome DevTools → Memory tab

2. Take heap snapshot

3. Play game for a while

4. Take another snapshot

5. Compare - detached DOM nodes or growing arrays indicate leaks

Common causes:

• Event listeners not removed

• Animation frames not canceled

• Timers not cleared

• RPGBridge handlers not removed

Fix pattern:

useEffect(() => {
  const handler = { id: 'my-handler', handler: handleEvent };
  RPGBridge.AddEventHandler(handler);

  const timerId = setInterval(doSomething, 1000);
  let frameId = requestAnimationFrame(animate);

  return () => {
    // CRITICAL: Clean up everything
    RPGBridge.RemoveEventHandlerById('my-handler');
    clearInterval(timerId);
    cancelAnimationFrame(frameId);
  };
}, []);

Issue: Performance Problems

Profile:

1. DevTools → Performance tab

2. Click Record

3. Perform slow action

4. Stop recording

5. Analyze flame graph

Common causes:

• Expensive calculations in render

• Missing useMemo/useCallback

• Too many observers

• Large lists without virtualization

Solution:

// ❌ Recalculates every render
const filtered = items.filter(expensive Filter);

// ✅ Only when items change
const filtered = useMemo(
  () => items.filter(expensiveFilter),
  [items]
);

Debugging Specific Systems

Battle System

// Add to BattleMain
useEffect(() => {
  console.log('[Battle] Phase:', BattleManager.phase());
  console.log('[Battle] Inputting:', BattleManager.isInputting());
  console.log('[Battle] Actor:', BattleManager.actor()?.name());
}, [/* some dependency */]);

Input System

// Log all input events
const { addEventListener } = useInputContext();

useEffect(() => {
  addEventListener('debug-all', 'trigger', RPGMakerKeys.OK, () => {
    console.log('[Input] OK pressed');
    return false; // Don't consume, let others handle
  });

  // Same for other keys...
}, []);

Asset Loading

// Check if assets loaded
console.log('Manifest loaded:', RPGBridge.IsInitialized());
console.log('Asset path:', /* check manifest */);

// Listen for load errors
window.addEventListener('error', (e) => {
  if (e.target.tagName === 'IMG') {
    console.error('[Asset] Failed to load image:', e.target.src);
  }
});

Development Workflow

Hot Reload Setup

For React changes:

cd menus
yarn dev # Starts Vite dev server

For override changes: Restart RPG Maker MZ playtest

Test Specific Screens

Create a test map with events that trigger specific screens:

// Event: Show Shop
RPGBridge.CreateEvent(
  RPGEventType.SCREEN_OPEN,
  RPGScreen.ShopScreen,
  { /* shop data */ },
  'TestShop'
);

Mock Data for Testing

// Create mock pageData for testing components in isolation
const mockPageData = {
  runtime: {
    gameParty: {
      members: () => [/* mock actors */],
      gold: () => 1000,
    }
  },
  commands: {
    buy: (item, qty) => console.log('Buy:', item, qty),
    sell: (item, qty) => console.log('Sell:', item, qty),
  }
};

<ShopScreen pageData={mockPageData} hasFocus={true} />

Logging Best Practices

Structured Logging

const log = {
  debug: (...args) => console.log('[DEBUG]', ...args),
  info: (...args) => console.log('[INFO]', ...args),
  warn: (...args) => console.warn('[WARN]', ...args),
  error: (...args) => console.error('[ERROR]', ...args),
};

log.debug('Component mounted', { props, state });
log.error('Failed to load data', error);

Conditional Logging

const DEBUG = process.env.NODE_ENV !== 'production';

const debug = (...args) => {
  if (DEBUG) console.log(...args);
};

Performance Logging

const perfLog = (label, fn) => {
  const start = performance.now();
  const result = fn();
  console.log(`[Perf] ${label}: ${(performance.now() - start).toFixed(2)}ms`);
  return result;
};

const data = perfLog('Calculate Items', () => {
  return expensiveCalculation();
});

See Also

• State Management Best Practices

• Plugin Troubleshooting

• Production Checklist