level_manager.gd

Go to the documentation of this file.

extends RefCounted
 
 
 
const DataCacheManager = preload("res://scripts/systems/dataCacheManager/data_cache_manager.gd")
 
var level := {}
var layers := []
var tile_size := Vector2i(32, 32)
var legend := {}
var objects := []
var triggers := []
var metadata := {}
var tile_dimensions_cache := Vector2i(-1, -1)
var rects_by_type_cache := {}
var tile_records_cache := {}
var cache_hits := 0
var cache_misses := 0
var data_cache_manager = DataCacheManager.new()
 
 
 
func load_level(file_path:String) -> void:
    reset()
    var data = data_cache_manager.load_json(file_path)
    if not data is Dictionary:
        return
    level = data.duplicate(true)
    tile_size = _parse_tile_size(level.get("tile_size", [32, 32]))
    legend = level.get("legend", {}).duplicate(true)
    metadata = level.get("metadata", level.get("background", {})).duplicate(true) if level.get("metadata", level.get("background", {})) is Dictionary else {}
    layers = _normalize_layers(level)
    objects = _normalize_objects(level.get("objects", []), level.get("spawns", []))
    triggers = level.get("triggers", []).duplicate(true) if level.get("triggers", []) is Array else []
 
 
 
func get_tile_dimensions() -> Vector2i:
    if tile_dimensions_cache.x >= 0 and tile_dimensions_cache.y >= 0:
        cache_hits += 1
        return tile_dimensions_cache
    cache_misses += 1
    var width := 0
    var height := 0
    for layer in layers:
        if not layer is Dictionary:
            continue
        for row in layer.get("tiles", []):
            width = max(width, str(row).length())
        height = max(height, layer.get("tiles", []).size())
    tile_dimensions_cache = Vector2i(width, height)
    return tile_dimensions_cache
 
 
 
func get_pixel_dimensions() -> Vector2:
    var tile_dimensions = get_tile_dimensions()
    return Vector2(tile_dimensions.x * tile_size.x, tile_dimensions.y * tile_size.y)
 
 
 
func get_tile(x:int, y:int, layer_id:String = "") -> String:
    var layer = _get_layer(layer_id)
    if layer.is_empty():
        return ""
    var layer_tiles = layer.get("tiles", [])
    if y < 0 or y >= layer_tiles.size():
        return ""
    var row = str(layer_tiles[y])
    if x < 0 or x >= row.length():
        return ""
    return row[x]
 
 
 
func get_tile_metadata(tile:String) -> Dictionary:
    return legend.get(tile, {}).duplicate(true)
 
 
 
func get_rects_by_type(type:String) -> Array:
    if rects_by_type_cache.has(type):
        cache_hits += 1
        return rects_by_type_cache.get(type, []).duplicate(true)
    cache_misses += 1
    var rects = []
    for layer in layers:
        if not bool(layer.get("collision", true)):
            continue
        var layer_tiles = layer.get("tiles", [])
        for y in range(layer_tiles.size()):
            var row = str(layer_tiles[y])
            for x in range(row.length()):
                var tile = row[x]
                var tile_metadata = get_tile_metadata(tile)
                if str(tile_metadata.get("type", "")) == type:
                    rects.append(Rect2(Vector2(x * tile_size.x, y * tile_size.y), Vector2(tile_size)))
    rects_by_type_cache[type] = rects
    return rects.duplicate(true)
 
 
 
func get_tile_records(options:Dictionary = {}) -> Array:
    var include_empty = bool(options.get("include_empty", false))
    var records = _tile_records_for_include_empty(include_empty)
    var world_rect = options.get("world_rect", Rect2())
    if not world_rect is Rect2 or world_rect.size.x <= 0.0 or world_rect.size.y <= 0.0:
        return records.duplicate(true)
    var margin = float(options.get("margin", 0.0))
    var visible_rect:Rect2 = world_rect.grow(margin) if margin != 0.0 else world_rect
    var visible_records := []
    for record in records:
        if _record_intersects_world_rect(record, visible_rect):
            visible_records.append(record)
    return visible_records.duplicate(true)
 
 
 
func build_tile_draw_records(tile_rows:Array, tile_definitions:Dictionary = {}, options:Dictionary = {}) -> Array:
    var include_empty:bool = bool(options.get("include_empty", true))
    var empty_symbols:Array = options.get("empty_symbols", [" "]) if options.get("empty_symbols", []) is Array else [" "]
    var records:Array = []
    for y in range(tile_rows.size()):
        var row_text:String = str(tile_rows[y])
        for x in range(row_text.length()):
            var symbol:String = row_text.substr(x, 1)
            if not include_empty and empty_symbols.has(symbol):
                continue
            var tile:Dictionary = tile_definitions.get(symbol, {}) if tile_definitions.get(symbol, {}) is Dictionary else {}
            var metadata:Dictionary = tile.get("metadata", {}) if tile.get("metadata", {}) is Dictionary else {}
            records.append({
                "cell": Vector2i(x, y),
                "symbol": symbol,
                "tile": tile.duplicate(true),
                "metadata": metadata.duplicate(true)
            })
    return records
 
 
 
func compile_grid_runtime(tile_rows:Array, tile_definitions:Dictionary = {}, objects:Array = [], options:Dictionary = {}) -> Dictionary:
    var runtime_tile_size:Vector2 = _vector2(options.get("tile_size", Vector2(float(tile_size.x), float(tile_size.y))), Vector2(float(tile_size.x), float(tile_size.y)))
    var include_empty:bool = bool(options.get("include_empty", true))
    var empty_symbols:Array = options.get("empty_symbols", [" "]) if options.get("empty_symbols", []) is Array else [" "]
    var surface_colors:Dictionary = options.get("surface_colors", {}) if options.get("surface_colors", {}) is Dictionary else {}
    var raw_records:Array = build_tile_draw_records(tile_rows, tile_definitions, {
        "include_empty": include_empty,
        "empty_symbols": empty_symbols
    })
    var records:Array = []
    var colliders:Array = []
    var hazards:Array = []
    var by_cell:Dictionary = {}
    var width:int = 0
    for y in range(tile_rows.size()):
        width = max(width, str(tile_rows[y]).length())
    for raw_record in raw_records:
        if not raw_record is Dictionary:
            continue
        var record:Dictionary = _compile_tile_runtime_record(raw_record, runtime_tile_size, surface_colors)
        var symbol:String = str(record.get("symbol", ""))
        if not include_empty and empty_symbols.has(symbol):
            continue
        records.append(record)
        by_cell[_cell_key(record.get("cell", Vector2i.ZERO))] = record
        if str(record.get("type", "")) == "solid":
            colliders.append(record)
        elif str(record.get("type", "")) == "hazard":
            hazards.append(record)
    var fill_runs:Array = build_tile_fill_runs(records, ["color"], {
        "include_empty": include_empty,
        "empty_symbols": empty_symbols
    })
    return {
        "schema_version": 1,
        "tile_size": runtime_tile_size,
        "dimensions": Vector2i(width, tile_rows.size()),
        "tile_records": records,
        "tile_fill_runs": fill_runs,
        "solid_records": colliders,
        "hazard_records": hazards,
        "records_by_cell": by_cell,
        "object_draw_records": build_object_draw_records(objects, options)
    }
 
 
 
func compile_loaded_runtime(layer_id:String = "", options:Dictionary = {}) -> Dictionary:
    var layer:Dictionary = _get_layer(layer_id)
    if layer.is_empty():
        return {}
    var tile_rows:Array = layer.get("tiles", []) if layer.get("tiles", []) is Array else []
    var tile_definitions:Dictionary = {}
    for symbol in legend.keys():
        var metadata_value = legend.get(symbol, {})
        var metadata:Dictionary = metadata_value if metadata_value is Dictionary else {}
        tile_definitions[str(symbol)] = {
            "metadata": metadata.duplicate(true),
            "sprite": str(metadata.get("sprite", metadata.get("sprite_id", "")))
        }
    var runtime_options:Dictionary = options.duplicate(true)
    if not runtime_options.has("tile_size"):
        runtime_options["tile_size"] = Vector2(float(tile_size.x), float(tile_size.y))
    return compile_grid_runtime(tile_rows, tile_definitions, objects, runtime_options)
 
 
 
func runtime_tile_at_cell(runtime:Dictionary, cell:Vector2i, fallback:Dictionary = {}) -> Dictionary:
    var by_cell:Dictionary = runtime.get("records_by_cell", {}) if runtime.get("records_by_cell", {}) is Dictionary else {}
    var record = by_cell.get(_cell_key(cell), fallback)
    return record.duplicate(true) if record is Dictionary else fallback.duplicate(true)
 
 
 
func runtime_tile_ref_at_cell(runtime:Dictionary, cell:Vector2i) -> Dictionary:
    var by_cell:Dictionary = runtime.get("records_by_cell", {}) if runtime.get("records_by_cell", {}) is Dictionary else {}
    var record = by_cell.get(_cell_key(cell), {})
    return record if record is Dictionary else {}
 
 
 
