novafarma/docs/TILED_MAP_GUIDE.md

# 🗺️ TILED MAP EDITOR - Integration Guide

**Last Updated:** 2025-12-14

---

## 📋 OVERVIEW

This guide explains how to use **Tiled Map Editor** for creating smooth 2D/2.5D maps in NovaFarma instead of procedural generation.

---

## 1️⃣ INSTALL TILED

### Download:
- **Website:** https://www.mapeditor.org/
- **Version:** Latest stable (1.10+)
- **License:** Free & Open Source

### Installation:
1. Download for your OS (Windows/Mac/Linux)
2. Install normally
3. Launch Tiled

---

## 2️⃣ CREATE TILESET

### Step 1: Prepare Tileset Image

Create a smooth tileset PNG file: `assets/tilesets/smooth_tileset.png`

**Requirements:**
- ✅ Smooth painted style (Stardew Valley)
- ✅ Tile size: 48x48px
- ✅ NO grid lines in image
- ✅ Seamless tiles
- ✅ PNG with transparency

**Example Tileset Layout:**
```
[Grass] [Dirt]  [Water] [Stone]
[Path]  [Farm]  [Sand]  [Wood]
[Tree]  [Rock]  [Bush]  [Flower]
```

### Step 2: Create Tileset in Tiled

1. **File → New → New Tileset**
2. Settings:
   - Name: `smooth_tileset`
   - Type: `Based on Tileset Image`
   - Image: `smooth_tileset.png`
   - Tile width: `48`
   - Tile height: `48`
   - Margin: `0`
   - Spacing: `0`
3. Click **Save As** → `assets/tilesets/smooth_tileset.tsx`

---

## 3️⃣ CREATE MAP

### Step 1: New Map

1. **File → New → New Map**
2. Settings:
   - Orientation: `Orthogonal` (for 2D) or `Isometric` (for 2.5D)
   - Tile layer format: `CSV` or `Base64`
   - Tile size: `48x48`
   - Map size: `100x100` (or your desired size)
3. Click **Save As** → `assets/maps/smooth_world.tmx`

### Step 2: Add Layers

Create these layers (from bottom to top):
1. **Ground** - Base terrain (grass, dirt, water)
2. **Decorations** - Trees, rocks, bushes
3. **Structures** - Buildings, fences
4. **Overlay** - Top layer effects

### Step 3: Paint Map

1. Select tileset
2. Click tiles to paint
3. Use **Stamp Tool** (B) for custom patterns
4. Use **Fill Tool** (F) for large areas
5. Use **Eraser** (E) to remove

---

## 4️⃣ EXPORT TO JSON

### Export Map:

1. **File → Export As...**
2. Format: **JSON map files (*.json)**
3. Save to: `assets/maps/smooth_world.json`
4. ✅ Done!

---

## 5️⃣ INTEGRATE WITH PHASER

### PreloadScene.js

```javascript
preload() {
    // Load tileset image
    this.load.image('smooth_tileset', 'assets/tilesets/smooth_tileset.png');
    
    // Load Tiled JSON map
    this.load.tilemapTiledJSON('smooth_world', 'assets/maps/smooth_world.json');
}
```

### GameScene.js - Create Map

```javascript
create() {
    // Create tilemap from Tiled JSON
    const map = this.make.tilemap({ key: 'smooth_world' });
    
    // Add tileset image to map
    // 'smooth_tileset' = name in Tiled
    // 'smooth_tileset' = key loaded in preload
    const tileset = map.addTilesetImage('smooth_tileset', 'smooth_tileset');
    
    // Create layers
    this.groundLayer = map.createLayer('Ground', tileset, 0, 0);
    this.decorLayer = map.createLayer('Decorations', tileset, 0, 0);
    this.structureLayer = map.createLayer('Structures', tileset, 0, 0);
    
    // Set collision (optional)
    this.groundLayer.setCollisionByProperty({ collides: true });
    
    // Enable collision with player (optional)
    this.physics.add.collider(this.player, this.groundLayer);
    
    console.log('🗺️ Tiled map loaded!');
}
```

---

## 6️⃣ REPLACE PROCEDURAL GENERATION

### Option A: Completely Replace

**In GameScene.js:**

```javascript
create() {
    // REMOVE:
    // this.terrainSystem = new TerrainSystem(...);
    // this.terrainSystem.generate();
    
    // ADD:
    const map = this.make.tilemap({ key: 'smooth_world' });
    const tileset = map.addTilesetImage('smooth_tileset', 'smooth_tileset');
    this.groundLayer = map.createLayer('Ground', tileset, 0, 0);
    
    // Player spawn
    this.player = new Player(this, 50, 50); // Grid position
}
```

### Option B: Hybrid Approach

Use Tiled for base terrain, procedural for decorations:

```javascript
create() {
    // Load base terrain from Tiled
    const map = this.make.tilemap({ key: 'smooth_world' });
    const tileset = map.addTilesetImage('smooth_tileset', 'smooth_tileset');
    this.groundLayer = map.createLayer('Ground', tileset, 0, 0);
    
    // Add procedural decorations
    this.spawnTrees();
    this.spawnRocks();
}
```

