### Installation Guide

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Instructions on how to install and enable the TileMapDual plugin in your Godot project.

```APIDOC
## Installation

Copy the `addons/TileMapDual` folder to your Godot project and enable the plugin in Project Settings.

```
project/
├── addons/
│   └── TileMapDual/
│       ├── plugin.cfg
│       ├── plugin.gd
│       ├── tile_map_dual.gd
│       └── ... (other plugin files)
```

Enable the plugin via: **Project → Project Settings → Plugins → TileMapDual → Enable**
```

--------------------------------

### Install TileMapDual Plugin

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Copy the addon folder to your project and enable the plugin in Project Settings.

```text
project/
├── addons/
│   └── TileMapDual/
│       ├── plugin.cfg
│       ├── plugin.gd
│       ├── tile_map_dual.gd
│       └── ... (other plugin files)
```

--------------------------------

### TileMapDual Node Setup

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Demonstrates how to set up and use the TileMapDual node in a Godot scene, including assigning a tileset and drawing cells programmatically.

```APIDOC
## TileMapDual Node

The main node that provides dual-grid tilemap functionality by extending TileMapLayer.

TileMapDual automatically creates a display layer that shows the properly-smoothed tiles while you draw on an invisible world grid using just the fully-filled tile. The plugin handles all the complex terrain matching automatically based on Godot's terrain system.

```gdscript
# Basic scene setup with TileMapDual
extends Node2D

func _ready():
    # Create a TileMapDual node
    var tilemap = TileMapDual.new()

    # Assign your prepared dual-grid tileset (must have terrains configured)
    tilemap.tile_set = preload("res://assets/tileset/square.tres")

    # Add to scene tree
    add_child(tilemap)

    # Draw some tiles programmatically using terrain 1 (filled tile)
    tilemap.draw_cell(Vector2i(0, 0), 1)
    tilemap.draw_cell(Vector2i(1, 0), 1)
    tilemap.draw_cell(Vector2i(2, 0), 1)
    tilemap.draw_cell(Vector2i(0, 1), 1)
    tilemap.draw_cell(Vector2i(1, 1), 1)
    tilemap.draw_cell(Vector2i(2, 1), 1)
```
```

--------------------------------

### Basic Scene Setup with TileMapDual Node

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Demonstrates how to create and configure a TileMapDual node programmatically in a Godot scene. Ensure your tileset has terrains configured.

```gdscript
# Basic scene setup with TileMapDual
extends Node2D

func _ready():
    # Create a TileMapDual node
    var tilemap = TileMapDual.new()

    # Assign your prepared dual-grid tileset (must have terrains configured)
    tilemap.tile_set = preload("res://assets/tileset/square.tres")

    # Add to scene tree
    add_child(tilemap)

    # Draw some tiles programmatically using terrain 1 (filled tile)
    tilemap.draw_cell(Vector2i(0, 0), 1)
    tilemap.draw_cell(Vector2i(1, 0), 1)
    tilemap.draw_cell(Vector2i(2, 0), 1)
    tilemap.draw_cell(Vector2i(0, 1), 1)
    tilemap.draw_cell(Vector2i(1, 1), 1)
    tilemap.draw_cell(Vector2i(2, 1), 1)
```

--------------------------------

### Determine TileSet Grid Shape

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Use `Display.tileset_gridshape` to get the grid shape of a TileSet. This function categorizes combinations of `TileSet.tile_shape` and `TileSet.tile_offset_axis` for dual-grid alignment.

```gdscript
# GridShape enum values:
# Display.GridShape.SQUARE       - Standard square tiles
# Display.GridShape.ISO          - Isometric diamond tiles
# Display.GridShape.HALF_OFF_HORI - Half-offset horizontal
# Display.GridShape.HALF_OFF_VERT - Half-offset vertical
# Display.GridShape.HEX_HORI     - Hexagonal with horizontal offset
# Display.GridShape.HEX_VERT     - Hexagonal with vertical offset

# Example: Check the grid shape of a tileset
func get_grid_type(tile_set: TileSet) -> String:
    var shape = Display.tileset_gridshape(tile_set)
    match shape:
        Display.GridShape.SQUARE:
            return "Square Grid"
        Display.GridShape.ISO:
            return "Isometric Grid"
        Display.GridShape.HEX_HORI:
            return "Horizontal Hexagonal Grid"
        Display.GridShape.HEX_VERT:
            return "Vertical Hexagonal Grid"
        _:
            return "Other Grid Type"

```

