sprite_manager.gd

Go to the documentation of this file.

extends RefCounted
 
 
 
var packs := {}
var sprites := {}
var sprite_sets := {}
var warm_profiles := {}
var requested_sprites := {}
var texture_cache := {}
var scaled_texture_cache := {}
var animation_frame_cache := {}
var path_texture_cache := {}
var sheet_cell_cache := {}
var source_image_cache := {}
var greyscale_material_cache:ShaderMaterial = null
 
const SpriteAnimationRect = preload("res://scripts/systems/spriteManager/sprite_animation_rect.gd")
 
 
 
func load_pack(file_path:String) -> void:
    var file = FileAccess.open(file_path, FileAccess.READ)
    if file == null:
        return
    var data = JSON.parse_string(file.get_as_text())
    if not data is Dictionary:
        return
    load_pack_data(data, file_path.get_file().get_basename())
 
 
 
func load_pack_data(data:Dictionary, fallback_pack_id:String = "sprite_pack") -> void:
    var pack_id = str(data.get("id", fallback_pack_id))
    packs[pack_id] = data.duplicate(true)
    if data.has("sprite_sets"):
        _clear_sheet_dependent_cache()
    for set_id in data.get("sprite_sets", {}).keys():
        var set_definition = data["sprite_sets"][set_id].duplicate(true)
        set_definition["id"] = str(set_id)
        set_definition["pack_id"] = pack_id
        sprite_sets[str(set_id)] = set_definition
    for profile_id in data.get("warm_profiles", {}).keys():
        var warm_profile = data["warm_profiles"][profile_id].duplicate(true)
        warm_profile["id"] = str(profile_id)
        warm_profile["pack_id"] = pack_id
        warm_profiles[str(profile_id)] = warm_profile
    for required in data.get("required_sprites", []):
        if required is Dictionary:
            ensure_required_sprites(required)
    for sprite_id in data.get("sprites", {}).keys():
        var sprite = data["sprites"][sprite_id].duplicate(true)
        sprite["id"] = str(sprite_id)
        sprite["pack_id"] = pack_id
        _invalidate_sprite_cache(str(sprite_id))
        sprites[str(sprite_id)] = sprite
 
 
 
func manifest_with_required_sprites(data:Dictionary) -> Dictionary:
    var next_data = data.duplicate(true)
    var next_sprites = next_data.get("sprites", {})
    if not next_sprites is Dictionary:
        next_sprites = {}
    for required in next_data.get("required_sprites", []):
        if not required is Dictionary:
            continue
        for entry in required_sprite_entries(required):
            var id = str(entry.get("id", ""))
            if id != "" and not next_sprites.has(id):
                next_sprites[id] = entry
    next_data["sprites"] = next_sprites
    return next_data
 
 
 
func load_packs(file_paths:Array) -> void:
    for file_path in file_paths:
        load_pack(str(file_path))
 
 
 
func get_sprite(sprite_id:String) -> Dictionary:
    return sprites.get(sprite_id, {}).duplicate(true)
 
 
 
func get_sprite_set(set_id:String) -> Dictionary:
    return sprite_sets.get(set_id, {}).duplicate(true)
 
 
 
func get_sprite_path(sprite_id:String, default_path:String = "") -> String:
    var sprite = sprites.get(sprite_id, {})
    if not sprite is Dictionary:
        return default_path
    return str(sprite.get("path", default_path))
 
 
 
func get_texture(sprite_id:String):
    if texture_cache.has(sprite_id):
        return texture_cache[sprite_id]
    var sprite = sprites.get(sprite_id, {})
    if not sprite is Dictionary or sprite.is_empty():
        return null
    var texture = null
    if sprite.has("animation"):
        var frames = get_animation_frames(sprite_id)
        texture = frames[0] if not frames.is_empty() else null
    elif sprite.has("sheet") or sprite.has("cell"):
        texture = _texture_from_sheet(sprite)
    else:
        var path = str(sprite.get("path", ""))
        if path == "":
            return null
        texture = get_texture_for_path(path)
    if texture != null:
        texture_cache[sprite_id] = texture
    return texture
 
 
 
