name	Map Editor Tool
description	Comprehensive guide for using the visual map editor. Use when designing game worlds, placing buildings, NPCs, or managing map JSON files.

Map Editor Tool

Overview

The Map Editor is a visual tool for designing buildings and placing objects in your Babylon.js game world. It uses a grid-based system where each cell represents 1 unit in the 3D world.

Location: tools/map-editor.html
Access: Open directly in web browser - no server needed!

Getting Started

1. Open the Map Editor

Simply open tools/map-editor.html in your web browser:

# From your project root
open tools/map-editor.html
# or
firefox tools/map-editor.html
# or copy the full path and open in browser
/home/gianfiorenzo/Documents/Vs\ Code/babylon_fp/tools/map-editor.html

2. Using the Tools

Available Tools:

🧱 Wall - Create solid walls for buildings (2 units wide × 1 unit deep × 3 units tall)
⬜ Floor - Create floor tiles (thin, walkable)
🚪 Door - Create doorways (2 units wide × 1 unit deep × 2.2 units tall, interactive in-game)
🪟 Window - Create windows (2 units wide × 1 unit deep × 1.5 units tall)
👤 NPC Spawn - Mark NPC spawn points
🎮 Player Spawn - Mark player spawn points
❌ Erase - Remove tiles

How to Use:

Click a tool button to select it (it will highlight green)
Click on the grid to place tiles
Use the Rotation dropdown or press 'R' to rotate (0°, 90°, 180°, 270°)
Click on existing tiles with the Erase tool to remove them
Hover over the grid to see coordinates

3. Grid System

Grid Size: 100x100 by default (adjustable)
Cell Size: 1 unit per cell
World Size: 100x100 units total
Origin: Center of the grid is world position (0, 0, 0)

Coordinate Conversion:

Grid (50, 50) = World (0, 0) (center)
Grid (0, 0) = World (-50, -50) (top-left corner)
Grid (100, 100) = World (50, 50) (bottom-right corner)

4. Visual Features

Cursor Preview 👁️

Semi-transparent preview of the tile you're about to place
Shows exactly what the tile will look like before clicking
Preview follows your mouse cursor in real-time
Changes instantly when you switch tools or rotation

Orientation Indicators 🧭

All rotatable items show a bright green line on their "front" edge:

Walls, Doors, Windows:

0° (Horizontal): Green line on bottom edge (facing south)
90° (Vertical): Green line on left edge (facing west)
180°: Green line on top edge (facing north)
270°: Green line on right edge (facing east)

NPC & Player Spawns:

Default orientation facing south (down) with green line on bottom

Already-placed tiles show a darker green line (more subtle) to indicate their orientation.

Erase Tool Visual ❌

Shows a red X under cursor when erase tool is selected
Clear visual indication of what will be deleted

5. Building Types

Walls

Default height: 3 units
Blocks player movement
Used for building exteriors and interiors
Rotatable: 0°, 90°, 180°, 270°

Floors

Thin tiles (0.1 units high)
Create interior floors or platforms
Collision enabled
Walkable

Doors

Height: 2.2 units
Width: 1.0 units (can occupy 2 grid units with rotation)
Can be made interactive with the DoorSystem
Initially blocks movement in-game
Rotatable for proper wall orientation

Windows

Placed higher on walls (1.5 units from top)
Semi-transparent
Blocks movement (glass)
Rotatable for proper wall orientation

Spawn Points

Player Spawn: Where the player starts (only one per map)
NPC Spawn: Where NPCs are placed (link to NPC id in JSON)
Include npcId in the JSON to link to specific NPC data

Advanced Features

Drag Painting 🎨

Left-click and drag to paint multiple tiles quickly
Works with: Wall, Floor, Window, and Erase tools
Perfect for creating large areas without clicking repeatedly
Release mouse button to stop painting

NPC Schedule Editor 📅

Automatically opens when you select/place an NPC
Edit waypoint times, positions, and npc type
Add, edit, or remove waypoints
Time validation ensures consistent schedules
Export/import preserves all schedule data

Map Import/Export

Exporting Your Map

Once you've designed your map:

Copy JSON: Copies the map data to your clipboard
Download JSON: Downloads as a .json file
Save the file to /public/data/maps/your_map_name.json

Importing Maps

Click Import JSON button
Select a .json file from your computer
Map and all schedule data are restored
Existing data is replaced

Rotation & Building Walls

Wall Placement

Horizontal Wall (0° or 180°)

Place walls at grid positions with X-spacing of 2:

Grid: (0,0) → (2,0) → (4,0) → (6,0)
World: x=-50, x=-48, x=-46, x=-44

Vertical Wall (90° or 270°)

Place walls at grid positions with Y-spacing of 2:

Grid: (0,0) → (0,2) → (0,4) → (0,6)
World: z=-50, z=-48, z=-46, z=-44

Creating Corners

Horizontal wall at (0,0) rotation=0°
Vertical wall at (0,0) rotation=90°
Creates an L-shaped corner

How Rotation Works

0°: Horizontal (default) - 2 units wide along X-axis, 1 unit deep along Z-axis
90°: Vertical - 1 unit wide along X-axis, 2 units deep along Z-axis
180°: Horizontal (flipped)
270°: Vertical (flipped)

Loading Maps in Game

To load your map in the game:

Save your JSON file to /public/data/maps/
In src/Game.ts, uncomment and modify the map loading line:

// In the init() method
await this.mapBuilder.loadMapFromFile('/data/maps/your_map_name.json');

Tips for Organization

Version Control

Save maps as JSON files in /public/data/maps/
Commit maps to git for team collaboration
Use descriptive filenames

Map Organization

Create separate maps for different areas:

town_center.json - Main plaza
residential_01.json - House group 1
bakery.json - Bakery building
police_station.json - Police station

Naming Conventions

{area}_{building_type}_{variant}.json

Examples:
- downtown_shop_general.json
- downtown_shop_bakery.json
- residential_house_01.json
- plaza_fountain.json

Map Metadata

Include metadata in your maps:

{
  "metadata": {
    "gridSize": 100,
    "cellSize": 1,
    "worldSize": 100,
    "version": "1.0.0",
    "description": "Town bakery - single story building",
    "author": "Your Name",
    "created": "2025-10-15"
  },
  "tiles": [...],
  "spawns": [...],
  "schedules": [...]
}

JSON Structure

Complete Map Format

{
  "metadata": {
    "gridSize": 100,
    "cellSize": 1,
    "description": "Bakery"
  },
  "tiles": [
    {
      "gridX": 10,
      "gridY": 15,
      "type": "wall",
      "rotation": 0
    }
  ],
  "spawns": [
    {
      "gridX": 20,
      "gridY": 25,
      "type": "npcSpawn",
      "npcId": "baker"
    }
  ],
  "schedules": [
    {
      "npcId": "baker",
      "waypoints": [
        {"time": "06:00", "gridX": 20, "gridY": 25},
        {"time": "09:00", "gridX": 15, "gridY": 20}
      ]
    }
  ]
}

Advanced Usage

Multi-Story Buildings

To create multi-story buildings:

Create multiple floor plans as separate map files
Load them with different Y offsets in code
Or modify positions before building in code

Complex Structures

For complex buildings:

Start with the outer walls
Add interior walls to create rooms
Place floors
Add doors and windows
Mark spawn points for NPCs

Performance Tips

Keep maps under 500 tiles for best performance
Use floor tiles sparingly (they add geometry)
Group related structures in separate map files
Reuse maps with position offsets for similar buildings

Example Workflow

Sketch: Draw your building layout on paper
Design: Open map editor and create the structure
Place NPCs: Click NPC Spawn, edit schedule in modal
Export: Download JSON file
Save: Move to /public/data/maps/
Test: Load in game and walk through
Iterate: Adjust and refine
Commit: Save to version control

Troubleshooting

Map doesn't load in game:

Check browser console for errors
Verify JSON syntax is valid
Ensure file path in Game.ts is correct
Check the file exists in /public/data/maps/

Walls overlap or look wrong:

Remember spacing: horizontal walls use X-spacing of 2, vertical use Y-spacing of 2
Check grid coordinates vs world coordinates
Verify rotation settings (green line should face outward)

Player gets stuck:

Add doors where needed
Check for overlapping collision geometry
Verify spawn points are in valid, open locations

Schedule editor not showing:

Make sure you've selected an NPC spawn point
Click on the NPC spawn to select it
The editor should appear automatically

Keyboard Shortcuts

R - Rotate selected tool by 90°
E - Select Erase tool
D - Select Floor tool
W - Select Wall tool

Development Commands

List all maps

ls -1 /home/gianfiorenzo/Documents/Vs\ Code/babylon_fp/public/data/maps/*.json

Validate map JSON

cd /home/gianfiorenzo/Documents/Vs\ Code/babylon_fp
for f in public/data/maps/*.json; do
  echo "Checking $f..."
  node -e "JSON.parse(require('fs').readFileSync('$f'))" && echo "✓ Valid"
done

Count buildings in a map

cd /home/gianfiorenzo/Documents/Vs\ Code/babylon_fp
cat public/data/maps/example.json | grep -c '"type"'

Future Enhancements

Planned features:

Undo/Redo functionality
Copy/Paste regions
Prefab buildings (templates)
Height adjustments
Texture selection
3D preview panel
Multi-map management
Collision layer visualization

Install Skill

SKILL.md