Auto-explore system (Caves of Qud style) #40
Description
Summary
Implement an auto-explore feature inspired by Caves of Qud. Press Y (controller) or Y key (keyboard) to toggle auto-explore. The player automatically moves through unexplored areas of the current floor, taking one step per tick at a configurable speed.
Reference: Caves of Qud
Qud's auto-explore:
- Automatically navigates the current zone, prioritizing unexplored tiles
- Stops when: hostile creature spotted, player takes damage, player becomes hungry
- Can dig through walls if digging tools equipped (not relevant for us)
- Configurable speed (turns per second)
- Configurable enemy detection settings (ignore by level/distance)
- Very popular QoL feature — makes backtracking and floor-clearing painless
Controls
- Y button (controller) — toggle auto-explore on/off
- Y key (keyboard) — toggle auto-explore on/off
- Any movement input or attack cancels auto-explore immediately
Exploration Tracking
A tile is "explored" if the player has been within perception range of it — i.e., close enough that an item on that tile would have been detected. This uses the existing perception radius (base 15 tiles + 5 per PERCEPTION stat, see minimap.gd). Auto-explore targets the nearest unexplored tile (one that has never been within perception range).
Auto-Stop Conditions (ALL configurable)
| Setting | Default | Description |
|---|---|---|
| Explore speed | ~5 turns/sec | Turns per second during auto-explore |
| HP threshold | 50% | Stop when HP drops below X% |
| Sanity threshold | 50% | Stop when Sanity drops below X% |
| Enemy threat detection | ON (any threat) | Stop when an enemy of threat level ≥ X is perceived on minimap |
| Stop for items | ON | Stop when an item or vending machine is encountered |
| Stop on damage | ON | Stop when player takes damage from any source |
| Stop at stairs/exit | ON | Stop when stairs or exit is reached |
| Stop when fully explored | ON | Stop when no reachable unexplored tiles remain |
The only non-configurable stop is manual input (any movement/action input always cancels auto-explore).
Settings UI
Add a new Auto-Explore tab in the settings panel (same popup style as the Codex). Contains sliders/toggles for all the configurable options above.
Consideration: Browsing UI During Auto-Explore
Playtester request: ability to open and browse the Codex (and potentially other read-only UI panels) while auto-explore continues in the background. This would let players read item/enemy entries during downtime instead of staring at the screen.
Design thoughts:
- Auto-explore would need to run as a background process independent of UI state
- Only read-only panels (Codex, maybe inventory viewing) — anything that requires game decisions (vending machine, equip) should pause or cancel auto-explore
- Stop conditions should still trigger and interrupt/overlay the UI with a notification
- May be too complex for good UX — evaluate during implementation, omit if it feels janky
Future Consideration: Directional Auto-Explore
Consider a variant where auto-explore prefers the overall direction the camera is facing when activated. Instead of pure nearest-unexplored, it would bias pathfinding toward the forward direction. Could be a toggle or separate binding. Useful for "I want to keep going this way" vs "explore everything."
Implementation Notes
- Pathfinding infrastructure already exists (
scripts/autoload/pathfinding_manager.gd) - Perception range already calculated in
minimap.gd(15.0 + perception * 5.0) — reuse this for exploration tracking - Need a persistent set of "perceived tiles" that gets updated each turn as the player moves
- New player state in the input state machine for auto-explore mode
- Visual indicator (HUD element) showing auto-explore is active
References
scripts/autoload/pathfinding_manager.gd— existing A* pathfindingscripts/ui/minimap.gd— perception range calculation, item discoveryscripts/player/input_state_machine.gd— player state machinescripts/player/states/— existing player statesscripts/ui/— settings panel, codex panel (reference for tab UI)