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:

bash

# 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:

code

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:

code

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

Creating Corners

code

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:

typescript

// 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

code

{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:

json

{
  "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

json

{
  "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

bash

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

Validate map JSON

bash

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

bash

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

Future Enhancements

Planned features: