Grid Placement

Placing a Placeable Scene

This guide walks you through the steps to successfully place a Placeable scene on the grid using the GridPlacement 5.1 GDScript runtime. Unlike legacy versions, 5.1 focuses on scenes as the primary unit of placement rather than individual tiles.

🚀 User Implementation Steps

1. Configure the Placeable Scene

Before you can place anything, you need a scene configured as a Placeable:

  • Create your Scene: Build your building or prop as a standard Godot scene (e.g., house.tscn).
  • Define Footprint: Set the Footprint data on the Placeable resource. This tells the system how many grid cells the object occupies.
  • Add Visuals: Ensure the visuals are centered correctly so they align with the grid cells during preview.

2. Register with the Building System

The BuildingSystem needs to know about your placeable. Usually, you provide a template or resource to the system when entering build mode.

1
2
3

# Example: Entering build mode via your game UI
func _on_building_selected(house_template: Placeable):
    building_system.enter_build_mode(house_template)

3. Move and Validate

Once in build mode, the system handles the heavy lifting:

  • Move your cursor to see the preview ghost and placement indicators.
  • The system will automatically run Placement Rules (like occupancy checks or boundary limits).
  • Indicators will tint red/green based on the results from the PlacementValidator.

4. Confirm Placement

Trigger the placement action (e.g., left-click):

  • The system runs a final set of “Commit Rules”.
  • If valid, the scene is instantiated at the target location and registered with the grid state.

🏛️ Orchestration Behind the Scenes

While the user steps are simple, GridPlacement 5.1 orchestrates a layered workflow to ensure stability and engine-independence:

  1. Input Translation: High-level Godot input events are translated into clean “Placement Commands” by adapters.
  2. Workflow Orchestration: A PlacementWorkflow manages the state machine (Preview → Validating → Committing).
  3. Service-Layer Validation: The PlacementService queries the authoritative grid state to see if the move is legal, without ever touching the visual nodes themselves.
  4. Effect Interpretation: Instead of direct node manipulation, the workflow emits GBOrchestratorOutput. A GPEffectApplier interprets these outputs to transform, show, or hide the Godot nodes.

This separation ensures that your business logic (the “Rules”) remains clean and testable, while Godot handles the rendering.

🔗 Deep Dive

For a full breakdown of the service-oriented design and how the runtime chain flows from Input to State, see the: