# LogicAtlas

{% embed url="<https://www.youtube.com/watch?v=cadwgJ_I_74>" %}

***

### 1. INTRODUCTI"ON

**LogicAtlas** is a pipeline utility designed to bridge the gap between 2D asset creation and game engine integration. While traditional texture packers only merge images, LogicAtlas allows developers to pre-calculate **logic data**—specifically **Pivot Points (Anchors)**—during the packing phase.

This tool completely eliminates the need to manually adjust sprite offset values inside game engines (Godot, Unity, Engines of creation), saving hours of setup time for UI elements, character animations, and props.

***

### 2. SYSTEM REQUIREMENTS & INSTALLATION

#### 2.1 Hardware Specifications

LogicAtlas is built as a lightweight, native Windows application.

* **OS:** Windows 10 (1903+) or Windows 11.
* **Processor:** x64 Architecture.
* **RAM:** 200MB available.
* **Dependencies:** None. (Relies on **.NET Framework 4.8**, pre-installed on all modern Windows versions).

#### 2.2 Installation

LogicAtlas is **Portable Software**.

1. Extract the LogicAtlas\_v1.0.0.zip package.
2. Place the folder in your development tools directory.
3. Run LogicAtlas.exe.

> **Security Note:** Verify the digital signature or hash if downloaded from third parties. On first run, Windows SmartScreen may flag the app as "unrecognized" due to its indie nature. Select **More Info > Run Anyway**.

***

### 3. CORE ALGORITHM: SHELF PACKING

LogicAtlas utilizes a **Shelf Bin-Packing Algorithm** optimized for sprite strips and UI assets.

1. **Sorting:** Input sprites are sorted by **Height (Descending)**. This ensures the tallest items establish the "shelf" height, minimizing wasted vertical space.
2. **Placement:** Sprites are placed left-to-right until the row width exceeds the calculated heuristic width (typically TotalArea × 1.2).
3. **New Row:** When a row is full, a new coordinates shelf is created based on the tallest item in the previous row.
4. **Bleed:** A hard-coded **2px padding** is applied between sprites to prevents texture bleeding (sub-pixel sampling artifacts) in game engines.

***

### 4. DATA SPECIFICATION (JSON)

Upon export, LogicAtlas generates two files:

1. \[Filename].png: The composite texture sheet.
2. \[Filename].json: The logic dataset.

#### 4.1 JSON Structure

The data is formatted as a standardized JSON object for easy parsing in any language (C#, GDScript, Python, Lua).

```
{
  "atlas": "Characters_Packed.png",
  "sprites": [
    {
      "name": "Hero_Idle_01",    // Original filename string
      "x": 0,                    // X position in Atlas (px)
      "y": 0,                    // Y position in Atlas (px)
      "w": 64,                   // Width (px)
      "h": 128,                  // Height (px)
      "pivot_x": 0.500,          // Normalized Horizontal Anchor (0.0 - 1.0)
      "pivot_y": 1.000           // Normalized Vertical Anchor (0.0 - 1.0)
    },
    ...
  ]
}
  
```

#### 4.2 Interpreting Pivot Data

Pivots are **Normalized**, meaning they represent a percentage of the sprite's dimensions relative to the top-left corner.

* 0.0, 0.0 = Top Left
* 0.5, 0.5 = Center
* 0.5, 1.0 = Bottom Center (Feet)

**Formula to calculate engine offset (pixels):**

```
OffsetX​ = Width×PivotX
OffsetY​ = Height×PivotY 
```

***

### 5. ENGINE INTEGRATION EXAMPLES

#### 5.1 Godot 4.x (GDScript)

Use this snippet to load a sprite dynamically using LogicAtlas data.

```
func load_atlas_sprite(sprite_name: String, json_path: String):
    # 1. Load Data
    var file = FileAccess.open(json_path, FileAccess.READ)
    var data = JSON.parse_string(file.get_as_text())
    
    # 2. Find Sprite
    var target = null
    for s in data.sprites:
        if s.name == sprite_name:
            target = s
            break
            
    if target:
        # 3. Apply to Sprite2D
        $Sprite2D.texture = load("res://" + data.atlas)
        $Sprite2D.region_enabled = true
        $Sprite2D.region_rect = Rect2(target.x, target.y, target.w, target.h)
        
        # 4. Apply Pivot Logic (Center depends on engine default)
        # Godot default centers textures, so we adjust offset relative to center
        # Or simply set the node's offset directly:
        $Sprite2D.offset = Vector2(target.w * target.pivot_x, target.h * target.pivot_y)
  
```

#### 5.2 Unity (C#)

Unity requires slicing the texture via the SpriteEditor, usually manually. You can automate this via an **Editor Script**.

1. Read the JSON using JsonUtility.
2. Create SpriteMetaData objects.
3. Set spriteMetaData.pivot = new Vector2(data.pivot\_x, 1.0f - data.pivot\_y);\
   (Note: Unity Y-axis is often inverted relative to screen space, logic may vary).

***

### 6. INTERFACE REFERENCE

#### 6.1 The Logic Inspector (Left Panel)

* **Sprite List:** Displays all loaded assets. Drag-and-drop support is enabled here and on the main viewport.
* **Visualizer:**
  * **X / Y Fields:** Manual entry for precise pivoting.
  * **Presets (TL, C, BC):** Quick-set buttons for common game use cases (UI, Props, Characters).

#### 6.2 The Viewport (Right Panel)

* **Canvas:** Renders the packed result in real-time.
* **Mouse Interaction:**
  * **Left Click:** Selects a sprite and highlights it in the list.
  * **Crosshair:** A Cyan + indicates the current pivot point for the selected sprite.

#### 6.3 Exporting

* **Export Pack + Data:** Opens a Save Dialog.
  * Input: MyAtlas
  * Output: MyAtlas.png AND MyAtlas.json.
  * **Note:** The filenames must remain matching for the JSON to reference the correct image.

***

### 7. TROUBLESHOOTING

**Issue: The exported PNG looks blurry in my Image Viewer.**

* **Cause:** Most Windows photo viewers apply bilinear filtering when zooming in.
* **Solution:** Open the PNG in a dedicated pixel-art tool (Aseprite) or Game Engine. LogicAtlas exports raw, uncompressed pixels.

**Issue: Drag and Drop is not working.**

* **Cause:** You may be running LogicAtlas as "Administrator" while dragging from a standard Explorer window. Windows forbids drag-and-drop between differing privilege levels.
* **Solution:** Run LogicAtlas normally (do not use "Run as Admin").

**Issue: Pivot points are slightly off in-game.**

* **Cause:** Sub-pixel positioning.
* **Solution:** Ensure your game engine's "Snap to Pixel" settings align with the sprite dimensions. LogicAtlas floats allow for sub-pixel precision, but pixel-art games may need flooring.

***

### 8. LICENSE & LEGAL

**(c) 2025** [**Andras Gregori**](https://linktr.ee/agregori) **@** [**GregOrigin LLC**](https://gregorigin.com/)**.**

* **Asset Rights:** You own 100% of the PNG atlases and JSON data generated by this tool. You may use them in commercial projects without attribution.
* **Software Rights:** You may not decompile, reverse engineer, or redistribute the LogicAtlas.exe binary.

***

End of Manual