novafarma/.agent/workflows/tiled-map-setup.md

# 🗺️ TILED MAP EDITOR - Complete Workflow Guide

**Date:** 15.12.2025  
**Estimated Time:** 4-6 hours  
**Difficulty:** Medium (requires artistic touch)

---

## 📋 **OVERVIEW**

This guide will take you through creating a professional 100x100 tile map using **Tiled Map Editor**.

**What you'll create:**
- Beautiful grass-covered base layer
- Organic dirt paths winding through the map
- Natural pond with lily pads and flowers
- Trees, bushes, and decorative elements
- Professional-quality exported JSON for Phaser

---

## 🎯 **PHASE 1: PREPARATION (30-45 min)**

### **Step 1.1: Install Tiled Map Editor**

1. Open browser to https://www.mapeditor.org/
2. Download **Windows Installer** (latest stable version, v1.11.x)
3. Run installer → Accept defaults → Install
4. Launch Tiled for first time
5. Verify installation: `File → About Tiled`

---

### **Step 1.2: Create Tileset Image**

**Option A: Use Existing Assets** (Quick - 10 min)
- Check if you already have tileset in `assets/tilesets/`
- If exists, skip to Step 1.3

**Option B: Create New Tileset** (30-40 min)

**Tools needed:**
- **Photoshop**, **GIMP**, **Paint.NET**, or **Aseprite**

**Tileset Specifications:**
- **Tile Size:** 48x48 pixels
- **Grid:** No spacing, no margin
- **Format:** PNG with transparency
- **Recommended size:** 8x8 grid = 384x384px (64 tiles)

**Tiles to create:**