func get_scaled_texture(sprite_id:String, size:int = 32):
    var cache_key = "%s|%d" % [sprite_id, size]
    if scaled_texture_cache.has(cache_key):
        return scaled_texture_cache[cache_key]
    var texture = get_texture(sprite_id)
    if texture == null or not texture is Texture2D:
        return null
    var sprite = sprites.get(sprite_id, {})
    var path = str(sprite.get("path", "")) if sprite is Dictionary else ""
    var image = _image_from_texture_or_path(texture, path)
    if image == null or image.is_empty():
        return null
    image.resize(size, size, Image.INTERPOLATE_NEAREST)
    var scaled = ImageTexture.create_from_image(image)
    scaled_texture_cache[cache_key] = scaled
    return scaled
 
 
 
func get_texture_with_fallback(sprite_ids:Array):
    for sprite_id in sprite_ids:
        var texture = get_texture(str(sprite_id))
        if texture != null:
            return texture
    return null
 
 
 
func rotation_for_vector(direction:Vector2, base_direction:String = "right") -> float:
    if direction.length_squared() <= 0.0001:
        return 0.0
    return direction.angle() - _angle_for_direction(base_direction)
 
 
 
func get_texture_for_definition(definition:Dictionary, options:Dictionary = {}):
    var sprite_key = str(options.get("sprite_key", "sprite_id"))
    var path_key = str(options.get("path_key", "image_path"))
    var fallback_sprite_id = str(options.get("fallback_sprite_id", ""))
    var sprite_id = str(definition.get(sprite_key, fallback_sprite_id))
    if sprite_id != "":
        var texture = get_texture(sprite_id)
        if texture != null:
            return texture
    var path = str(definition.get(path_key, definition.get("icon_path", definition.get("path", ""))))
    if path != "":
        return get_texture_for_path(path)
    return null
 
 
 
func get_scaled_texture_for_definition(definition:Dictionary, size:int = 32, options:Dictionary = {}):
    var sprite_key = str(options.get("sprite_key", "sprite_id"))
    var path_key = str(options.get("path_key", "image_path"))
    var fallback_sprite_id = str(options.get("fallback_sprite_id", ""))
    var sprite_id = str(definition.get(sprite_key, fallback_sprite_id))
    if sprite_id != "":
        var texture = get_scaled_texture(sprite_id, size)
        if texture != null:
            return texture
    var path = str(definition.get(path_key, definition.get("icon_path", definition.get("path", ""))))
    var cache_key = "definition:%s|%d" % [path, size]
    if scaled_texture_cache.has(cache_key):
        return scaled_texture_cache[cache_key]
    var texture = get_texture_for_definition(definition, {"path_key": path_key})
    if texture == null or not texture is Texture2D:
        return null
    var image = _image_from_texture_or_path(texture, path)
    if image == null or image.is_empty():
        return texture
    image.resize(size, size, Image.INTERPOLATE_NEAREST)
    var scaled = ImageTexture.create_from_image(image)
    scaled_texture_cache[cache_key] = scaled
    return scaled
 
 
 
func get_animation_frames(sprite_id:String) -> Array:
    if animation_frame_cache.has(sprite_id):
        return animation_frame_cache[sprite_id].duplicate()
    var sprite = sprites.get(sprite_id, {})
    if not sprite is Dictionary or sprite.is_empty():
        return []
    if not sprite.has("animation"):
        var texture = get_texture(sprite_id)
        var single = [texture] if texture != null else []
        animation_frame_cache[sprite_id] = single
        return single.duplicate()
    var frames := []
    var animation = sprite.get("animation", {})
    for cell in _animation_cells(animation):
        var frame_definition = sprite.duplicate(true)
        frame_definition.erase("animation")
        frame_definition["cell"] = cell
        var texture = _texture_from_sheet(frame_definition)
        if texture != null:
            frames.append(texture)
    animation_frame_cache[sprite_id] = frames
    return frames.duplicate()
 
 
 
func get_animation_definition(sprite_id:String) -> Dictionary:
    var sprite = sprites.get(sprite_id, {})
    if not sprite is Dictionary:
        return {}
    var animation = sprite.get("animation", {}).duplicate(true)
    if animation.is_empty():
        animation["fps"] = float(sprite.get("fps", 0.0))
    else:
        animation["fps"] = float(animation.get("fps", sprite.get("fps", 8.0)))
    animation["frames"] = _animation_cells(animation)
    return animation
 
 
 
