Input Actions Configuration
Status: Draft
The plugin integrates with Godot’s standard InputMap system. GBActions is a simple resource containing editable action names that correspond to the input mappings configured in Godot’s project settings.
Overview
Section titled “Overview”Refactored in v5.0.0: Action names consolidated from scattered locations into centralized GBActions resource.
There is no custom input system - the plugin simply responds to standard Godot input events through the InputMap. GBActions provides a centralized location for these action name strings, making them easier to manage and customize.
GBActions is not a system - it’s a simple configuration resource containing:
- String constants for action names (e.g.,
"gb_select","gb_rotate") - Editable properties that can be customized per project
- Centralized location for all input action names used by the plugin
- Mapping to Godot’s InputMap configured in Project Settings → Input Map
How It Works
Section titled “How It Works”- Plugin User Setup: In Godot’s Project Settings → Input Map, the user defines input actions
- GBActions Resource: Contains string names matching the InputMap action names
- Systems Integration: ManipulationSystem and PlaceableSelectionUI read from GBActions to know which input actions to listen for
- Standard Godot Input: All input handling uses Godot’s built-in
Input.is_action_pressed(), etc.
Major Enhancements in v5.0.0
Section titled “Major Enhancements in v5.0.0”🏗️ Architectural Improvements
Section titled “🏗️ Architectural Improvements”- Centralized Action Names: Action name strings refactored from scattered locations (BuildingSystem, ManipulationSystem) into GBActions resource
- Easier Customization: All input action names in one location for project-specific customization
- Better Organization: Clear separation between plugin action names and project input configuration
🔧 Configuration Refactoring
Section titled “🔧 Configuration Refactoring”- GBActions Resource: Refactored (not new) - consolidates action name strings previously scattered across multiple systems
- Editable Action Names: Each action name is an exported property that can be customized
- Project Integration: Seamless integration with Godot’s standard InputMap system
📊 Action Categories
Section titled “📊 Action Categories”- Building Actions: Core building mode controls (
gb_select,gb_cancel,gb_rotate) - Manipulation Actions: Move, rotate, flip, and demolish controls
- Navigation Actions: Grid targeting and camera controls
- UI Actions: User interface interaction controls
🐛 Debugging & Testing
Section titled “🐛 Debugging & Testing”- Action Name Validation: Easier to debug input issues with centralized action names
- Project Customization: Clear documentation of which actions need InputMap configuration
- Consistency Checking: All systems use the same action name references
Core Actions (Proposed)
Section titled “Core Actions (Proposed)”| Action Name | Default Binding (Example) | Purpose |
|---|---|---|
gb_select | Left Mouse Button | Pick placeable / confirm placement |
gb_cancel | Right Mouse Button / Esc | Cancel preview / exit mode |
gb_rotate | R key / Mouse Wheel Click | Rotate active preview |
gb_cycle_variant_next | E / Mouse Wheel Up | Next variant in sequence |
gb_cycle_variant_prev | Q / Mouse Wheel Down | Previous variant |
gb_toggle_mode | Tab | Cycle build modes (build / demolish / inspect) |
gb_multi_place_toggle | M | Enable/disable multi‑place session |
(Adapt these to actual project actions if already defined.)
Setup Process
Section titled “Setup Process”1. Configure InputMap
Section titled “1. Configure InputMap”In Godot’s Project Settings → Input Map, add these actions:
2. Customize GBActions (Optional)
Section titled “2. Customize GBActions (Optional)”Edit the GBActions resource to change action names if needed:
@export var select_action: String = "my_custom_select" # Instead of "gb_select"3. Systems Integration
Section titled “3. Systems Integration”- ManipulationSystem: Reads from GBActions to know which input actions to listen for
- PlaceableSelectionUI: Uses these action names for build mode initiation
- All input handling: Uses standard Godot
Input.is_action_pressed(actions.select_action)
Action Flow Architecture
Section titled “Action Flow Architecture”Input Event Processing
Section titled “Input Event Processing”Flow: Raw Input Event → Godot InputMap → GBActions Resource → ManipulationSystem → State Update → UI/Visual Feedback
Key Points
Section titled “Key Points”- No custom input system - pure Godot InputMap integration
- GBActions is just a string container - editable action name references
- Systems read action names from GBActions resource at runtime
- Plugin user configures the actual key bindings in Godot’s InputMap
Handling Flow
Section titled “Handling Flow”- Input event received through Godot’s standard input system
- Systems check
Input.is_action_pressed(GBActions.select_action) - ManipulationSystem processes the input and updates state
- UI updates automatically through signals
Event Guarding
Section titled “Event Guarding”During preview:
- Confirm suppressed if
can_placefalse - Rotate / variant cycling allowed even when invalid
- Cancel always available
Multi‑Place Mode
Section titled “Multi‑Place Mode”If enabled, after a successful placement the preview remains active; selection persists. Exiting requires explicit cancel or mode switch.
Mouse vs Keyboard Cohesion
Section titled “Mouse vs Keyboard Cohesion”Variant cycling supports both dedicated keys and mouse wheel for rapid iteration. Ensure the InputMap binds both for accessibility.
Input Feedback
Section titled “Input Feedback”Invalid actions (e.g. confirm when invalid) should produce subtle feedback:
- Flash invalid indicator color
- Optional tooltip / message via GBMessages
Cross‑References
Section titled “Cross‑References”- Manipulation System:
systems/manipulation_system.md - Configuration & Settings (Actions list resource):
systems/configuration_and_settings.md - Placeable Selection UI:
systems/placeable_selection_ui.md
Community & Purchase Hub: Linktree – All Grid Builder Links