--------------------------------

### Set up Dual-Grid TileSet

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Configure a TileSet for TileMapDual with specific tile arrangements and terrain settings for square grids. Ensure terrain peering bits are correctly set.

```gdscript
# TileSet requirements:
# 1. Create a 4x4 grid texture with 15+1 unique tiles
# 2. Tile at (2,1) should be the fully-filled tile (terrain 1)
# 3. Tile at (0,3) should be the empty tile (terrain 0)
# 4. Configure terrain_set_0 with mode = 1 (Match Corners)

# Tileset template positions for square grids:
# Row 0: (0,0) (1,0) (2,0) (3,0)
# Row 1: (0,1) (1,1) (2,1-FULL) (3,1)
# Row 2: (0,2) (1,2) (2,2) (3,2)
# Row 3: (0,3-EMPTY) (1,3) (2,3) (3,3)

# Example scene setup (.tscn excerpt):
# [node name="TileMapDual" type="TileMapLayer"]
# tile_set = preload("res://assets/tileset/square.tres")
# script = preload("res://addons/TileMapDual/tile_map_dual.gd")

# The tileset needs:
# - terrain_set_0 configured with Match Corners mode
# - Each tile's terrains_peering_bit values set for 4 corners
# - Terrain 0 = empty/background, Terrain 1 = filled/foreground
```

--------------------------------

### Configure Isometric TileSet

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Set up an isometric dual-grid tileset by configuring the TileSet's shape, size, and adding an atlas source with isometric tiles. Drawing cells is similar to square grids.

```gdscript
extends Node2D

func setup_isometric_tilemap():
    var tilemap = TileMapDual.new()

    # Load isometric tileset
    var tile_set = TileSet.new()
    tile_set.tile_shape = TileSet.TILE_SHAPE_ISOMETRIC
    tile_set.tile_size = Vector2i(64, 32)  # Standard isometric ratio

    # Add atlas source with isometric tiles
    var atlas = TileSetAtlasSource.new()
    atlas.texture = preload("res://assets/tileset_iso.png")
    atlas.texture_region_size = Vector2i(64, 32)
    tile_set.add_source(atlas)

    tilemap.tile_set = tile_set
    add_child(tilemap)

    # Drawing works the same as square grids
    tilemap.draw_cell(Vector2i(0, 0), 1)
    tilemap.draw_cell(Vector2i(1, 0), 1)
```

--------------------------------

### Display Material Property

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Explains the `display_material` property for applying custom shaders and materials to the visible tiles.

```APIDOC
## Display Material Property

Custom material property to apply shader effects to the rendered display tiles.

The `display_material` property allows you to assign ShaderMaterial or CanvasItemMaterial to the visible display layer without affecting the hidden world grid. This is essential for visual effects like lighting, outlines, or custom rendering.

```gdscript
extends Node2D

@onready var tilemap: TileMapDual = $TileMapDual

func _ready():
    # Apply a custom shader material to the display tiles
    var shader_material = ShaderMaterial.new()
    shader_material.shader = preload("res://assets/shader/shader.gdshader")

    # Set the material on the display layer
    tilemap.display_material = shader_material
```
```

--------------------------------

### Set up Hexagonal Grid TileMap

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Configure TileMapDual for hexagonal grids in horizontal or vertical orientation. The plugin automatically handles dual-grid offsets. Hex coordinates use Godot's standard system.

```gdscript
extends Node2D

func setup_hex_tilemap():
    var tilemap = TileMapDual.new()

    # Configure hexagonal tileset
    var tile_set = TileSet.new()
    tile_set.tile_shape = TileSet.TILE_SHAPE_HEXAGON
    tile_set.tile_offset_axis = TileSet.TILE_OFFSET_AXIS_HORIZONTAL  # or VERTICAL
    tile_set.tile_size = Vector2i(64, 64)

    # Add hex atlas with proper terrain configuration
    var atlas = TileSetAtlasSource.new()
    atlas.texture = preload("res://assets/Hex Dual Hori Flat - 64x48.png")
    tile_set.add_source(atlas)

    tilemap.tile_set = tile_set
    add_child(tilemap)

    # Hex coordinates work with Godot's standard hex coordinate system
    tilemap.draw_cell(Vector2i(0, 0), 1)
    tilemap.draw_cell(Vector2i(1, 0), 1)
    tilemap.draw_cell(Vector2i(0, 1), 1)
```

--------------------------------

### Connect to TileSetWatcher Signals

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Connect to signals from `TileSetWatcher` to monitor real-time changes in the tileset. This is useful for custom extensions that need to react to events like terrain configuration updates.

```gdscript
# Available signals from TileSetWatcher:
# - tileset_deleted: Emitted when tile_set is cleared or replaced
# - tileset_created: Emitted when tile_set is created or replaced
# - tileset_resized: Emitted when tile_set.tile_size changes
# - tileset_reshaped: Emitted when GridShape would be different
# - atlas_added(source_id, atlas): Emitted when new Atlas is added
# - atlas_autotiled(source_id, atlas): Emitted when auto-tile dialog is accepted
# - terrains_changed: Emitted when atlas or terrain configuration changes

# Example: Custom handler for tileset changes (advanced usage)
extends TileMapDual

func _ready():
    super._ready()
    # Access internal watcher for custom signal handling
    _tileset_watcher.terrains_changed.connect(_on_terrains_changed)

func _on_terrains_changed():
    print("Terrain configuration updated!")

```

--------------------------------

### Avoid Deep Nesting in GDScript

Source: https://github.com/pablogila/tilemapdual/blob/main/CONTRIBUTING.md

Demonstrates a cleaner way to handle conditional logic in GDScript by returning early instead of deep nesting.

```gdscript
def test():
    if condition:
        do_something()
        ...
```

```gdscript
def test():
    if not condition:
        return
    do_something()
    ...
```

--------------------------------

### Paint and Erase Tiles at Runtime

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Handles mouse input to paint or erase tiles within a specified radius. Use this for interactive terrain modification based on user input.

```gdscript
extends Node2D

@onready var tilemap: TileMapDual = $TileMapDual

var brush_size: int = 2

func _input(event: InputEvent):
    if event is InputEventMouseButton and event.pressed:
        var cell = tilemap.local_to_map(get_global_mouse_position())

        if event.button_index == MOUSE_BUTTON_LEFT:
            paint_area(cell, brush_size, 1)  # Paint filled tiles
        elif event.button_index == MOUSE_BUTTON_RIGHT:
            paint_area(cell, brush_size, -1)  # Erase tiles

func paint_area(center: Vector2i, radius: int, terrain: int):
    for x in range(-radius, radius + 1):
        for y in range(-radius, radius + 1):
            if Vector2(x, y).length() <= radius:
                tilemap.draw_cell(center + Vector2i(x, y), terrain)
```

--------------------------------

### draw_cell() Method

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Explains the `draw_cell()` method for programmatically adding, removing, or modifying tiles on the TileMapDual.

```APIDOC
## draw_cell() Method

Public method to programmatically add and remove tiles on the dual-grid tilemap.

The `draw_cell()` method allows you to draw or erase tiles via code, making it useful for procedural level generation or runtime tile manipulation. The terrain parameter determines which terrain type to draw, with terrain 1 typically being the filled tile and terrain -1 erasing the cell completely.

```gdscript
extends Node2D

@onready var tilemap: TileMapDual = $TileMapDual

func _ready():
    # Draw a filled tile at position (5, 3) using terrain 1
    tilemap.draw_cell(Vector2i(5, 3), 1)

    # Draw using terrain 0 (empty tile) - keeps the cell but shows empty
    tilemap.draw_cell(Vector2i(6, 3), 0)

    # Completely remove a tile using terrain -1
    tilemap.draw_cell(Vector2i(7, 3), -1)

# Example: Procedural rectangle generation
func generate_room(top_left: Vector2i, size: Vector2i):
    for x in range(size.x):
        for y in range(size.y):
            tilemap.draw_cell(top_left + Vector2i(x, y), 1)

