Manipulation System

The ManipulationSystem is a core entry point that coordinates how players target, preview, rotate, and place objects. It bridges user input with the underlying placement and validation systems.

🎯 Key Entry Point

When to use: Any time you need to handle object placement, movement, or rotation in your game.

Main class: ManipulationSystem (extends Node) State management: ManipulationState (Resource) Configuration: ManipulationSettings (Resource)

Responsibilities

• Hold current selection & active variant (provided by the Placeable Selection UI)
• Maintain & update ManipulationState (preview, placing, cancelled)
• Build and cache an indicator setup (shape, offset, transforms) each frame
• Invoke the Placement Chain / Rule Pipeline when the cursor moves or state changes
• Expose high‑level perform actions: begin_preview(), confirm_place(), cancel()
• Relay configuration from GBConfig (e.g. rotation snap, default indicator size, visual settings)

Major Enhancements in v5.0.0

🏗️ Architectural Improvements

• Dependency Injection Integration: Full integration with GBCompositionContainer for better decoupling
• Enhanced State Management: Improved ManipulationState with better lifecycle handling
• Unified Configuration: All manipulation settings consolidated in GBConfig

🔧 Interaction Enhancements

• Better Move/Rotate/Flip/Demolish Modes: Enhanced manipulation modes from v4.1.0+ with improved validation
• Improved Preview System: More responsive preview updates and better visual feedback
• Enhanced Post-Placement Commands: Better handling of move, demolish, and info interactions
• Performance Optimizations: Reduced allocations and faster state transitions

📊 Mode Support (v4.1.0+)

The manipulation system now fully supports advanced manipulation modes:

• Move Mode: Pick and relocate existing instances with full validation
• Rotate Mode: Rotate structures with configurable snap angles
• Flip Mode: Mirror structures horizontally or vertically
• Demolish Mode: Remove structures with optional cost/refund logic

🐛 Debugging & Diagnostics

• Enhanced Logging: Better tracing of manipulation state changes
• Visual Debug Support: Integration with GBDebugSettings for manipulation debugging
• Performance Monitoring: Built-in timing for manipulation operations

Key Classes (Conceptual)

Name	Role
ManipulationSystem	Central controller; owns references to cursor/positioner, current placeable, rule validator, indicator node(s).
ManipulationSettings	Settings resource (rotation step degrees, default indicator shape, per‑frame validation toggle, etc.).
ManipulationState	Lightweight state data (selected, preview_active, last_valid, rotation_degrees, variant_index).
RuleCheckIndicator	Visual node updated by the system after each validation pass.
GBMessages	(Optional) Messaging bus for broadcasting placed / cancelled events.

Update Loop (High Level)

Player Input → (Actions) → ManipulationSystem
  1. Update cursor world position (snap to grid if configured)
  2. If selection changed: rebuild preview context
  3. If rotation/variant changed: recompute geometry & invalidate cached tiles
  4. Build IndicatorCollisionTestSetup
  5. Run Placement Rule Pipeline
  6. Update indicator visuals (valid / invalid)

Rotation & Variant Handling

Rotation snaps by rotation_step_degrees (e.g. 90°). The system never mutates the original resource; it applies rotation through a transform or meta data passed to rule evaluation.

Variant changes (from the UI) trigger:

• Reset rotation (configurable – default: preserve rotation)
• Clear cached collision geometry (variant may have different shapes)
• Re‑evaluate rules immediately

Interaction with Placement Chain

The Manipulation System produces a placement context consumed by the Placement Chain (systems/placement_chain.md):

• World position / snapped tile
• Active placeable & variant data
• Indicator collision setup
• Previously computed collision tiles (optional reuse)

The chain returns aggregated rule results which the Manipulation System maps to: indicator tint, tooltip text, can_place flag.

Event Flow

Trigger	System Reaction
Selection changed	Reset state, build new preview indicator
Move cursor	Rebuild test setup → rule pass → indicator update
Rotate (action)	Adjust rotation → invalidate tiles → rule pass
Cycle variant	Swap variant ref → invalidate tiles → rule pass
Confirm place	If can_place true: emit placed event, persist structure, optionally keep preview (multi‑place mode)
Cancel	Clear preview; state returns to idle

Post-Placement Commands (Move / Demolish / Info)

The Manipulation System also mediates interactions with existing placed instances:

Command	High-Level Steps	Notes
Move	Pick instance → capture its resource + state → enter move preview (same validation loop) → confirm to re‑instantiate at new location → remove original	Original instance remains until confirm; cancel restores without changes.
Demolish	Select instance → optional dependency / cost check → remove node + free resources → emit demolish event	Can reuse rule pipeline for pre-removal constraints.
Info	Hover/select → fetch PlaceableInstance metadata → display UI panel / tooltip	No rule validation; may highlight occupied tiles.

State Transitions:

• Idle → Move: sets selected_placeable from instance, enters preview mode.
• Idle → Demolish: triggers removal path (no preview) or enters a confirm overlay state.
• Idle → Info: temporary highlight; state often stays Idle (non-exclusive).

Input Mapping Examples (conceptual – defined in GBActions):

• gb_move
• gb_demolish
• gb_info

These actions integrate with the Placement Chain (see systems/placement_chain.md#move--demolish--info-commands) for shared validation & feedback when applicable.

Performance Notes

• Per‑frame validation only active while previewing; system can suspend checks if the cursor hasn’t moved and no rotation/variant change occurred (micro‑optimization).
• Cached tile map keyed by (variant_id, rotation, snapped_tile) can amortize rapid back‑and‑forth cursor motion.

Extensibility

Add new interaction (e.g. scaling) by:

1. Extending ManipulationSettings to hold scale steps
2. Injecting scale into test setup transform
3. Adjust rule evaluators that depend on size

Cross‑References

• Placement Rules Pipeline: systems/placement_rules.md
• Context & State Overview: systems/context_and_state.md
• Configuration & Settings: systems/configuration_and_settings.md
• Input & Actions: systems/input_and_actions.md
• Building System Process: systems/building_system_process.md

---

Support / Purchase Hub: Linktree – All Grid Builder Links