Multiplayer Building

{
  "name": "multiplayer-building",
  "description": "Networking systems for multiplayer building games. Use when implementing networked construction, delta synchronization, client prediction, or conflict resolution.",
  "tags": [
    "building-game",
    "web",
    "javascript",
    "code-generation"
  ],
  "sub_skills": [],
  "source": "claude-user",
  "type": "template",
  "depends_on": [],
  "enhances": [
    "performance-at-scale",
    "structural-physics"
  ],
  "last_reviewed_at": null,
  "review_score": null,
  "relevance_tier": null
}

/**
 * BuildingNetworkManager - Complete networking system for multiplayer building
 * 
 * Integrates delta compression, client prediction, and conflict resolution
 * into a unified networking layer for building mechanics.
 * 
 * Server-authoritative model with client prediction for responsiveness.
 * 
 * Usage:
 *   // Server
 *   const server = new BuildingNetworkServer(buildingSystem);
 *   server.onClientMessage(clientId, message);
 *   
 *   // Client  
 *   const client = new BuildingNetworkClient(buildingSystem);
 *   client.connect(serverUrl);
 *   client.placeRequest(pieceType, position, rotation);
 */

import { DeltaCompressor, DeltaReceiver } from './delta-compression.js';
import { ClientPrediction } from './client-prediction.js';
import { ConflictResolver, BuildingPermissionSystem } from './conflict-resolver.js';

/**
 * Message types for building network protocol
 */
export const MessageType = {
  // Client -> Server
  PLACE_REQUEST: 'place_request',
  DESTROY_REQUEST: 'destroy_request',
  UPGRADE_REQUEST: 'upgrade_request',
  ROTATE_REQUEST: 'rotate_request',
  CLAIM_REGION: 'claim_region',
  AUTHORIZE_PLAYER: 'authorize_player',
  
  // Server -> Client
  PLACE_CONFIRMED: 'place_confirmed',
  PLACE_REJECTED: 'place_rejected',
  PIECE_DESTROYED: 'piece_destroyed',
  PIECE_UPDATED: 'piece_updated',
  FULL_SYNC: 'full_sync',
  DELTA_UPDATE: 'delta_update',
  REGION_UPDATE: 'region_update',
  
  // Bidirectional
  PING: 'ping',
  PONG: 'pong',
  ACK: 'ack',
  ERROR: 'error'
};

/**
 * Rate limiter for building operations
 */
class RateLimiter {
  constructor(options = {}) {
    this.limits = {
      place: options.placePerSecond ?? 5,
      destroy: options.destroyPerSecond ?? 10,
      upgrade: options.upgradePerSecond ?? 3
    };
    this.buckets = new Map(); // clientId -> { action -> { count, resetTime } }
  }

  check(clientId, action) {
    const limit = this.limits[action] ?? 10;
    let clientBuckets = this.buckets.get(clientId);
    
    if (!clientBuckets) {
      clientBuckets = {};
      this.buckets.set(clientId, clientBuckets);
    }

    const now = Date.now();
    let bucket = clientBuckets[action];
    
    if (!bucket || now > bucket.resetTime) {
      bucket = { count: 0, resetTime: now + 1000 };
      clientBuckets[action] = bucket;
    }

    if (bucket.count >= limit) {
      return { 
        allowed: false, 
        retryAfter: bucket.resetTime - now 
      };
    }

    bucket.count++;
    return { allowed: true };
  }

  reset(clientId) {
    this.buckets.delete(clientId);
  }
}

/**
 * Server-side building network manager
 */
export class BuildingNetworkServer {
  constructor(buildingSystem, options = {}) {
    this.buildingSystem = buildingSystem;
    
    // Configuration
    this.tickRate = options.tickRate ?? 20; // Updates per second
    this.maxClientsPerUpdate = options.maxClientsPerUpdate ?? 50;
    
    // Subsystems
    this.deltaCompressor = new DeltaCompressor({
      maxHistorySize: options.deltaHistorySize ?? 64,
      compactMode: true
    });
    this.conflictResolver = new ConflictResolver({
      strategy: options.conflictStrategy ?? 'first_write',
      conflictWindow: options.conflictWindow ?? 100,
      enableLocking: options.enableLocking ?? false
    });
    this.permissions = new BuildingPermissionSystem({
      defaultAllow: options.defaultAllowBuilding ?? true,
      regionRadius: options.regionRadius ?? 50
    });
    this.rateLimiter = new RateLimiter(options.rateLimits);
    
    // Client management
    this.clients = new Map(); // clientId -> ClientState
    this.clientPositions = new Map(); // clientId -> position (for spatial broadcasts)
    
    // State
    this.stateVersion = 0;
    this.lastTickTime = 0;
    this.tickInterval = null;
    
    // Callbacks (implement these to send messages)
    this.sendToClient = options.sendToClient ?? null;
    this.broadcastToAll = options.broadcastToAll ?? null;
    this.broadcastToNearby = options.broadcastToNearby ?? null;
    
    // Set up conflict resolver callbacks
    this.conflictResolver.onRequestProcessed = (pending, success, reason) => {
      this.handleRequestProcessed(pending, success, reason);
    };
    
    // Statistics
    this.stats = {
      messagesReceived: 0,
      messagesSent: 0,
      placementsProcessed: 0,
      destructionsProcessed: 0,
      conflictsResolved: 0
    };
  }

  /**
   * Start the server tick loop
   */
  start() {
    if (this.tickInterval) return;
    
    const tickMs = 1000 / this.tickRate;
    this.tickInterval = setInterval(() => this.tick(), tickMs);
    this.lastTickTime = Date.now();
  }

  /**
   * Stop the server tick loop
   */
  stop() {
    if (this.tickInterval) {
      clearInterval(this.tickInterval);
      this.tickInterval = null;
    }
  }

  /**
   * Server tick - process updates and send deltas
   */
  tick() {
    const now = Date.now();
    const deltaTime = now - this.lastTickTime;
    this.lastTickTime = now;

    // Record current state
    this.stateVersion++;
    this.deltaCompressor.recordState(this.buildingSystem);

    // Send updates to clients
    this.sendUpdatesToClients();

    // Clean up
    this.conflictResolver.cleanupExpiredLocks();
  }

  /**
   * Send delta updates to all clients
   */
  sendUpdatesToClients() {
    if (!this.sendToClient) return;

    let clientsProcessed = 0;
    
    for (const [clientId, clientState] of this.clients) {
      if (clientsProcessed >= this.maxClientsPerUpdate) break;
      
      const delta = this.deltaCompressor.getDeltaForClient(clientId);
      
      if (delta && !delta.isEmpty) {
        const message = {
          type: delta.isFull ? MessageType.FULL_SYNC : MessageType.DELTA_UPDATE,
          data: delta.serialize(true),
          version: this.stateVersion
        };
        
        this.sendToClient(clientId, message);
        this.stats.messagesSent++;
      }
      
      clientsProcessed++;
    }
  }

  /**
   * Handle incoming message from client
   */
  onClientMessage(clientId, message) {
    this.stats.messagesReceived++;
    
    switch (message.type) {
      case MessageType.PLACE_REQUEST:
        this.handlePlaceRequest(clientId, message);
        break;
      case MessageType.DESTROY_REQUEST:
        this.handleDestroyRequest(clientId, message);
        break;
      case MessageType.UPGRADE_REQUEST:
        this.handleUpgradeRequest(clientId, message);
        break;
      case MessageType.CLAIM_REGION:
        this.handleClaimRegion(clientId, message);
        break;
      case MessageType.AUTHORIZE_PLAYER:
        this.handleAuthorizePlayer(clientId, message);
        break;
      case MessageType.ACK:
        this.handleAck(clientId, message);
        break;
      case MessageType.PING:
        this.handlePing(clientId, message);
        break;
      default:
        console.warn(`Unknown message type: ${message.type}`);
    }
  }

  /**
   * Handle place request
   */
  handlePlaceRequest(clientId, message) {
    // Rate limit check
    const rateCheck = this.rateLimiter.check(clientId, 'place');
    if (!rateCheck.allowed) {
      this.sendReject(clientId, message.tempId, `Rate limited. Retry in ${rateCheck.retryAfter}ms`);
      return;
    }

    // Permission check
    const position = message.position;
    if (!this.permissions.canBuild(clientId, position)) {
      this.sendReject(clientId, message.tempId, 'No permission to build in this area');
      return;
    }

    // Validate placement (collision, resources, etc.)
    const validation = this.validatePlacement(message, clientId);
    if (!validation.valid) {
      this.sendReject(clientId, message.tempId, validation.reason);
      return;
    }

    // Submit to conflict resolver
    const client = this.clients.get(clientId);
    this.conflictResolver.submitPlaceRequest(message, { id: clientId, ...client });
  }

  /**
   * Handle destroy request
   */
  handleDestroyRequest(clientId, message) {
    const rateCheck = this.rateLimiter.check(clientId, 'destroy');
    if (!rateCheck.allowed) {
      this.sendReject(clientId, message.tempId, 'Rate limited');
      return;
    }

    const piece = this.buildingSystem.getPieceById(message.pieceId);
    if (!piece) {
      this.sendReject(clientId, message.tempId, 'Piece not found');
      return;
    }

    // Permission check
    if (!this.permissions.canBuild(clientId, piece.position)) {
      this.sendReject(clientId, message.tempId, 'No permission to destroy in this area');
      return;
    }

    // Destroy piece
    const destroyed = this.buildingSystem.destroyPiece(piece);
    this.stats.destructionsProcessed++;

    // Broadcast destruction
    this.broadcastPieceDestroyed(message.pieceId, destroyed);

    // Confirm to requester
    this.sendConfirm(clientId, message.tempId, message.pieceId, { destroyed: destroyed.length });
  }

  /**
   * Handle upgrade request
   */
  handleUpgradeRequest(clientId, message) {
    const rateCheck = this.rateLimiter.check(clientId, 'upgrade');
    if (!rateCheck.allowed) {
      this.sendReject(clientId, message.tempId, 'Rate limited');
      return;
    }

    const piece = this.buildingSystem.getPieceById(message.pieceId);
    if (!piece) {
      this.sendReject(clientId, message.tempId, 'Piece not found');
      return;
    }

    // Permission check
    if (!this.permissions.canBuild(clientId, piece.position)) {
      this.sendReject(clientId, message.tempId, 'No permission');
      return;
    }

    // Upgrade piece
    const upgraded = this.buildingSystem.upgradePiece(piece, message.material);
    if (!upgraded) {
      this.sendReject(clientId, message.tempId, 'Cannot upgrade');
      return;
    }

    // Broadcast update
    this.broadcastPieceUpdated(piece);

    // Confirm
    this.sendConfirm(clientId, message.tempId, piece.id, { material: message.material });
  }

  /**
   * Handle region claim request
   */
  handleClaimRegion(clientId, message) {
    const result = this.permissions.claimRegion(clientId, message.position);
    
    if (result.success) {
      this.send(clientId, {
        type: MessageType.REGION_UPDATE,
        action: 'claimed',
        regionId: result.regionId,
        position: message.position
      });
    } else {
      this.send(clientId, {
        type: MessageType.ERROR,
        error: result.reason
      });
    }
  }

  /**
   * Handle authorize player request
   */
  handleAuthorizePlayer(clientId, message) {
    const result = this.permissions.authorize(clientId, message.playerId, message.regionId);
    
    this.send(clientId, {
      type: MessageType.REGION_UPDATE,
      action: result.success ? 'authorized' : 'error',
      playerId: message.playerId,
      error: result.reason
    });
  }

  /**
   * Handle acknowledgment
   */
  handleAck(clientId, message) {
    this.deltaCompressor.acknowledgeVersion(clientId, message.version);
  }

  /**
   * Handle ping
   */
  handlePing(clientId, message) {
    this.send(clientId, {
      type: MessageType.PONG,
      clientTime: message.clientTime,
      serverTime: Date.now()
    });
  }

  /**
   * Handle processed request from conflict resolver
   */
  handleRequestProcessed(pending, success, reason) {
    const clientId = pending.client.id;
    const message = pending.request;

    if (success) {
      // Actually place the piece
      const piece = this.buildingSystem.place(
        message.pieceType,
        message.position,
        message.rotation,
        message.material
      );
      
      this.stats.placementsProcessed++;

      // Send confirmation
      this.sendConfirm(clientId, message.tempId, piece.id, {
        position: piece.position,
        rotation: piece.rotation
      });

      // Broadcast to nearby players
      if (this.broadcastToNearby) {
        this.broadcastToNearby(message.position, {
          type: MessageType.PIECE_UPDATED,
          piece: this.serializePiece(piece)
        }, clientId);
      }
    } else {
      this.sendReject(clientId, message.tempId, reason);
    }
  }

  /**
   * Validate placement request
   */
  validatePlacement(message, clientId) {
    // Check collision
    if (this.buildingSystem.checkCollision(message.position, message.pieceType)) {
      return { valid: false, reason: 'Position occupied' };
    }

    // Check structural validity
    if (!this.buildingSystem.isValidPlacement(message.pieceType, message.position)) {
      return { valid: false, reason: 'Invalid placement - needs support' };
    }

    // Additional validation (resources, limits, etc.) would go here

    return { valid: true };
  }

  /**
   * Send confirmation to client
   */
  sendConfirm(clientId, tempId, serverId, data = {}) {
    this.send(clientId, {
      type: MessageType.PLACE_CONFIRMED,
      tempId,
      serverId,
      ...data
    });
  }

  /**
   * Send rejection to client
   */
  sendReject(clientId, tempId, reason) {
    this.send(clientId, {
      type: MessageType.PLACE_REJECTED,
      tempId,
      reason
    });
  }

  /**
   * Broadcast piece destroyed
   */
  broadcastPieceDestroyed(pieceId, cascadeDestroyed = []) {
    const message = {
      type: MessageType.PIECE_DESTROYED,
      pieceId,
      cascade: cascadeDestroyed.map(p => p.id)
    };

    if (this.broadcastToAll) {
      this.broadcastToAll(message);
    }
  }

  /**
   * Broadcast piece updated
   */
  broadcastPieceUpdated(piece) {
    const message = {
      type: MessageType.PIECE_UPDATED,
      piece: this.serializePiece(piece)
    };

    if (this.broadcastToAll) {
      this.broadcastToAll(message);
    }
  }

  /**
   * Send message to client
   */
  send(clientId, message) {
    if (this.sendToClient) {
      this.sendToClient(clientId, message);
      this.stats.messagesSent++;
    }
  }

  /**
   * Serialize piece for network
   */
  serializePiece(piece) {
    return {
      id: piece.id,
      type: piece.type,
      position: { x: piece.position.x, y: piece.position.y, z: piece.position.z },
      rotation: piece.rotation?.y ?? 0,
      material: piece.material?.name ?? 'default',
      health: piece.health
    };
  }

  // ==================== Client Management ====================

  /**
   * Register new client
   */
  addClient(clientId, playerData = {}) {
    this.clients.set(clientId, {
      id: clientId,
      joinedAt: Date.now(),
      ...playerData
    });

    // Send full state sync
    const fullSync = this.deltaCompressor.getDeltaForClient(clientId);
    this.send(clientId, {
      type: MessageType.FULL_SYNC,
      data: fullSync?.serialize(true),
      version: this.stateVersion
    });
  }

  /**
   * Remove client
   */
  removeClient(clientId) {
    this.clients.delete(clientId);
    this.clientPositions.delete(clientId);
    this.deltaCompressor.removeClient(clientId);
    this.rateLimiter.reset(clientId);
  }

  /**
   * Update client position (for spatial queries)
   */
  updateClientPosition(clientId, position) {
    this.clientPositions.set(clientId, position);
  }

  /**
   * Get statistics
   */
  getStats() {
    return {
      ...this.stats,
      clients: this.clients.size,
      stateVersion: this.stateVersion,
      deltaCompressor: this.deltaCompressor.getStats(),
      conflictResolver: this.conflictResolver.getStats()
    };
  }
}

/**
 * Client-side building network manager
 */
export class BuildingNetworkClient {
  constructor(buildingSystem, options = {}) {
    this.buildingSystem = buildingSystem;
    
    // Subsystems
    this.prediction = new ClientPrediction(buildingSystem, {
      predictionTimeout: options.predictionTimeout ?? 5000,
      enableGhostVisuals: options.enableGhostVisuals ?? true,
      sendToServer: (msg) => this.send(msg)
    });
    this.deltaReceiver = new DeltaReceiver();
    
    // Connection state
    this.connected = false;
    this.socket = null;
    this.serverUrl = null;
    
    // Latency tracking
    this.latency = 0;
    this.pingInterval = null;
    this.lastPingTime = 0;
    
    // Callbacks
    this.onConnected = options.onConnected ?? null;
    this.onDisconnected = options.onDisconnected ?? null;
    this.onError = options.onError ?? null;
    this.onPlaceConfirmed = options.onPlaceConfirmed ?? null;
    this.onPlaceRejected = options.onPlaceRejected ?? null;
    
    // Statistics
    this.stats = {
      messagesSent: 0,
      messagesReceived: 0,
      bytesReceived: 0
    };
  }

  /**
   * Connect to server
   */
  connect(serverUrl) {
    this.serverUrl = serverUrl;
    
    // WebSocket connection (implement based on your networking layer)
    this.socket = new WebSocket(serverUrl);
    
    this.socket.onopen = () => {
      this.connected = true;
      this.startPing();
      if (this.onConnected) this.onConnected();
    };
    
    this.socket.onclose = () => {
      this.connected = false;
      this.stopPing();
      if (this.onDisconnected) this.onDisconnected();
    };
    
    this.socket.onerror = (error) => {
      if (this.onError) this.onError(error);
    };
    
    this.socket.onmessage = (event) => {
      this.onMessage(JSON.parse(event.data));
    };
  }

  /**
   * Disconnect from server
   */
  disconnect() {
    if (this.socket) {
      this.socket.close();
      this.socket = null;
    }
    this.connected = false;
    this.stopPing();
  }

  /**
   * Send message to server
   */
  send(message) {
    if (!this.connected || !this.socket) return false;
    
    this.socket.send(JSON.stringify(message));
    this.stats.messagesSent++;
    return true;
  }

  /**
   * Handle incoming message
   */
  onMessage(message) {
    this.stats.messagesReceived++;
    
    switch (message.type) {
      case MessageType.PLACE_CONFIRMED:
        this.handlePlaceConfirmed(message);
        break;
      case MessageType.PLACE_REJECTED:
        this.handlePlaceRejected(message);
        break;
      case MessageType.FULL_SYNC:
      case MessageType.DELTA_UPDATE:
        this.handleStateUpdate(message);
        break;
      case MessageType.PIECE_DESTROYED:
        this.handlePieceDestroyed(message);
        break;
      case MessageType.PIECE_UPDATED:
        this.handlePieceUpdated(message);
        break;
      case MessageType.PONG:
        this.handlePong(message);
        break;
      case MessageType.ERROR:
        this.handleError(message);
        break;
    }
  }

  /**
   * Handle place confirmed
   */
  handlePlaceConfirmed(message) {
    this.prediction.onServerConfirm(message.tempId, message.serverId, message);
    if (this.onPlaceConfirmed) this.onPlaceConfirmed(message);
  }

  /**
   * Handle place rejected
   */
  handlePlaceRejected(message) {
    this.prediction.onServerReject(message.tempId, message.reason);
    if (this.onPlaceRejected) this.onPlaceRejected(message);
  }

  /**
   * Handle state update (full sync or delta)
   */
  handleStateUpdate(message) {
    const result = this.deltaReceiver.apply(message.data, this.buildingSystem);
    
    // Acknowledge receipt
    this.send({
      type: MessageType.ACK,
      version: message.version
    });
    
    // Reconcile predictions with server state
    if (result.type === 'full_sync') {
      this.prediction.reconcileWithServerState(message.data.pieces);
    }
  }

  /**
   * Handle piece destroyed
   */
  handlePieceDestroyed(message) {
    this.buildingSystem.removePieceById(message.pieceId);
    
    // Also remove cascade destroyed pieces
    for (const pieceId of (message.cascade || [])) {
      this.buildingSystem.removePieceById(pieceId);
    }
  }

  /**
   * Handle piece updated
   */
  handlePieceUpdated(message) {
    const piece = this.buildingSystem.getPieceById(message.piece.id);
    if (piece) {
      this.buildingSystem.updatePieceFromNetwork(piece, message.piece);
    } else {
      this.buildingSystem.addPieceFromNetwork(message.piece);
    }
  }

  /**
   * Handle pong
   */
  handlePong(message) {
    this.latency = Date.now() - message.clientTime;
  }

  /**
   * Handle error
   */
  handleError(message) {
    console.error('Server error:', message.error);
    if (this.onError) this.onError(message);
  }

  // ==================== Building Operations ====================

  /**
   * Request piece placement
   */
  placeRequest(pieceType, position, rotation, options = {}) {
    return this.prediction.predictPlace(pieceType, position, rotation, options);
  }

  /**
   * Request piece destruction
   */
  destroyRequest(piece) {
    return this.prediction.predictDestroy(piece);
  }

  /**
   * Request piece upgrade
   */
  upgradeRequest(piece, material) {
    const tempId = this.prediction.generateTempId();
    
    this.send({
      type: MessageType.UPGRADE_REQUEST,
      tempId,
      pieceId: piece.id,
      material
    });
    
    return tempId;
  }

  // ==================== Utilities ====================

  /**
   * Start ping interval
   */
  startPing() {
    this.pingInterval = setInterval(() => {
      this.lastPingTime = Date.now();
      this.send({
        type: MessageType.PING,
        clientTime: this.lastPingTime
      });
    }, 1000);
  }

  /**
   * Stop ping interval
   */
  stopPing() {
    if (this.pingInterval) {
      clearInterval(this.pingInterval);
      this.pingInterval = null;
    }
  }

  /**
   * Update - call every frame
   */
  update(deltaTime) {
    this.prediction.update(deltaTime);
  }

  /**
   * Get latency
   */
  getLatency() {
    return this.latency;
  }

  /**
   * Get statistics
   */
  getStats() {
    return {
      ...this.stats,
      connected: this.connected,
      latency: this.latency,
      prediction: this.prediction.getStats(),
      deltaReceiver: {
        currentVersion: this.deltaReceiver.currentVersion,
        pendingDeltas: this.deltaReceiver.pendingDeltas.length
      }
    };
  }
}

export default { BuildingNetworkServer, BuildingNetworkClient };

/**
 * ClientPrediction - Optimistic placement with rollback for responsive building
 * 
 * Players expect immediate feedback when placing. With network latency,
 * waiting for server confirmation feels sluggish. This system predicts
 * placement locally and reconciles with server responses.
 * 
 * Usage:
 *   const prediction = new ClientPrediction(buildingSystem, networkManager);
 *   const localPiece = prediction.predictPlace(pieceType, position, rotation);
 *   // When server responds:
 *   prediction.onServerConfirm(tempId, serverId, success);
 */

import * as THREE from 'three';

/**
 * Prediction states
 */
export const PredictionState = {
  PENDING: 'pending',       // Waiting for server response
  CONFIRMED: 'confirmed',   // Server accepted
  REJECTED: 'rejected',     // Server rejected
  TIMEOUT: 'timeout',       // No response in time
  CORRECTED: 'corrected'    // Accepted but position adjusted
};

/**
 * Individual prediction record
 */
export class PredictionRecord {
  constructor(tempId, pieceData, options = {}) {
    this.tempId = tempId;
    this.pieceData = pieceData;
    this.localPiece = null;
    
    this.state = PredictionState.PENDING;
    this.serverId = null;
    this.serverData = null;
    this.error = null;
    
    this.createdAt = Date.now();
    this.resolvedAt = null;
    this.timeout = options.timeout ?? 5000;
    this.retryCount = 0;
    this.maxRetries = options.maxRetries ?? 2;
    
    // Callbacks
    this.onConfirm = options.onConfirm ?? null;
    this.onReject = options.onReject ?? null;
    this.onTimeout = options.onTimeout ?? null;
  }

  /**
   * Check if prediction has timed out
   */
  isTimedOut() {
    return this.state === PredictionState.PENDING && 
           Date.now() - this.createdAt > this.timeout;
  }

  /**
   * Mark as confirmed
   */
  confirm(serverId, serverData = null) {
    this.state = serverData?.corrected 
      ? PredictionState.CORRECTED 
      : PredictionState.CONFIRMED;
    this.serverId = serverId;
    this.serverData = serverData;
    this.resolvedAt = Date.now();
    
    if (this.onConfirm) {
      this.onConfirm(this);
    }
  }

  /**
   * Mark as rejected
   */
  reject(error) {
    this.state = PredictionState.REJECTED;
    this.error = error;
    this.resolvedAt = Date.now();
    
    if (this.onReject) {
      this.onReject(this);
    }
  }

  /**
   * Mark as timed out
   */
  markTimeout() {
    this.state = PredictionState.TIMEOUT;
    this.resolvedAt = Date.now();
    
    if (this.onTimeout) {
      this.onTimeout(this);
    }
  }

  /**
   * Get latency (request to response time)
   */
  getLatency() {
    if (!this.resolvedAt) return null;
    return this.resolvedAt - this.createdAt;
  }
}

/**
 * Ghost piece for visual prediction
 */
export class GhostPiece {
  constructor(piece, options = {}) {
    this.piece = piece;
    this.isPredicted = true;
    this.opacity = options.opacity ?? 0.7;
    this.pulseSpeed = options.pulseSpeed ?? 2;
    this.pulseAmount = options.pulseAmount ?? 0.2;
    
    // Visual state
    this.baseOpacity = this.opacity;
    this.currentOpacity = this.opacity;
    this.time = 0;
    
    // Apply ghost appearance
    this.applyGhostMaterial();
  }

  /**
   * Make piece look like a ghost/prediction
   */
  applyGhostMaterial() {
    const mesh = this.piece.mesh || this.piece;
    if (!mesh.material) return;

    // Clone material to avoid affecting others
    if (!mesh._originalMaterial) {
      mesh._originalMaterial = mesh.material;
      mesh.material = mesh.material.clone();
    }

    mesh.material.transparent = true;
    mesh.material.opacity = this.opacity;
    
    // Slight color tint to indicate prediction
    if (mesh.material.color) {
      mesh.material.color.multiplyScalar(1.1);
    }
  }

  /**
   * Update ghost animation
   */
  update(deltaTime) {
    this.time += deltaTime;
    
    // Pulse opacity
    const pulse = Math.sin(this.time * this.pulseSpeed) * this.pulseAmount;
    this.currentOpacity = this.baseOpacity + pulse;
    
    const mesh = this.piece.mesh || this.piece;
    if (mesh.material) {
      mesh.material.opacity = Math.max(0.3, Math.min(0.9, this.currentOpacity));
    }
  }

  /**
   * Convert to solid (confirmed) piece
   */
  solidify() {
    const mesh = this.piece.mesh || this.piece;
    
    if (mesh._originalMaterial) {
      mesh.material = mesh._originalMaterial;
      delete mesh._originalMaterial;
    } else if (mesh.material) {
      mesh.material.transparent = false;
      mesh.material.opacity = 1.0;
    }
    
    this.isPredicted = false;
  }

  /**
   * Fade out and remove
   */
  fadeOut(duration = 300) {
    return new Promise((resolve) => {
      const mesh = this.piece.mesh || this.piece;
      const startOpacity = mesh.material?.opacity ?? 1;
      const startTime = performance.now();

      const animate = () => {
        const elapsed = performance.now() - startTime;
        const progress = Math.min(elapsed / duration, 1);
        
        if (mesh.material) {
          mesh.material.opacity = startOpacity * (1 - progress);
        }

        if (progress < 1) {
          requestAnimationFrame(animate);
        } else {
          resolve();
        }
      };

      animate();
    });
  }
}

/**
 * Main client prediction system
 */
export class ClientPrediction {
  constructor(buildingSystem, options = {}) {
    this.buildingSystem = buildingSystem;
    
    // Configuration
    this.predictionTimeout = options.predictionTimeout ?? 5000;
    this.maxPendingPredictions = options.maxPendingPredictions ?? 10;
    this.enableGhostVisuals = options.enableGhostVisuals ?? true;
    this.autoRetry = options.autoRetry ?? true;
    this.maxRetries = options.maxRetries ?? 2;
    
    // State
    this.predictions = new Map(); // tempId -> PredictionRecord
    this.ghostPieces = new Map(); // tempId -> GhostPiece
    this.tempIdCounter = 0;
    this.serverIdMap = new Map(); // tempId -> serverId (for reconciliation)
    
    // Network interface (set by network manager)
    this.sendToServer = options.sendToServer ?? null;
    
    // Callbacks
    this.onPredictionConfirmed = options.onPredictionConfirmed ?? null;
    this.onPredictionRejected = options.onPredictionRejected ?? null;
    this.onPredictionTimeout = options.onPredictionTimeout ?? null;
    
    // Statistics
    this.stats = {
      totalPredictions: 0,
      confirmed: 0,
      rejected: 0,
      timeouts: 0,
      corrections: 0,
      avgLatency: 0,
      latencySum: 0
    };
  }

  /**
   * Generate unique temporary ID
   */
  generateTempId() {
    return `pred_${Date.now()}_${++this.tempIdCounter}`;
  }

  /**
   * Predict a piece placement
   */
  predictPlace(pieceType, position, rotation, options = {}) {
    // Check prediction limit
    if (this.predictions.size >= this.maxPendingPredictions) {
      console.warn('Too many pending predictions');
      return null;
    }

    const tempId = this.generateTempId();
    
    // Create piece data
    const pieceData = {
      type: pieceType,
      position: position.clone(),
      rotation: rotation?.clone() ?? new THREE.Euler(),
      material: options.material ?? 'default',
      tempId
    };

    // Create local piece immediately
    const localPiece = this.buildingSystem.createPiece(pieceData);
    localPiece.id = tempId;
    localPiece.isPredicted = true;
    
    // Add to building system (but mark as predicted)
    this.buildingSystem.addPredictedPiece(localPiece);

    // Create prediction record
    const record = new PredictionRecord(tempId, pieceData, {
      timeout: this.predictionTimeout,
      maxRetries: this.maxRetries,
      onConfirm: (r) => this.handleConfirm(r),
      onReject: (r) => this.handleReject(r),
      onTimeout: (r) => this.handleTimeout(r)
    });
    record.localPiece = localPiece;
    
    this.predictions.set(tempId, record);
    this.stats.totalPredictions++;

    // Create ghost visual
    if (this.enableGhostVisuals) {
      const ghost = new GhostPiece(localPiece);
      this.ghostPieces.set(tempId, ghost);
    }

    // Send to server
    if (this.sendToServer) {
      this.sendToServer({
        type: 'place_request',
        tempId,
        pieceType,
        position: this.serializeVector(position),
        rotation: this.serializeRotation(rotation),
        material: options.material
      });
    }

    return localPiece;
  }

  /**
   * Predict piece destruction
   */
  predictDestroy(piece) {
    const tempId = this.generateTempId();
    const pieceId = piece.id;

    // Remove locally immediately
    const removedPiece = this.buildingSystem.removePiece(piece);
    
    // Create prediction record
    const record = new PredictionRecord(tempId, {
      action: 'destroy',
      pieceId,
      removedPiece
    }, {
      timeout: this.predictionTimeout,
      onReject: (r) => {
        // Rollback: restore the piece
        if (r.pieceData.removedPiece) {
          this.buildingSystem.addPiece(r.pieceData.removedPiece);
        }
      }
    });

    this.predictions.set(tempId, record);

    // Send to server
    if (this.sendToServer) {
      this.sendToServer({
        type: 'destroy_request',
        tempId,
        pieceId
      });
    }

    return tempId;
  }

  /**
   * Handle server confirmation
   */
  onServerConfirm(tempId, serverId, serverData = null) {
    const record = this.predictions.get(tempId);
    if (!record) return;

    record.confirm(serverId, serverData);
  }

  /**
   * Handle server rejection
   */
  onServerReject(tempId, error) {
    const record = this.predictions.get(tempId);
    if (!record) return;

    record.reject(error);
  }

  /**
   * Internal confirm handler
   */
  handleConfirm(record) {
    const { tempId, serverId, serverData, localPiece } = record;

    // Update piece ID
    if (localPiece) {
      localPiece.id = serverId;
      localPiece.isPredicted = false;
      
      // Apply any server corrections
      if (serverData?.position) {
        const pos = this.deserializeVector(serverData.position);
        if (!localPiece.position.equals(pos)) {
          localPiece.position.copy(pos);
          this.stats.corrections++;
        }
      }
      
      // Register with building system under real ID
      this.buildingSystem.confirmPredictedPiece(tempId, serverId);
    }

    // Solidify ghost
    const ghost = this.ghostPieces.get(tempId);
    if (ghost) {
      ghost.solidify();
      this.ghostPieces.delete(tempId);
    }

    // Track mapping
    this.serverIdMap.set(tempId, serverId);

    // Update stats
    this.stats.confirmed++;
    const latency = record.getLatency();
    if (latency) {
      this.stats.latencySum += latency;
      this.stats.avgLatency = this.stats.latencySum / this.stats.confirmed;
    }

    // Clean up
    this.predictions.delete(tempId);

    // Callback
    if (this.onPredictionConfirmed) {
      this.onPredictionConfirmed(record);
    }
  }

  /**
   * Internal reject handler
   */
  handleReject(record) {
    const { tempId, localPiece, error } = record;

    // Remove predicted piece
    if (localPiece) {
      this.buildingSystem.removePredictedPiece(tempId);
    }

    // Fade out ghost
    const ghost = this.ghostPieces.get(tempId);
    if (ghost) {
      ghost.fadeOut().then(() => {
        this.ghostPieces.delete(tempId);
      });
    }

    // Update stats
    this.stats.rejected++;

    // Clean up
    this.predictions.delete(tempId);

    // Callback
    if (this.onPredictionRejected) {
      this.onPredictionRejected(record, error);
    }
  }

  /**
   * Internal timeout handler
   */
  handleTimeout(record) {
    const { tempId, localPiece } = record;

    // Retry if enabled
    if (this.autoRetry && record.retryCount < record.maxRetries) {
      record.retryCount++;
      record.createdAt = Date.now();
      record.state = PredictionState.PENDING;
      
      // Resend request
      if (this.sendToServer) {
        this.sendToServer({
          type: 'place_request',
          tempId,
          pieceType: record.pieceData.type,
          position: this.serializeVector(record.pieceData.position),
          rotation: this.serializeRotation(record.pieceData.rotation),
          retry: record.retryCount
        });
      }
      return;
    }

    // Remove predicted piece
    if (localPiece) {
      this.buildingSystem.removePredictedPiece(tempId);
    }

    // Remove ghost
    const ghost = this.ghostPieces.get(tempId);
    if (ghost) {
      ghost.fadeOut().then(() => {
        this.ghostPieces.delete(tempId);
      });
    }

    // Update stats
    this.stats.timeouts++;

    // Clean up
    this.predictions.delete(tempId);

    // Callback
    if (this.onPredictionTimeout) {
      this.onPredictionTimeout(record);
    }
  }

  /**
   * Update predictions - call every frame
   */
  update(deltaTime) {
    // Check for timeouts
    for (const [tempId, record] of this.predictions) {
      if (record.isTimedOut()) {
        record.markTimeout();
      }
    }

    // Update ghost visuals
    for (const ghost of this.ghostPieces.values()) {
      ghost.update(deltaTime);
    }
  }

  /**
   * Get pending prediction count
   */
  getPendingCount() {
    return this.predictions.size;
  }

  /**
   * Check if a piece is predicted
   */
  isPredicted(pieceOrId) {
    const id = pieceOrId.id ?? pieceOrId;
    return this.predictions.has(id);
  }

  /**
   * Get real server ID for a temp ID
   */
  getServerId(tempId) {
    return this.serverIdMap.get(tempId);
  }

  /**
   * Reconcile with server state (after full sync)
   */
  reconcileWithServerState(serverPieces) {
    // Remove any predictions that conflict with server state
    for (const [tempId, record] of this.predictions) {
      const localPiece = record.localPiece;
      if (!localPiece) continue;

      // Check if server has a piece at same position
      const conflicting = serverPieces.find(sp => 
        this.vectorsEqual(sp.position, localPiece.position)
      );

      if (conflicting) {
        // Server has authoritative piece - remove prediction
        this.handleReject(record);
      }
    }
  }

  /**
   * Serialize vector for network
   */
  serializeVector(v) {
    return { x: v.x, y: v.y, z: v.z };
  }

  /**
   * Deserialize vector from network
   */
  deserializeVector(data) {
    return new THREE.Vector3(data.x, data.y, data.z);
  }

  /**
   * Serialize rotation for network
   */
  serializeRotation(r) {
    if (!r) return { y: 0 };
    return { x: r.x, y: r.y, z: r.z };
  }

  /**
   * Compare vectors
   */
  vectorsEqual(a, b, tolerance = 0.01) {
    if (!a || !b) return false;
    return (
      Math.abs(a.x - b.x) < tolerance &&
      Math.abs(a.y - b.y) < tolerance &&
      Math.abs(a.z - b.z) < tolerance
    );
  }

  /**
   * Get statistics
   */
  getStats() {
    return {
      ...this.stats,
      pending: this.predictions.size,
      ghosts: this.ghostPieces.size,
      confirmRate: this.stats.totalPredictions > 0
        ? Math.round(this.stats.confirmed / this.stats.totalPredictions * 100) + '%'
        : 'N/A',
      avgLatencyMs: Math.round(this.stats.avgLatency)
    };
  }

  /**
   * Reset statistics
   */
  resetStats() {
    this.stats = {
      totalPredictions: 0,
      confirmed: 0,
      rejected: 0,
      timeouts: 0,
      corrections: 0,
      avgLatency: 0,
      latencySum: 0
    };
  }

  /**
   * Clear all predictions
   */
  clear() {
    // Remove all predicted pieces
    for (const [tempId, record] of this.predictions) {
      if (record.localPiece) {
        this.buildingSystem.removePredictedPiece(tempId);
      }
    }

    this.predictions.clear();
    this.ghostPieces.clear();
    this.serverIdMap.clear();
  }
}

export default ClientPrediction;

/**
 * ConflictResolver - Handle simultaneous building operations from multiple players
 * 
 * When two players try to place at the same position at the same time,
 * or modify the same piece, this system determines who wins and how
 * to notify the losing party.
 * 
 * Supports multiple resolution strategies:
 * - First-write-wins (simplest)
 * - Timestamp-based (fairest with clock sync)
 * - Lock-based (most robust)
 * - Optimistic with version checking
 * 
 * Usage:
 *   const resolver = new ConflictResolver({ strategy: 'timestamp' });
 *   const result = resolver.resolvePlace(request1, request2);
 */

/**
 * Resolution strategies
 */
export const ResolutionStrategy = {
  FIRST_WRITE: 'first_write',     // First request to arrive wins
  TIMESTAMP: 'timestamp',          // Earlier client timestamp wins
  LOCK: 'lock',                    // Pre-acquired locks required
  OPTIMISTIC: 'optimistic'        // Version-based conflict detection
};

/**
 * Conflict types
 */
export const ConflictType = {
  POSITION: 'position',            // Same placement position
  PIECE: 'piece',                  // Same piece modified
  REGION: 'region',                // Same building region
  RESOURCE: 'resource'            // Same resource consumed
};

/**
 * Conflict result
 */
export class ConflictResult {
  constructor(winner, loser, type) {
    this.winner = winner;
    this.loser = loser;
    this.type = type;
    this.timestamp = Date.now();
    this.reason = null;
  }

  setReason(reason) {
    this.reason = reason;
    return this;
  }
}

/**
 * Lock for region-based conflict prevention
 */
export class RegionLock {
  constructor(region, owner, options = {}) {
    this.region = region;
    this.owner = owner;
    this.createdAt = Date.now();
    this.expiresAt = options.expiresAt ?? Date.now() + 30000; // 30s default
    this.authorized = new Set([owner]);
  }

  isExpired() {
    return Date.now() > this.expiresAt;
  }

  isAuthorized(playerId) {
    return this.authorized.has(playerId);
  }

  authorize(playerId) {
    this.authorized.add(playerId);
  }

  revoke(playerId) {
    if (playerId !== this.owner) {
      this.authorized.delete(playerId);
    }
  }

  extend(duration = 30000) {
    this.expiresAt = Date.now() + duration;
  }
}

/**
 * Pending request for conflict window
 */
class PendingRequest {
  constructor(request, client) {
    this.request = request;
    this.client = client;
    this.receivedAt = Date.now();
    this.clientTimestamp = request.timestamp ?? Date.now();
    this.position = request.position;
    this.pieceId = request.pieceId;
    this.processed = false;
    this.result = null;
  }
}

/**
 * Main conflict resolver
 */
export class ConflictResolver {
  constructor(options = {}) {
    this.strategy = options.strategy ?? ResolutionStrategy.FIRST_WRITE;
    this.conflictWindow = options.conflictWindow ?? 100; // ms to wait for conflicts
    this.positionTolerance = options.positionTolerance ?? 0.5; // units
    this.enableLocking = options.enableLocking ?? false;
    this.maxClockSkew = options.maxClockSkew ?? 1000; // Max allowed clock difference
    
    // State
    this.pendingRequests = [];
    this.locks = new Map(); // regionKey -> RegionLock
    this.pieceVersions = new Map(); // pieceId -> version
    this.processTimer = null;
    
    // Callbacks
    this.onConflictResolved = options.onConflictResolved ?? null;
    this.onRequestProcessed = options.onRequestProcessed ?? null;
    
    // Statistics
    this.stats = {
      requestsProcessed: 0,
      conflictsDetected: 0,
      conflictsResolved: 0,
      lockDenials: 0
    };
  }

