Migration Guide v5.1.0

Overview

This page contains a concise, practical migration checklist for upgrading to v5.1.0 from v5.0.x. The main change in v5.1.0 is the introduction of intelligent target resolution in the Grid Targeting system.

Summary:

• The Grid Targeting system now resolves logical targets from collision objects instead of using collision objects directly as targets
• Most code will continue to work unchanged, but code that assumes targets are collision objects may need updates
• Add metadata or Manipulatable components to enable target resolution for custom objects

---

Prerequisites

• Grid Building v5.0.x already installed and working
• Understanding of your current collision object setup

---

Step 1 — Understand the target resolution change

In v5.1.0, when GridTargetingState.set_collider() is called with a collision object, the system now resolves the logical target using this priority:

1. Direct metadata: Check collision object for "root_node" metadata
2. Manipulatable siblings: Search sibling nodes for Manipulatable components
3. Manipulatable children: Search direct children for Manipulatable components
4. Fallback: Use collision object itself (maintains backward compatibility)

What this means:

• If your collision objects have no metadata and no Manipulatable components, behavior is identical to v5.0.x
• If you want collision shapes on child nodes to target parent objects, you need to add resolution metadata

---

Step 2 — Identify objects that need target resolution

Review your placeable objects and determine if any have collision shapes that should target different nodes:

• Simple objects: Collision on the same node as the logical object → No changes needed
• Complex objects: Collision shapes on child nodes, logical target on parent → Add resolution metadata

Example scenarios requiring resolution:

• Building with collision Area2D as child of Building root node
• Vehicle with multiple collision shapes targeting the vehicle root
• Multi-part objects where collision detection happens on components

---

Step 3 — Add target resolution metadata (if needed)

For objects where collision shapes are on child nodes but should target parent nodes:

Option 1: Metadata (recommended for custom objects)

# In your placeable object's _ready() or setup method
func _ready() -> void:
    # If collision shape is on $CollisionArea child
    $CollisionArea.set_meta("root_node", NodePath(".."))  # Target parent

Option 2: Manipulatable component (automatic for manipulatable objects)

# Manipulatable objects automatically participate in resolution
func _ready() -> void:
    var manipulatable: Manipulatable = Manipulatable.new()
    manipulatable.root = self  # This node becomes the target
    $CollisionArea.add_child(manipulatable)

---

Step 4 — Update code that assumes targets are collision objects

If your code expects GridTargetingState.get_target() to return collision objects, update it to handle resolved targets:

Before (v5.0.x):

func _on_target_changed(target: Node2D, _old: Node2D) -> void:
    if target is Area2D:  # Assumed target was collision object
        show_info_for_collision_area(target)

After (v5.1.0):

func _on_target_changed(target: Node2D, _old: Node2D) -> void:
    if target is MyBuilding:  # Target is now resolved logical object
        show_info_for_building(target)

---

Step 5 — Test target resolution

1. Run your game and hover over objects with collision shapes
2. Verify that GridTargetingState.get_target() returns the expected logical targets
3. Check that UI components (TargetInformer, indicators) display information for the correct objects
4. Test manipulation and building operations to ensure they work with resolved targets

---

Step 6 — Validation

Use the built-in validation to check for target resolution issues:

# In your test/debug code
func validate_targeting() -> void:
    var targeting_state = composition_container.get_targeting_state()
    var issues = targeting_state.get_runtime_issues()
    for issue in issues:
        push_warning("Targeting issue: " + issue)

---

FAQ / common pitfalls

• Q: My code stopped working after upgrade!

  • A: Check if your code assumes get_target() returns collision objects. Update to handle resolved targets.

• Q: Do I need to add metadata to all my objects?

  • A: No — only add metadata if you want collision shapes on child nodes to target parent objects. Objects without metadata work exactly as before.

• Q: How do I know if resolution is working?

  • A: Check the console for GBMetadataResolver debug prints, or inspect GridTargetingState.get_target() in the debugger.

• Q: What if I have multiple collision shapes on one object?

  • A: All collision shapes should point to the same logical target using consistent metadata or Manipulatable setup.

---

References

• Breaking changes: ../guides/breaking-changes/
• Grid Targeting guide: ../guides/grid_targeting/
• API: ../api/GridTargetingState/, ../api/GBMetadataResolver/

---