---

## 7️⃣ WANG TILES (AUTOMATIC SMOOTH TRANSITIONS)

### What are Wang Tiles?

**Wang Tiles** (also called **Terrain Brush**) automatically create smooth transitions between different terrain types!

### Benefits:
- ✅ **Auto-blending** grass → dirt → water
- ✅ **Smooth edges** (no hard lines!)
- ✅ **Fast painting** (one click!)
- ✅ **Natural look**

### Setup in Tiled:

#### Step 1: Create Wang Set

1. **View → Tilesets → Your Tileset**
2. Click **+** (Add Terrain Set)
3. Name: `Terrain_Set`
4. Type: `Corner` or `Edge` (recommended: Corner)

#### Step 2: Assign Tiles

1. Select transition tiles in tileset
2. Click **Terrain Brush** icon
3. Paint terrain types on tile corners
4. Tiled auto-calculates transitions!

#### Step 3: Paint with Wang Tiles

1. In map, select **Terrain Brush Tool** (T)
2. Choose terrain type (grass, dirt, water)
3. Paint freely - transitions are automatic! ✨

### Example Setup:

```
Terrain Types:
- Grass (main)
- Dirt (paths)
- Water (ponds)
- Sand (beach)

Tiled auto-creates:
- Grass → Dirt smooth edges
- Water → Sand beach transitions
- Dirt → Water pond edges
```

### Required Tiles:

For full Wang/Terrain set, you need **47 tiles** per terrain pair:
- 1 full tile
- 4 edges
- 4 corners
- 4 inverted corners
- 34 combinations

**Tip:** Use tileset generators or paint manually!

---

## 8️⃣ ADVANCED FEATURES

### Collision Detection

**In Tiled:**
1. Select tiles
2. Right-click → **Tile Properties**
3. Add custom property: `collides = true`

**In Phaser:**
```javascript
this.groundLayer.setCollisionByProperty({ collides: true });
this.physics.add.collider(this.player, this.groundLayer);
```

### Multiple Tilesets

```javascript
const tileset1 = map.addTilesetImage('terrain', 'terrain_image');
const tileset2 = map.addTilesetImage('objects', 'objects_image');

this.groundLayer = map.createLayer('Ground', [tileset1, tileset2], 0, 0);
```

### Object Layers

**In Tiled:**
1. Add **Object Layer**
2. Place spawn points, triggers, etc.

**In Phaser:**
```javascript
const spawnPoints = map.getObjectLayer('SpawnPoints').objects;

spawnPoints.forEach(point => {
    if (point.name === 'PlayerSpawn') {
        this.player = new Player(this, point.x, point.y);
    }
});
```

---

## 8️⃣ TIPS & BEST PRACTICES

### ✅ DO:
- Use **smooth painted tiles** (Stardew Valley style)
- Keep tile size consistent (48x48)
- Organize layers logically
- Use object layers for spawn points
- Export to JSON (not XML!)
- Version control your .tmx files

### ❌ DON'T:
- Don't use pixel art tiles (unless requested!)
- Don't mix tile sizes
- Don't hardcode positions
- Don't forget to export after changes
- Don't use too many layers (performance!)

---

## 9️⃣ SMOOTH TILESET CREATION

### Generate Smooth Tiles

For each tile type, create smooth 48x48 painted tiles:

**Grass Tile:**
```
- Base: #4a9d5f (green)
- Gradient: lighter green on top
- Texture: soft brush strokes
- Edges: slightly darker
```

**Water Tile:**
```
- Base: #2a7fbc (blue)
- Highlights: circular shine spots
- Gradient: deeper blue at bottom
- Reflection: white soft spots
```

**Dirt Tile:**
```
- Base: #8b6f47 (brown)
- Texture: organic patches
- Shadows: darker brown spots
- Natural variation
```

---

## 🔟 FILE STRUCTURE

```
novafarma/
├── assets/
│   ├── tilesets/
│   │   ├── smooth_tileset.png  (Tileset image)
│   │   └── smooth_tileset.tsx  (Tiled tileset)
│   └── maps/
│       ├── smooth_world.tmx    (Tiled map - editable)
│       └── smooth_world.json   (Exported JSON - used in game)
├── src/
│   └── scenes/
│       ├── PreloadScene.js     (Load map & tileset)
│       └── GameScene.js        (Create map)
```

---

## 📚 RESOURCES

- **Tiled Docs:** https://doc.mapeditor.org/
- **Phaser Tilemap:** https://photonstorm.github.io/phaser3-docs/Phaser.Tilemaps.Tilemap.html
- **Tutorial:** https://www.youtube.com/results?search_query=phaser+3+tiled

---

## ⚠️ COMMON ISSUES

### "Tileset not found"
- Check tileset name matches in Tiled and Phaser
- Verify image path in .tmx file

### "Layer not visible"
- Check layer is not hidden in Tiled
- Verify layer name spelling

### "Tiles appearing blocky"
- Don't use pixel art!
- Use smooth painted tiles
- Check tile size is 48x48

---

**Ready to use Tiled for smooth beautiful maps!** 🗺️✨