func build_tile_fill_runs(records:Array, merge_fields:Array = ["color"], options:Dictionary = {}) -> Array:
    var include_empty:bool = bool(options.get("include_empty", true))
    var empty_symbols:Array = options.get("empty_symbols", [" "]) if options.get("empty_symbols", []) is Array else [" "]
    var runs:Array = []
    var current:Dictionary = {}
    var current_key:String = ""
    var current_row:int = -999999
    var current_end_x:int = -999999
    for item in records:
        if not item is Dictionary:
            continue
        var record:Dictionary = item
        var symbol:String = str(record.get("symbol", ""))
        if not include_empty and empty_symbols.has(symbol):
            continue
        var cell:Vector2i = record.get("cell", Vector2i.ZERO)
        var key:String = _draw_record_merge_key(record, merge_fields)
        var can_extend:bool = not current.is_empty() and cell.y == current_row and cell.x == current_end_x and key == current_key
        if can_extend:
            var span:Vector2i = current.get("span", Vector2i.ONE)
            span.x += 1
            current["span"] = span
            current_end_x = cell.x + 1
            continue
        if not current.is_empty():
            runs.append(current.duplicate(true))
        current = record.duplicate(true)
        current["span"] = Vector2i(1, 1)
        current_key = key
        current_row = cell.y
        current_end_x = cell.x + 1
    if not current.is_empty():
        runs.append(current.duplicate(true))
    return runs
 
 
 
func get_visible_draw_records(records:Array, world_rect:Rect2, tile_pixel_size:Vector2 = Vector2.ZERO, options:Dictionary = {}) -> Array:
    if world_rect.size.x <= 0.0 or world_rect.size.y <= 0.0:
        return records.duplicate(true)
    var pixel_size:Vector2 = tile_pixel_size if tile_pixel_size != Vector2.ZERO else Vector2(float(tile_size.x), float(tile_size.y))
    var origin:Vector2 = _vector2(options.get("origin", Vector2.ZERO), Vector2.ZERO)
    var margin:float = float(options.get("margin", 0.0))
    var visible_records:Array = []
    for record in records:
        if not record is Dictionary:
            continue
        var rect:Rect2 = draw_record_world_rect(record, pixel_size, origin)
        if rect_intersects_world_rect(rect, world_rect, margin):
            visible_records.append(record)
    return visible_records
 
 
 
func draw_record_world_rect(record:Dictionary, tile_pixel_size:Vector2 = Vector2.ZERO, origin:Vector2 = Vector2.ZERO) -> Rect2:
    if record.get("rect", null) is Rect2:
        return record.get("rect", Rect2())
    var pixel_size:Vector2 = tile_pixel_size if tile_pixel_size != Vector2.ZERO else Vector2(float(tile_size.x), float(tile_size.y))
    var cell:Vector2i = record.get("cell", Vector2i.ZERO)
    var span:Vector2i = record.get("span", Vector2i.ONE)
    var size:Vector2 = Vector2(pixel_size.x * float(max(1, span.x)), pixel_size.y * float(max(1, span.y)))
    return Rect2(origin + Vector2(float(cell.x) * pixel_size.x, float(cell.y) * pixel_size.y), size)
 
 
 
func get_objects_in_rect(kind:String = "", world_rect:Rect2 = Rect2(), options:Dictionary = {}) -> Array:
    var source_objects:Array = get_objects(kind)
    if world_rect.size.x <= 0.0 or world_rect.size.y <= 0.0:
        return source_objects
    var margin:float = float(options.get("margin", 0.0))
    var default_size := Vector2(float(tile_size.x), float(tile_size.y))
    var object_size:Vector2 = _vector2(options.get("object_size", default_size))
    var offset:Vector2 = _vector2(options.get("offset", Vector2.ZERO))
    var visible_objects:Array = []
    for object in source_objects:
        var rect:Rect2 = object_world_rect(object, object_size, offset)
        if rect_intersects_world_rect(rect, world_rect, margin):
            visible_objects.append(object)
    return visible_objects
 
 
 
func object_world_rect(object:Dictionary, fallback_size:Vector2 = Vector2.ZERO, offset:Vector2 = Vector2.ZERO) -> Rect2:
    var default_size := Vector2(float(tile_size.x), float(tile_size.y))
    var size_value:Vector2 = _vector2(object.get("size", fallback_size if fallback_size != Vector2.ZERO else default_size))
    var position:Vector2 = _object_world_position(object) + offset
    return Rect2(position, size_value)
 
 
 
func object_world_position(object:Dictionary, options:Dictionary = {}) -> Vector2:
    var size_value:Vector2 = _vector2(options.get("tile_size", Vector2(float(tile_size.x), float(tile_size.y))), Vector2(float(tile_size.x), float(tile_size.y)))
    var normalized:Dictionary = object.duplicate(true)
    if options.has("position_units") and not normalized.has("position_units"):
        normalized["position_units"] = str(options.get("position_units", "pixels"))
    return _object_world_position_with_tile_size(normalized, size_value)
 
 
 
func tile_units_to_world_position(value, tile_pixel_size:Vector2 = Vector2.ZERO) -> Vector2:
    var size_value:Vector2 = tile_pixel_size if tile_pixel_size != Vector2.ZERO else Vector2(float(tile_size.x), float(tile_size.y))
    return _vector2(value, Vector2.ZERO) * size_value
 
 
 
func world_position_to_tile_units(position:Vector2, tile_pixel_size:Vector2 = Vector2.ZERO, digits:int = 3) -> Array:
    var size_value:Vector2 = tile_pixel_size if tile_pixel_size != Vector2.ZERO else Vector2(float(tile_size.x), float(tile_size.y))
    return [
        _round_float(position.x / float(max(1.0, size_value.x)), digits),
        _round_float(position.y / float(max(1.0, size_value.y)), digits)
    ]
 
 
 
func object_visual_rect(object:Dictionary, fallback_size:Vector2 = Vector2.ZERO, options:Dictionary = {}) -> Rect2:
    var default_tile_size:Vector2 = _vector2(options.get("tile_size", Vector2(float(tile_size.x), float(tile_size.y))), Vector2(float(tile_size.x), float(tile_size.y)))
    var default_size:Vector2 = fallback_size if fallback_size != Vector2.ZERO else default_tile_size
    var size_value:Vector2 = _vector2(object.get("visual_size", object.get("size", default_size)), default_size)
    if str(object.get("visual_units", options.get("visual_units", "pixels"))) == "tiles":
        size_value *= default_tile_size
    var anchor:Vector2 = _vector2(object.get("visual_anchor", options.get("visual_anchor", Vector2(0.5, 0.5))), Vector2(0.5, 0.5))
    var visual_offset:Vector2 = _vector2(object.get("visual_offset", options.get("visual_offset", Vector2.ZERO)), Vector2.ZERO)
    if str(object.get("visual_offset_units", options.get("visual_offset_units", "pixels"))) == "tiles":
        visual_offset *= default_tile_size
    var placement:Vector2 = _object_visual_placement(object, default_tile_size, options)
    return Rect2(placement - size_value * anchor + visual_offset, size_value)
 
 
 
func build_object_draw_records(objects:Array, options:Dictionary = {}) -> Array:
    var default_tile_size:Vector2 = _vector2(options.get("tile_size", Vector2(float(tile_size.x), float(tile_size.y))), Vector2(float(tile_size.x), float(tile_size.y)))
    var default_size:Vector2 = _vector2(options.get("fallback_size", default_tile_size), default_tile_size)
    var records:Array = []
    for item in objects:
        if not item is Dictionary:
            continue
        var object:Dictionary = item
        var fallback_size:Vector2 = _vector2(object.get("_fallback_visual_size", default_size), default_size)
        var visual_rect:Rect2 = object_visual_rect(object, fallback_size, options)
        var center:Vector2 = _vector2(object.get("_world_center", visual_rect.get_center()), visual_rect.get_center())
        records.append({
            "object": object.duplicate(true),
            "rect": visual_rect,
            "center": center,
            "kind": str(object.get("kind", "")),
            "sprite_id": str(object.get("sprite_id", "")),
            "category": str(object.get("category", "object")),
            "display_name": str(object.get("display_name", object.get("id", object.get("kind", "Object")))),
            "tags": object.get("tags", []) if object.get("tags", []) is Array else []
        })
    return records
 
 
 
func rect_intersects_world_rect(rect:Rect2, world_rect:Rect2, margin:float = 0.0) -> bool:
    var cull_rect:Rect2 = world_rect.grow(margin) if margin != 0.0 else world_rect
    return rect.intersects(cull_rect) or cull_rect.has_point(rect.position)
 
 
