GridService2D

AUTO-GENERATED FILE — DO NOT EDIT MANUALLY

Source: core/services/grid_service_2d.gd

Version: 5.1

class_name: GridService2D extends: RefCounted

Summary

GridService2D

Canonical service for grid metadata and coordinate conversion in 2D.

Responsibilities:

• Maintain the current target TileMapLayer used for conversions.
• Maintain the set of known/available map layers for a scope.
• Provide conversion helpers between world space (Vector2) and grid space (Vector2i).

Invariants / Notes:

• When _target_map is set, conversions delegate to the map’s to_local()/to_global() and local_to_map()/map_to_local() APIs.
• When _target_map is null, conversions fall back to _tile_size.

Conversion contract (fallback mode, when _target_map is null):

• world_to_grid: uses local = world - _origin, then floori(local / _tile_size) per axis.
• grid_to_world: returns the tile center at _origin + (grid * _tile_size) + (_tile_size * 0.5).
• If a tile size axis is 0, that axis maps to 0 in world_to_grid.
• No bounds checking; negative coordinates are valid.

Signals

• target_map_changed
  • Emitted when the active target map changes.
• maps_changed
  • Emitted when the collection of known maps changes.
• tile_size_changed
  • Emitted when the fallback tile size changes.

Exports

(none)

Methods

• set_target_map()
  • Sets the target map layer.

When non-null, conversions will use this map as the authoritative coordinate space. Emits target_map_changed if the value actually changed.

• get_target_map()
  • Gets the active target map layer (may be null).
• set_maps()
  • Sets the list of available maps.

This is typically populated by a level context or bootstrapper. Emits maps_changed.

• get_maps()

  • Gets the list of available maps.

• set_tile_size()

  • Sets the fallback tile size used for conversions when no target map is configured. Emits tile_size_changed if the value actually changed.

• get_tile_size()

  • Gets the fallback tile size used for the grid.

• set_origin()

  • Sets the origin used for fallback conversions.

• get_origin()

  • Gets the origin used for fallback conversions.

• world_to_grid()

  • Converts a world-space position to a grid cell coordinate.

• When _target_map is set, converts via the map.

• Otherwise uses _tile_size as a simple uniform grid.

Behavior contract (fallback mode):

• Computes local = world_position - _origin.
• Computes grid = floor(local / _tile_size) per-axis (not rounding).
• If _tile_size.x == 0, x is returned as 0 (same for y).
• grid_to_world()
  • Converts a grid cell coordinate to a world-space position.

Returns the world position at the tile’s center.

Behavior contract:

• In map mode, uses map_to_local + to_global (TileMapLayer decides what its center means).
• In fallback mode, returns _origin + (grid * _tile_size) + (_tile_size * 0.5).
• snap_to_tile_center()
  • Snaps a world-space position to the center of the nearest tile.

Behavior contract: Equivalent to grid_to_world(world_to_grid(world_position)).

• is_valid_grid_position()
  • Checks if a grid position is valid.

NOTE: Currently permissive (always true). Callers that require bounds validation should enforce it via their target map / rules.