hermeticormus/claude-code-game-development/level-design-patterns

# TileMap setup and painting at runtime
class_name LevelTileMap extends TileMap
 
const LAYER_GROUND: int = 0
const LAYER_DECOR: int = 1
const SOURCE_ID: int = 0  # TileSet source index
 
func paint_tile(pos: Vector2i, atlas_x: int, atlas_y: int, layer: int = LAYER_GROUND) -> void:
    set_cell(layer, pos, SOURCE_ID, Vector2i(atlas_x, atlas_y))
 
func clear_tile(pos: Vector2i, layer: int = LAYER_GROUND) -> void:
    erase_cell(layer, pos)
 
func get_terrain_type(pos: Vector2i) -> StringName:
    var tile_data: TileData = get_cell_tile_data(LAYER_GROUND, pos)
    if tile_data:
        return tile_data.get_custom_data(&"terrain_type") as StringName
    return &""
 
# Terrain autotile: paint using terrain set instead of individual atlas coords
func paint_terrain_region(positions: Array[Vector2i], terrain_set: int, terrain: int) -> void:
    set_cells_terrain_connect(LAYER_GROUND, positions, terrain_set, terrain)

# Configure NavMesh baking for specific agent types
@tool
class_name NavMeshConfigurator extends EditorScript
 
func configure_for_humanoid(nav_region: NavigationRegion3D) -> void:
    var mesh := NavigationMesh.new()
    # Agent dimensions
    mesh.agent_radius = 0.5         # Half character width
    mesh.agent_height = 1.8         # Character height
    mesh.agent_max_climb = 0.35     # Step height (stair riser)
    mesh.agent_max_slope = 45.0     # Max walkable slope degrees
    # Mesh generation precision
    mesh.cell_size = 0.25           # Smaller = more precise, slower bake
    mesh.cell_height = 0.1
    # Filtering
    mesh.filter_low_hanging_obstacles = true
    mesh.filter_ledge_spans = true
    mesh.filter_walkable_low_height_spans = true
    nav_region.navigation_mesh = mesh
 
func bake_async(nav_region: NavigationRegion3D) -> void:
    # Bake on background thread to avoid frame hitches
    nav_region.bake_navigation_mesh(true)  # true = on_thread

class_name LevelStreamer extends Node
signal zone_loaded(zone_name: StringName)
signal zone_unloaded(zone_name: StringName)
 
var _loaded_zones: Dictionary = {}  # zone_name -> Node
var _loading_requests: Dictionary = {}  # zone_name -> path
 
func request_zone_load(zone_name: StringName, scene_path: String) -> void:
    if zone_name in _loaded_zones or zone_name in _loading_requests:
        return
    _loading_requests[zone_name] = scene_path
    ResourceLoader.load_threaded_request(scene_path)
 
func _process(_delta: float) -> void:
    for zone_name in _loading_requests.keys():
        var path: String = _loading_requests[zone_name]
        var status := ResourceLoader.load_threaded_get_status(path)
        match status:
            ResourceLoader.THREAD_LOAD_LOADED:
                var scene: PackedScene = ResourceLoader.load_threaded_get(path)
                _activate_zone(zone_name, scene)
                _loading_requests.erase(zone_name)
            ResourceLoader.THREAD_LOAD_FAILED:
                push_error("Failed to load zone: %s" % path)
                _loading_requests.erase(zone_name)
 
func _activate_zone(zone_name: StringName, scene: PackedScene) -> void:
    var instance := scene.instantiate()
    instance.name = zone_name
    get_tree().root.add_child(instance)
    _loaded_zones[zone_name] = instance
    zone_loaded.emit(zone_name)
 
func unload_zone(zone_name: StringName) -> void:
    if zone_name not in _loaded_zones:
        return
    _loaded_zones[zone_name].queue_free()
    _loaded_zones.erase(zone_name)
    zone_unloaded.emit(zone_name)

# Area3D trigger that loads next zone on player enter
class_name ZoneTrigger extends Area3D
@export var zone_to_load: String
@export var zone_to_unload: String
@export var preload_distance: float = 30.0  # meters before trigger
 
@onready var streamer: LevelStreamer = get_node("/root/LevelStreamer")
 
func _ready() -> void:
    body_entered.connect(_on_body_entered)
    # Visual range pre-trigger: start loading before player arrives
    monitoring = true
 
func _on_body_entered(body: Node3D) -> void:
    if body.is_in_group(&"player"):
        if zone_to_load and not zone_to_load.is_empty():
            streamer.request_zone_load(zone_to_load as StringName, "res://levels/%s.tscn" % zone_to_load)
        if zone_to_unload and not zone_to_unload.is_empty():
            # Delay unload to prevent pop-in during transition
            get_tree().create_timer(2.0).timeout.connect(
                func(): streamer.unload_zone(zone_to_unload as StringName)
            )

# @tool script: replace CSG greybox with final modular pieces
@tool
class_name GreyboxReplacer extends EditorScript
 
# In editor, select CSGBox3D nodes and run this to measure for kit piece placement
func measure_csg_for_kit(csg: CSGBox3D) -> Dictionary:
    return {
        "position": csg.global_position,
        "size": csg.size,
        "rotation": csg.rotation,
        # Output: designer places kit piece matching these dimensions
    }
 
# CSG usage for greybox (do NOT use CSG in final build - poor performance)
# res://levels/greybox/
#   csg_corridor_ns.tscn  - North-South corridor
#   csg_room_small.tscn   - Small room
#   csg_room_large.tscn   - Large room

# Validates kit pieces snap to grid
@tool
class_name KitGridValidator extends EditorScript
const GRID_SIZE: float = 4.0  # 4m grid
 
func validate_grid_alignment(node: Node3D) -> bool:
    var pos := node.global_position
    var snapped := pos.snapped(Vector3.ONE * GRID_SIZE)
    var offset := (pos - snapped).length()
    if offset > 0.01:
        push_warning("%s is %.3f off grid at %s" % [node.name, offset, pos])
        return false
    return true
 
func snap_to_grid(node: Node3D) -> void:
    node.global_position = node.global_position.snapped(Vector3.ONE * GRID_SIZE)