Public API Surface

GridPlacement GDScript 5.1 – Public API Surface

Scope: Legacy GridBuilding 5.0 / 5.1 GDScript public API. Status: Frozen for 5.1; breaking changes require strong justification. Audience: External users integrating the 5.1 GDScript addon into their projects.

1. Overview

This document enumerates the stable public API surface for GridPlacement GDScript 5.1. These are the classes, nodes, signals, and exported properties that external users are expected to interact with.

API Stability Contract

• Public APIs listed here should not change without major version bump
• Internal APIs (not listed here) may change between minor versions
• All breaking changes will be documented in migration guides

2. Core Systems (Public)

2.1 GridTargetingSystem

Type: Node
Status: Public
Purpose: Handles grid cell targeting and cursor positioning

Key Signals

• target_changed(cell: Vector2i) - Emitted when target cell changes
• target_cleared() - Emitted when no valid target exists

Key Methods

• get_target_cell() -> Vector2i - Returns current target cell
• set_target_cell(cell: Vector2i) -> void - Sets target cell manually
• clear_target() -> void - Clears current target

Exported Properties

• enabled: bool - Whether targeting system is active
• snap_to_grid: bool - Whether to snap cursor to grid cells

2.2 GridPositioner2D

Type: Node2D Status: Public Purpose: Visual cursor controller handling input and visibility logic.

Key Signals

• cursor_moved(tile_pos: Vector2i) - Emitted when the visual cursor moves to a new tile
• cursor_visibility_changed(is_visible: bool) - Emitted when the cursor’s semantic visibility changes

Key Methods

• set_input_processing_enabled(enabled: bool) -> void - Enables/disables input handling
• is_input_processing_enabled() -> bool - Returns current input processing state

2.3 PlacementSystem

Type: Node
Status: Public
Purpose: Handles building placement, validation, and execution

Key Signals

• placement_requested(data: Dictionary) - Emitted when placement is requested
• placement_completed(result: Dictionary) - Emitted when placement succeeds
• placement_failed(error: String) - Emitted when placement fails

Key Methods

• can_place(cell: Vector2i, building_id: String) -> bool - Validates placement
• try_place(cell: Vector2i, building_id: String) -> Dictionary - Attempts placement
• remove_building(cell: Vector2i) -> bool - Removes building at cell

Exported Properties

• enabled: bool - Whether placement system is active
• require_valid_target: bool - Whether to validate target before placement

2.3 ManipulationSystem

Type: Node
Status: Public
Purpose: Handles building manipulation (move, rotate, demolish)

Key Signals

• manipulation_started(data: Dictionary) - Emitted when manipulation begins
• manipulation_completed(result: Dictionary) - Emitted when manipulation completes
• manipulation_cancelled() - Emitted when manipulation is cancelled

Key Methods

• start_move(cell: Vector2i) -> bool - Starts move operation
• start_rotate(cell: Vector2i) -> bool - Starts rotate operation
• confirm_manipulation() -> Dictionary - Confirms current manipulation
• cancel_manipulation() -> void - Cancels current manipulation

Exported Properties

• enabled: bool - Whether manipulation system is active
• allow_rotation: bool - Whether rotation is allowed

3. Configuration and Settings (Public)

3.1 GridBuildingConfig

Type: Resource
Status: Public
Purpose: Main configuration resource for grid building system

Key Properties

• grid_size: Vector2i - Size of the grid (cells)
• cell_size: Vector2 - Size of each cell in pixels
• enable_collision_validation: bool - Whether to validate collisions
• enable_bounds_validation: bool - Whether to validate bounds

3.2 CursorSettings

Type: Resource
Status: Public
Purpose: Cursor appearance and behavior settings

Key Properties

• cursor_texture: Texture2D - Texture for placement cursor
• invalid_cursor_texture: Texture2D - Texture for invalid placement
• cursor_scale: float - Scale factor for cursor

4. Data Structures (Public)

4.1 PlacementRequest

Type: Dictionary
Status: Public
Purpose: Request structure for placement operations

Required Keys

• cell: Vector2i - Target cell position
• building_id: String - ID of building to place
• rotation: int - Rotation angle (0, 90, 180, 270)

Optional Keys

• force: bool - Whether to force placement (skip validation)
• user_id: int - User/owner identifier

4.2 PlacementResult

Type: Dictionary
Status: Public
Purpose: Result structure for placement operations

Keys

• status: String - “ok” or “error”
• cell: Vector2i - Placed cell position (if successful)
• building_id: String - ID of placed building
• error: String - Error message (if failed)

4.3 ManipulationData

Type: Dictionary
Status: Public
Purpose: Data structure for manipulation operations

Required Keys

• cell: Vector2i - Target cell position
• operation: String - “move”, “rotate”, or “demolish”
• state: String - “idle”, “active”, “confirming”, “completed”

5. Utilities (Public)

5.1 GridMath

Type: Static Script
Status: Public
Purpose: Grid coordinate and position calculations

Key Methods

• world_to_grid(world_pos: Vector2) -> Vector2i - Converts world position to grid cell
• grid_to_world(cell: Vector2i) -> Vector2 - Converts grid cell to world position
• get_cell_rect(cell: Vector2i, size: Vector2i) -> Rect2i - Returns rect for cell area

6. Global Access (Public)

6.1 Autoloads

These singletons are part of the public API:

• GBGlobals - Global state and configuration access
  • get_config() -> GridBuildingConfig
  • get_grid_system() -> Node
  • is_initialized() -> bool

7. Internal APIs (Not Public)

The following are internal and subject to change:

• Test helpers under test/ directories
• Internal state managers (e.g., gb_internals.gd)
• Legacy injector system components
• Scene-specific controllers not listed above
• Any class prefixed with _ or marked # Internal

8. Migration Path to 6.0

When migrating from 5.1 GDScript to 6.0 C#:

See GDSCRIPT_5_1_TO_6_0_MIGRATION.md for detailed migration guide.

9. Deprecation Policy

• Deprecated APIs will be marked with # @deprecated: Use X instead comments
• Deprecated APIs will remain functional for at least one minor version
• Breaking changes will only occur in major versions (6.0+)

9.1 Breaking change (low impact): removed validation shims on GBCompositionContainer

These methods were removed from GBCompositionContainer because they were low-impact convenience shims with no meaningful runtime adoption in the 5.0/5.1 line (no call sites in the canonical plugin + demo repos).

• Removed

  • get_readiness_issues()
  • validate_editor()
  • validate_structure()
  • validate_readiness()
  • validate_runtime()

• Why removed

  • They duplicated ConfigurationValidator entry points.
  • They encouraged a “container as validator” pattern that isn’t used by the runtime boot path.
  • Keeping unused public-ish shims increases maintenance cost and confuses the intended validation flow.

• What to use instead

  • Runtime validation (authoritative): composition_container.get_runtime_issues()
  • Structure validation: composition_container.get_structure_issues()
  • Editor validation: composition_container.get_editor_issues() or GBConfigurationValidator.validate_editor(composition_container)
  • Injector-driven runtime boolean: GBInjectorSystem.validate_runtime() (aggregates container issues + injector checks)

10. Support and Questions

For questions about the public API:

• Check GDSCRIPT_5_1_REMAINING_WORK.md for known issues
• Review ROADMAP.md for planned changes
• Open a discussion for clarification on unclear API behaviors

Last Updated: 2025-12-11
API Version: 5.1.x
Status: Stable (Maintenance Mode)