# Example: Clear an area
func clear_area(top_left: Vector2i, size: Vector2i):
    for x in range(size.x):
        for y in range(size.y):
            tilemap.draw_cell(top_left + Vector2i(x, y), -1)
```
```

--------------------------------

### Implement Multiple Terrain Layers

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Use multiple TileMapDual nodes stacked with different z_index values to manage complex multi-terrain environments. Each layer handles a single terrain type with transparency.

```gdscript
extends Node2D

@onready var ground_layer: TileMapDual = $GroundLayer
@onready var grass_layer: TileMapDual = $GrassLayer
@onready var water_layer: TileMapDual = $WaterLayer

func _ready():
    # Draw base ground everywhere
    for x in range(20):
        for y in range(20):
            ground_layer.draw_cell(Vector2i(x, y), 1)

    # Add grass patches on top
    grass_layer.draw_cell(Vector2i(5, 5), 1)
    grass_layer.draw_cell(Vector2i(6, 5), 1)
    grass_layer.draw_cell(Vector2i(5, 6), 1)

    # Add water areas (rendered on top with transparency)
    water_layer.draw_cell(Vector2i(10, 10), 1)
    water_layer.draw_cell(Vector2i(11, 10), 1)

# Scene structure:
# Node2D
# ─ GroundLayer (TileMapDual) - z_index: 0
# ─ GrassLayer (TileMapDual)  - z_index: 1
# ─ WaterLayer (TileMapDual)  - z_index: 2
```

--------------------------------

### Retrieve Terrain Type with get_cell()

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Demonstrates how to use the get_cell() method to query the terrain type of a tile at a given coordinate. This is useful for game logic that depends on tile types.

```gdscript
extends Node2D

@onready var tilemap: TileMapDual = $TileMapDual

func check_tile_at_position(cell: Vector2i) -> void:
    var terrain = tilemap.get_cell(cell)

    match terrain:
        -1:
            print("Cell is empty (no tile)")
        0:
            print("Cell has empty terrain tile")
        1:
            print("Cell has filled terrain tile")
        _:
            print("Cell has terrain type: ", terrain)

func is_cell_filled(cell: Vector2i) -> bool:
    return tilemap.get_cell(cell) == 1
```

--------------------------------

### Apply Custom Shaders with display_material

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Shows how to assign a ShaderMaterial or CanvasItemMaterial to the display layer of the TileMapDual node to apply visual effects without altering the world grid.

```gdscript
extends Node2D

@onready var tilemap: TileMapDual = $TileMapDual

func _ready():
    # Apply a custom shader material to the display tiles
    var shader_material = ShaderMaterial.new()
    shader_material.shader = preload("res://assets/shader/shader.gdshader")

    # Set the material on the display layer
    tilemap.display_material = shader_material
```

--------------------------------

### Draw Tiles with TileMapDualLegacy

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Use the legacy `TileMapDualLegacy` node for compatibility with older versions. The `draw` method accepts cell coordinates, tile state (filled, empty, remove), and an optional atlas ID.

```gdscript
# Legacy API - use TileMapDual for new projects
extends Node2D

@onready var legacy_tilemap: TileMapDualLegacy = $TileMapDualLegacy

func _ready():
    # Legacy draw method: draw(cell, tile, atlas_id)
    # tile: 1 = filled, 0 = empty, -1 = remove
    # atlas_id: defaults to 0

    # Draw a filled tile
    legacy_tilemap.draw(Vector2i(5, 3), 1, 0)

    # Draw an empty tile
    legacy_tilemap.draw(Vector2i(6, 3), 0, 0)

    # Remove a tile completely
    legacy_tilemap.draw(Vector2i(7, 3), -1)

    # Apply material to display layer
    legacy_tilemap.display_material = preload("res://my_material.tres")

    # Force full tileset update
    legacy_tilemap.update_full_tileset()

```

--------------------------------

### Programmatically Draw and Erase Tiles with draw_cell()

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Shows how to use the draw_cell() method to add, modify, or remove tiles at specific coordinates. Terrain -1 erases the cell, terrain 1 is typically a filled tile, and terrain 0 represents an empty tile.

