NPC Face Editor

Overview

The NPC Face Editor allows you to create custom pixel art faces for your NPCs. Each NPC can have a unique face that will be displayed in-game on a 128x128 texture.

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

Features

Drawing Canvas

• 512x512 Editor Canvas: Large canvas for easy pixel art creation
• 128x128 Preview: Real-time preview of how the face will look in-game
• Pixelated Rendering: Sharp, retro pixel art aesthetic

Drawing Tools

1. Draw Tool (✏️)

• Default tool for drawing pixels
• Use selected color and brush size
• Click and drag to draw

2. Erase Tool (🧹)

• Removes pixels by painting with the NPC's skin color
• Same brush size controls as draw tool
• Useful for fixing mistakes

3. Fill Tool (🪣)

• Flood fill an area with selected color
• Click on any region to fill all connected pixels of the same color
• Great for filling large areas quickly

4. Eyedropper Tool (💧)

• Pick colors from the canvas
• Click any pixel to select its color
• Useful for matching existing colors

Brush Sizes

Four square brush sizes available:

• 1x1: Single pixel precision
• 2x2: Small square brush
• 8x8: Large square brush for quick coverage
• 16x16: XL square brush (same size as default face eye)

Color Palette

Preset Colors

12 pre-selected colors optimized for NPC faces:

