# LOGICATLAS // GODOT 4.x INTEGRATION MANUAL

**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: <andras@gregorigin.com>.

Check me out at [GitHub](https://github.com/gregorik) or [Linktree](https://linktr.ee/agregori) for other standalone tools.