```gdscript
extends Node2D

@onready var tilemap: TileMapDual = $TileMapDual

func _ready():
    # Draw a filled tile at position (5, 3) using terrain 1
    tilemap.draw_cell(Vector2i(5, 3), 1)

    # Draw using terrain 0 (empty tile) - keeps the cell but shows empty
    tilemap.draw_cell(Vector2i(6, 3), 0)

    # Completely remove a tile using terrain -1
    tilemap.draw_cell(Vector2i(7, 3), -1)

# Example: Procedural rectangle generation
func generate_room(top_left: Vector2i, size: Vector2i):
    for x in range(size.x):
        for y in range(size.y):
            tilemap.draw_cell(top_left + Vector2i(x, y), 1)

# Example: Clear an area
func clear_area(top_left: Vector2i, size: Vector2i):
    for x in range(size.x):
        for y in range(size.y):
            tilemap.draw_cell(top_left + Vector2i(x, y), -1)
```

--------------------------------

### Inspect TileMapDual Cache

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Access and inspect cached cell data for debugging purposes. Requires extending the TileMapDual class.

```gdscript
extends TileMapDual

func debug_cache():
    # Access cached cells through display
    var cache = _display.cached_cells

    for cell in cache.cells:
        var data = cache.cells[cell]
        print("Cell %s: terrain=%d" % [cell, data.terrain])

func check_terrain_at(cell: Vector2i) -> int:
    # Get terrain using cache
    return _display.cached_cells.get_terrain_at(cell)
```

--------------------------------

### Enable Godot 4.3 Compatibility Mode

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Enable `godot_4_3_compatibility` for older Godot versions to ensure proper change detection. This mode performs double-checks on all cells during refresh cycles.

```gdscript
extends Node2D

@onready var tilemap: TileMapDual = $TileMapDual

func _ready():
    # Enable compatibility mode for Godot 4.3 and below
    tilemap.godot_4_3_compatibility = true

    # Adjust refresh time if needed (0.0 to 0.1 seconds)
    tilemap.refresh_time = 0.02  # Default value

    # The plugin auto-detects Godot version, but you can override:
    # tilemap.godot_4_3_compatibility = false  # For Godot 4.4+

```

--------------------------------

### Generate Terrain Chunk with Noise

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Generates a 16x16 chunk of terrain based on noise values. This is useful for procedural level generation. Ensure FastNoiseLite is available.

```gdscript
# For performance-critical scenarios, batch operations:
func generate_terrain_chunk(offset: Vector2i, noise: FastNoiseLite):
    for x in range(16):
        for y in range(16):
            var world_pos = offset + Vector2i(x, y)
            var noise_val = noise.get_noise_2d(world_pos.x, world_pos.y)
            var terrain = 1 if noise_val > 0.0 else -1
            tilemap.draw_cell(world_pos, terrain)
```

--------------------------------

### get_cell() Method

Source: https://context7.com/pablogila/tilemapdual/llms.txt

Details the `get_cell()` method for retrieving the terrain type of a specific cell.

```APIDOC
## get_cell() Method

Public method to retrieve the terrain value at a specific cell coordinate.

The `get_cell()` method returns the terrain type assigned to a given cell position, useful for game logic that needs to know what type of tile exists at a location.

```gdscript
extends Node2D

@onready var tilemap: TileMapDual = $TileMapDual

func check_tile_at_position(cell: Vector2i) -> void:
    var terrain = tilemap.get_cell(cell)

    match terrain:
        -1:
            print("Cell is empty (no tile)")
        0:
            print("Cell has empty terrain tile")
        1:
            print("Cell has filled terrain tile")
        _:
            print("Cell has terrain type: ", terrain)

func is_cell_filled(cell: Vector2i) -> bool:
    return tilemap.get_cell(cell) == 1
```
```

--------------------------------

### TileCache Internal Structure

Source: https://context7.com/pablogila/tilemapdual/llms.txt

The `TileCache` system internally tracks tile data for efficient change detection. It maps cell coordinates to tile information, including source ID, atlas coordinates, and terrain values.

```gdscript
# TileCache is used internally by TileMapDual
# Understanding its structure can help with debugging

# Cache structure per cell:
# {
#   Vector2i(x, y): {
#     'sid': int,      # Source ID in TileSet
#     'tile': Vector2i, # Atlas coordinates
#     'terrain': int    # Terrain value
#   }
# }

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.