name: track-editor description: Comprehensive documentation for the Car Game Track Editor, a React-based visual track design tool for creating element-based racing tracks.

Track Editor Skill

This skill provides comprehensive expertise in developing and maintaining the Car Game Track Editor, a React-based visual track design tool that creates element-based racing tracks.

Overview

The Track Editor is a sophisticated drag-and-drop interface that allows users to create custom racing tracks using a modern element-based system. It provides real-time visual feedback, validation, and supports both creation and editing of track layouts.

Reference Documentation

Primary Reference: track.md - Complete track data structure specification

The track.md file serves as the canonical reference for:

Track JSON format validation
Element type definitions and properties
Required elements for valid tracks
Best practices for track design

Core Architecture

File Structure

client/src/screens/
├── TrackEditor.tsx      # Main editor component
├── TrackEditor.css      # Editor styling
└── components/          # Reusable editor components

Technology Stack

Frontend: React 18 with TypeScript
State Management: React hooks (useState, useEffect, useRef)
Canvas: HTML5 Canvas for track rendering
Persistence: Local file system via browser APIs
Validation: Shared validation utilities from @shared

Key Features

1. Element-Based Design System

The editor uses a modern element system where all track components are unified elements with common properties:

interface TrackElement {
  id: string;
  type: ElementType;
  x: number;
  y: number;
  position: { x: number; y: number };
  width: number;
  height: number;
  rotation: number;
  layer: number;
  // Type-specific properties...
}

2. Visual Element Library

Road Elements:

road - Straight road segments
road_curve - Curved road pieces

Logical Elements (Invisible in Game):

checkpoint - Race progress tracking
spawn - Vehicle starting positions

Interactive Elements:

wall - Collision barriers
finish - Race completion line
boost_pad - Speed enhancement zones
oil_slick - Hazard areas
ramp - Jump elements

3. Canvas Management Features

Selection System:

Click to select individual elements
Canvas selection shows track dimensions
Multi-element operations support

Auto-Expand Canvas:

Optional automatic canvas expansion
Maintains elements within bounds
Configurable via left panel checkbox

Grid System:

Snap-to-grid functionality
Rotation snapping for precise alignment
Configurable grid spacing

4. Element Manipulation

Placement:

Drag-and-drop from element palette
Position validation and snapping
Real-time visual feedback

Editing:

In-place resizing with handles
Rotation controls with grid snapping
Property panels for detailed editing

Organization:

Layer-based rendering system
Z-order management
Element grouping capabilities

Supported Capabilities (Current Implementation)

Core Editing:

Create, select, move, resize, and rotate elements on a canvas
Snap-to-grid positioning and rotation snapping
Auto-expand canvas as elements approach edges (optional)
Hide other layers for focused editing (optional)
Canvas selection for editing track dimensions

Selection & Workflow:

Single selection and multi-select (Ctrl+click)
Drag-and-drop movement for selected elements
Undo support (Ctrl+Z + UI button)
Tool pinning (double-click tool to keep it active)
Keyboard shortcuts for tools (1-9, 0)

Element Ordering:

Bring to Front / Send to Back for selected elements
Duplicate and delete selected elements

Curve System:

Curve preset library (45°/90° left/right)
Custom curve drawing mode
Curve auto-snapping to nearby road endpoints

Layers & Properties:

Per-element layer assignment (-1, 0, 1, 2)
Per-element width/height/position/rotation editing
Checkpoint ordering controls

Persistence & Loading:

Save and load tracks from server storage
Track list dialog for quick load/copy/delete

UI/UX:

Collapsible left/right panels with resize handles
Visual tool icons and tool hints
Properties panel for selected elements

Implementation Guide

Adding New Element Types

Define Element Interface (in shared types):

// shared/types/track.ts
export interface NewElementProperties extends TrackElementProperties {
  customProperty: string;
}

Update Element Type Union:

type ElementType = 'road' | 'wall' | ... | 'new_element';

Add to Element Palette (TrackEditor.tsx):

const elementTypes = [
  // ... existing elements
  {
    type: 'new_element' as const,
    name: 'New Element',
    icon: '🆕',
    defaultWidth: 100,
    defaultHeight: 100,
    color: '#ff5722'
  }
];

Implement Rendering (TrackEditor.tsx):

// In drawElement function
case 'new_element':
  ctx.fillStyle = '#ff5722';
  ctx.fillRect(x, y, width, height);
  // Add custom rendering logic
  break;

Add Game Renderer Support (GameRenderer.tsx):

// In element rendering switch
case 'new_element': {
  // Implement PIXI.js rendering
  break;
}

Update Validation (shared/utils/validation.ts):

// Add validation rules for new element

Canvas Interaction Patterns

Mouse Event Handling:

const handleCanvasMouseDown = (e: MouseEvent) => {
  const rect = canvasRef.current!.getBoundingClientRect();
  const x = e.clientX - rect.left;
  const y = e.clientY - rect.top;
  
  // Hit testing logic
  // Selection logic
  // Drag initiation
};

Selection Management:

const [selectedElement, setSelectedElement] = useState<string | null>(null);
const [selectedType, setSelectedType] = useState<'element' | 'canvas'>('element');
 
// Selection state determines UI behavior

Canvas Auto-Expansion:

const [autoExpand, setAutoExpand] = useState(false);
 
useEffect(() => {
  if (autoExpand) {
    // Calculate required canvas size
    // Update track dimensions
    // Preserve element positions
  }
}, [elements, autoExpand]);

Track Validation Integration

Real-Time Validation

The editor implements continuous validation using the shared validation utilities:

import { validateTrack } from '@shared';
 
const validateCurrentTrack = () => {
  const result = validateTrack(currentTrack);
  setValidationErrors(result.errors);
  setIsValid(result.isValid);
};
 
useEffect(validateCurrentTrack, [elements]);

Validation Feedback

Error Display:

Visual indicators on invalid elements
Detailed error messages in validation panel
Save prevention for invalid tracks

Required Element Checking:

Checkpoint sequence validation
Spawn point requirement checking
Minimum road surface verification

Grid and Snapping System

Grid Configuration

const GRID_SIZE = 20; // pixels
const SNAP_THRESHOLD = 10; // pixels
const ROTATION_SNAP = Math.PI / 8; // 22.5 degrees

Snapping Logic

const snapToGrid = (value: number): number => {
  return Math.round(value / GRID_SIZE) * GRID_SIZE;
};
 
const snapRotation = (rotation: number): number => {
  return Math.round(rotation / ROTATION_SNAP) * ROTATION_SNAP;
};

Save/Load System

Track Serialization

const saveTrack = () => {
  const trackData = {
    id: trackId,
    name: trackName,
    width: canvasWidth,
    height: canvasHeight,
    elements: elements,
    // ... other metadata
  };
  
  // Validation before save
  const validation = validateTrack(trackData);
  if (!validation.isValid) {
    showValidationErrors(validation.errors);
    return;
  }
  
  // File save logic
};

Track Loading

const loadTrack = async (file: File) => {
  const content = await file.text();
  const trackData = JSON.parse(content);
  
  // Validate loaded data
  const validation = validateTrack(trackData);
  if (!validation.isValid) {
    throw new Error('Invalid track file');
  }
  
  // Update editor state
  setElements(trackData.elements);
  setCanvasWidth(trackData.width);
  setCanvasHeight(trackData.height);
};