func _compile_tile_runtime_record(raw_record:Dictionary, runtime_tile_size:Vector2, surface_colors:Dictionary) -> Dictionary:
    var record:Dictionary = raw_record.duplicate(true)
    var tile:Dictionary = record.get("tile", {}) if record.get("tile", {}) is Dictionary else {}
    var metadata:Dictionary = record.get("metadata", {}) if record.get("metadata", {}) is Dictionary else {}
    var surface:String = str(metadata.get("surface", metadata.get("type", "")))
    var tile_type:String = str(metadata.get("type", "empty" if surface == "void" else "floor"))
    var cell:Vector2i = record.get("cell", Vector2i.ZERO)
    record["type"] = tile_type
    record["surface"] = surface
    record["collision_shape"] = str(metadata.get("collision_shape", ""))
    record["friction"] = float(metadata.get("friction", 1.0))
    record["bounce"] = float(metadata.get("bounce", 0.82))
    record["sprite_id"] = str(tile.get("sprite", metadata.get("sprite_id", "")))
    record["draw_grid"] = bool(metadata.get("draw_grid", true)) and str(record.get("symbol", "")) != " "
    record["draw_sprite"] = str(record.get("symbol", "")) != " "
    record["rect"] = Rect2(Vector2(float(cell.x) * runtime_tile_size.x, float(cell.y) * runtime_tile_size.y), runtime_tile_size)
    if metadata.has("color"):
        record["color"] = _color_from_value(metadata.get("color", "#ffffff"), Color.WHITE)
    elif surface_colors.has(surface):
        record["color"] = _color_from_value(surface_colors.get(surface), Color.WHITE)
    elif surface_colors.has(tile_type):
        record["color"] = _color_from_value(surface_colors.get(tile_type), Color.WHITE)
    return record
 
 
func _cell_key(cell:Vector2i) -> String:
    return "%d,%d" % [cell.x, cell.y]
 
 
func _color_from_value(value, fallback:Color) -> Color:
    if value is Color:
        return value
    var text:String = str(value)
    if text == "":
        return fallback
    return Color(text)
 
 
func _tile_records_for_include_empty(include_empty:bool) -> Array:
    var cache_key = "all" if include_empty else "non_empty"
    if tile_records_cache.has(cache_key):
        cache_hits += 1
        return tile_records_cache.get(cache_key, [])
    cache_misses += 1
    var records := []
    for layer in layers:
        var layer_id = str(layer.get("id", "terrain"))
        var layer_tiles = layer.get("tiles", [])
        for y in range(layer_tiles.size()):
            var row = str(layer_tiles[y])
            for x in range(row.length()):
                var tile = row[x]
                var tile_metadata = get_tile_metadata(tile)
                if not include_empty and str(tile_metadata.get("type", "")) == "empty":
                    continue
                records.append({
                    "layer": layer_id,
                    "tile": tile,
                    "cell": Vector2i(x, y),
                    "position": Vector2(x * tile_size.x, y * tile_size.y),
                    "metadata": tile_metadata
                })
    tile_records_cache[cache_key] = records
    return records
 
 
func _record_intersects_world_rect(record:Dictionary, world_rect:Rect2) -> bool:
    var tile_rect = Rect2(record.get("position", Vector2.ZERO), Vector2(tile_size))
    return rect_intersects_world_rect(tile_rect, world_rect)
 
 
 
func get_objects(kind:String = "") -> Array:
    var results := []
    for object in objects:
        if not object is Dictionary:
            continue
        if kind != "" and str(object.get("kind", "")) != kind:
            continue
        results.append(object.duplicate(true))
    return results
 
 
 
func get_spawns(kind:String = "") -> Array:
    var spawns = []
    for object in get_objects(kind):
        var entry = object.duplicate(true)
        if entry.has("tile"):
            var tile = entry["tile"]
            if tile is Array and tile.size() >= 2:
                entry["position"] = Vector2(float(tile[0]) * tile_size.x, float(tile[1]) * tile_size.y)
        spawns.append(entry)
    return spawns
 
 
func get_exits() -> Array:
    return get_objects("exit")
 
 
func get_triggers(type:String = "") -> Array:
    var results := []
    for trigger in triggers:
        if not trigger is Dictionary:
            continue
        if type != "" and str(trigger.get("type", "")) != type:
            continue
        results.append(trigger.duplicate(true))
    return results
 
 
func get_layers() -> Array:
    return layers.duplicate(true)
 
 
func get_level() -> Dictionary:
    return level.duplicate(true)
 
 
 
func get_cache_stats() -> Dictionary:
    return {
        "tile_dimensions_cached": tile_dimensions_cache.x >= 0 and tile_dimensions_cache.y >= 0,
        "rect_type_cache_entries": rects_by_type_cache.size(),
        "tile_record_cache_entries": tile_records_cache.size(),
        "cache_hits": cache_hits,
        "cache_misses": cache_misses,
        "data_cache_entries": int(data_cache_manager.get_cache_stats().get("entries", 0)),
        "data_cache_hits": int(data_cache_manager.get_cache_stats().get("cache_hits", 0)),
        "data_cache_misses": int(data_cache_manager.get_cache_stats().get("cache_misses", 0))
    }
 
 
 
func clear_caches() -> void:
    tile_dimensions_cache = Vector2i(-1, -1)
    rects_by_type_cache.clear()
    tile_records_cache.clear()
    cache_hits = 0
    cache_misses = 0
 
 
 
func get_background() -> Dictionary:
    if level.has("background") and level["background"] is Dictionary:
        return level["background"].duplicate(true)
    return metadata.duplicate(true)
 
 
 
func get_summary(data:Dictionary = {}) -> Dictionary:
    var target = data if not data.is_empty() else level
    var target_layers = _normalize_layers(target)
    var target_objects = _normalize_objects(target.get("objects", []), target.get("spawns", []))
    var dimensions := Vector2i.ZERO
    for layer in target_layers:
        for row in layer.get("tiles", []):
            dimensions.x = max(dimensions.x, str(row).length())
        dimensions.y = max(dimensions.y, layer.get("tiles", []).size())
    return {
        "id": str(target.get("id", "")),
        "name": str(target.get("name", "")),
        "dimensions": dimensions,
        "layers": target_layers.size(),
        "objects": target_objects.size(),
        "triggers": target.get("triggers", []).size() if target.get("triggers", []) is Array else 0
    }
 
 
 
func validate_level(data:Dictionary = {}) -> Array:
    var target = data if not data.is_empty() else level
    var issues := []
    if target.is_empty():
        return [_issue("empty_level", "level", "No level data loaded.")]
    var target_legend = target.get("legend", {})
    if not target_legend is Dictionary or target_legend.is_empty():
        issues.append(_issue("missing_legend", "legend", "Level must define a tile legend."))
    var normalized_layers = _normalize_layers(target)
    if normalized_layers.is_empty():
        issues.append(_issue("missing_layers", "layers", "Level must define at least one tile layer or legacy tiles array."))
    var seen_layer_ids := {}
    var expected_width := -1
    var expected_height := -1
    for layer_index in range(normalized_layers.size()):
        var layer = normalized_layers[layer_index]
        var layer_path = "layers[%d]" % layer_index
        var layer_id = str(layer.get("id", ""))
        if layer_id == "":
            issues.append(_issue("missing_layer_id", layer_path, "Layer is missing an id."))
        elif seen_layer_ids.has(layer_id):
            issues.append(_issue("duplicate_layer_id", layer_path, "Duplicate layer id '%s'." % layer_id))
        seen_layer_ids[layer_id] = true
        var layer_tiles = layer.get("tiles", [])
        if not layer_tiles is Array or layer_tiles.is_empty():
            issues.append(_issue("empty_layer", "%s.tiles" % layer_path, "Layer must contain tile rows."))
            continue
        if expected_height < 0:
            expected_height = layer_tiles.size()
        elif layer_tiles.size() != expected_height:
            issues.append(_issue("layer_height_mismatch", "%s.tiles" % layer_path, "Layer height does not match the first layer."))
        for y in range(layer_tiles.size()):
            var row = str(layer_tiles[y])
            if expected_width < 0:
                expected_width = row.length()
            elif row.length() != expected_width:
                issues.append(_issue("row_width_mismatch", "%s.tiles[%d]" % [layer_path, y], "Tile row width does not match the first row."))
            for x in range(row.length()):
                var tile = row[x]
                if target_legend is Dictionary and not target_legend.has(tile):
                    issues.append(_issue("unknown_tile", "%s.tiles[%d][%d]" % [layer_path, y, x], "Tile '%s' is not in the legend." % tile))
    var normalized_objects = _normalize_objects(target.get("objects", []), target.get("spawns", []))
    var seen_object_ids := {}
    var player_spawns := 0
    for index in range(normalized_objects.size()):
        var object = normalized_objects[index]
        var object_path = "objects[%d]" % index
        var object_id = str(object.get("id", ""))
        if object_id != "":
            if seen_object_ids.has(object_id):
                issues.append(_issue("duplicate_object_id", object_path, "Duplicate object id '%s'." % object_id))
            seen_object_ids[object_id] = true
        if str(object.get("kind", "")) == "player":
            player_spawns += 1
        var tile = object.get("tile", [])
        if not _is_tile_array(tile):
            issues.append(_issue("invalid_object_tile", "%s.tile" % object_path, "Object tile must be a two-number array."))
        elif expected_width > 0 and expected_height > 0:
            var cell = _cell_from_array(tile)
            if cell.x < 0 or cell.y < 0 or cell.x >= expected_width or cell.y >= expected_height:
                issues.append(_issue("object_out_of_bounds", "%s.tile" % object_path, "Object is outside level bounds."))
    if player_spawns <= 0:
        issues.append(_issue("missing_player_spawn", "objects", "Level needs at least one player spawn."))
    return issues
 
 
