Debug

1 - Debug Mode

Debug Mode is a checkbox on the Game Manager. It tells the framework that you are running a level directly out of the Editor rather than booting the game properly, and systems across the framework adjust accordingly.

The problem it solves: a GS_Play project normally boots to a title stage, waits for the player to start a game, then loads the first level and places the player. Pressing play on the level you are currently editing should not do any of that — it should just run this level, now.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• What Changes
• Reading the Flag
• Using It in Your Own Manager
• See Also

What Changes

Debug Mode is a single flag, but three systems consult it, and together they turn “boot the game” into “run this level”.

Game Manager — the game begins on its own

Normally startup completing means the framework is ready, and the game itself begins when your project decides it does — a title screen, a New Game button, a cutscene ending.

In Debug Mode, the Game Manager calls begin-game itself as soon as startup completes. OnBeginGame fires with no title flow, so gameplay systems come up immediately.

Stage Manager — you stay in the level you are editing

Normally the Stage Manager loads the project’s configured starting stage once startup completes, unloading whatever level you happened to be in.

In Debug Mode, if the current level has a Stage Data component, the Stage Manager adopts that level as the current stage instead of loading the default one. You keep working in the level you pressed play on.

If the level has no Stage Data, there is nothing to adopt and the default stage loads as usual — which is a useful thing to know when a level unexpectedly navigates away from itself.

Unit Manager — the player is placed for you

Normally a player unit waits for the correct level to load and for the game flow to position it.

In Debug Mode, the Unit Manager places the player unit at the debug exit point as soon as it registers, so you get a controllable character in the level without a stage transition having happened.

Reading the Flag

IsInDebug on the Game Manager request bus returns the flag, and it is exposed to scripts as In Debug.

Every manager already reads it. GS_ManagerComponent queries it during activation and caches it, so any manager subclass has the answer available without asking again.

Using It in Your Own Manager

The pattern the built-in managers follow is worth copying: branch on the flag anywhere your system’s behaviour depends on how the game was started rather than on the game’s state.

Typical uses:

• Skip a wait. If your manager normally waits for a game-flow cue that debug startup never sends, act immediately instead.
• Substitute a stand-in. Provide a debug default where a real session would have supplied something — a placeholder save, a default loadout, a starting position.
• Say more. The framework’s managers print what they are doing in debug. Combine with Logging Depth on the individual manager you are diagnosing.

A custom manager reads the cached flag it inherits from the manager base, so there is nothing to wire up — the value is populated before your setup hook runs.

The manager component template already includes the query, so a scaffolded manager has the flag available from its first build.

See Also

For related systems:

• Game Manager — where the flag is authored
• Manager (Base) — caches the flag for every manager
• Stage Manager — the level-loading branch
• ImGui Debug Menu — the other in-game debug surface

For conceptual overviews and usage guides:

• The Basics: Debugging

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

2 - ImGui Debug Menu

GS_Play adds a GS_Play entry to the in-game ImGui menu bar that any gem can contribute to. Each gem owns its own sub-menu, its own contents, and its own imgui dependency.

The core invariant: the anchor is content-free. GS_Core provides a component that broadcasts while the menu bar is being drawn, and gems draw their own entries in response. GS_Core never knows what other gems put there.

That makes the debug surface decentralised — a gem’s debug UI ships and versions with that gem — and it is a small, clear example of how the framework prefers extension to work.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• Shipped Menus
• How It Works
• Adding a Menu to Your Gem
• See Also

Shipped Menus

Core ▸ Options

The Options window reads the entire option catalog, groups it by category, and renders the right widget for each option — checkbox, slider, dropdown or colour picker. It offers Apply All, Save, Reset All and per-option reset, with tooltips showing each option’s key, description and apply-target type. A preset dropdown lists Custom plus every loaded preset, keeping a snapshot of hand-tuned values so you can try a preset and return to your own.

Every edit goes through OptionsManagerRequestBus, so it exercises apply, persist and notify exactly as your own menus will. This is the fastest way to verify a new option end to end — author it, run, and drive it live before building any UI.

Audio ▸ Audio Mixer

Enumerates the configured volume channels and gives each a slider, plus master. Useful for balancing a mix without rebuilding.

How It Works

GS_ImGuiMenuComponent in GS_Core draws the top-level entry and broadcasts on a notification bus while the menu bar is open. Handlers draw their own sub-menu in response.

The bus is ordered. Each handler returns a sort key, so menu order is deterministic rather than dependent on which gem happened to register first. Core returns the lowest key and is always first; the default places everything else after it.

A handler that only wants a menu entry implements the menu notification alone. A handler that also wants windows additionally implements the imgui update listener — one component can own both its menu entry and the windows it opens. Core and PhantomCam both do this.

Adding a Menu to Your Gem

Create a component in your gem that handles the menu notification, returns a sort key, and draws its own sub-menu. Add the imgui update listener too if it opens windows.

Three things bite in practice, and all three are worth checking before concluding your menu is broken:

CMake. ImGui dependencies go PUBLIC on your gem’s private object target so the enable define propagates to the editor target through its public dependency, which keeps it ODR-safe. The editor target then needs no imgui configuration of its own. Add the imgui gem as a runtime dependency of the client module.

Guard each window separately. If your update handler returns early when one window is closed, every window below that point in the same function silently stops drawing. Check each window’s open flag around its own draw rather than returning.

See Also

For related systems:

• Settings — what the Core Options window edits
• Options Manager — the bus every edit writes through
• Mixing & Effects — what the Audio Mixer window drives

For conceptual overviews and usage guides:

• The Basics: GS_Core

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.