• Black (#000000) - Eyes, outlines
• White (#FFFFFF) - Eyes, teeth
• Brown (#8B4513) - Hair, eyebrows
• Blue (#4169E1) - Eyes
• Green (#228B22) - Eyes
• Red (#FF0000) - Blush, details
• Gold (#FFD700) - Jewelry, decorations
• Pink (#FF69B4) - Blush, lips
• Gray (#808080) - Beards, shadows
• Sienna (#A0522D) - Dark hair
• Tan (#DEB887) - Light skin tones
• Purple (#9370DB) - Mystical effects

Custom Color Picker

• Full color picker for any hex color
• Located below the preset palette
• Selected color is automatically used for drawing

Quick Actions

Clear (🗑️)

• Clears the entire canvas
• Fills with NPC's skin color
• Use this to start fresh

Default Face (😊)

• Loads the default hard-coded face
• Features: Simple eyes, nose, and mouth
• Good starting point for customization

Workflow

Creating a New Face

1. Open NPC Editor (tools/npc-editor.html)
2. Select an NPC from the list
3. Click "✏️ Edit Face" button
4. Draw your face:
   • Start with the Default Face button for a template
   • Or clear and draw from scratch
   • Use different tools and brush sizes as needed
5. Preview your work in the 128x128 preview box
6. Save when satisfied

Editing an Existing Face

1. Open the Face Editor for an NPC with a saved face
2. The existing face will load automatically
3. Make your changes
4. Save to update

Best Practices

Resolution Awareness

• Editor is 512x512, but game uses 128x128
• What looks smooth at 512px may look blocky at 128px
• Check the preview frequently! This is how it will appear in-game

Design Tips

• Keep it simple: Small details may not be visible at 128x128
• Use contrast: High contrast features read better at low resolution
• Symmetry: Most faces look better when symmetrical
• Reference the default: The default face is well-proportioned for the 128px resolution
• Test in-game: Load the NPC in-game to see the actual result

Color Choices

• Skin tones are inherited from NPC's base color
• Use darker shades for depth (eyebrows, shadows)
• Use lighter shades for highlights
• Black and white work well for high contrast features
• Consider which colors contrast with the NPC's shirt color

Technical Details

Data Storage

Format

Faces are stored as Base64-encoded PNG data URLs:

{
  "id": "baker",
  "name": "Baker",
  "faceData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Size Considerations

• Base64 PNG data is quite large (10-30KB per face)
• Stored in localStorage and JSON export
• Included in full NPC collection exports
• ~100-200 custom faces should fit comfortably in localStorage

In-Game Rendering

Texture Application

1. Game loads NPC definition with faceData
2. Creates 128x128 DynamicTexture
3. Loads face from data URL into texture
4. Applies texture to face plane mesh
5. Face plane is positioned slightly in front of head cube

Fallback Behavior

• If faceData is not provided: Uses default hard-coded face
• If faceData fails to load: Falls back to default face with console warning
• Default face: Simple eyes, nose, and mouth in NPC's skin color

Canvas Details

• Editor Canvas: 512x512 pixels for ease of editing
• Game Texture: 128x128 pixels for performance
• Downscaling: Automatic when saving/previewing
• Image Format: PNG via canvas.toDataURL()

Integration with Game

Schema Support

The NpcDefinition schema includes optional faceData:

interface NpcDefinition {
  id: string;
  name: string;
  color: [number, number, number];      // RGB 0-1
  shirtColor?: [number, number, number];
  pantsColor?: [number, number, number];
  faceData?: string;                    // Base64 PNG data URL
  speed?: number;
  schedule?: Waypoint[];
  hasHat?: boolean;
}

NPC System

The NPC class constructor accepts faceData in options:

const npc = new NPC(scene, name, schedule, {
  color: skinColor,
  shirtColor: shirtColor,
  pantsColor: pantsColor,
  faceData: "data:image/png;base64,..." // Optional
});

Loading Process

1. Game.ts loads NPC definitions from JSON
2. Extracts faceData if present
3. Passes to NpcSystem.createNpc()
4. NPC constructor stores faceData
5. buildMinecraftStyleNPC() creates face texture
6. Custom face loaded or default face created

Export and Import

Exporting NPCs with Faces

When you export NPCs from the NPC Editor:

[
  {
    "id": "custom_npc",
    "name": "Custom NPC",
    "color": [0.9, 0.7, 0.5],
    "shirtColor": [0.87, 0.72, 0.53],
    "pantsColor": [0.55, 0.27, 0.07],
    "faceData": "data:image/png;base64,...",
    "speed": 1.4,
    "schedule": [...],
    "metadata": {}
  }
]

Importing

• Face data is preserved during import
• Compatible with both individual files and collection format
• Face images will load in-game automatically

Troubleshooting

Face Not Showing in Game

• Check console: Look for load errors (F12 → Console)
• Verify faceData: Ensure it's a valid data URL
• Check format: Should start with "data:image/png;base64,"
• Browser compatibility: Ensure browser supports data URLs
• Test with default face: Try resetting to default to isolate issue

Face Looks Blurry or Distorted

• This is expected at 128x128 - texture is very small
• Keep designs simple and high-contrast
• Avoid very thin lines (they won't show)
• Test in-game to see actual appearance

Face Editor Not Opening

• Check browser console for errors (F12)
• Ensure you're clicking "Edit Face" button
• Try refreshing the page
• Clear browser cache if persisting
• Make sure NPC editor is open and NPC is selected

Changes Not Saving

• Ensure you click "💾 Save Face" button
• Check localStorage isn't full (clear old data if needed)
• Verify NPC list updates after save
• Export NPCs to verify faceData is included
• Check browser console for any save errors

Face Data Too Large

• If faceData exceeds localStorage limits:
  1. Delete older/unused face data
  2. Export and backup important NPCs
  3. Clear local cache: Settings → Site Data → Clear
  4. Create simpler faces (fewer colors/details)

Performance Considerations

Memory Usage

• Each custom face: ~10-30KB of data
• Stored in localStorage (typically 5-10MB limit)
• ~100-200 custom faces should fit comfortably
• Consider exporting and clearing if running low on space

Loading Time

• Face images load asynchronously
• No blocking of main thread
• Minimal performance impact
• Default face shown if custom face fails to load

In-Game Performance

• 128x128 textures are very lightweight
• No impact on frame rate
• Standard Babylon.js texture management
• Efficiently cached by GPU
• Multiple NPCs can have custom faces without issue

Development Commands

Export all NPC faces

cd /home/gianfiorenzo/Documents/Vs\ Code/babylon_fp
cat public/data/npcs/*.json | grep faceData | wc -l

Check face data validity

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

Remove all face data (reset)

cd /home/gianfiorenzo/Documents/Vs\ Code/babylon_fp
# Backup first!
cp public/data/npcs/*.json public/data/npcs/backup/
# Then modify to remove faceData fields

Verify PNG encoding

cd /home/gianfiorenzo/Documents/Vs\ Code/babylon_fp
# Check if face data starts with correct PNG data URL prefix
grep -o '"faceData": "data:image/png;base64,[^"]*"' public/data/npcs/*.json | head -1

Keyboard Shortcuts

Currently the Face Editor uses mouse-only controls. Potential future shortcuts:

• D - Draw tool
• E - Erase tool
• F - Fill tool
• I - Eyedropper
• [ / ] - Decrease/increase brush size
• Ctrl+Z - Undo (not yet implemented)
• Space - Pan canvas (not yet implemented)

Future Enhancements

Potential improvements for future versions:

• Undo/Redo history
• Layer system for organization
• Animation frames for expressions
• Face templates/presets
• Import/export individual faces
• Symmetry tool for better proportions
• Grid overlay for alignment
• Zoom and pan for detail work
• Animation system for animated expressions
• Facial expression presets (happy, sad, angry, etc.)