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

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

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:

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:

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:

this.groundLayer.setCollisionByProperty({ collides: true });
this.physics.add.collider(this.player, this.groundLayer);

Multiple Tilesets

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:

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