ManipulationSystem

AUTO-GENERATED FILE — DO NOT EDIT MANUALLY

Source: systems/manipulation/manipulation_system.gd

Version: 5.1

class_name: ManipulationSystem extends: GBSystem

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 view / 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

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

Exports

(none)

Methods

• resolve_gb_dependencies()
  • Resolves dependencies from the container.

[param p_container] GBCompositionContainer from which dependencies are resolved.

• _log_warning()
• _ensure_state_signal_connections()
• _ensure_targeting_connections()
• _ensure_mode_connections()
• _ensure_building_connections()
• _are_dependencies_ready()
  • 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.
• get_runtime_issues()
• _validate_dependencies()
  • Validates that all required components were injected by the container. Returns true if all dependencies are present; logs errors and returns false otherwise.
• _ensure_initialized()
  • Ensure dependencies are initialized; returns cached state or runs validation
• _ensure_manipulation_settings()
  • 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.
• _check_dependencies_resolved()
  • Checks if dependencies have been properly resolved. Returns false and logs error if not resolved.
• _get_unsupported_node_type_message()
  • Gets the unsupported node type error message. [param p_node_class] The class name of the unsupported node
• try_move()
  • Attempts to move a targeted object. Failed or successful move data available through state signals.[br][br] [code]p_root[/code]: [i]Node[/i] - Container node to search for Manipulatable component [return] ManipulationData describing the attempted move (status/message set on failures).
• _start_move()
  • 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.

• try_placement()
  • Attempts to place a manipulated object at the desired location. Validates placement rules and commits the move if successful.[br][br] [code]p_move[/code]: [i]ManipulationData[/i] - Movement data containing source and move copy information [return] Validation results from placement rule evaluation.
• is_ready()
  • Checks if the manipulation system is ready for operations.
• cancel()
  • Cancels the active manipulation action. Atomic/idempotent: safe to call multiple times. Guarantees that after return: indicators are torn down, physics restored, targeting cleared, active manipulatable reset, and manipulation state data == null.
• try_demolish()
  • Attempts to demolish the given manipulatable object and returns manipulation data for result inspection. Only succeeds if the object is configured as demolishable. Uses ManipulationStateMachine for validation logic (pure, testable).

[code]p_manipulatable[/code]: [i]Manipulatable[/i] - Component to demolish [return] ManipulationData describing the demolish attempt.

• demolish()
  • Demolishes a manipulatable object and returns true when the object is successfully removed. The object is queued for deletion synchronously - it will be freed at the end of the frame. [code]p_manipulatable[/code]: [i]Manipulatable[/i] - Component to demolish; defaults to active manipulatable when null [return] true if demolish was successful, false otherwise
• rotate()
  • Rotates the target node by the specified degrees. Delegates to ManipulationParent’s transform coordination. [param p_target] Node to rotate. [param degrees] Degrees to rotate (positive/negative allowed). [return] True when rotation was applied; false when target is unsupported.
• flip_horizontal()
  • Flips the target node horizontally. Delegates to transform handler component.
• flip_vertical()
  • Flips the target node vertically. Delegates to transform handler component.
• get_targeted()
  • Get the current targeted manipulatable for this manipulation system. Returns the root node if a manipulatable is set, otherwise null.
• set_targeted()
  • Sets the targeted object by resolving it to a Manipulatable component. Delegates to ManipulationState.set_targeted() which uses GBMetadataResolver.
• _unhandled_input()
  • Handles input events for manipulation system controls. Responds to demolish, info, moving, and off mode actions.[br][br] [code]event[/code]: [i]InputEvent[/i] - Input event to process for manipulation controls
• _set_mode()
• _toggle_mode()
• _input()
  • Route standard input to unhandled to support tests or scenes that call _input directly.
• _perform_manipulation_actions()
• _finish()
  • Finishes a manipulation action and cleans up resources. Uses ManipulationStateMachine to determine cleanup commands. Atomic/idempotent: safe to call multiple times.
• _on_mode_changed()
• _process()
  • While moving, keep the target copy aligned with the positioner so tests detect movement shifts.
• _apply_orchestrator_output()
• _apply_effect()
• _on_target_changed()
• _on_preview_changed()
• _clear_manipulation_data()
  • Helper to clear manipulation data
• _get_demolish_display_name()
  • Gets a display name appropriate for demolish messaging, preferring the manipulatable root when available.
• _debug_node()
  • Gets a display name appropriate for demolition messaging, preferring the manipulatable root when available.
• _describe_layers()
• has_active_manipulation()
  • Returns true if the system is currently processing an active manipulation Active manipulation means there’s manipulation data with a non-terminal status