Debugging
Start with the narrowest tool that can explain the problem. Most XRF issues can be isolated with a focused build, runtime logs, and the debug panel before a native engine debugger is needed.
Choose the right tool
| Problem | Start with |
|---|---|
| Build output is missing or stale | The relevant build command and project verification |
| A script throws or behaves incorrectly | Logs and a focused test |
| An NPC uses the wrong scheme or animation | AI and logics |
| A form is missing or misaligned | UI forms |
| Weather does not switch as expected | Weather |
| Lua code is slow or uses too much memory | Performance statistics |
| A Lua API or engine callback behaves unexpectedly | Engine debugging |
The XRF debug panel can inspect objects, managers, tasks, treasures, memory, profiling, and merged runtime data without leaving the game.
Basic workflow
- Reproduce the issue with a known engine variant and save.
- Rebuild only the affected target when possible.
- Check the engine and Lua logs for the first relevant error.
- Inspect live state with the debug panel or an engine overlay.
- Reduce the problem to a focused test, config section, scheme, or engine API call.
- Verify the fix with the same engine, save, and reproduction steps.
Do not build scripts with --no-lua-logs while investigating runtime behavior. Use a disposable save for console
commands, object mutation, teleportation, or forced weather changes.