1. **Grass Tiles (16 tiles):**
   - Base grass (#4a9d5f - rich green)
   - Grass variants (lighter/darker patches)
   - Transition tiles (grass to dirt)
   - Corner pieces

2. **Dirt/Path Tiles (12 tiles):**
   - Dirt base (#8b6f47 - brown)
   - Horizontal path
   - Vertical path
   - Corner pieces (NW, NE, SW, SE)
   - T-junctions
   - Cross-junction

3. **Water Tiles (8 tiles):**
   - Water center (#2a7fbc - blue)
   - Water edge pieces (8 directions)
   - Optionally: animated frames

4. **Decoration Tiles (28 tiles):**
   - Tree (round crown) - 2-4 tiles tall
   - Tree variations (3-4 types)
   - Flowers (red, yellow, pink, purple)
   - Bushes (small, medium)
   - Rocks (small, medium, large)
   - Lily pads
   - Lily pad with pink flower

**Save as:** `assets/tilesets/smooth_tileset.png`

---

### **Step 1.3: Import Tileset into Tiled**

1. Launch **Tiled Map Editor**
2. **File → New → New Tileset**
3. Configure:
   - **Name:** `smooth_tileset`
   - **Type:** Based on Tileset Image
   - **Source:** Browse to `smooth_tileset.png`
   - **Tile width:** 48
   - **Tile height:** 48
   - **Margin:** 0
   - **Spacing:** 0
4. Click **Save As** → `assets/tilesets/smooth_tileset.tsx`
5. Verify tiles appear in **Tilesets panel**

---

## 🎨 **PHASE 2: MAP CREATION (1-2 hours)**

### **Step 2.1: Create New Map**

1. **File → New → New Map**
2. Configure:
   - **Orientation:** Orthogonal (not isometric!)
   - **Tile layer format:** CSV (for simplicity)
   - **Tile render order:** Right Down
   - **Map size:**
     - Width: **100 tiles**
     - Height: **100 tiles**
   - **Tile size:**
     - Width: **48 px**
     - Height: **48 px**
3. Click **Save As** → `assets/maps/world.tmx`

**Map is now 4800x4800 pixels total!**

---

### **Step 2.2: Add Tileset to Map**

1. Right-click in **Tilesets panel**
2. **Add Tileset → Browse** → Select `smooth_tileset.tsx`
3. Tileset now appears in panel

---

## 🌱 **PHASE 3: LAYER PAINTING (2-3 hours)**

### **Step 3.1: Base Grass Layer (15 min)**

1. **Layer → Add Layer → Tile Layer**
2. Name: **`Ground`**
3. Select **grass base tile** from tileset
4. **Edit → Fill With Stamp (Bucket Tool)** or press **B**
5. Click anywhere on map → Entire map fills with grass!

**Add grass variations:**
1. Select **grass variant tile**
2. Use **Stamp Brush (B)** to paint random patches
3. Create natural variation (10-20% of map)
4. **Tip:** Use large brush for organic look

---

### **Step 3.2: Dirt Paths Layer (30-45 min)**

1. **Layer → Add Layer → Tile Layer**
2. Name: **`Paths`**
3. Select **dirt path tiles**

**Path Design Strategy:**
- **Main paths:** 2-3 tiles wide
- **Secondary paths:** 1 tile wide
- **Avoid:** Straight lines, 90° angles
- **Create:** Gentle curves, organic flow

**How to paint:**
1. Start from center (spawn point area)
2. Draw main vertical path (center to north/south)
3. Draw main horizontal path (center to east/west)
4. Add diagonal shortcuts
5. Connect with curves using corner tiles
6. Add winding secondary paths

**Corner Tiles:**
- Use appropriate NW, NE, SW, SE corners for smooth curves
- Use T-junctions where paths intersect
- Use cross-junction for major intersections

**Time:** 30-45 minutes for natural path network

---

### **Step 3.3: Pond Creation (30-45 min)**

1. **Layer → Add Layer → Tile Layer**
2. Name: **`Water`**

**Pond Design:**

**Shape:** Organic, irregular (NOT square!)
- Think kidney bean, amoeba, natural lake
- Size: ~15x20 tiles (medium pond)
- Location: Off-center (e.g., northeast quadrant)

**Painting Steps:**
1. Select **water center tile**
2. Paint rough pond shape (filled blob)
3. Add **water edge tiles** around perimeter
   - Use appropriate edge tile for each direction
   - Corners need special corner-edge tiles
4. Refine edges for smooth, natural look

**Lily Pads (Layer: Decorations):**
1. Place 3-5 **lily pad tiles** on water
2. Add **lily pad with pink flower** (1-2)
3. Space them naturally (not in straight line!)

**Optional Koi Fish:**
- Add 2-3 koi fish tiles swimming in pond

---

### **Step 3.4: Trees & Decorations Layer (30-45 min)**

1. **Layer → Add Layer → Tile Layer**
2. Name: **`Decorations`**

**Tree Placement:**
- **Quantity:** 20-30 trees across map
- **Clustering:** Group 2-4 trees together
- **Spacing:** Leave open areas for farming
- **Placement:** Avoid paths and spawn area
- **Variation:** Use different tree types

**Flowers:**
- **Quantity:** 30-50 individual flowers
- **Colors:** Mix red, yellow, pink, purple
- **Placement:** Along paths, near trees, random clusters
- **Avoid:** Dense flower fields (keep sparse)

**Bushes:**
- **Quantity:** 15-25 bushes
- **Placement:** Fill gaps, create variety
- **Mix:** Small and medium sizes

**Rocks (Optional):**
- **Quantity:** 10-15 decorative rocks
- **Placement:** Near paths, water edge

**Reference Density:** Aim for 25-30% decoration coverage

---

## 🚧 **PHASE 4: COLLISION & OBJECTS (30 min)**

### **Step 4.1: Collision Properties**

**Set tile collisions:**
1. Select **Tileset panel** → Click your tileset
2. For each **water tile**:
   - Right-click → **Tile Properties**
   - Add custom property: `collides` = `true` (boolean)
3. For each **tree tile**:
   - Add `collides` = `true`
4. For **large rocks**:
   - Add `collides` = `true`

---

### **Step 4.2: Object Layer - Spawn Points**

1. **Layer → Add Layer → Object Layer**
2. Name: **`SpawnPoints`**

**Add Player Spawn:**
1. Select **Insert Point** tool (P key)
2. Click on center of map (50, 50)
3. **Object Properties:**
   - Name: `PlayerSpawn`
   - Type: `spawn`
   - Custom properties:
     - `gridX` = `50` (number)
     - `gridY` = `50` (number)

**Optional NPC Spawns:**
- Repeat for any NPC spawn locations
- Name them: `NPCSpawn_1`, `NPCSpawn_2`, etc.

---

## 📤 **PHASE 5: EXPORT (15 min)**

### **Step 5.1: Export to JSON**

1. **File → Export As**
2. Select format: **JSON map files (*.tmj *.json)**
3. Save as: `assets/maps/world.json`
4. Verify file created successfully

---

### **Step 5.2: Verify JSON Structure**

Open `world.json` and verify:

```json
{
  "width": 100,
  "height": 100,
  "tilewidth": 48,
  "tileheight": 48,
  "layers": [
    { "name": "Ground", "type": "tilelayer", ... },
    { "name": "Paths", "type": "tilelayer", ... },
    { "name": "Water", "type": "tilelayer", ... },
    { "name": "Decorations", "type": "tilelayer", ... },
    { "name": "SpawnPoints", "type": "objectgroup", ... }
  ],
  "tilesets": [ ... ]
}
```

---

## 🎮 **PHASE 6: INTEGRATION (30-45 min)**

### **Step 6.1: Load Map in Phaser**

Create/modify loader system - I can help with code when ready!

---

## ✅ **FINAL CHECKLIST**

Before considering map complete:

- [ ] All 100x100 tiles painted (no gaps)
- [ ] Paths look natural and organic
- [ ] Pond has smooth edges and lily pads
- [ ] Trees properly distributed (20-30)
- [ ] Flowers placed (30-50)
- [ ] Bushes added (15-25)
- [ ] Collision properties set
- [ ] Player spawn point placed
- [ ] Exported to JSON successfully
- [ ] File saved in correct location

---

## 📊 **TIME BREAKDOWN**

| Phase | Task | Time |
|-------|------|------|
| 1 | Preparation (install, tileset) | 30-45 min |
| 2 | Map creation | 15 min |
| 3.1 | Grass base layer | 15 min |
| 3.2 | Dirt paths | 30-45 min |
| 3.3 | Pond creation | 30-45 min |
| 3.4 | Trees & decorations | 30-45 min |
| 4 | Collision & objects | 30 min |
| 5 | Export | 15 min |
| **TOTAL** | | **3-4.5 hours** |

*Note: First-time users may need 4-6 hours*

---

## 💡 **TIPS FOR SUCCESS**

1. **Take breaks** - Don't rush, enjoy the creative process
2. **Save often** - Ctrl+S frequently!
3. **Zoom in/out** - Use mouse wheel for different perspectives
4. **Undo is your friend** - Ctrl+Z if you make mistakes
5. **Reference images** - Look at real top-down maps for inspiration
6. **Test early** - Export and test in Phaser after each layer

---

## 🐛 **TROUBLESHOOTING**

**Map too large to see:**
- Zoom out: Ctrl + Mouse wheel down
- Fit to view: View → Zoom → Fit in View

**Tiles not aligning:**
- Check tile size is exactly 48x48
- Check margin/spacing is 0

**Export fails:**
- Ensure map folder exists: `assets/maps/`
- Check write permissions

**Collisions not working in game:**
- Verify custom properties spelling: `collides` (lowercase)
- Check boolean value, not string

---

**Ready to create your map? Let me know when to help with Phaser integration!** 🗺️✨