func create_texture_node(sprite_id:String, options:Dictionary = {}) -> TextureRect:
    var request_metadata = options.get("manifest", options)
    record_sprite_request(sprite_id, request_metadata if request_metadata is Dictionary else {})
    var sprite = sprites.get(sprite_id, {})
    if not sprite is Dictionary:
        sprite = {}
    var frames = get_animation_frames(sprite_id)
    if frames.is_empty():
        return null
    if frames.size() > 1:
        var animation = get_animation_definition(sprite_id)
        var node = SpriteAnimationRect.new()
        var animation_options = options.duplicate()
        animation_options["fps"] = float(options.get("fps", animation.get("fps", 8.0)))
        node.configure(frames, animation_options)
        _apply_texture_node_options(node, sprite, options)
        return node
    var node = TextureRect.new()
    node.texture = frames[0]
    node.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED
    node.expand_mode = TextureRect.EXPAND_IGNORE_SIZE
    node.mouse_filter = Control.MOUSE_FILTER_IGNORE
    _apply_texture_node_options(node, sprite, options)
    return node
 
 
 
func ensure_required_sprites(config:Dictionary) -> Array:
    var generated := []
    for sprite in required_sprite_entries(config):
        var id = str(sprite.get("id", ""))
        if sprites.has(id):
            continue
        sprites[id] = sprite
        generated.append(id)
    return generated
 
 
 
func record_sprite_request(sprite_id:String, metadata:Dictionary = {}) -> void:
    sprite_id = sprite_id.strip_edges()
    if sprite_id == "":
        return
    var request = requested_sprites.get(sprite_id, {})
    request["id"] = sprite_id
    request["required"] = bool(metadata.get("required", true))
    request["placeholder"] = bool(metadata.get("placeholder", true))
    for key in ["display_name", "category", "direction", "tags"]:
        if metadata.has(key):
            request[key] = metadata[key]
    if not request.has("display_name"):
        request["display_name"] = sprite_id.capitalize().replace("_", " ")
    if not request.has("tags"):
        request["tags"] = []
    requested_sprites[sprite_id] = request
 
 
 
func get_requested_sprite_entries() -> Array:
    var entries := []
    var ids = requested_sprites.keys()
    ids.sort()
    for id in ids:
        entries.append(requested_sprites[id].duplicate(true))
    return entries
 
 
 
func clear_requested_sprites() -> void:
    requested_sprites.clear()
 
 
 
func manifest_with_requested_sprites(data:Dictionary) -> Dictionary:
    var next_data = data.duplicate(true)
    var next_sprites = next_data.get("sprites", {})
    if not next_sprites is Dictionary:
        next_sprites = {}
    for entry in get_requested_sprite_entries():
        var id = str(entry.get("id", ""))
        if id == "" or next_sprites.has(id):
            continue
        next_sprites[id] = entry
    next_data["sprites"] = next_sprites
    return next_data
 
 
 
func warm_texture_cache(sprite_ids:Array = []) -> Dictionary:
    var ids := sprite_ids.duplicate()
    if ids.is_empty():
        ids = sprites.keys()
    var warmed := {
        "requested": ids.size(),
        "textures": 0,
        "animations": 0,
        "missing": []
    }
    for id_value in ids:
        var sprite_id = str(id_value)
        var frames = get_animation_frames(sprite_id)
        if frames.is_empty():
            warmed["missing"].append(sprite_id)
            continue
        warmed["textures"] = int(warmed["textures"]) + 1
        if frames.size() > 1:
            warmed["animations"] = int(warmed["animations"]) + 1
    return warmed
 
 
func warm_texture_cache_for_profile(profile_id:String, options:Dictionary = {}) -> Dictionary:
    var profile:Dictionary = get_warm_profile(profile_id)
    if profile.is_empty():
        return {
            "id": profile_id,
            "requested": 0,
            "textures": 0,
            "animations": 0,
            "scaled_textures": 0,
            "skipped_optional": 0,
            "missing": [profile_id]
        }
    var sprites_to_warm:Array = _profile_sprite_ids(profile, options)
    var warmed:Dictionary = warm_texture_cache(sprites_to_warm)
    warmed["skipped_optional"] = int(profile.get("_skipped_optional", 0))
    var scaled_count:int = 0
    var skipped_scaled_optional:int = 0
    for scaled_entry in _profile_scaled_entries(profile, options):
        if _should_skip_optional_profile_entry(scaled_entry, options):
            skipped_scaled_optional += 1
            continue
        var sprite_id:String = str(scaled_entry.get("id", scaled_entry.get("sprite_id", "")))
        var size:int = max(1, int(scaled_entry.get("size", options.get("size", 32))))
        if sprite_id.is_empty():
            continue
        if get_scaled_texture(sprite_id, size) != null:
            scaled_count += 1
        elif not warmed.get("missing", []).has(sprite_id):
            warmed["missing"].append(sprite_id)
    warmed["id"] = profile_id
    warmed["scaled_textures"] = scaled_count
    warmed["skipped_optional"] = int(warmed.get("skipped_optional", 0)) + skipped_scaled_optional
    return warmed
 
 
