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:

{
  "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! 🗺️✨