# Pixeldex · Godot Tilemap CSV Loader Starter

Drop-in script for Godot 4.2+ that populates a `TileMap` node from a CSV file. Edit your levels in Numbers / Google Sheets / VS Code instead of the in-engine paint tool.

License: **CC0**.
Source: https://pixeldex.dev/prompts/godot-tilemap-csv-loader

---

## What's in this folder

| File | What it is |
|---|---|
| `TilemapLoader.gd` | The loader script. Single class with one public method. |
| `example-level.csv` | A 10×9 test room demonstrating the CSV format (walls, floor, decorations). |

---

## Usage (~2 minutes)

1. Drop `TilemapLoader.gd` into your project (e.g. `res://scripts/`).
2. Drop the CSV file(s) somewhere readable (e.g. `res://levels/`).
3. In your scene, add a `TileMap` node with a `TileSet` resource that has sources for IDs `0`, `1`, `2`, etc, matching whatever numbers your CSV uses.
4. From any script (or a scene's `_ready`):

```gdscript
var loader := TilemapLoader.new()
loader.load_from_csv($TileMap, "res://levels/example-level.csv")
```

5. Press Play. The tilemap populates from the CSV.

---

## CSV format

```
# Lines starting with # are comments and skipped
# Each row in the file = one row of tiles
# Cells are integers = tile source IDs in your TileSet
# Use -1 for empty (no tile placed at that position)
1,1,1,1,1
1,0,0,0,1
1,0,2,0,1
1,0,0,0,1
1,1,1,1,1
```

**Rules:**
- Trailing whitespace and BOM characters are stripped automatically (so Excel exports work).
- Rows with fewer cells than the longest row get padded with empty.
- Non-integer cells log a warning and become empty rather than crash the load.
- Source IDs not found in the TileSet log a warning and skip that cell.

---

## Pro workflow

Once your CSV format is set:

1. Open `example-level.csv` in Google Sheets or Numbers.
2. Edit visually, colored cells become tile IDs by exporting as CSV.
3. Save / export back to your project's `res://levels/` folder.
4. Hit Play in Godot.

For procedural generation: write the same CSV string from Python / Rust / whatever, save to disk, point the loader at it. Now your levels are data, not in-engine art.

---

## Pairing ideas

- Pair with the [Godot FSM player controller starter](https://pixeldex.dev/prompts/godot-fsm-player-controller) and you've got a playable level in ~10 minutes.
- Pair with the [coyote-time platformer prompt](https://pixeldex.dev/prompts/unity-2d-platformer-coyote-time), same CSV format works if you adapt the loader to Unity's Tilemap API (different engine, same pattern).

---

If you ship something with this, a link to https://pixeldex.dev helps. Not required.