func get_warm_profile(profile_id:String) -> Dictionary:
    return warm_profiles.get(profile_id, {}).duplicate(true)
 
 
func get_warm_profile_ids() -> Array:
    var ids:Array = warm_profiles.keys()
    ids.sort()
    return ids
 
 
 
func clear_texture_cache() -> void:
    texture_cache.clear()
    scaled_texture_cache.clear()
    animation_frame_cache.clear()
    path_texture_cache.clear()
    sheet_cell_cache.clear()
    source_image_cache.clear()
 
 
 
func clear_transient_cache(options:Dictionary = {}) -> Dictionary:
    var preserve_source_images:bool = bool(options.get("preserve_source_images", true))
    var preserve_path_textures:bool = bool(options.get("preserve_path_textures", false))
    var before:Dictionary = get_cache_stats()
    texture_cache.clear()
    scaled_texture_cache.clear()
    animation_frame_cache.clear()
    sheet_cell_cache.clear()
    if not preserve_path_textures:
        path_texture_cache.clear()
    if not preserve_source_images:
        source_image_cache.clear()
    var after:Dictionary = get_cache_stats()
    return _cache_clear_result(before, after)
 
 
 
func trim_texture_cache(keep_sprite_ids:Array = [], options:Dictionary = {}) -> Dictionary:
    var preserve_source_images:bool = bool(options.get("preserve_source_images", true))
    var preserve_path_textures:bool = bool(options.get("preserve_path_textures", false))
    var clear_sheet_cells:bool = bool(options.get("clear_sheet_cells", true))
    var keep_ids:Dictionary = {}
    for id_value in keep_sprite_ids:
        var sprite_id:String = str(id_value)
        if sprite_id != "":
            keep_ids[sprite_id] = true
    var before:Dictionary = get_cache_stats()
    for sprite_id in texture_cache.keys().duplicate():
        if not keep_ids.has(str(sprite_id)):
            texture_cache.erase(sprite_id)
    for sprite_id in animation_frame_cache.keys().duplicate():
        if not keep_ids.has(str(sprite_id)):
            animation_frame_cache.erase(sprite_id)
    for cache_key in scaled_texture_cache.keys().duplicate():
        var owner_id:String = str(cache_key).split("|")[0]
        if owner_id.begins_with("definition:") or not keep_ids.has(owner_id):
            scaled_texture_cache.erase(cache_key)
    if clear_sheet_cells:
        sheet_cell_cache.clear()
    if not preserve_path_textures:
        path_texture_cache.clear()
    if not preserve_source_images:
        source_image_cache.clear()
    var after:Dictionary = get_cache_stats()
    return _cache_clear_result(before, after)
 
 
 
func _invalidate_sprite_cache(sprite_id:String) -> void:
    texture_cache.erase(sprite_id)
    animation_frame_cache.erase(sprite_id)
    var existing_sprite = sprites.get(sprite_id, {})
    if existing_sprite is Dictionary:
        var existing_path = str(existing_sprite.get("path", ""))
        if existing_path != "":
            source_image_cache.erase(existing_path)
    for key in scaled_texture_cache.keys():
        if str(key).begins_with("%s|" % sprite_id):
            scaled_texture_cache.erase(key)
 
 
 
func _clear_sheet_dependent_cache() -> void:
    sheet_cell_cache.clear()
    animation_frame_cache.clear()
    for id in sprites.keys():
        var sprite = sprites[id]
        if sprite is Dictionary and (sprite.has("sheet") or sprite.has("cell") or sprite.has("animation") or sprite.has("set")):
            texture_cache.erase(str(id))
 
 
 
func get_cache_stats() -> Dictionary:
    return {
        "textures": texture_cache.size(),
        "scaled_textures": scaled_texture_cache.size(),
        "animations": animation_frame_cache.size(),
        "path_textures": path_texture_cache.size(),
        "sheet_cells": sheet_cell_cache.size(),
        "source_images": source_image_cache.size()
    }
 
 
func _cache_clear_result(before:Dictionary, after:Dictionary) -> Dictionary:
    var cleared := {}
    for key in before.keys():
        cleared[key] = max(0, int(before.get(key, 0)) - int(after.get(key, 0)))
    return {
        "before": before,
        "after": after,
        "cleared": cleared
    }
 
 
 
func required_sprite_entries(config:Dictionary) -> Array:
    var prefix = str(config.get("prefix", config.get("thing_id", "")))
    var states = config.get("states", [])
    var entries := []
    if prefix == "" or not states is Array:
        return entries
    var directions = config.get("directions", [])
    var directional_states = config.get("directional_states", states)
    var tags = config.get("tags", [])
    var category = str(config.get("category", ""))
    for state in states:
        var state_id = str(state)
        var state_directions = directions if _state_is_directional(state_id, directional_states) else []
        if state_directions is Array and not state_directions.is_empty():
            for direction in state_directions:
                entries.append(_required_sprite_entry(config, prefix, state_id, str(direction), tags, category))
        else:
            entries.append(_required_sprite_entry(config, prefix, state_id, "", tags, category))
    return entries
 
 
 
func get_missing_assignments(required_ids:Array = []) -> Array:
    var ids := required_ids.duplicate()
    if ids.is_empty():
        for id in sprites.keys():
            if bool(sprites[id].get("required", false)):
                ids.append(str(id))
    ids.sort()
    var missing := []
    for id in ids:
        var sprite = get_sprite(str(id))
        if sprite.is_empty():
            missing.append({"id": str(id), "reason": "missing_definition"})
        elif bool(sprite.get("placeholder", false)):
            missing.append({"id": str(id), "reason": "placeholder"})
        elif not _has_texture_source(sprite):
            missing.append({"id": str(id), "reason": "missing_source"})
    return missing
 
 
 
func find_by_tags(tags:Array) -> Array:
    var matches := []
    for sprite in sprites.values():
        var sprite_tags = sprite.get("tags", [])
        var has_all := true
        for tag in tags:
            if not sprite_tags.has(str(tag)):
                has_all = false
                break
        if has_all:
            matches.append(sprite.duplicate(true))
    return matches
 
 
 
func get_all_sprites() -> Array:
    var list := []
    for sprite in sprites.values():
        list.append(sprite.duplicate(true))
    return list
 
 
 
func get_all_sprite_sets() -> Array:
    var list := []
    for set_definition in sprite_sets.values():
        list.append(set_definition.duplicate(true))
    return list
 
 
 
func reset() -> void:
    packs.clear()
    sprites.clear()
    sprite_sets.clear()
    warm_profiles.clear()
    requested_sprites.clear()
    clear_texture_cache()
 
 
func _has_texture_source(sprite:Dictionary) -> bool:
    return str(sprite.get("path", "")) != "" or sprite.has("sheet") or sprite.has("cell") or sprite.has("animation")
 
 
func _profile_sprite_ids(profile:Dictionary, options:Dictionary = {}) -> Array:
    var ids:Array = []
    var skipped_optional:int = 0
    for key in ["sprites", "sprite_ids", "animations"]:
        var values = profile.get(key, [])
        if values is Array:
            for value in values:
                if value is Dictionary:
                    if _should_skip_optional_profile_entry(value, options):
                        skipped_optional += 1
                        continue
                    var sprite_id:String = str(value.get("id", value.get("sprite_id", "")))
                    if sprite_id != "" and not ids.has(sprite_id):
                        ids.append(sprite_id)
                else:
                    var sprite_id:String = str(value)
                    if sprite_id != "" and not ids.has(sprite_id):
                        ids.append(sprite_id)
    if skipped_optional > 0:
        profile["_skipped_optional"] = skipped_optional
    return ids
 
 
func _should_skip_optional_profile_entry(entry:Dictionary, options:Dictionary) -> bool:
    return bool(options.get("skip_optional", false)) and bool(entry.get("optional", false))
 
 
func _profile_scaled_entries(profile:Dictionary, options:Dictionary = {}) -> Array:
    var entries:Array = []
    var scaled_values = profile.get("scaled", profile.get("scaled_textures", []))
    if scaled_values is Array:
        for value in scaled_values:
            if value is Dictionary:
                entries.append(value.duplicate(true))
            else:
                entries.append({"id": str(value), "size": int(options.get("size", 32))})
    var scaled_sizes = profile.get("scaled_sizes", {})
    if scaled_sizes is Dictionary:
        for sprite_id in scaled_sizes.keys():
            entries.append({"id": str(sprite_id), "size": int(scaled_sizes[sprite_id])})
    return entries
 
 
func _apply_texture_node_options(node:TextureRect, sprite:Dictionary, options:Dictionary) -> void:
    node.flip_h = bool(options.get("mirror_h", sprite.get("mirror_h", sprite.get("flip_h", false))))
    node.flip_v = bool(options.get("mirror_v", sprite.get("mirror_v", sprite.get("flip_v", false))))
    if bool(options.get("greyscale", options.get("grayscale", sprite.get("greyscale", sprite.get("grayscale", false))))):
        node.material = _greyscale_material()
 
 
func _greyscale_material() -> ShaderMaterial:
    if greyscale_material_cache != null:
        return greyscale_material_cache
    var shader = Shader.new()
    shader.code = "shader_type canvas_item;\nvoid fragment() {\n\tvec4 color = texture(TEXTURE, UV) * COLOR;\n\tfloat grey = dot(color.rgb, vec3(0.299, 0.587, 0.114));\n\tCOLOR = vec4(vec3(grey), color.a);\n}\n"
    var material = ShaderMaterial.new()
    material.shader = shader
    greyscale_material_cache = material
    return greyscale_material_cache
 
 
func _state_is_directional(state_id:String, directional_states) -> bool:
    if directional_states is Array:
        return directional_states.has(state_id) or directional_states.has("*")
    return bool(directional_states)
 
 
func _angle_for_direction(direction:String) -> float:
    match direction.to_lower():
        "right":
            return 0.0
        "down":
            return PI * 0.5
        "left":
            return PI
        "up":
            return -PI * 0.5
        _:
            return 0.0
 
 
func _required_sprite_entry(config:Dictionary, prefix:String, state_id:String, direction:String, tags, category:String) -> Dictionary:
    var id = "%s_%s" % [prefix, state_id]
    if direction != "":
        id = "%s_%s" % [id, direction]
    var display = str(config.get("display_name_prefix", prefix.capitalize().replace("_", " ")))
    display += " " + state_id.capitalize().replace("_", " ")
    if direction != "":
        display += " " + direction.capitalize()
    var entry := {
        "id": id,
        "display_name": display,
        "placeholder": true,
        "required": true,
        "tags": tags.duplicate(true) if tags is Array else []
    }
    if category != "":
        entry["category"] = category
    if direction != "":
        entry["direction"] = direction
    return entry
 
 
func _texture_from_sheet(sprite:Dictionary):
    var sheet = _sheet_config(sprite)
    var path = str(sheet.get("path", ""))
    if path == "":
        return null
    var cell = _cell_config(sprite)
    if cell.is_empty():
        return null
    var cell_width = int(sheet.get("cell_width", sheet.get("width", 64)))
    var cell_height = int(sheet.get("cell_height", sheet.get("height", 64)))
    var row = max(0, int(cell.get("row", cell.get("y", 0))))
    var column = max(0, int(cell.get("column", cell.get("x", 0))))
    var cache_key = "%s|%d|%d|%d|%d" % [path, cell_width, cell_height, row, column]
    if sheet_cell_cache.has(cache_key):
        return sheet_cell_cache[cache_key]
    var source_image = _get_source_image(path)
    if source_image == null or source_image.is_empty():
        var source_texture = get_texture_for_path(path)
        if source_texture == null or not source_texture is Texture2D:
            return null
        source_image = _image_from_texture_or_path(source_texture, path)
        if source_image == null or source_image.is_empty():
            return null
    var region = Rect2i(column * cell_width, row * cell_height, cell_width, cell_height)
    if region.position.x + region.size.x > source_image.get_width() or region.position.y + region.size.y > source_image.get_height():
        return null
    var image = Image.create(cell_width, cell_height, false, source_image.get_format())
    image.blit_rect(source_image, region, Vector2i.ZERO)
    var texture = ImageTexture.create_from_image(image)
    sheet_cell_cache[cache_key] = texture
    return texture
 
 
