Debugging
In-game diagnostics, the flags and environment variables the code reads, and how to reproduce a problem headless (checked against the source on 2026-11-10).
In-game diagnostics
Typed cheat words work in Play when the build has cheats enabled (the CMake option
GALAXY_EGGBERT_ENABLE_CHEATS, ON by default; OFF compiles out typed words, F12 and the hidden
cheat menu). The full list is on Cheats & Diagnostics; these are the ones
that help when debugging:
| Word or key | Effect |
|---|---|
debug | Toggles the diagnostics panel (only in Play): simulation time and ticks, mission and sky region, lives, Blupi's raw position and cell, velocity in blocks/s, yaw, movement mode (ground or air, vehicle), animation state and icon, game speed, keys and touches held, gamepad and accelerometer state. Upper right on desktop, upper centre on touch layouts. Lines built by src/GalaxyEggbert/Game/DebugOverlay.hpp |
position | Shows Blupi's place (x, y, z) in the active cheats' list, with the world's X, Y and Z axes drawn as arrows that turn with the camera |
fps | Shows the frames drawn per second in the cheats' list |
ghost, megablupi, zoom | Walk through walls; invincibility; step the chase camera out |
help / cheats, F1 | A paused overlay listing every cheat word; F1 shows the controls help |
| F5, F6, Tab | Normal and fast game speed; Tab steps slow motion 0.5, 0.25, 0.125 and back. F7/F8 (faster still) only after the quick cheat |
| F12 | The cheat menu |
fairplay turns the toggles off and locks cheat entry (typing it again unlocks);
honest locks every cheat until the game quits. If a debugging word does nothing, check for
those.
Command-line flags
Parsed in src/GalaxyEggbertCNA/main.cpp. Run the game from its build directory, where a
post-build step stages its assets.
| Flag | Effect |
|---|---|
--mission N | Skip the menus and start mission N |
--spawn x,y,z[,yaw] | With --mission: place Blupi at that raw grid position (yaw 0 faces -Z, 90 faces +X) |
--autoplay <script> | Play the mission by a QA script, write autoplay_trace.txt, exit 0 when it passed (Testing & QA) |
--galaxy | With --mission: start from the selected player's own galaxy |
--golden-capture, --golden-capture-trace | The deterministic captures behind tests/golden/ |
--record-demo <file>, --demo-ticks N, --demo-title <text>, --verify-demo <file> | Record a main-menu demo; replay one and compare its end state (tools/record_demo.sh, tools/verify_demos.sh) |
--user DIR | Keep the player's files (savedata.txt, resume.txt, demos/, customworlds/) in DIR instead of the system's per-user folder; GALAXY_USER_DIR does the same |
$XDG_DATA_HOME/Galaxy Eggbert on Linux). When you
experiment with saves, resume or the editor, pass --user with a throwaway directory so your own
progress is not touched. The QA scripts already set GALAXY_USER_DIR to their run directory.Diagnostic environment variables
Each of these is read by the code named; the effects and graphics settings themselves
(GALAXY_EFFECTS, GALAXY_TEXTURES) are on Configuration.
| Variable | Effect | Read in |
|---|---|---|
GALAXY_PERF=1 | Every 120 frames prints the mean draw time and the models drawn, their triangles and the models culled per frame; also prints how terrain changes were patched or rebuilt and how long it took | GalaxyEggbertGameDraw.cpp, GalaxyEggbertGameLoad.cpp |
GALAXY_MODEL_CULL=0 | Draws every object model, without the frustum test | GalaxyEggbertGame.cpp |
GALAXY_EFFECTS_DEBUG=shadow|occlusion|gi|sprites | With the 3D effects on: draws the terrain as the sun's shadow factor or the ambient occlusion alone; gi and sprites (Ultra) show the light from around and the light the sprites take | SceneShaders.cpp |
GALAXY_ULTRA_DEBUG=1..9 | Ultra's final pass: 1 no grade, 2 no glow, 3 fixed exposure, 4 the scene as drawn, 5 the exposure, 6 ambient occlusion, 7 contact shadow, 8 reflection weight, 9 the light scattered by the air | UltraFinish.cpp |
GALAXY_RELIEF_GI=0 | Ultra without the global illumination on the terrain reliefs, to compare | WorldRenderer.cpp |
GALAXY_INTERP_TRACE=<file> | In Play, writes one line per drawn frame to the file: the step, the interpolation alpha, the drawn eye position, camera shake and the moving objects drawn between steps (for frame rates above 60) | GalaxyEggbertGameDraw.cpp |
GALAXY_RESUME_SELFTEST=<ticks> | At that tick of a mission, serializes the resume log, restores from it, and prints RESUME SELFTEST equal or ... different: <fields> (exit code 1 when different) | GalaxyEggbertGameDemo.cpp |
GALAXY_TERRAIN_RELIEF=0|1 | Overrides the Setup's 3D terrain reliefs; _DIR reads reliefs from another directory, _RADIUS sets the radius around the camera's target (default 8 blocks), _OVERHANG=1 keeps overhangs into the air, _TIMING prints the first relief build's time | GalaxyEggbertGameLoad.cpp, GalaxyEggbertGameScene.cpp |
GALAXY_ACCEL_PAD=1 | Shows the accelerometer-steering pad without a sensor | GalaxyEggbertGameUpdate.cpp |
AUTOPLAY_SHOTS=N, AUTOPLAY_REALTIME=1 | With --autoplay: save a frame every N ticks into autoplay_shots/; pace at 60 Hz instead of as fast as possible | GalaxyEggbertGame.cpp |
Headless runs
The game needs a GL context. Under Xvfb, keep it silent with the dummy audio driver, as the QA scripts do:
cd build-cna-opengl3
SDL_AUDIODRIVER=dummy SDL_VIDEODRIVER=x11 xvfb-run -a -s "-screen 0 1280x720x24" \
./GalaxyEggbert --user qa-user --mission 12 --spawn 48,1,68,0For anything you want to repeat, prefer the scripts: tools/autoplay.sh for gameplay and
tools/qa_live.sh for screenshots (Testing & QA). Intermittent
loss of window focus or input has been seen under Xvfb; it has not been traced to a defect in this
code.
Reproducing a gameplay bug
- Start at the place:
--mission N --spawn x,y,z,yaw(thedebugpanel'scellline gives raw coordinates). - Write a short probe script (
tools/autoplay/probes/holds examples) withtrace Nto log every tick,shots Nto save frames, andmortalto keep going past a death; run it withtools/autoplay.sh. The run is deterministic, so it reproduces the same way every time. - Compare with the original's code (
Decor.cppand friends inmobile-eggbert) and search the ledgers before changing anything. - Turn the reproduction into a test that fails without the fix (usually in
VerifyBlupiMovementorVerifyInteractionSystem).
Context loss (F9)
On native desktop builds, CNA's runtime maps F9 to a simulated GL context loss and recreation. Use it to
check that textures and meshes come back. The black distant floor seen after F9 was a CNA defect
(upstream_bugs.md UB-009: only the base mip level was restored), fixed in CNA; the game has no
workaround of its own.
Logs
- The game writes its messages to standard output, prefixed
GalaxyEggbertCNA:(for example the relief count and3D effects:lines when a shader or render target cannot be made). - The QA scripts keep the game's output as
game.login their run directory, next toautoplay_trace.txt. - Android:
adb logcat -s SDL SDL/APP GalaxyEggbertshows the game's and CNA's output (ANDROID.md).
API documentation (Doxygen)
When CMake finds Doxygen, it adds the target GalaxyEggbertDocs
(cmake --build build-cna-opengl3 --target GalaxyEggbertDocs), which runs Doxygen in the build
directory with a configured copy of the repository's Doxyfile. That file leaves
INPUT empty and RECURSIVE = NO, so as committed it does not point Doxygen at the
sources; the output has not been checked for this page. The headers' own comments (and the
Classes pages) are the better reference.