# 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gregorigin.gitbook.io/logicatlas-to-godot-integration/logicatlas-godot-4.x-integration-manual.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.