func make_template_level(id:String = "new_platformer_level", width:int = 24, height:int = 10) -> Dictionary:
    var empty_row = ".".repeat(max(1, width))
    var ground_row = "#".repeat(max(1, width))
    var tile_rows := []
    for y in range(max(1, height)):
        tile_rows.append(ground_row if y == height - 1 else empty_row)
    return {
        "schema_version": 1,
        "id": id,
        "name": id.replace("_", " ").capitalize(),
        "tile_size": [64, 64],
        "metadata": {
            "game_type": "platformer",
            "theme": "starter",
            "music": "prototype_loop",
            "background": "day"
        },
        "legend": {
            ".": {"type": "empty"},
            "#": {"type": "solid", "sprite": "grass_tile"},
            "^": {"type": "hazard", "sprite": "spike_strip"},
            "o": {"type": "pickup", "sprite": "coin_pickup"},
            "F": {"type": "checkpoint", "sprite": "checkpoint_flag"}
        },
        "layers": [
            {"id": "terrain", "type": "tiles", "collision": true, "visible": true, "tiles": tile_rows}
        ],
        "objects": [
            {"id": "player_start", "kind": "player", "tile": [2, max(0, height - 2)], "facing": "right"},
            {"id": "exit_01", "kind": "exit", "tile": [max(0, width - 2), max(0, height - 2)], "target": ""}
        ],
        "triggers": []
    }
 
 
func reset() -> void:
    level.clear()
    layers.clear()
    legend.clear()
    objects.clear()
    triggers.clear()
    metadata.clear()
    tile_dimensions_cache = Vector2i(-1, -1)
    rects_by_type_cache.clear()
    tile_records_cache.clear()
    cache_hits = 0
    cache_misses = 0
    tile_size = Vector2i(32, 32)
 
 
func _normalize_layers(data:Dictionary) -> Array:
    var normalized := []
    if data.get("layers", []) is Array and not data.get("layers", []).is_empty():
        for raw_layer in data.get("layers", []):
            if not raw_layer is Dictionary:
                continue
            var layer = raw_layer.duplicate(true)
            layer["id"] = str(layer.get("id", "terrain"))
            layer["type"] = str(layer.get("type", "tiles"))
            layer["collision"] = bool(layer.get("collision", true))
            layer["visible"] = bool(layer.get("visible", true))
            var layer_tiles := []
            for row in layer.get("tiles", []):
                layer_tiles.append(str(row))
            layer["tiles"] = layer_tiles
            normalized.append(layer)
        return normalized
    var legacy_tiles := []
    for row in data.get("tiles", []):
        legacy_tiles.append(str(row))
    if not legacy_tiles.is_empty():
        normalized.append({
            "id": "terrain",
            "type": "tiles",
            "collision": true,
            "visible": true,
            "tiles": legacy_tiles
        })
    return normalized
 
 
func _normalize_objects(next_objects, legacy_spawns) -> Array:
    var normalized := []
    if next_objects is Array and not next_objects.is_empty():
        for raw_object in next_objects:
            if not raw_object is Dictionary:
                continue
            var object = raw_object.duplicate(true)
            if not object.has("id") or str(object.get("id", "")) == "":
                object["id"] = "%s_%d" % [str(object.get("kind", "object")), normalized.size()]
            normalized.append(object)
        return normalized
    if legacy_spawns is Array:
        for index in range(legacy_spawns.size()):
            var spawn = legacy_spawns[index]
            if not spawn is Dictionary:
                continue
            var object = spawn.duplicate(true)
            if not object.has("id") or str(object.get("id", "")) == "":
                object["id"] = "%s_%d" % [str(object.get("kind", "spawn")), index]
            normalized.append(object)
    return normalized
 
 
