Skip to content

Add debug console with teleport, stat editing, and spawn commands #76

@aebrer

Description

@aebrer

Summary

Add a developer/debug console toggled with the ~ key that lets us teleport the player, modify stats on the fly, and spawn items/entities anywhere. As the world gets more complex, this saves huge amounts of manual walking and RNG-wrangling when testing encounters, loot tables, and level transitions.

Current Behavior

There is no in-game debug tooling. Testing a specific level, enemy, item drop, or stat threshold requires playing through the game naturally or manually editing save/state files.

Proposed Behavior

A hidden LineEdit-based console overlay that opens with ~, accepts typed commands, supports Tab autocomplete, and closes with ~ or Escape. While open, game input (movement, camera, actions) is suppressed.

Acceptance Criteria

  • ~ key toggles the console overlay visible/hidden
  • Console has a scrollable output log and a single-line input field
  • help command lists all available commands with brief usage
  • Tab autocomplete cycles through matching commands and entity/item IDs
  • teleport <x> <y> — instant move to grid coordinates in current level (player.snap_visual_position() + grid update)
  • level <level_id> — transition to any loaded level (LevelManager.transition_to_level())
  • stat <stat_name> <value> — set HP, Sanity, Max HP, Max Sanity, STR, PER, ANOM, etc. (StatBlock)
  • spawn_item <item_id> [x] [y] — drop item at player position or specified grid coords (ItemSpawner.spawn_forced_item())
  • spawn_entity <entity_id> [x] [y] — spawn entity at player position or specified grid coords (EntityRenderer.add_entity_billboard() / ChunkManager._spawn_debug_entity_near_player() pattern)
  • clear or cls — empties the console output log
  • Console blocks all gameplay input while focused
  • Console works in both FPV and Tactical camera modes

Technical Notes

  • UI: A CanvasLayer with a PanelContainer + RichTextLabel (output) + LineEdit (input), probably added to scenes/game.tscn or as a separate autoload scene.
  • Input: Use _unhandled_input on the console to catch ~ when not focused; while focused, LineEdit handles text input. Consider adding a "debug_console" action to the InputMap.
  • Command parser: Split by whitespace; first token is command, rest are args. Simple switch/lookup table.
  • Autocomplete sources:
    • Commands: static array
    • Entity IDs: EntityRegistry._entities.keys() (or public getter)
    • Item IDs: may need to expose from ItemPool or item definition files
  • Teleportation: Reuse player.snap_visual_position() after updating player.grid_position. Ensure chunk is loaded at target before teleporting.
  • Entity/item spawn at arbitrary coords: Need to verify the target chunk is generated/loaded; if not, either force-load it or reject the command with a message.
  • Dev-only gating: Could wrap initialization in a debug_enabled check, but since this is a single-player game with no anti-cheat concerns, always-available is fine as long as it's hidden.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestgameplayGameplay mechanics and designneeds-researchReady for automated research pass

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions