Builder Ux

{
  "name": "builder-ux",
  "description": "Builder user experience systems for Three.js building games. Use when implementing prefab/blueprint save/load, undo/redo command patterns, ghost preview placement, multi-select, or copy/paste building mechanics.",
  "tags": [
    "building-game",
    "ui-design",
    "code-generation"
  ],
  "sub_skills": [],
  "source": "claude-user",
  "type": "template",
  "depends_on": [],
  "enhances": [
    "3d-building-advanced",
    "structural-physics",
    "multiplayer-building"
  ],
  "last_reviewed_at": "2026-05-26",
  "review_score": 72,
  "relevance_tier": "B"
}

/**
 * BlueprintManager - Save, load, and share building designs
 * 
 * Serializes building structures into portable blueprints that can be
 * saved, shared, and placed elsewhere. Used in games like Rust, 
 * Satisfactory, and No Man's Sky for building prefabs.
 * 
 * Usage:
 *   const blueprints = new BlueprintManager();
 *   const { blueprint } = blueprints.save(selectedPieces, 'My Base');
 *   const { pieces } = blueprints.load(blueprint.id, newPosition);
 */

import * as THREE from 'three';

/**
 * Blueprint format version for compatibility
 */
export const BLUEPRINT_VERSION = 1;

/**
 * Blueprint validation result
 * @typedef {Object} ValidationResult
 * @property {boolean} valid - Whether blueprint is valid
 * @property {Array} errors - List of validation errors
 * @property {Array} warnings - List of warnings
 */

export class BlueprintManager {
  /**
   * Create blueprint manager
   * @param {Object} options - Configuration options
   */
  constructor(options = {}) {
    this.blueprints = new Map();
    this.maxBlueprints = options.maxBlueprints ?? 100;
    this.maxPiecesPerBlueprint = options.maxPiecesPerBlueprint ?? 500;
    
    // Storage backend
    this.storage = options.storage ?? null;
    this.storageKey = options.storageKey ?? 'building_blueprints';
    
    // Thumbnail generation
    this.thumbnailEnabled = options.thumbnailEnabled ?? true;
    this.thumbnailSize = options.thumbnailSize ?? 128;
    
    // Event callbacks
    this.onSave = options.onSave ?? null;
    this.onLoad = options.onLoad ?? null;
    this.onDelete = options.onDelete ?? null;
    
    // Load existing blueprints from storage
    if (this.storage) {
      this.loadFromStorage();
    }
  }

  /**
   * Save pieces as a blueprint
   * @param {Array} pieces - Building pieces to save
   * @param {string} name - Blueprint name
   * @param {Object} metadata - Additional metadata
   * @returns {Object} Save result with blueprint
   */
  save(pieces, name, metadata = {}) {
    // Validation
    if (!pieces || pieces.length === 0) {
      return { success: false, reason: 'No pieces provided' };
    }
    
    if (pieces.length > this.maxPiecesPerBlueprint) {
      return { 
        success: false, 
        reason: `Exceeds maximum pieces (${this.maxPiecesPerBlueprint})` 
      };
    }
    
    if (this.blueprints.size >= this.maxBlueprints) {
      return { 
        success: false, 
        reason: `Blueprint limit reached (${this.maxBlueprints})` 
      };
    }

    // Calculate bounds and origin
    const bounds = this.calculateBounds(pieces);
    const origin = this.calculateOrigin(bounds);

    // Convert pieces to relative coordinates
    const blueprintPieces = pieces.map(piece => this.serializePiece(piece, origin));

    // Adjust bounds to be relative
    const relativeBounds = {
      min: {
        x: bounds.min.x - origin.x,
        y: bounds.min.y - origin.y,
        z: bounds.min.z - origin.z
      },
      max: {
        x: bounds.max.x - origin.x,
        y: bounds.max.y - origin.y,
        z: bounds.max.z - origin.z
      }
    };

    // Create blueprint object
    const blueprint = {
      id: this.generateId(),
      version: BLUEPRINT_VERSION,
      name: name || 'Untitled Blueprint',
      created: Date.now(),
      modified: Date.now(),
      bounds: relativeBounds,
      size: {
        x: relativeBounds.max.x - relativeBounds.min.x,
        y: relativeBounds.max.y - relativeBounds.min.y,
        z: relativeBounds.max.z - relativeBounds.min.z
      },
      pieces: blueprintPieces,
      metadata: {
        author: metadata.author ?? 'Unknown',
        description: metadata.description ?? '',
        tags: metadata.tags ?? [],
        pieceCount: pieces.length,
        materialCounts: this.countMaterials(pieces),
        thumbnail: null
      }
    };

    // Store blueprint
    this.blueprints.set(blueprint.id, blueprint);
    
    // Persist to storage
    this.persistBlueprint(blueprint);

    // Callback
    if (this.onSave) {
      this.onSave(blueprint);
    }

    return { success: true, blueprint };
  }

  /**
   * Load blueprint and generate pieces at position
   * @param {string} blueprintId - Blueprint to load
   * @param {THREE.Vector3} position - World position to place at
   * @param {number} rotation - Y-axis rotation in radians
   * @returns {Object} Load result with pieces array
   */
  load(blueprintId, position, rotation = 0) {
    const blueprint = this.blueprints.get(blueprintId);
    
    if (!blueprint) {
      return { success: false, reason: 'Blueprint not found' };
    }

    // Validate version compatibility
    if (blueprint.version > BLUEPRINT_VERSION) {
      return { 
        success: false, 
        reason: `Blueprint version ${blueprint.version} not supported` 
      };
    }

    // Generate pieces with world positions
    const pieces = blueprint.pieces.map(piece => 
      this.deserializePiece(piece, position, rotation)
    );

    // Update last used time
    blueprint.metadata.lastUsed = Date.now();
    this.persistBlueprint(blueprint);

    // Callback
    if (this.onLoad) {
      this.onLoad(blueprint, pieces);
    }

    return { success: true, pieces, blueprint };
  }

  /**
   * Preview blueprint without placing (for ghost display)
   * @param {string} blueprintId - Blueprint to preview
   * @param {THREE.Vector3} position - Preview position
   * @param {number} rotation - Y-axis rotation
   * @returns {Object} Preview data
   */
  preview(blueprintId, position, rotation = 0) {
    const result = this.load(blueprintId, position, rotation);
    
    if (result.success) {
      return {
        success: true,
        pieces: result.pieces,
        bounds: this.getTransformedBounds(result.blueprint, position, rotation)
      };
    }
    
    return result;
  }

  /**
   * Get blueprint by ID
   * @param {string} blueprintId - Blueprint ID
   * @returns {Object|null} Blueprint or null
   */
  get(blueprintId) {
    return this.blueprints.get(blueprintId) ?? null;
  }

  /**
   * Delete a blueprint
   * @param {string} blueprintId - Blueprint to delete
   * @returns {Object} Delete result
   */
  delete(blueprintId) {
    const blueprint = this.blueprints.get(blueprintId);
    
    if (!blueprint) {
      return { success: false, reason: 'Blueprint not found' };
    }
    
    this.blueprints.delete(blueprintId);
    this.removeFromStorage(blueprintId);
    
    if (this.onDelete) {
      this.onDelete(blueprint);
    }
    
    return { success: true };
  }

  /**
   * Rename a blueprint
   * @param {string} blueprintId - Blueprint to rename
   * @param {string} newName - New name
   * @returns {Object} Rename result
   */
  rename(blueprintId, newName) {
    const blueprint = this.blueprints.get(blueprintId);
    
    if (!blueprint) {
      return { success: false, reason: 'Blueprint not found' };
    }
    
    blueprint.name = newName;
    blueprint.modified = Date.now();
    this.persistBlueprint(blueprint);
    
    return { success: true, blueprint };
  }

  /**
   * Update blueprint metadata
   * @param {string} blueprintId - Blueprint to update
   * @param {Object} updates - Metadata updates
   * @returns {Object} Update result
   */
  updateMetadata(blueprintId, updates) {
    const blueprint = this.blueprints.get(blueprintId);
    
    if (!blueprint) {
      return { success: false, reason: 'Blueprint not found' };
    }
    
    Object.assign(blueprint.metadata, updates);
    blueprint.modified = Date.now();
    this.persistBlueprint(blueprint);
    
    return { success: true, blueprint };
  }

  /**
   * List all blueprints
   * @param {Object} options - Filter and sort options
   * @returns {Array} Blueprint summaries
   */
  list(options = {}) {
    let blueprints = Array.from(this.blueprints.values());
    
    // Filter by tag
    if (options.tag) {
      blueprints = blueprints.filter(bp => 
        bp.metadata.tags.includes(options.tag)
      );
    }
    
    // Filter by search term
    if (options.search) {
      const term = options.search.toLowerCase();
      blueprints = blueprints.filter(bp => 
        bp.name.toLowerCase().includes(term) ||
        bp.metadata.description.toLowerCase().includes(term)
      );
    }
    
    // Sort
    const sortField = options.sortBy ?? 'modified';
    const sortDir = options.sortDir ?? 'desc';
    
    blueprints.sort((a, b) => {
      let aVal = sortField === 'name' ? a.name : a[sortField];
      let bVal = sortField === 'name' ? b.name : b[sortField];
      
      if (typeof aVal === 'string') {
        aVal = aVal.toLowerCase();
        bVal = bVal.toLowerCase();
      }
      
      const comparison = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
      return sortDir === 'desc' ? -comparison : comparison;
    });
    
    // Return summaries
    return blueprints.map(bp => ({
      id: bp.id,
      name: bp.name,
      pieceCount: bp.metadata.pieceCount,
      size: bp.size,
      tags: bp.metadata.tags,
      created: bp.created,
      modified: bp.modified,
      thumbnail: bp.metadata.thumbnail
    }));
  }

  /**
   * Export blueprint as JSON string
   * @param {string} blueprintId - Blueprint to export
   * @returns {string|null} JSON string or null
   */
  export(blueprintId) {
    const blueprint = this.blueprints.get(blueprintId);
    
    if (!blueprint) return null;
    
    // Create export copy without internal fields
    const exportData = {
      ...blueprint,
      exportedAt: Date.now(),
      exportVersion: BLUEPRINT_VERSION
    };
    
    return JSON.stringify(exportData, null, 2);
  }

  /**
   * Import blueprint from JSON string
   * @param {string} jsonString - JSON blueprint data
   * @returns {Object} Import result
   */
  import(jsonString) {
    try {
      const data = JSON.parse(jsonString);
      
      // Validate structure
      const validation = this.validateBlueprint(data);
      if (!validation.valid) {
        return { 
          success: false, 
          reason: 'Invalid blueprint format',
          errors: validation.errors 
        };
      }
      
      // Generate new ID to avoid conflicts
      const blueprint = {
        ...data,
        id: this.generateId(),
        imported: true,
        importedAt: Date.now(),
        modified: Date.now()
      };
      
      // Store
      this.blueprints.set(blueprint.id, blueprint);
      this.persistBlueprint(blueprint);
      
      return { success: true, blueprint };
      
    } catch (e) {
      return { success: false, reason: `Parse error: ${e.message}` };
    }
  }

  /**
   * Validate blueprint structure
   * @param {Object} data - Blueprint data to validate
   * @returns {ValidationResult} Validation result
   */
  validateBlueprint(data) {
    const errors = [];
    const warnings = [];
    
    // Required fields
    if (!data.pieces || !Array.isArray(data.pieces)) {
      errors.push('Missing or invalid pieces array');
    }
    
    if (!data.name) {
      warnings.push('Missing name, will use default');
    }
    
    // Version check
    if (data.version && data.version > BLUEPRINT_VERSION) {
      errors.push(`Unsupported version: ${data.version}`);
    }
    
    // Piece validation
    if (data.pieces) {
      for (let i = 0; i < data.pieces.length; i++) {
        const piece = data.pieces[i];
        
        if (!piece.type) {
          errors.push(`Piece ${i}: missing type`);
        }
        
        if (!piece.localPosition) {
          errors.push(`Piece ${i}: missing localPosition`);
        }
      }
      
      if (data.pieces.length > this.maxPiecesPerBlueprint) {
        errors.push(`Too many pieces: ${data.pieces.length} (max: ${this.maxPiecesPerBlueprint})`);
      }
    }
    
    return {
      valid: errors.length === 0,
      errors,
      warnings
    };
  }

  /**
   * Duplicate a blueprint
   * @param {string} blueprintId - Blueprint to duplicate
   * @param {string} newName - Name for duplicate
   * @returns {Object} Duplicate result
   */
  duplicate(blueprintId, newName) {
    const original = this.blueprints.get(blueprintId);
    
    if (!original) {
      return { success: false, reason: 'Blueprint not found' };
    }
    
    const duplicate = {
      ...JSON.parse(JSON.stringify(original)),
      id: this.generateId(),
      name: newName || `${original.name} (Copy)`,
      created: Date.now(),
      modified: Date.now()
    };
    
    this.blueprints.set(duplicate.id, duplicate);
    this.persistBlueprint(duplicate);
    
    return { success: true, blueprint: duplicate };
  }

  /**
   * Calculate bounding box of pieces
   */
  calculateBounds(pieces) {
    const min = new THREE.Vector3(Infinity, Infinity, Infinity);
    const max = new THREE.Vector3(-Infinity, -Infinity, -Infinity);
    
    for (const piece of pieces) {
      const pos = piece.position;
      min.x = Math.min(min.x, pos.x);
      min.y = Math.min(min.y, pos.y);
      min.z = Math.min(min.z, pos.z);
      max.x = Math.max(max.x, pos.x);
      max.y = Math.max(max.y, pos.y);
      max.z = Math.max(max.z, pos.z);
    }
    
    return { min, max };
  }

  /**
   * Calculate blueprint origin (center bottom)
   */
  calculateOrigin(bounds) {
    return new THREE.Vector3(
      (bounds.min.x + bounds.max.x) / 2,
      bounds.min.y, // Keep Y at base
      (bounds.min.z + bounds.max.z) / 2
    );
  }

  /**
   * Serialize a piece for storage
   */
  serializePiece(piece, origin) {
    return {
      type: piece.type,
      localPosition: {
        x: piece.position.x - origin.x,
        y: piece.position.y - origin.y,
        z: piece.position.z - origin.z
      },
      rotation: {
        x: piece.rotation?.x ?? 0,
        y: piece.rotation?.y ?? 0,
        z: piece.rotation?.z ?? 0
      },
      material: piece.material?.name ?? 'wood',
      variant: piece.variant ?? null,
      customData: piece.customData ?? null
    };
  }

  /**
   * Deserialize a piece to world coordinates
   */
  deserializePiece(piece, worldOrigin, rotation) {
    // Rotate local position around Y axis
    const cos = Math.cos(rotation);
    const sin = Math.sin(rotation);
    
    const rotatedX = piece.localPosition.x * cos - piece.localPosition.z * sin;
    const rotatedZ = piece.localPosition.x * sin + piece.localPosition.z * cos;
    
    return {
      type: piece.type,
      position: new THREE.Vector3(
        worldOrigin.x + rotatedX,
        worldOrigin.y + piece.localPosition.y,
        worldOrigin.z + rotatedZ
      ),
      rotation: new THREE.Euler(
        piece.rotation.x,
        piece.rotation.y + rotation,
        piece.rotation.z
      ),
      material: { name: piece.material },
      variant: piece.variant,
      customData: piece.customData
    };
  }

  /**
   * Get transformed bounds for a blueprint placement
   */
  getTransformedBounds(blueprint, position, rotation) {
    const cos = Math.cos(rotation);
    const sin = Math.sin(rotation);
    const bounds = blueprint.bounds;
    
    // Rotate corners
    const corners = [
      { x: bounds.min.x, z: bounds.min.z },
      { x: bounds.max.x, z: bounds.min.z },
      { x: bounds.max.x, z: bounds.max.z },
      { x: bounds.min.x, z: bounds.max.z }
    ];
    
    const transformed = corners.map(c => ({
      x: position.x + (c.x * cos - c.z * sin),
      z: position.z + (c.x * sin + c.z * cos)
    }));
    
    return {
      min: {
        x: Math.min(...transformed.map(c => c.x)),
        y: position.y + bounds.min.y,
        z: Math.min(...transformed.map(c => c.z))
      },
      max: {
        x: Math.max(...transformed.map(c => c.x)),
        y: position.y + bounds.max.y,
        z: Math.max(...transformed.map(c => c.z))
      }
    };
  }

  /**
   * Count materials in piece collection
   */
  countMaterials(pieces) {
    const counts = {};
    
    for (const piece of pieces) {
      const material = piece.material?.name ?? 'unknown';
      counts[material] = (counts[material] ?? 0) + 1;
    }
    
    return counts;
  }

  /**
   * Generate unique ID
   */
  generateId() {
    const timestamp = Date.now().toString(36);
    const random = Math.random().toString(36).substr(2, 8);
    return `bp_${timestamp}_${random}`;
  }

  /**
   * Persist blueprint to storage
   */
  persistBlueprint(blueprint) {
    if (!this.storage) return;
    
    try {
      const all = JSON.parse(this.storage.getItem(this.storageKey) || '{}');
      all[blueprint.id] = blueprint;
      this.storage.setItem(this.storageKey, JSON.stringify(all));
    } catch (e) {
      console.warn('Failed to persist blueprint:', e);
    }
  }

  /**
   * Remove blueprint from storage
   */
  removeFromStorage(blueprintId) {
    if (!this.storage) return;
    
    try {
      const all = JSON.parse(this.storage.getItem(this.storageKey) || '{}');
      delete all[blueprintId];
      this.storage.setItem(this.storageKey, JSON.stringify(all));
    } catch (e) {
      console.warn('Failed to remove blueprint from storage:', e);
    }
  }

  /**
   * Load all blueprints from storage
   */
  loadFromStorage() {
    if (!this.storage) return;
    
    try {
      const all = JSON.parse(this.storage.getItem(this.storageKey) || '{}');
      
      for (const [id, blueprint] of Object.entries(all)) {
        this.blueprints.set(id, blueprint);
      }
    } catch (e) {
      console.warn('Failed to load blueprints from storage:', e);
    }
  }

  /**
   * Clear all blueprints
   */
  clear() {
    this.blueprints.clear();
    
    if (this.storage) {
      this.storage.removeItem(this.storageKey);
    }
  }

  /**
   * Get statistics
   */
  getStats() {
    let totalPieces = 0;
    
    for (const bp of this.blueprints.values()) {
      totalPieces += bp.metadata.pieceCount;
    }
    
    return {
      count: this.blueprints.size,
      maxBlueprints: this.maxBlueprints,
      totalPieces,
      averagePieces: this.blueprints.size > 0 
        ? Math.round(totalPieces / this.blueprints.size) 
        : 0
    };
  }
}

export default BlueprintManager;

/**
 * CommandHistory - Undo/redo system using command pattern
 * 
 * Every building action becomes a command object with execute() and undo()
 * methods. This enables undo/redo, networked replication (serialize commands
 * and send to server), and macro recording (save command sequences).
 * 
 * Usage:
 *   const history = new CommandHistory({ maxSize: 50 });
 *   history.execute(new PlaceCommand(piece, position, buildingSystem));
 *   history.undo();
 *   history.redo();
 */

import * as THREE from 'three';

/**
 * Base command class - extend this for specific operations
 */
export class BuildCommand {
  constructor() {
    this.id = `cmd_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`;
    this.timestamp = Date.now();
    this.executed = false;
  }

  /**
   * Execute the command
   * @returns {Object} Execution result { success: boolean, ... }
   */
  execute() {
    throw new Error('execute() must be implemented by subclass');
  }

  /**
   * Undo the command (reverse execute)
   * @returns {Object} Undo result { success: boolean, ... }
   */
  undo() {
    throw new Error('undo() must be implemented by subclass');
  }

  /**
   * Check if command can be executed in current state
   * @returns {boolean} Whether command is valid
   */
  canExecute() {
    return true;
  }

  /**
   * Get command type name
   * @returns {string} Command type
   */
  getType() {
    return this.constructor.name;
  }

  /**
   * Get human-readable description
   * @returns {string} Description
   */
  getDescription() {
    return this.getType();
  }

  /**
   * Serialize command for networking/saving
   * @returns {Object} Serialized data
   */
  serialize() {
    return {
      type: this.getType(),
      id: this.id,
      timestamp: this.timestamp,
      data: this.getData()
    };
  }

  /**
   * Get command-specific data for serialization
   * Override in subclasses
   * @returns {Object} Command data
   */
  getData() {
    return {};
  }
}

/**
 * Place a building piece
 */
export class PlaceCommand extends BuildCommand {
  constructor(pieceData, position, rotation, buildingSystem) {
    super();
    this.pieceData = pieceData;
    this.position = position.clone();
    this.rotation = rotation?.clone() ?? new THREE.Euler();
    this.buildingSystem = buildingSystem;
    this.placedPiece = null;
  }

  execute() {
    if (!this.canExecute()) {
      return { success: false, reason: 'Cannot place here' };
    }

    this.placedPiece = this.buildingSystem.placePiece(
      this.pieceData,
      this.position,
      this.rotation
    );
    
    this.executed = true;
    
    return { 
      success: true, 
      piece: this.placedPiece,
      pieceId: this.placedPiece?.id
    };
  }

  undo() {
    if (!this.placedPiece) {
      return { success: false, reason: 'No piece to remove' };
    }

    this.buildingSystem.removePiece(this.placedPiece.id);
    this.executed = false;
    
    return { success: true, removedId: this.placedPiece.id };
  }

  canExecute() {
    return this.buildingSystem.canPlace?.(this.pieceData, this.position) ?? true;
  }

  getDescription() {
    return `Place ${this.pieceData.type}`;
  }

  getData() {
    return {
      pieceType: this.pieceData.type,
      material: this.pieceData.material?.name,
      position: { x: this.position.x, y: this.position.y, z: this.position.z },
      rotation: { x: this.rotation.x, y: this.rotation.y, z: this.rotation.z },
      placedPieceId: this.placedPiece?.id
    };
  }
}

/**
 * Remove a building piece
 */
export class RemoveCommand extends BuildCommand {
  constructor(piece, buildingSystem) {
    super();
    this.piece = piece;
    this.buildingSystem = buildingSystem;
    this.savedState = null;
  }

  execute() {
    // Save full state for undo
    this.savedState = {
      id: this.piece.id,
      type: this.piece.type,
      position: this.piece.position.clone(),
      rotation: this.piece.rotation?.clone() ?? new THREE.Euler(),
      material: this.piece.material,
      health: this.piece.health,
      variant: this.piece.variant,
      customData: this.piece.customData
    };

    this.buildingSystem.removePiece(this.piece.id);
    this.executed = true;
    
    return { success: true, removedId: this.piece.id };
  }

  undo() {
    if (!this.savedState) {
      return { success: false, reason: 'No saved state' };
    }

    // Restore piece
    const restored = this.buildingSystem.placePiece(
      { 
        type: this.savedState.type, 
        material: this.savedState.material,
        variant: this.savedState.variant
      },
      this.savedState.position,
      this.savedState.rotation
    );

    // Restore additional properties
    if (restored) {
      restored.health = this.savedState.health;
      restored.customData = this.savedState.customData;
    }

    this.piece = restored;
    this.executed = false;
    
    return { success: true, piece: restored };
  }

  getDescription() {
    return `Remove ${this.piece.type}`;
  }

  getData() {
    return {
      pieceId: this.piece.id,
      pieceType: this.piece.type,
      savedState: this.savedState
    };
  }
}

/**
 * Upgrade a piece's material
 */
export class UpgradeCommand extends BuildCommand {
  constructor(piece, newMaterial, buildingSystem) {
    super();
    this.piece = piece;
    this.newMaterial = newMaterial;
    this.oldMaterial = null;
    this.buildingSystem = buildingSystem;
  }

  execute() {
    this.oldMaterial = this.piece.material;
    this.buildingSystem.upgradePiece(this.piece.id, this.newMaterial);
    this.executed = true;
    
    return { 
      success: true, 
      pieceId: this.piece.id,
      oldMaterial: this.oldMaterial?.name,
      newMaterial: this.newMaterial?.name
    };
  }

  undo() {
    if (!this.oldMaterial) {
      return { success: false, reason: 'No previous material' };
    }

    this.buildingSystem.upgradePiece(this.piece.id, this.oldMaterial);
    this.executed = false;
    
    return { success: true, pieceId: this.piece.id };
  }

  getDescription() {
    return `Upgrade to ${this.newMaterial?.name ?? 'unknown'}`;
  }

  getData() {
    return {
      pieceId: this.piece.id,
      oldMaterial: this.oldMaterial?.name,
      newMaterial: this.newMaterial?.name
    };
  }
}

/**
 * Rotate a piece
 */
export class RotateCommand extends BuildCommand {
  constructor(piece, newRotation, buildingSystem) {
    super();
    this.piece = piece;
    this.newRotation = newRotation.clone();
    this.oldRotation = null;
    this.buildingSystem = buildingSystem;
  }

  execute() {
    this.oldRotation = this.piece.rotation.clone();
    this.piece.rotation.copy(this.newRotation);
    
    if (this.buildingSystem.onPieceModified) {
      this.buildingSystem.onPieceModified(this.piece);
    }
    
    this.executed = true;
    return { success: true, pieceId: this.piece.id };
  }

  undo() {
    if (!this.oldRotation) {
      return { success: false, reason: 'No previous rotation' };
    }

    this.piece.rotation.copy(this.oldRotation);
    
    if (this.buildingSystem.onPieceModified) {
      this.buildingSystem.onPieceModified(this.piece);
    }
    
    this.executed = false;
    return { success: true, pieceId: this.piece.id };
  }

  getDescription() {
    return `Rotate ${this.piece.type}`;
  }
}

/**
 * Batch command - execute multiple commands as one undo unit
 */
export class BatchCommand extends BuildCommand {
  constructor(commands, description = null) {
    super();
    this.commands = commands;
    this.customDescription = description;
    this.executedCommands = [];
  }

  execute() {
    this.executedCommands = [];

    for (const command of this.commands) {
      if (command.canExecute()) {
        const result = command.execute();
        if (result.success) {
          this.executedCommands.push(command);
        }
      }
    }

    this.executed = true;
    
    return {
      success: this.executedCommands.length > 0,
      executed: this.executedCommands.length,
      total: this.commands.length,
      failed: this.commands.length - this.executedCommands.length
    };
  }

  undo() {
    // Undo in reverse order
    for (let i = this.executedCommands.length - 1; i >= 0; i--) {
      this.executedCommands[i].undo();
    }

    this.executedCommands = [];
    this.executed = false;
    
    return { success: true };
  }

  getDescription() {
    return this.customDescription ?? `Batch (${this.commands.length} operations)`;
  }

  getData() {
    return {
      commands: this.commands.map(c => c.serialize()),
      executedCount: this.executedCommands.length
    };
  }
}

/**
 * CommandHistory - Manages the undo/redo stack
 */
export class CommandHistory {
  constructor(options = {}) {
    this.maxSize = options.maxSize ?? 100;
    this.undoStack = [];
    this.redoStack = [];
    
    // Grouping support (for compound operations)
    this.isGrouping = false;
    this.groupCommands = [];
    this.groupDescription = null;
    
    // Event callbacks
    this.onExecute = options.onExecute ?? null;
    this.onUndo = options.onUndo ?? null;
    this.onRedo = options.onRedo ?? null;
    this.onChange = options.onChange ?? null;
  }

  /**
   * Execute a command and add to history
   * @param {BuildCommand} command - Command to execute
   * @returns {Object} Execution result
   */
  execute(command) {
    if (!command.canExecute()) {
      return { success: false, reason: 'Command cannot be executed' };
    }

    const result = command.execute();

    if (result.success) {
      if (this.isGrouping) {
        // Add to current group
        this.groupCommands.push(command);
      } else {
        // Add to undo stack
        this.undoStack.push(command);
        
        // Clear redo stack (new action invalidates redo)
        this.redoStack = [];
        
        // Enforce max size
        this.enforceMaxSize();
      }

      if (this.onExecute) this.onExecute(command, result);
      if (this.onChange) this.onChange(this.getStatus());
    }

    return result;
  }

  /**
   * Undo the last command
   * @returns {Object} Undo result
   */
  undo() {
    if (this.undoStack.length === 0) {
      return { success: false, reason: 'Nothing to undo' };
    }

    const command = this.undoStack.pop();
    const result = command.undo();

    if (result.success) {
      this.redoStack.push(command);
      
      if (this.onUndo) this.onUndo(command, result);
      if (this.onChange) this.onChange(this.getStatus());
    } else {
      // Restore to stack if undo failed
      this.undoStack.push(command);
    }

    return result;
  }

  /**
   * Redo the last undone command
   * @returns {Object} Redo result
   */
  redo() {
    if (this.redoStack.length === 0) {
      return { success: false, reason: 'Nothing to redo' };
    }

    const command = this.redoStack.pop();
    const result = command.execute();

    if (result.success) {
      this.undoStack.push(command);
      
      if (this.onRedo) this.onRedo(command, result);
      if (this.onChange) this.onChange(this.getStatus());
    } else {
      // Restore to stack if redo failed
      this.redoStack.push(command);
    }

    return result;
  }

  /**
   * Begin a command group (multiple commands as one undo unit)
   * @param {string} description - Group description
   */
  beginGroup(description = null) {
    if (this.isGrouping) {
      console.warn('Already in a command group');
      return;
    }
    
    this.isGrouping = true;
    this.groupCommands = [];
    this.groupDescription = description;
  }

  /**
   * End the current command group
   * @returns {Object} Result with grouped command
   */
  endGroup() {
    if (!this.isGrouping) {
      return { success: false, reason: 'Not in a command group' };
    }

    this.isGrouping = false;

    if (this.groupCommands.length === 0) {
      return { success: true, commands: 0 };
    }

    // Create batch command from group
    const batch = new BatchCommand(this.groupCommands, this.groupDescription);
    batch.executedCommands = [...this.groupCommands]; // Already executed
    batch.executed = true;

    // Add batch to undo stack
    this.undoStack.push(batch);
    this.redoStack = [];
    this.enforceMaxSize();

    const count = this.groupCommands.length;
    this.groupCommands = [];
    this.groupDescription = null;

    if (this.onChange) this.onChange(this.getStatus());

    return { success: true, commands: count };
  }

  /**
   * Cancel current command group (undo all grouped commands)
   */
  cancelGroup() {
    if (!this.isGrouping) return;

    // Undo all grouped commands in reverse order
    for (let i = this.groupCommands.length - 1; i >= 0; i--) {
      this.groupCommands[i].undo();
    }

    this.isGrouping = false;
    this.groupCommands = [];
    this.groupDescription = null;
  }

  /**
   * Check if undo is available
   */
  canUndo() {
    return this.undoStack.length > 0 && !this.isGrouping;
  }

  /**
   * Check if redo is available
   */
  canRedo() {
    return this.redoStack.length > 0 && !this.isGrouping;
  }

  /**
   * Clear all history
   */
  clear() {
    this.undoStack = [];
    this.redoStack = [];
    this.isGrouping = false;
    this.groupCommands = [];
    
    if (this.onChange) this.onChange(this.getStatus());
  }

  /**
   * Get current history status (for UI)
   */
  getStatus() {
    return {
      undoCount: this.undoStack.length,
      redoCount: this.redoStack.length,
      canUndo: this.canUndo(),
      canRedo: this.canRedo(),
      isGrouping: this.isGrouping,
      groupSize: this.groupCommands.length,
      lastUndo: this.undoStack.length > 0 
        ? this.undoStack[this.undoStack.length - 1].getDescription() 
        : null,
      lastRedo: this.redoStack.length > 0
        ? this.redoStack[this.redoStack.length - 1].getDescription()
        : null
    };
  }

  /**
   * Get undo history descriptions (for UI menu)
   */
  getUndoHistory(limit = 10) {
    return this.undoStack
      .slice(-limit)
      .reverse()
      .map(cmd => ({
        id: cmd.id,
        type: cmd.getType(),
        description: cmd.getDescription(),
        timestamp: cmd.timestamp
      }));
  }

  /**
   * Get redo history descriptions
   */
  getRedoHistory(limit = 10) {
    return this.redoStack
      .slice(-limit)
      .reverse()
      .map(cmd => ({
        id: cmd.id,
        type: cmd.getType(),
        description: cmd.getDescription(),
        timestamp: cmd.timestamp
      }));
  }

  /**
   * Enforce maximum history size
   */
  enforceMaxSize() {
    while (this.undoStack.length > this.maxSize) {
      this.undoStack.shift();
    }
  }

  /**
   * Serialize full history for saving
   */
  serialize() {
    return {
      version: 1,
      undoStack: this.undoStack.map(cmd => cmd.serialize()),
      redoStack: this.redoStack.map(cmd => cmd.serialize())
    };
  }
}

export default CommandHistory;

/**
 * GhostPreview - Transparent placement preview system
 * 
 * Shows a semi-transparent preview of what will be placed before the
 * player commits. Changes color based on placement validity (green = valid,
 * red = invalid). Essential for good building UX.
 * 
 * Usage:
 *   const ghost = new GhostPreview(scene);
 *   ghost.show('wall', cursorPosition, rotation);
 *   ghost.setValid(canPlaceHere);
 *   ghost.updatePosition(newPosition);
 *   ghost.hide();
 */

import * as THREE from 'three';

/**
 * Ghost preview states
 */
export const GhostState = {
  HIDDEN: 'hidden',
  VALID: 'valid',
  INVALID: 'invalid',
  BLOCKED: 'blocked'
};

export class GhostPreview {
  /**
   * Create ghost preview system
   * @param {THREE.Scene} scene - Scene to add ghosts to
   * @param {Object} options - Configuration options
   */
  constructor(scene, options = {}) {
    this.scene = scene;
    
    // Appearance
    this.validColor = new THREE.Color(options.validColor ?? 0x00ff00);
    this.invalidColor = new THREE.Color(options.invalidColor ?? 0xff0000);
    this.blockedColor = new THREE.Color(options.blockedColor ?? 0xff8800);
    this.opacity = options.opacity ?? 0.5;
    this.wireframe = options.wireframe ?? false;
    
    // Animation
    this.pulseEnabled = options.pulseEnabled ?? true;
    this.pulseSpeed = options.pulseSpeed ?? 3;
    this.pulseAmount = options.pulseAmount ?? 0.3;
    this.pulsePhase = 0;
    
    // State
    this.state = GhostState.HIDDEN;
    this.currentType = null;
    this.activeGhost = null;
    
    // Mesh cache
    this.meshCache = new Map();
    
    // External mesh factory (optional)
    this.meshFactory = options.meshFactory ?? null;
    
    // Snap settings
    this.snapEnabled = options.snapEnabled ?? true;
    this.snapGrid = options.snapGrid ?? 1;
    this.snapRotation = options.snapRotation ?? Math.PI / 4; // 45 degrees
    
    // Group for blueprint previews
    this.blueprintGroup = null;
  }

  /**
   * Show ghost preview at position
   * @param {string} pieceType - Type of piece to preview
   * @param {THREE.Vector3} position - World position
   * @param {THREE.Euler|number} rotation - Rotation (Euler or Y angle)
   * @returns {THREE.Mesh} The ghost mesh
   */
  show(pieceType, position, rotation = 0) {
    // Hide current ghost if different type
    if (this.activeGhost && this.currentType !== pieceType) {
      this.hide();
    }

    // Get or create ghost mesh
    let ghost = this.meshCache.get(pieceType);
    
    if (!ghost) {
      ghost = this.createGhostMesh(pieceType);
      this.meshCache.set(pieceType, ghost);
    }

    // Apply position (with optional snapping)
    const snappedPos = this.snapEnabled 
      ? this.snapPosition(position) 
      : position;
    ghost.position.copy(snappedPos);

    // Apply rotation
    if (typeof rotation === 'number') {
      ghost.rotation.set(0, rotation, 0);
    } else if (rotation instanceof THREE.Euler) {
      ghost.rotation.copy(rotation);
    }

    // Add to scene if not already
    if (!ghost.parent) {
      this.scene.add(ghost);
    }

    ghost.visible = true;
    this.activeGhost = ghost;
    this.currentType = pieceType;
    this.state = GhostState.VALID;
    
    // Set initial valid color
    this.setGhostColor(ghost, this.validColor);

    return ghost;
  }

  /**
   * Hide current ghost preview
   */
  hide() {
    if (this.activeGhost) {
      this.activeGhost.visible = false;
    }
    
    if (this.blueprintGroup) {
      this.blueprintGroup.visible = false;
    }
    
    this.state = GhostState.HIDDEN;
  }

  /**
   * Update ghost position
   * @param {THREE.Vector3} position - New position
   * @param {THREE.Euler|number} rotation - Optional new rotation
   */
  updatePosition(position, rotation = null) {
    if (!this.activeGhost) return;

    const snappedPos = this.snapEnabled 
      ? this.snapPosition(position) 
      : position;
    
    this.activeGhost.position.copy(snappedPos);

    if (rotation !== null) {
      if (typeof rotation === 'number') {
        this.activeGhost.rotation.y = this.snapEnabled
          ? this.snapRotationValue(rotation)
          : rotation;
      } else if (rotation instanceof THREE.Euler) {
        this.activeGhost.rotation.copy(rotation);
      }
    }
  }

  /**
   * Set validity state (changes color)
   * @param {boolean} isValid - Whether placement is valid
   * @param {string} reason - Optional reason for invalidity
   */
  setValid(isValid, reason = null) {
    if (!this.activeGhost && !this.blueprintGroup) return;

    const target = this.blueprintGroup ?? this.activeGhost;
    
    if (isValid) {
      this.state = GhostState.VALID;
      this.setGhostColor(target, this.validColor);
    } else {
      this.state = reason === 'blocked' ? GhostState.BLOCKED : GhostState.INVALID;
      const color = this.state === GhostState.BLOCKED 
        ? this.blockedColor 
        : this.invalidColor;
      this.setGhostColor(target, color);
    }
  }

  /**
   * Update animation (call from render loop)
   * @param {number} deltaTime - Time since last frame
   */
  update(deltaTime) {
    if (this.state === GhostState.HIDDEN || !this.pulseEnabled) return;

    this.pulsePhase += deltaTime * this.pulseSpeed;
    
    // Calculate pulsing opacity
    const pulse = (Math.sin(this.pulsePhase) + 1) / 2;
    const opacity = this.opacity * (1 - this.pulseAmount + pulse * this.pulseAmount);

    const target = this.blueprintGroup ?? this.activeGhost;
    if (target) {
      this.setGhostOpacity(target, opacity);
    }
  }

  /**
   * Show blueprint preview (multiple pieces)
   * @param {Array} pieces - Pieces to preview
   * @param {THREE.Vector3} position - Blueprint origin position
   * @param {number} rotation - Y-axis rotation
   * @returns {THREE.Group} The preview group
   */
  showBlueprint(pieces, position, rotation = 0) {
    this.hide();

    // Create group for blueprint
    this.blueprintGroup = new THREE.Group();
    this.blueprintGroup.name = 'blueprint-preview';

    // Create ghost for each piece
    for (const piece of pieces) {
      const ghost = this.createGhostMesh(piece.type);
      ghost.position.copy(piece.position);
      
      if (piece.rotation) {
        ghost.rotation.copy(piece.rotation);
      }
      
      this.blueprintGroup.add(ghost);
    }

    // Position and rotate the group
    const snappedPos = this.snapEnabled 
      ? this.snapPosition(position) 
      : position;
    
    this.blueprintGroup.position.copy(snappedPos);
    this.blueprintGroup.rotation.y = rotation;

    this.scene.add(this.blueprintGroup);
    this.state = GhostState.VALID;
    this.setGhostColor(this.blueprintGroup, this.validColor);

    return this.blueprintGroup;
  }

  /**
   * Update blueprint preview position
   * @param {THREE.Vector3} position - New position
   * @param {number} rotation - New Y rotation
   */
  updateBlueprintPosition(position, rotation = null) {
    if (!this.blueprintGroup) return;

    const snappedPos = this.snapEnabled 
      ? this.snapPosition(position) 
      : position;
    
    this.blueprintGroup.position.copy(snappedPos);

    if (rotation !== null) {
      this.blueprintGroup.rotation.y = this.snapEnabled
        ? this.snapRotationValue(rotation)
        : rotation;
    }
  }

  /**
   * Rotate current ghost by increment
   * @param {number} angle - Angle to rotate by (radians)
   */
  rotate(angle) {
    const target = this.blueprintGroup ?? this.activeGhost;
    if (!target) return;

    target.rotation.y += angle;

    if (this.snapEnabled) {
      target.rotation.y = this.snapRotationValue(target.rotation.y);
    }
  }

  /**
   * Create ghost mesh for piece type
   */
  createGhostMesh(pieceType) {
    let geometry;

    // Use factory if provided
    if (this.meshFactory) {
      try {
        const baseMesh = this.meshFactory.createMesh(pieceType);
        geometry = baseMesh.geometry.clone();
      } catch (e) {
        geometry = this.getDefaultGeometry(pieceType);
      }
    } else {
      geometry = this.getDefaultGeometry(pieceType);
    }

    // Create semi-transparent material
    const material = new THREE.MeshBasicMaterial({
      color: this.validColor,
      transparent: true,
      opacity: this.opacity,
      side: THREE.DoubleSide,
      depthWrite: false,
      wireframe: this.wireframe
    });

    const mesh = new THREE.Mesh(geometry, material);
    mesh.renderOrder = 999; // Render on top
    mesh.userData.isGhost = true;

    return mesh;
  }

  /**
   * Get default geometry for piece type
   */
  getDefaultGeometry(pieceType) {
    const geometries = {
      foundation: () => new THREE.BoxGeometry(4, 0.2, 4),
      wall: () => new THREE.BoxGeometry(4, 3, 0.2),
      floor: () => new THREE.BoxGeometry(4, 0.1, 4),
      ceiling: () => new THREE.BoxGeometry(4, 0.1, 4),
      pillar: () => new THREE.BoxGeometry(0.5, 3, 0.5),
      roof: () => this.createRoofGeometry(),
      ramp: () => this.createRampGeometry(),
      stairs: () => this.createStairsGeometry(),
      door: () => new THREE.BoxGeometry(1.2, 2.5, 0.2),
      window: () => new THREE.BoxGeometry(2, 1.5, 0.2),
      fence: () => new THREE.BoxGeometry(4, 1.5, 0.1),
      halfWall: () => new THREE.BoxGeometry(4, 1.5, 0.2)
    };

    const factory = geometries[pieceType] ?? (() => new THREE.BoxGeometry(1, 1, 1));
    return factory();
  }

  /**
   * Create angled roof geometry
   */
  createRoofGeometry() {
    const geometry = new THREE.BufferGeometry();
    
    const vertices = new Float32Array([
      // Triangle face 1
      -2, 0, -2,   2, 0, -2,   0, 1.5, 0,
      // Triangle face 2
      2, 0, -2,   2, 0, 2,   0, 1.5, 0,
      // Triangle face 3
      2, 0, 2,   -2, 0, 2,   0, 1.5, 0,
      // Triangle face 4
      -2, 0, 2,   -2, 0, -2,   0, 1.5, 0,
      // Bottom face
      -2, 0, -2,   -2, 0, 2,   2, 0, 2,
      -2, 0, -2,   2, 0, 2,   2, 0, -2
    ]);
    
    geometry.setAttribute('position', new THREE.BufferAttribute(vertices, 3));
    geometry.computeVertexNormals();
    
    return geometry;
  }

  /**
   * Create ramp geometry
   */
  createRampGeometry() {
    const geometry = new THREE.BufferGeometry();
    
    const vertices = new Float32Array([
      // Ramp surface
      -2, 0, 2,   2, 0, 2,   2, 2, -2,
      -2, 0, 2,   2, 2, -2,   -2, 2, -2,
      // Bottom
      -2, 0, 2,   -2, 0, -2,   2, 0, -2,
      -2, 0, 2,   2, 0, -2,   2, 0, 2,
      // Sides
      -2, 0, 2,   -2, 2, -2,   -2, 0, -2,
      2, 0, 2,   2, 0, -2,   2, 2, -2,
      // Back
      -2, 2, -2,   2, 2, -2,   2, 0, -2,
      -2, 2, -2,   2, 0, -2,   -2, 0, -2
    ]);
    
    geometry.setAttribute('position', new THREE.BufferAttribute(vertices, 3));
    geometry.computeVertexNormals();
    
    return geometry;
  }

  /**
   * Create stairs geometry (simplified)
   */
  createStairsGeometry() {
    const group = new THREE.Group();
    const stepCount = 6;
    const stepHeight = 0.5;
    const stepDepth = 0.5;
    const width = 2;

    for (let i = 0; i < stepCount; i++) {
      const stepGeo = new THREE.BoxGeometry(width, stepHeight, stepDepth);
      const step = new THREE.Mesh(stepGeo);
      step.position.set(0, i * stepHeight + stepHeight / 2, -i * stepDepth);
      group.add(step);
    }

    // Merge into single geometry
    const geometry = new THREE.BoxGeometry(width, stepCount * stepHeight, stepCount * stepDepth);
    return geometry;
  }

  /**
   * Set color of ghost mesh or group
   */
  setGhostColor(target, color) {
    if (target.material) {
      target.material.color.copy(color);
    }

    if (target.children) {
      target.children.forEach(child => {
        if (child.material) {
          child.material.color.copy(color);
        }
      });
    }
  }

  /**
   * Set opacity of ghost mesh or group
   */
  setGhostOpacity(target, opacity) {
    if (target.material) {
      target.material.opacity = opacity;
    }

    if (target.children) {
      target.children.forEach(child => {
        if (child.material) {
          child.material.opacity = opacity;
        }
      });
    }
  }

  /**
   * Snap position to grid
   */
  snapPosition(position) {
    return new THREE.Vector3(
      Math.round(position.x / this.snapGrid) * this.snapGrid,
      Math.round(position.y / this.snapGrid) * this.snapGrid,
      Math.round(position.z / this.snapGrid) * this.snapGrid
    );
  }

  /**
   * Snap rotation to increments
   */
  snapRotationValue(rotation) {
    return Math.round(rotation / this.snapRotation) * this.snapRotation;
  }

  /**
   * Get current ghost position
   */
  getPosition() {
    const target = this.blueprintGroup ?? this.activeGhost;
    return target?.position.clone() ?? null;
  }

  /**
   * Get current ghost rotation
   */
  getRotation() {
    const target = this.blueprintGroup ?? this.activeGhost;
    return target?.rotation.clone() ?? null;
  }

  /**
   * Get current state
   */
  getState() {
    return this.state;
  }

  /**
   * Check if ghost is currently valid
   */
  isValid() {
    return this.state === GhostState.VALID;
  }

  /**
   * Check if ghost is visible
   */
  isVisible() {
    return this.state !== GhostState.HIDDEN;
  }

  /**
   * Configure snap settings
   */
  setSnapSettings(grid, rotation) {
    if (grid !== undefined) this.snapGrid = grid;
    if (rotation !== undefined) this.snapRotation = rotation;
  }

  /**
   * Enable or disable snapping
   */
  setSnapEnabled(enabled) {
    this.snapEnabled = enabled;
  }

  /**
   * Dispose of all resources
   */
  dispose() {
    this.hide();

    // Dispose cached meshes
    for (const [type, mesh] of this.meshCache) {
      if (mesh.geometry) mesh.geometry.dispose();
      if (mesh.material) mesh.material.dispose();
      if (mesh.parent) mesh.parent.remove(mesh);
    }

    this.meshCache.clear();

    // Dispose blueprint group
    if (this.blueprintGroup) {
      this.blueprintGroup.traverse(child => {
        if (child.geometry) child.geometry.dispose();
        if (child.material) child.material.dispose();
      });
      
      if (this.blueprintGroup.parent) {
        this.blueprintGroup.parent.remove(this.blueprintGroup);
      }
      
      this.blueprintGroup = null;
    }
  }
}

export default GhostPreview;