func _get_layer(layer_id:String = "") -> Dictionary:
    if layers.is_empty():
        return {}
    if layer_id == "":
        return layers[0].duplicate(true)
    for layer in layers:
        if str(layer.get("id", "")) == layer_id:
            return layer.duplicate(true)
    return {}
 
 
func _parse_tile_size(value) -> Vector2i:
    if value is Array and value.size() >= 2:
        return Vector2i(int(value[0]), int(value[1]))
    if value is Vector2i:
        return value
    if value is Vector2:
        return Vector2i(int(value.x), int(value.y))
    return Vector2i(32, 32)
 
 
func _object_world_position(object:Dictionary) -> Vector2:
    var position_value:Variant = object.get("position", null)
    if position_value is Vector2:
        return position_value
    if position_value is Vector2i:
        return Vector2(float(position_value.x), float(position_value.y))
    if position_value is Array and position_value.size() >= 2:
        return Vector2(float(position_value[0]), float(position_value[1]))
    var tile_value:Variant = object.get("tile", [])
    if tile_value is Vector2i:
        return Vector2(tile_value.x * tile_size.x, tile_value.y * tile_size.y)
    if tile_value is Vector2:
        return Vector2(tile_value.x * tile_size.x, tile_value.y * tile_size.y)
    if tile_value is Array and tile_value.size() >= 2:
        return Vector2(float(tile_value[0]) * tile_size.x, float(tile_value[1]) * tile_size.y)
    return Vector2.ZERO
 
 
func _object_visual_placement(object:Dictionary, default_tile_size:Vector2, options:Dictionary) -> Vector2:
    var center_value:Variant = object.get("_world_center", null)
    if center_value is Vector2:
        return center_value
    if center_value is Vector2i:
        return Vector2(float(center_value.x), float(center_value.y))
    if center_value is Array and center_value.size() >= 2:
        return Vector2(float(center_value[0]), float(center_value[1]))
    var origin:Vector2 = _object_world_position_with_tile_size(object, default_tile_size)
    var anchor_mode:String = str(object.get("placement_anchor", options.get("placement_anchor", "center")))
    if anchor_mode == "origin":
        return origin
    return origin + default_tile_size * 0.5
 
 
func _object_world_position_with_tile_size(object:Dictionary, size_value:Vector2) -> Vector2:
    var position_value:Variant = object.get("position", null)
    if position_value is Vector2:
        return position_value
    if position_value is Vector2i:
        return Vector2(float(position_value.x), float(position_value.y))
    if position_value is Array and position_value.size() >= 2:
        var position_units:String = str(object.get("position_units", "pixels"))
        var parsed:Vector2 = Vector2(float(position_value[0]), float(position_value[1]))
        return parsed * size_value if position_units == "tiles" else parsed
    var tile_value:Variant = object.get("tile", [])
    if tile_value is Vector2i:
        return Vector2(tile_value.x * size_value.x, tile_value.y * size_value.y)
    if tile_value is Vector2:
        return Vector2(tile_value.x * size_value.x, tile_value.y * size_value.y)
    if tile_value is Array and tile_value.size() >= 2:
        return Vector2(float(tile_value[0]) * size_value.x, float(tile_value[1]) * size_value.y)
    return Vector2.ZERO
 
 
func _vector2(value, fallback:Vector2 = Vector2.ZERO) -> Vector2:
    if value is Vector2:
        return value
    if value is Vector2i:
        return Vector2(float(value.x), float(value.y))
    if value is Array and value.size() >= 2:
        return Vector2(float(value[0]), float(value[1]))
    if value is Dictionary:
        return Vector2(float(value.get("x", fallback.x)), float(value.get("y", fallback.y)))
    return fallback
 
 
func _draw_record_merge_key(record:Dictionary, merge_fields:Array) -> String:
    var parts:Array = []
    for field_value in merge_fields:
        var field:String = str(field_value)
        parts.append("%s=%s" % [field, str(record.get(field, null))])
    return "|".join(parts)
 
 
func _is_tile_array(value) -> bool:
    return value is Array and value.size() >= 2 and (value[0] is int or value[0] is float) and (value[1] is int or value[1] is float)
 
 
func _cell_from_array(value:Array) -> Vector2i:
    return Vector2i(int(value[0]), int(value[1]))
 
 
func _round_float(value:float, digits:int = 3) -> float:
    var factor:float = pow(10.0, digits)
    return round(value * factor) / factor
 
 
func _issue(type:String, path:String, message:String) -> Dictionary:
    return {"type": type, "path": path, "message": message}