func get_texture_for_path(path:String):
    if path == "":
        return null
    if path_texture_cache.has(path):
        return path_texture_cache[path]
    var texture = null
    if _should_use_resource_loader(path):
        texture = load(path)
    else:
        var image = _get_source_image(path)
        if image != null and not image.is_empty():
            texture = ImageTexture.create_from_image(image)
        elif ResourceLoader.exists(path):
            texture = load(path)
    if texture != null:
        path_texture_cache[path] = texture
    return texture
 
 
func _get_source_image(path:String):
    if path == "":
        return null
    if source_image_cache.has(path):
        return source_image_cache[path]
    var image = _load_image(path)
    if image != null and not image.is_empty():
        source_image_cache[path] = image
    return image
 
 
func _image_from_texture_or_path(texture:Texture2D, path:String = ""):
    if path != "" and source_image_cache.has(path):
        return source_image_cache[path].duplicate()
    if texture == null:
        return null
    var image = texture.get_image()
    if image != null and not image.is_empty() and path != "":
        source_image_cache[path] = image
    return image.duplicate() if image != null else null
 
 
func _sheet_config(sprite:Dictionary) -> Dictionary:
    var sheet = sprite.get("sheet", {})
    if sheet is Dictionary and not sheet.is_empty():
        if sheet.has("set"):
            var set_definition = get_sprite_set(str(sheet.get("set", "")))
            for key in sheet.keys():
                if key != "set":
                    set_definition[key] = sheet[key]
            return set_definition
        return sheet.duplicate(true)
    if sprite.has("set"):
        return get_sprite_set(str(sprite.get("set", "")))
    return {}
 
 
func _cell_config(sprite:Dictionary) -> Dictionary:
    var cell = sprite.get("cell", {})
    if cell is Dictionary:
        return cell.duplicate(true)
    if cell is Array and cell.size() >= 2:
        return {"row": int(cell[0]), "column": int(cell[1])}
    var sheet = sprite.get("sheet", {})
    if sheet is Dictionary and (sheet.has("row") or sheet.has("column")):
        return {"row": int(sheet.get("row", 0)), "column": int(sheet.get("column", 0))}
    return {}
 
 
func _animation_cells(animation:Dictionary) -> Array:
    var cells := []
    if animation.has("frames") and animation["frames"] is Array:
        for frame in animation["frames"]:
            if frame is Dictionary:
                cells.append(frame.duplicate(true))
            elif frame is Array and frame.size() >= 2:
                cells.append({"row": int(frame[0]), "column": int(frame[1])})
    if cells.is_empty() and animation.has("range"):
        var range_definition = animation.get("range", {})
        if range_definition is Dictionary:
            var row = int(range_definition.get("row", 0))
            var from_column = int(range_definition.get("from_column", range_definition.get("start_column", 0)))
            var to_column = int(range_definition.get("to_column", range_definition.get("end_column", from_column)))
            var step = 1 if to_column >= from_column else -1
            var column = from_column
            while true:
                cells.append({"row": row, "column": column})
                if column == to_column:
                    break
                column += step
    return cells
 
 
func _load_image(path:String):
    if path == "":
        return null
    if ResourceLoader.exists(path):
        var resource = ResourceLoader.load(path)
        if resource is Texture2D:
            var texture_image = resource.get_image()
            if texture_image != null and not texture_image.is_empty():
                return texture_image
    if not FileAccess.file_exists(path):
        return null
    var image = Image.load_from_file(path)
    if image == null or image.is_empty():
        return null
    return image
 
 
func _should_use_resource_loader(path:String) -> bool:
    if path == "" or not ResourceLoader.exists(path):
        return false
    if not OS.has_feature("editor"):
        return true
    return _has_import_cache(path)
 
 
func _has_import_cache(path:String) -> bool:
    var import_file_path = "%s.import" % path
    if not FileAccess.file_exists(import_file_path):
        return false
    var config = ConfigFile.new()
    if config.load(import_file_path) != OK:
        return false
    var dest_files = config.get_value("deps", "dest_files", PackedStringArray())
    for dest_file in dest_files:
        if FileAccess.file_exists(str(dest_file)):
            return true
    return false