  /**
   * Submit a placement request
   */
  submitPlaceRequest(request, client) {
    const pending = new PendingRequest(request, client);
    this.pendingRequests.push(pending);
    
    // Schedule processing after conflict window
    this.scheduleProcessing();
    
    return pending;
  }

  /**
   * Submit a modification request
   */
  submitModifyRequest(request, client) {
    // Modifications can be processed immediately with version check
    if (this.strategy === ResolutionStrategy.OPTIMISTIC) {
      return this.processOptimisticModify(request, client);
    }
    
    const pending = new PendingRequest(request, client);
    pending.pieceId = request.pieceId;
    this.pendingRequests.push(pending);
    
    this.scheduleProcessing();
    return pending;
  }

  /**
   * Schedule batch processing of pending requests
   */
  scheduleProcessing() {
    if (this.processTimer) return;
    
    this.processTimer = setTimeout(() => {
      this.processTimer = null;
      this.processPendingRequests();
    }, this.conflictWindow);
  }

  /**
   * Process all pending requests
   */
  processPendingRequests() {
    if (this.pendingRequests.length === 0) return;

    // Group by conflict potential
    const positionGroups = this.groupByPosition(this.pendingRequests);
    const pieceGroups = this.groupByPiece(this.pendingRequests);

    // Process position conflicts (placements)
    for (const group of positionGroups.values()) {
      if (group.length > 1) {
        this.resolvePositionConflict(group);
      } else {
        this.processRequest(group[0]);
      }
    }

    // Process piece conflicts (modifications)
    for (const group of pieceGroups.values()) {
      if (group.length > 1) {
        this.resolvePieceConflict(group);
      } else if (!group[0].processed) {
        this.processRequest(group[0]);
      }
    }

    // Clear processed requests
    this.pendingRequests = this.pendingRequests.filter(r => !r.processed);
  }

  /**
   * Group requests by position
   */
  groupByPosition(requests) {
    const groups = new Map();
    
    for (const req of requests) {
      if (!req.position) continue;
      
      const key = this.getPositionKey(req.position);
      if (!groups.has(key)) {
        groups.set(key, []);
      }
      groups.get(key).push(req);
    }
    
    return groups;
  }

  /**
   * Group requests by piece ID
   */
  groupByPiece(requests) {
    const groups = new Map();
    
    for (const req of requests) {
      if (!req.pieceId) continue;
      
      if (!groups.has(req.pieceId)) {
        groups.set(req.pieceId, []);
      }
      groups.get(req.pieceId).push(req);
    }
    
    return groups;
  }

  /**
   * Get position key for grouping
   */
  getPositionKey(position) {
    const x = Math.round(position.x / this.positionTolerance);
    const y = Math.round(position.y / this.positionTolerance);
    const z = Math.round(position.z / this.positionTolerance);
    return `${x},${y},${z}`;
  }

  /**
   * Resolve conflict between placement requests
   */
  resolvePositionConflict(requests) {
    this.stats.conflictsDetected++;
    
    let winner;
    
    switch (this.strategy) {
      case ResolutionStrategy.FIRST_WRITE:
        winner = this.resolveFirstWrite(requests);
        break;
      case ResolutionStrategy.TIMESTAMP:
        winner = this.resolveByTimestamp(requests);
        break;
      case ResolutionStrategy.LOCK:
        winner = this.resolveByLock(requests);
        break;
      default:
        winner = this.resolveFirstWrite(requests);
    }

    // Process winner
    this.processRequest(winner);

    // Reject losers
    for (const req of requests) {
      if (req !== winner) {
        this.rejectRequest(req, 'Position conflict - another player placed first');
      }
    }

    this.stats.conflictsResolved++;
    
    // Callback
    if (this.onConflictResolved) {
      this.onConflictResolved(new ConflictResult(winner, requests.filter(r => r !== winner), ConflictType.POSITION));
    }
  }

  /**
   * Resolve conflict between piece modification requests
   */
  resolvePieceConflict(requests) {
    this.stats.conflictsDetected++;
    
    // For piece modifications, usually last write wins (most recent state)
    // Or use optimistic locking
    let winner;
    
    if (this.strategy === ResolutionStrategy.OPTIMISTIC) {
      // Find request with correct version
      const currentVersion = this.pieceVersions.get(requests[0].pieceId) ?? 0;
      winner = requests.find(r => r.request.version === currentVersion);
      
      if (!winner) {
        // All stale - reject all
        for (const req of requests) {
          this.rejectRequest(req, 'Piece was modified by another player');
        }
        return;
      }
    } else {
      winner = this.resolveByTimestamp(requests);
    }

    this.processRequest(winner);

    for (const req of requests) {
      if (req !== winner) {
        this.rejectRequest(req, 'Piece modification conflict');
      }
    }

    this.stats.conflictsResolved++;
  }

  /**
   * First-write-wins resolution
   */
  resolveFirstWrite(requests) {
    return requests.reduce((earliest, req) => 
      req.receivedAt < earliest.receivedAt ? req : earliest
    );
  }

  /**
   * Timestamp-based resolution
   */
  resolveByTimestamp(requests) {
    // Adjust for potential clock skew
    const adjusted = requests.map(req => ({
      req,
      adjustedTime: this.adjustTimestamp(req.clientTimestamp, req.client)
    }));

    return adjusted.reduce((earliest, curr) => 
      curr.adjustedTime < earliest.adjustedTime ? curr : earliest
    ).req;
  }

  /**
   * Lock-based resolution
   */
  resolveByLock(requests) {
    // Find request from lock holder
    for (const req of requests) {
      const regionKey = this.getRegionKey(req.position);
      const lock = this.locks.get(regionKey);
      
      if (lock && lock.isAuthorized(req.client.id) && !lock.isExpired()) {
        return req;
      }
    }
    
    // No valid lock holder - fall back to first-write
    return this.resolveFirstWrite(requests);
  }

  /**
   * Adjust timestamp for clock skew
   */
  adjustTimestamp(clientTimestamp, client) {
    const clockOffset = client.clockOffset ?? 0;
    return clientTimestamp - clockOffset;
  }

  /**
   * Process a winning request
   */
  processRequest(pending) {
    pending.processed = true;
    pending.result = { success: true };
    this.stats.requestsProcessed++;

    // Update version for piece modifications
    if (pending.pieceId) {
      const currentVersion = this.pieceVersions.get(pending.pieceId) ?? 0;
      this.pieceVersions.set(pending.pieceId, currentVersion + 1);
    }

    if (this.onRequestProcessed) {
      this.onRequestProcessed(pending, true);
    }
  }

  /**
   * Reject a losing request
   */
  rejectRequest(pending, reason) {
    pending.processed = true;
    pending.result = { success: false, reason };

    if (this.onRequestProcessed) {
      this.onRequestProcessed(pending, false, reason);
    }
  }

  /**
   * Process optimistic modify request
   */
  processOptimisticModify(request, client) {
    const pieceId = request.pieceId;
    const requestVersion = request.version;
    const currentVersion = this.pieceVersions.get(pieceId) ?? 0;

    if (requestVersion !== currentVersion) {
      return {
        success: false,
        reason: 'Version mismatch - piece was modified',
        currentVersion,
        needsResync: true
      };
    }

    // Update version
    this.pieceVersions.set(pieceId, currentVersion + 1);
    this.stats.requestsProcessed++;

    return {
      success: true,
      newVersion: currentVersion + 1
    };
  }

  // ==================== Lock Management ====================

  /**
   * Acquire a lock on a region
   */
  acquireLock(position, playerId, options = {}) {
    if (!this.enableLocking) {
      return { success: false, reason: 'Locking not enabled' };
    }

    const regionKey = this.getRegionKey(position);
    const existing = this.locks.get(regionKey);

    // Check for existing non-expired lock
    if (existing && !existing.isExpired()) {
      if (existing.owner === playerId) {
        // Extend existing lock
        existing.extend(options.duration);
        return { success: true, extended: true, lock: existing };
      }
      
      this.stats.lockDenials++;
      return { 
        success: false, 
        reason: 'Region locked by another player',
        owner: existing.owner
      };
    }

    // Create new lock
    const lock = new RegionLock(regionKey, playerId, options);
    this.locks.set(regionKey, lock);

    return { success: true, lock };
  }

  /**
   * Release a lock
   */
  releaseLock(position, playerId) {
    const regionKey = this.getRegionKey(position);
    const lock = this.locks.get(regionKey);

    if (!lock) {
      return { success: false, reason: 'No lock found' };
    }

    if (lock.owner !== playerId) {
      return { success: false, reason: 'Not lock owner' };
    }

    this.locks.delete(regionKey);
    return { success: true };
  }

  /**
   * Check if player can modify in region
   */
  canModifyRegion(position, playerId) {
    if (!this.enableLocking) return true;

    const regionKey = this.getRegionKey(position);
    const lock = this.locks.get(regionKey);

    if (!lock || lock.isExpired()) return true;
    return lock.isAuthorized(playerId);
  }

  /**
   * Get region key from position
   */
  getRegionKey(position) {
    // Larger regions than position tolerance
    const regionSize = 10;
    const x = Math.floor(position.x / regionSize);
    const z = Math.floor(position.z / regionSize);
    return `region_${x}_${z}`;
  }

  /**
   * Clean up expired locks
   */
  cleanupExpiredLocks() {
    for (const [key, lock] of this.locks) {
      if (lock.isExpired()) {
        this.locks.delete(key);
      }
    }
  }

  // ==================== Version Management ====================

  /**
   * Get current version of a piece
   */
  getPieceVersion(pieceId) {
    return this.pieceVersions.get(pieceId) ?? 0;
  }

  /**
   * Set piece version (for sync)
   */
  setPieceVersion(pieceId, version) {
    this.pieceVersions.set(pieceId, version);
  }

  /**
   * Remove piece version tracking
   */
  removePieceVersion(pieceId) {
    this.pieceVersions.delete(pieceId);
  }

  // ==================== Utilities ====================

  /**
   * Set resolution strategy
   */
  setStrategy(strategy) {
    this.strategy = strategy;
  }

  /**
   * Get statistics
   */
  getStats() {
    return {
      ...this.stats,
      pendingRequests: this.pendingRequests.length,
      activeLocks: this.locks.size,
      trackedPieces: this.pieceVersions.size,
      strategy: this.strategy
    };
  }

  /**
   * Reset statistics
   */
  resetStats() {
    this.stats = {
      requestsProcessed: 0,
      conflictsDetected: 0,
      conflictsResolved: 0,
      lockDenials: 0
    };
  }

  /**
   * Clear all state
   */
  clear() {
    this.pendingRequests = [];
    this.locks.clear();
    this.pieceVersions.clear();
    
    if (this.processTimer) {
      clearTimeout(this.processTimer);
      this.processTimer = null;
    }
  }
}

/**
 * Permission system for building regions (Rust Tool Cupboard style)
 */
export class BuildingPermissionSystem {
  constructor(options = {}) {
    this.regions = new Map(); // regionId -> { owner, authorized, bounds }
    this.defaultAllow = options.defaultAllow ?? true; // Allow building outside regions
    this.regionRadius = options.regionRadius ?? 50;
  }

  /**
   * Claim a region
   */
  claimRegion(playerId, position) {
    // Check for overlapping claims
    for (const [id, region] of this.regions) {
      if (this.regionsOverlap(region.center, position, this.regionRadius)) {
        if (region.owner !== playerId) {
          return { 
            success: false, 
            reason: 'Overlaps existing claim',
            owner: region.owner
          };
        }
      }
    }

    const regionId = `claim_${Date.now()}_${playerId}`;
    this.regions.set(regionId, {
      id: regionId,
      owner: playerId,
      authorized: new Set([playerId]),
      center: { x: position.x, y: position.y, z: position.z },
      radius: this.regionRadius,
      createdAt: Date.now()
    });

    return { success: true, regionId };
  }

  /**
   * Check if player can build at position
   */
  canBuild(playerId, position) {
    const region = this.getRegionAt(position);
    
    if (!region) {
      return this.defaultAllow;
    }

    return region.authorized.has(playerId);
  }

  /**
   * Authorize player in region
   */
  authorize(ownerId, playerId, regionId) {
    const region = this.regions.get(regionId);
    
    if (!region || region.owner !== ownerId) {
      return { success: false, reason: 'Not region owner' };
    }

    region.authorized.add(playerId);
    return { success: true };
  }

  /**
   * Revoke player authorization
   */
  revoke(ownerId, playerId, regionId) {
    const region = this.regions.get(regionId);
    
    if (!region || region.owner !== ownerId) {
      return { success: false, reason: 'Not region owner' };
    }

    if (playerId === ownerId) {
      return { success: false, reason: 'Cannot revoke owner' };
    }

    region.authorized.delete(playerId);
    return { success: true };
  }

  /**
   * Get region at position
   */
  getRegionAt(position) {
    for (const region of this.regions.values()) {
      const dist = Math.sqrt(
        Math.pow(position.x - region.center.x, 2) +
        Math.pow(position.z - region.center.z, 2)
      );
      
      if (dist <= region.radius) {
        return region;
      }
    }
    return null;
  }

  /**
   * Check if two regions overlap
   */
  regionsOverlap(center1, center2, radius) {
    const dist = Math.sqrt(
      Math.pow(center1.x - center2.x, 2) +
      Math.pow(center1.z - center2.z, 2)
    );
    return dist < radius * 2;
  }

  /**
   * Get all regions owned by player
   */
  getPlayerRegions(playerId) {
    const owned = [];
    for (const region of this.regions.values()) {
      if (region.owner === playerId) {
        owned.push(region);
      }
    }
    return owned;
  }

  /**
   * Remove region
   */
  removeRegion(regionId, playerId) {
    const region = this.regions.get(regionId);
    
    if (!region || region.owner !== playerId) {
      return { success: false, reason: 'Not region owner' };
    }

    this.regions.delete(regionId);
    return { success: true };
  }
}

export default ConflictResolver;