Skip to content
Grid Building Docs

ManipulationSystem

Summary

Section titled “Summary”

System for manipulating (move, rotate, flip, demolish, build preview integration) grid building objects.

Responsibilities: - Creates and manages a temporary manipulation copy (“move copy”) when entering MOVE workflows. - Delegates spatial translation to the external targeting/positioner system. (No per-frame movement logic here.) - Sets up and tears down placement validation rules for move and build actions. - Manages physics layer disabling/enabling during active manipulation. - Emits structured status transitions via ManipulationData.status (STARTED, FAILED, FINISHED, CANCELED).

Non‑Responsibilities (by design): - Calculating or enforcing cursor/keyboard driven position updates (handled by GridTargetingSystem & its positioner node). - Determining selection/target acquisition (handled by targeting state & systems). - Rendering or UI feedback (delegated to name displayer / external UI nodes).

Design Notes: - The move copy is parented under the active positioner when available so that any positioner movement (mouse, keyboard, gamepad) naturally repositions the copy without duplicate logic or tight coupling. - If no positioner exists (edge/test fallback), the copy is parented under the manipulation parent as a legacy behavior. - Rotation / flip actions operate directly on the target Node2D passed in, typically the move copy’s root while an action is active.

Signals

Section titled “Signals”
signal move_indicators_ready( indicators: Array[RuleCheckIndicator] )

Emitted when move indicators have been fully set up after physics frame Passes the array of created indicators for debugging and validation

Methods

Section titled “Methods”
static func create_with_injection( p_parent: Node, container: GBCompositionContainer ) -> ManipulationSystem

Creates a ManipulationSystem with dependency injection from container.

func _are_dependencies_ready( ) -> bool

Validates that all required dependencies are properly set. Returns list of validation issues (empty if valid). Checks if all critical dependencies are ready for operation. Returns true if the system can safely process operations.

func get_runtime_issues( ) -> Array[String]
func resolve_gb_dependencies( p_container: GBCompositionContainer ) -> void
func _ensure_manipulation_settings( ) -> void

Ensures _manipulation_settings is initialized with a default instance if null. This prevents string formatting crashes when dependencies haven’t been resolved yet. The default will be replaced with the real settings when resolve_gb_dependencies() is called.

func _check_dependencies_resolved( ) -> bool

Attempts to move a targeted object.

Checks if dependencies have been properly resolved. Returns false and logs error if not resolved.

func _get_unsupported_node_type_message( p_node_class: String ) -> String

Gets the unsupported node type error message. p_node_class: The class name of the unsupported node

func try_move( p_root: Node ) -> ManipulationData

Attempts to move a targeted object. Failed or successful move data available through state signals.

p_root: Node - Container node to search for Manipulatable component

func _start_move( p_data: ManipulationData ) -> bool

Validate all possible reasons for failing

Creates a manipulation (move) copy and prepares rule validation.

Flow: 1. Clone source manipulatable root via create_copy. 2. Parent under manipulation parent node. 3. Reset transform if configured. 4. Align initial global position to the parent root. Parent root is responsible for moving object. 5. Initialize placement validation rules using IndicatorManager. 6. Disable configured physics layers on the original source.

Returns true if setup succeeded; false if rule setup failed.

func try_placement( p_move: ManipulationData ) -> ValidationResults

Get the root of the move copy for transform operations

Attempts to place a manipulated object at the desired location. Validates placement rules and commits the move if successful.

p_move: ManipulationData - Movement data containing source and move copy information

func is_ready( ) -> bool

Checks if the manipulation system is ready for operations.

func cancel( )

Cancels the active manipulation action.

func try_demolish( p_manipulatable: Manipulatable ) -> ManipulationData

Only succeeds if the object is configured as demolishable.

p_manipulatable: Manipulatable - Component to demolish

func demolish( p_manipulatable: Manipulatable ) -> bool

Demolishes a manipulatable object and returns true when the object is successfully removed. p_manipulatable: Manipulatable - Component to demolish; defaults to active manipulatable when null

func rotate( p_target: Node, degrees: float )

Rotates the target node by the specified degrees. Delegates to ManipulationParent’s transform coordination.

func flip_horizontal( p_target: Node )

Flips the target node horizontally. Delegates to ManipulationParent’s transform coordination.

func flip_vertical( p_target: Node )

Flips the target node vertically. Delegates to ManipulationParent’s transform coordination.

func get_targeted( ) -> Node

Get the current targeted manipulatable for this manipulation system. Returns the root node if a manipulatable is set, otherwise null.

func set_targeted( p_obj_root: Node ) -> void

Sets the targeted object by resolving it to a Manipulatable component. Delegates to ManipulationState.set_targeted() which uses GBMetadataResolver.

func _unhandled_input( event: InputEvent ) -> void

Handles input events for manipulation system controls. Responds to demolish, info, moving, and off mode actions.

event: InputEvent - Input event to process for manipulation controls

func _input( event: InputEvent ) -> void

Route standard input to unhandled to support tests or scenes that call _input directly.

func _perform_manipulation_actions( event: InputEvent )
func _finish( p_data: ManipulationData ) -> void

Finishes a manipulation action and cleans up resources.

func _on_mode_changed( p_mode: GBEnums.Mode )
func _process( _delta: float ) -> void

While moving, keep the target copy aligned with the positioner so tests detect movement shifts.

func _on_target_changed( p_new: Node, p_old: Node )

:::note[Note] _process removed. Movement visuals are driven by reparenting the move copy under the positioner. :::

func _on_preview_changed( p_preview: Node )
func _send_manipulation_failed( p_manipulated: Manipulatable, p_action: GBEnums.Action )

Sends manipulation failed signal for failed operations.

func _disable_selected_physics( p_container: Node2D )

Disables physics layers for objects during manipulation.

func _enable_selected_physics( )

Re-enables physics layers that were disabled during manipulation.

func _on_source_tree_exiting( ) -> void

Handles source object leaving the scene tree during manipulation. Automatically cancels manipulation to prevent operating on deleted objects.

func _disconnect_source_monitoring( p_data: ManipulationData ) -> void

Disconnects source object monitoring signal if connected.

func _get_demolish_display_name( p_manipulatable: Manipulatable ) -> String

Gets a display name appropriate for demolish messaging, preferring the manipulatable root when available.

func _clear_manipulation_data( p_data: ManipulationData ) -> void

Clears manipulation data reference when the provided data matches the active state.

func _debug_node( n )
func _describe_layers( obj )

Source

Section titled “Source”

addons/grid_building/systems/manipulation/manipulation_system.gd

This API reference is automatically generated from the plugin source code. For implementation examples and usage guides, see the guides section.