Mode Toggle Behavior
In the Grid Building system, pressing a mode button (or its corresponding keyboard shortcut) will activate that mode. If you press the same button or key again while the mode is already active, the system will toggle back to OFF mode—provided the corresponding system (e.g., BuildingSystem, ManipulationSystem) exists and is enabled.
System Requirements per Mode
Section titled “System Requirements per Mode”Mode toggling only succeeds when its backing runtime systems and injected contexts are active (created + dependency validated). If a required system is missing or failed injection, pressing its action will either do nothing or immediately revert to OFF.
| Mode | Requires Active System(s) | Additional Requirements | Notes |
|---|---|---|---|
Build (BUILD) | BuildingSystem | States: building, targeting; IndicatorManager available via composition; valid GBConfig settings.building | Second press toggles OFF if still in BUILD. Preview cleared on exit. |
Move (MOVE) | ManipulationSystem | Active manipulatable target (via targeting state); manipulation.parent assigned | If setup fails (no target / invalid), status becomes FAILED and mode remains OFF. |
Demolish (DEMOLISH) | ManipulationSystem | Target object with Manipulatable root; permissions in manipulation settings | Toggle pattern identical: press again returns OFF. |
Info (INFO) | ManipulationSystem (for name display / context) | Target or hover context resolvable; name displayer injected | Used for inspecting objects; does not modify placement context. |
Off (OFF) | — | — | Entered explicitly or by pressing the currently active mode action again. |
Both BuildingSystem and ManipulationSystem contain OFF-mode toggle logic independently. This redundancy ensures projects that exclude one system still achieve consistent press-again-to-off behavior without hidden coupling.
Validation / Injection Impact
Section titled “Validation / Injection Impact”- All required systems must have passed
get_runtime_issues()during composition container initialization. Warnings in the build log indicate missing dependencies that can block toggling. - For Build mode, if
_indicator_context.get_manager()is null, the attempt to enter or perform build actions will fail silently or log a warning and remain OFF. - For Manipulation-derived modes (MOVE/DEMOLISH/INFO) a valid
_states.manipulationcontext and target discovery (GBSearchUtils.find_first) are prerequisites.
Failure Scenarios
Section titled “Failure Scenarios”| Scenario | Result |
|---|---|
| User presses Build but BuildingSystem not present | No mode change (stays OFF) |
| User presses Move with no manipulatable target | Mode stays OFF; manipulation data status FAILED |
| User presses Demolish; system active but target root is null | Status FAILED; stays/off resets |
| User presses Build while already BUILD | Mode toggles to OFF, preview cleared |
| User presses Move again while MOVE | Mode toggles to OFF, move copy (if any) cleaned up |
Recommended Setup Order
Section titled “Recommended Setup Order”- Compose container & injector (
GBInjectorSystem.initialize). - Verify build log: no dependency warnings for Building / Manipulation systems.
- Confirm IndicatorManager available (created via composition/injection).
- Ensure
manipulation.parentnode assigned (used for parenting move copies). - Bind input actions mapping to invoke mode toggles.
With these conditions satisfied, all mode toggles will exhibit consistent press-to-activate / press-again-to-off behavior.
Example
Section titled “Example”- Pressing the Build button (or key) once: enters Build mode.
- Pressing the Build button (or key) again: returns to OFF mode.
- This applies to Move, Demolish, and Info modes as well, as long as their systems are present.
This behavior ensures quick toggling and prevents accidental mode lock-in during editing or gameplay.