LOGICATLAS // GODOT 4.x INTEGRATION MANUAL

Native Import Plugin & Resource System, (c) Andras Gregori 2025

Version: 1.0.0, Compatibility: Godot 4.0, 4.1, 4.2+

1. OVERVIEW

This Integration Kit bridges LogicAtlas (Desktop) and Godot Engine.

By default, Godot treats .json files as simple text. This plugin intercepts LogicAtlas JSON exports and converts them into Native Resources.

• Automatic Slicing: Creates AtlasTexture sub-resources for every sprite in your sheet.
• Embedded Logic: Bakes Pivot Points and Offsets directly into the texture metadata.
• Dependency Tracking: If you edit the PNG in Photoshop/Aseprite, Godot automatically rebuilds the JSON resource without breaking your scene.

---

2. INSTALLATION

2.1 File Structure

Create the following folder structure in the root of your Godot project (res://).

res://
└── addons/
    └── logic_atlas/
        ├── plugin.cfg
        ├── plugin.gd
        ├── logic_atlas_importer.gd
        └── logic_atlas_entry.gd
  

2.2 The Scripts

Copy the following code into the respective files created above.

File 1: plugin.cfg

[plugin]
name="LogicAtlas System"
description="Native importer for LogicAtlas JSON/PNG pairs."
author="GregOrigin"
version="1.0"
script="plugin.gd"
  

File 2: logic_atlas_entry.gd

This defines the data container.

@tool
extends Resource
class_name LogicAtlasData

# Dictionary mapping "Sprite Name" -> AtlasTexture
@export var textures: Dictionary = {}

func get_sprite(name: String) -> AtlasTexture:
    if textures.has(name): return textures[name]
    return null
  

File 3: logic_atlas_importer.gd

This is the logic that runs when you drop a file involved.

@tool
extends EditorImportPlugin

func _get_importer_name(): return "gregorigin.logicatlas"
func _get_visible_name(): return "LogicAtlas Importer"
func _get_recognized_extensions(): return ["json"]
func _get_save_extension(): return "tres"
func _get_resource_type(): return "Resource"
func _get_priority(): return 1.0
func _get_import_order(): return 0
func _get_import_options(p,i): return []

func _import(source_file, save_path, options, platform_variants, gen_files):
    var file = FileAccess.open(source_file, FileAccess.READ)
    if file == null: return FileAccess.get_open_error()
    
    var json = JSON.new()
    if json.parse(file.get_as_text()) != OK: return ERR_PARSE_ERROR
    var data = json.data
    
    # Verify signature
    if not data.has("atlas") or not data.has("sprites"): return ERR_PARSE_ERROR 

    # Locate source texture (Dependency tracking)
    var png_path = source_file.get_base_dir().path_join(data["atlas"])
    var atlas_texture_src = load(png_path)
    if not atlas_texture_src: return ERR_FILE_NOT_FOUND

    # Setup Container
    var result = load("res://addons/logic_atlas/logic_atlas_entry.gd").new()
    
    # Process Sprites
    for s in data["sprites"]:
        var tile = AtlasTexture.new()
        tile.atlas = atlas_texture_src
        tile.region = Rect2(s["x"], s["y"], s["w"], s["h"])
        
        # Calculate Godot Offset (Center -> Pivot)
        var px_offset = Vector2(
            (s["w"] * s["pivot_x"]) - (s["w"] * 0.5),
            (s["h"] * s["pivot_y"]) - (s["h"] * 0.5)
        )
        
        # Embed Metadata
        tile.set_meta("logic_offset_px", px_offset)
        tile.set_meta("logic_pivot_norm", Vector2(s["pivot_x"], s["pivot_y"]))
        
        result.textures[s["name"]] = tile

    return ResourceSaver.save(result, save_path + "." + _get_save_extension())
  

File 4: plugin.gd

Registers the importer.

@tool
extends EditorPlugin

var import_plugin

func _enter_tree():
    import_plugin = preload("logic_atlas_importer.gd").new()
    add_import_plugin(import_plugin)

func _exit_tree():
    remove_import_plugin(import_plugin)
    import_plugin = null
  

---

3. ACTIVATION

1. Open your Godot Project.
2. Go to Project > Project Settings...
3. Click the Plugins tab.
4. Find "LogicAtlas System" and verify the Enable checkbox is checked.
5. Restart the Editor significantly reduces cache weirdness with new Import plugins.

---

4. WORKFLOW GUIDE

Step A: Exporting

1. Open LogicAtlas (Desktop App).
2. Load sprites, pack them, set your pivots visually.
3. Click "Export". Ensure you save the .json and .png in the same folder inside your Godot project.

Step B: Automatic Import

1. Switch to Godot.
2. Godot will detect the new .json file.
3. The Plugin acts immediately. The JSON file is no longer treated as text—it is now a Resource.

Step C: Using in Scenes

You have two ways to use the data.

Method 1: The Inspector

1. Double-click the .json file in the FileSystem.
2. Look at the Inspector. You will see a Textures dictionary.
3. Drag any internal resource (e.g., Hero_Idle, Tree_01) directly into a Sprite2D Texture slot.

Method 2: The "LogicSprite" Helper (Recommended)

To make use of the auto-pivoting, create a helper script named LogicSprite.gd:

# LogicSprite.gd
# Attach this to your node instead of standard Sprite2D
@tool
class_name LogicSprite extends Sprite2D

func _set_texture(value):
    super.set_texture(value)
    if texture and texture.has_meta("logic_offset_px"):
        offset = texture.get_meta("logic_offset_px")
  

Now, when you drag a texture from the Atlas into this node, the Offset property automatically snaps to the values you defined in the LogicAtlas Desktop app.

---

5. RE-IMPORTING & ITERATION

If you change your mind about where the "feet" of your character are:

1. Open LogicAtlas Desktop.
2. Open your project, move the pivot.
3. Re-export (Overwrite JSON).
4. Tab back to Godot.
5. Godot detects the file change, re-runs the importer, updates the offsets in the Resource.
6. Your game character updates position instantly.

---

6. TROUBLESHOOTING

Q: The JSON is still importing as a TextFile. Make sure the plugin is Enabled. If you added the files while Godot was open, select the JSON file, go to the Import dock (top left), select "LogicAtlas Importer" from the dropdown, and click Reimport.

Q: My sprites look blurry. LogicAtlas creates AtlasTexture resources. Ensure your source .png Import Settings (in Godot) are set to Texture2D > Filter: Nearest (for pixel art). AtlasTexture inherits the filter setting of the parent PNG.

Q: I moved the PNG to a different folder than the JSON. Don't do that. The JSON references the PNG by relative filename. Keep them together.

7. ABOUT

This Godot 4.x integration manual is part of LogicAtlas, a standalone tool by Andras Gregori.

For support and feature requests, please write to: [e-mail].

Check me out at GitHub or Linktree for other standalone tools.