Skip to content
Grid Building Docs

GBDiagnostics

Summary

Section titled “Summary”

Provide small, safe, static helpers for generating diagnostic strings that can be reused by runtime code and tests.

Notes: - Keep these functions side-effect free (no printing) so callers may log or assert as they prefer.

Methods

Section titled “Methods”
static func _is_verbose( ) -> bool

Check if verbose diagnostics mode is enabled via environment variable. Returns: true if GB_VERBOSE_TESTS is set to “1”, “true”, or “TRUE”.

static func format_debug( message: String, suite: String, file_path: String ) -> String

Format a debug message string, optionally including suite and file path if verbose mode is enabled. message: The core message to format. suite: Optional suite name to prefix in brackets. file_path: Optional file path to append in parentheses. Returns: Formatted string, enhanced if verbose mode is on.

static func format_indicator( indicator: Object ) -> String

Format an indicator object into a human-readable string for diagnostics. indicator: The indicator object to format (can be RuleCheckIndicator, Node, or generic Object). Returns: Formatted string like “name@position (extra_info)” or “<null>” if null.

static func format_tile_list( tile_list: Array ) -> String

Format a list of tile coordinates into a compact string. tile_list: Array of tile coordinates (e.g., Vector2i). Returns: String like “[tile1, tile2, …]” or ”[]” if null.

static func format_indicator_list( prefix: String, indicators: Array, _cls_name: String, _file_path: String ) -> String

Format a list of indicators into a multi-line string with a prefix. prefix: String to prepend to the list. indicators: Array of indicator objects. _cls_name: Unused parameter (for future extension). _file_path: Unused parameter (for future extension). Returns: Multi-line string with prefix and indented indicator details.

static func format_stack_summary( stack: Array, max_entries: int ) -> String

Format a compact stack summary string from get_stack() output. stack: Array returned by get_stack() (array of Dictionary/Frame objects) max_entries: maximum number of stack entries to include (default 6) Returns: a short string like: “[file1.gd:123:func1, file2.gd:45:func2, …]”. This is intentionally lightweight and side-effect free so callers can log it.

static func format_node_label( obj: Object ) -> String

Format a Node or Object for logging. obj: The object to format. Returns: Formatted string like “name(class)” or “<null>” etc.

static func format_visibility_context( node: Node, visual: CanvasItem, vp: Viewport, cam: Camera2D ) -> String

Build a visibility context string similar to GridPositioner2D._visibility_context node: The GridPositioner2D (or any CanvasItem/Node) providing context visual: The visual CanvasItem associated with the node (may be null) vp: Active Viewport (optional) cam: Active Camera2D (optional)

static func describe_collision_layers( obj: Object ) -> Array[int]

Describe collision layers of a CollisionObject2D. obj: The object to check (should be CollisionObject2D). Returns: Array of active collision layer indices (1-32).

static func format_shape_cast_collisions( shape_cast: ShapeCast2D ) -> String

Format current collisions of a ShapeCast2D for diagnostics. shape_cast: The ShapeCast2D to inspect. Returns: Formatted string like “colliding count=X -> collider1, collider2, …“.

static func format_canvas_item_state( ci: CanvasItem ) -> String

Format a CanvasItem’s render-related state (modulate, self_modulate, z_index, position, scale, texture info). ci: CanvasItem (Sprite2D, AnimatedSprite2D, etc.) or null. Returns: String with key properties for diagnosing visibility without relying solely on .visible.

static func camera_world_bounds( cam: Camera2D, vp: Viewport ) -> Dictionary

Compute world bounds rectangle for the active camera & viewport. cam: Active Camera2D (may be null) vp: Viewport owning the camera (may be null) Returns: Dictionary with keys: has(bool), center(Vector2), world_min(Vector2), world_max(Vector2), zoom(Vector2)

static func is_inside_camera_bounds( bounds: Dictionary, pos: Vector2 ) -> bool

Determine if a world position is inside provided camera world bounds bounds: Result from camera_world_bounds pos: World position to test Returns: true if inside or bounds invalid (fail open for safety)

static func is_offscreen( bounds: Dictionary, pos: Vector2 ) -> bool

Convenience negative predicate for offscreen detection

static func format_screen_state( cam: Camera2D, vp: Viewport, positioner_pos: Vector2, has_mouse: bool, mouse_world: Vector2, map: Object ) -> String

Format screen & mouse diagnostic state (formerly in GridPositioner2D) cam: Active camera vp: Active viewport positioner_pos: World position of positioner has_mouse: Whether we have cached mouse world position mouse_world: Last cached mouse world (ignored if has_mouse false) map: Tile map / target map providing coordinate -> tile projection (expects get_tile_from_global_position via GBPositioning2DUtils) Returns: Formatted string matching prior screen_state log output

static func _safe_get_tile_from_global_position( global_position: Vector2, map: Object ) -> Vector2i

Safe wrapper for getting tile position from global position. Handles both TileMapLayer and test objects with duck-typed interface. global_position: The world position to convert. map: The map object (TileMapLayer or duck-typed equivalent). Returns: The tile coordinate as Vector2i, or Vector2i.ZERO if conversion fails.

Source

Section titled “Source”

addons/grid_building/utils/gb_diagnostics.gd

This API reference is automatically generated from the plugin source code. For implementation examples and usage guides, see the guides section.