track-editor
Reference documentation for the Car Game Track Editor visual design tool.
Install
mkdir -p .claude/skills/track-editor && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/15094" && unzip -o skill.zip -d .claude/skills/track-editor && rm skill.zipInstalls to .claude/skills/track-editor
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Comprehensive documentation for the Car Game Track Editor, a React-based visual track design tool for creating element-based racing tracks.Key capabilities
- →Create, select, move, resize, and rotate track elements
- →Snap elements to a grid and rotate with snapping
- →Auto-expand the canvas as elements approach edges
- →Manage element layers and Z-order
- →Save and load tracks from server storage
- →Implement new element types by defining interfaces and rendering logic
How it works
The skill describes a React-based visual editor that uses an element-based design system, HTML5 Canvas for rendering, and React hooks for state management to allow users to create and manipulate racing tracks.
Inputs & outputs
When to use track-editor
- →Updating track editor components
- →Validating track JSON format
- →Extending element design systems
About this skill
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 segmentsroad_curve- Curved road pieces
Logical Elements (Invisible in Game):
checkpoint- Race progress trackingspawn- Vehicle starting positions
Interactive Elements:
wall- Collision barriersfinish- Race completion lineboost_pad- Speed enhancement zonesoil_slick- Hazard areasramp- 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 studio presets (45°/90° left/right, hairpins, S-bend, custom/straight)
- Cubic Bézier roads with draggable start/end and tangent handles
- Independent road width, red/white kerbs, exact world-coordinate controls
- Curve endpoint snapping with tangent alignment on the current layer
- Legacy quarter-circle conversion to editable curves
- Shared geometry in
shared/utils/roadGeometry.tsfor editor, game and minimap
Large-Track Navigation:
- Viewport-sized canvas, pointer-anchored wheel zoom and Space/middle-drag pan
- Fit track (F), independent grid visibility/snapping and marker visibility
- World/viewport-aware fit and minimum zoom, including large city layouts on mobile
- Collapsible responsive panels, undo/redo and input-safe keyboard shortcuts
Layers & Properties:
- Per-element layer assignment (-1, 0, 1, 2)
- Per-element width/height/position/rotation editing
- Checkpoint ordering controls
- Directional, swept race gates with automatic barrier-to-barrier span (including runoff)
- Race gate inspector with effective width, forward arrows, manual fit, undo and coverage warnings
- Finish markings have independent visible width/offset controls with undo, and are always clipped to same-layer asphalt in the editor, game and minimap
- Dashed cyan guides show hidden grass/runoff detection; fitting barriers preserves marking position/width
npm run tracks:migrate-finishesmigrates every legacy saved finish without changing road layouts or crossing planes- Gate selection matches the rendered span, with screen-space tolerance at city-wide zoom
- Urban Pacific City template with coordinated 220-360-unit roads, grid, checkpoints and barriers
- Shared vector scenery footprints/colors in editor, game and minimap; see track.md for supported types
Persistence & Loading:
- Save and load tracks from server storage
- Track list dialog for quick load/copy/delete
- Searchable/category-filtered picker with 27 templates: 23 F1 venues, three NASCAR speedways and Pacific City; Silverstone is available through Load
- F1 collection covers all 24 announced 2026 venues including Madrid and Barcelona; original arcade interpretations, with a separated Suzuka crossover
- SVG previews reuse road Bezier definitions without constructing full barriers
- Adjustable template road width rebuilds roads, barriers, race markers and an eight-car grid together
- Templates create independent IDs, preserve saved originals and support full-canvas undo/redo
- Template picker traps focus and closes with Escape; save confirmation is inline and load/save failures use dismissible error banners
- Shared construction in
shared/utils/circuitBuilder.tsand definitions inshared/tracks/circuitTemplates.ts npm run tracks:generateregenerates the 27 template JSON files; pass IDs to regenerate selected tracks only, preserving Silverstone and player data
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,
---
*Content truncated.*
When not to use it
- →When the task is not related to the Car Game Track Editor
- →When the focus is on game engine physics integration rather than editor functionality
- →When the task involves collaborative editing or cloud storage integration
Limitations
- →Persistence is limited to local file system via browser APIs
- →Does not include collaborative editing features
- →Does not include cloud storage integration
How it compares
This skill provides a detailed architectural and implementation guide for a specific track editor, offering concrete steps for extending its functionality, unlike general React or canvas documentation.
Compared to similar skills
track-editor side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| track-editor (this skill) | 0 | 9mo | No flags | Advanced |
| scroll-experience | 101 | 9mo | No flags | Intermediate |
| anthropic-frontend-design | 12 | 9mo | No flags | Intermediate |
| infographic-structure-creator | 1 | 8mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
scroll-experience
davila7
Expert in building immersive scroll-driven experiences - parallax storytelling, scroll animations, interactive narratives, and cinematic web experiences. Like NY Times interactives, Apple product pages, and award-winning web experiences. Makes websites feel like experiences, not just pages. Use when: scroll animation, parallax, scroll storytelling, interactive story, cinematic website.
anthropic-frontend-design
chaibuilder
Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
infographic-structure-creator
antvis
Generate or update infographic Structure components for this repo (TypeScript/TSX in src/designs/structures). Use when asked to design, implement, or modify structure layouts (list/compare/sequence/hierarchy/relation/geo/chart), including layout logic, component composition, and registration.
logo-with-variants
crafter-station
Create logo components with multiple variants (icon, wordmark, logo) and light/dark modes. Use when the user provides logo SVG files and wants to create a variant-based logo component following the Clerk pattern in the Elements project.
design-context
WellApp-ai
Refresh UI/UX context from design system, Storybook, and codebase
add-template
TonnyWong1052
Add new UI style template to the ui-style-react project. This skill should be used when users want to add a new style template with HTML/CSS code, create a new preview page, or register a template in the system. Triggers include "add template", "create new style", "add new template", or when users provide HTML code for a new UI style.