Level Context Integration (v5.0)

The GBLevelContext provides the essential bridge between systems and your game’s level structure, managing TileMapLayers, object placement, and spatial context.

⚠️ CRITICAL: Without a properly configured LevelContext node, systems will NOT run. The LevelContext is required for all targeting and placement operations.

For a complete setup overview, see Getting Started Setup.

Overview

GBLevelContext is responsible for:

  • Providing TileMapLayer references to targeting systems
  • Managing the objects parent for placed buildings
  • Supplying spatial context for grid operations

Core Properties

Required Properties

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

class_name GBLevelContext
extends GBGameNode

## The TileMapLayer to use as the tile selection target
@export var target_map: TileMapLayer

## All maps in the game level
@export var maps: Array[TileMapLayer]

## Where objects should be placed in the scene hierarchy  
@export var objects_parent: Node2D

Simple Setup Process

1. Create Level Context Node

Add a GBLevelContext node to your level scene:

  1. Add GBLevelContext Node: In your level scene, add a new Node
  2. Set Script: Assign gb_level_context.gd script in the Inspector
  3. Assign Properties: Use the Inspector to set:
    • target_map: Click and drag your Ground TileMapLayer
    • maps: Add your TileMapLayers to the array
    • objects_parent: Click and drag your Objects container

2. Scene Structure

Your level scene should look like this:

YourLevel (Node2D)
├── Ground (TileMapLayer)
├── Objects (Node2D)
└── GBLevelContext (Node)
    ├── script: gb_level_context.gd
    ├── target_map: NodePath("../Ground")  # Set via Inspector
    ├── maps: [NodePath("../Ground")]      # Set via Inspector  
    └── objects_parent: NodePath("../Objects")  # Set via Inspector

3. Objects Parent Setup

Make sure your Objects container is added to the required group:

1
2

# In your Objects node, add this group
objects_container.add_to_group("placed_parent")

Why This Works

System Integration: The LevelContext automatically provides:

  • Grid coordinate conversion
  • Collision detection on your TileMapLayers
  • Object parenting for placed buildings
  • Level-specific spatial context

Editor-Based Assignment: Using the Inspector provides:

  • Visual validation of node paths
  • Real-time updates
  • Error prevention for invalid paths

Common Issues

Missing Objects Parent Group

1
2

# Make sure your objects parent is in this group
objects_parent.add_to_group("placed_parent")

Multiple TileMapLayers

1
2
3

# For multiple layers, add them all to the maps array
level_context.target_map = ground_layer  # Primary targeting layer
level_context.maps = [ground_layer, water_layer, buildings_layer]

The GBLevelContext serves as the critical integration point between systems and your game’s level architecture. Simply create the node and assign the three properties in the Inspector - no complex scripting required.