Manipulation Workflow

This guide captures a key 5.0-era architecture rule:

• ManipulationSystem owns the business logic.
• ManipulationParent owns visual transforms and input-driven transform changes.

Why this split exists

5.0-era manipulation intentionally separates:

• system orchestration + lifecycle
• from scene transform concerns

So that:

• the system remains testable (as much as possible in the 5.0 architecture)
• the node hierarchy remains understandable

Responsibilities

Scene hierarchy shape (5.0 mental model)

1
2
3
4

GridPositioner2D
  └── ManipulationParent
      ├── IndicatorManager
      └── Preview / move-copy

Defining Manipulation Settings

Configure manipulation behavior through the GBCompositionContainer:

ManipulationSettings Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# In your ManipulationSettings resource
extends ManipulationSettings

## Rotation settings
@export var enable_rotation: bool = true
@export var rotation_snap_angle: float = 90.0  # Degrees
@export var rotation_steps: int = 4  # 0, 90, 180, 270

## Flip settings  
@export var enable_flip_horizontal: bool = true
@export var enable_flip_vertical: bool = true

## Movement settings
@export var enable_movement: bool = true
@export var snap_to_grid: bool = true

Settings Assignment (Editor-Based)

1. Create ManipulationSettings Resource:

   • In Inspector: Create New Resource → ManipulationSettings
   • Save as manipulation_settings.tres

2. Configure Properties:

   • Enable/disable rotation, flip, and movement features
   • Set rotation snap angles and steps
   • Configure grid snapping behavior

3. Assign to Container:

   • Add to GBSettings → manipulation property
   • Systems will automatically use these settings

Marking Objects as Manipulatable

Adding Manipulatable Child Nodes

To enable rotation and flip functionality on placeable objects:

1
2
3
4
5
6

# Your placeable object scene structure
YourPlaceableObject (Node2D)
├── Sprite2D (or other visual components)
├── CollisionShape2D
└── Manipulatable (Node)  # <-- Marker node
    └── script: manipulatable_marker.gd

Manipulatable Marker Setup

Create the marker node:

1. Add a child Node named “Manipulatable”
2. Attach the manipulatable_marker.gd script
3. Configure manipulation properties

Marker script example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# manipulatable_marker.gd
extends Node
class_name ManipulatableMarker

@export var enable_rotation: bool = true
@export var enable_flip_horizontal: bool = true  
@export var enable_flip_vertical: bool = true
@export var custom_pivot: Vector2 = Vector2.ZERO

func _ready():
    # Register with manipulation system
    ManipulationSystem.register_manipulatable(get_parent())

Configuration Options

Rotation Control:

• enable_rotation: Allow rotation shortcuts
• custom_pivot: Set rotation center point
• Rotation follows ManipulationSettings snap angles

Flip Control:

• enable_flip_horizontal: Allow horizontal flip
• enable_flip_vertical: Allow vertical flip
• Flip operations respect object orientation

Visual Feedback:

• ManipulationParent shows rotation/flip previews
• IndicatorManager displays manipulation handles
• Visual feedback follows settings configuration

Key implication

• Preview copies and indicators are transformed together by the parent, while the system enforces workflow rules.
• Objects without a Manipulatable child node cannot be rotated or flipped
• Settings control which manipulation features are available globally

This separation is a precursor to the later 5.1/6.0 direction: keep scene mutation localized and keep workflow logic centralized.