builder-ux

建造 UX

用于建造机制的预制件、蓝图、撤销/重做、选择和预览系统。

快速开始

import { BlueprintManager } from './scripts/blueprint-manager.js';
import { CommandHistory, PlaceCommand, BatchCommand } from './scripts/command-history.js';
import { GhostPreview } from './scripts/ghost-preview.js';
import { SelectionManager } from './scripts/selection-manager.js';

// Initialize systems
const blueprints = new BlueprintManager();
const history = new CommandHistory({ maxSize: 50 });
const ghost = new GhostPreview(scene);
const selection = new SelectionManager({ maxSelection: 100 });

// Save selected pieces as blueprint
const { blueprint } = blueprints.save(selection.getSelection(), 'My Base');

// Load blueprint at new position
const { pieces } = blueprints.load(blueprint.id, newPosition, rotation);

// Place with undo support
history.execute(new PlaceCommand(pieceData, position, rotation, buildingSystem));
history.undo(); // Removes piece
history.redo(); // Restores piece

// Ghost preview with validity feedback
ghost.show('wall', cursorPosition, rotation);
ghost.setValid(canPlace); // Green/red color
ghost.updatePosition(newCursorPosition);

// Multi-select with box selection
selection.boxSelect(startNDC, endNDC, camera, allPieces);
selection.selectConnected(startPiece, getNeighbors); // Flood fill

// Batch operations
history.beginGroup('Delete selection');
for (const piece of selection.getSelection()) {
  history.execute(new RemoveCommand(piece, buildingSystem));
}
history.endGroup();

参考

请参阅 references/builder-ux-advanced.md，了解：

• 使用 PlaceCommand、RemoveCommand、UpgradeCommand 和 BatchCommand 的命令模式
• 蓝图序列化格式和版本管理
• 带脉冲动画的幽灵预览渲染
• 选择系统：单选、追加选择、框选、半径选择、连通选择
• 复制/粘贴和蓝图共享

脚本

文件	行数	用途
blueprint-manager.js	~450	保存、加载、导出/导入建造设计
command-history.js	~400	基于命令模式的撤销/重做堆栈
ghost-preview.js	~380	带吸附功能的透明放置预览
selection-manager.js	~420	多选、框选和分组操作

核心模式

命令模式

每个建造操作都会变成一个包含 execute() 和 undo() 的命令。这样即可实现：

• 轻松实现撤销/重做
• 网络复制（序列化命令并发送到服务端）
• 宏录制（保存命令序列）
• 执行前验证

蓝图系统

蓝图存储相对位置，因此与位置和旋转无关。主要功能：

• 保存时自动居中
• 加载时支持旋转
• 导出/导入以供分享
• 生成缩略图

幽灵预览

在确认前显示放置意图：

• 绿色 = 可放置
• 红色 = 无效（碰撞、缺少支撑）
• 橙色 = 受阻（权限限制）
• 脉冲动画便于查看
• 网格/旋转吸附

选择管理器

支持多种选择模式：

• 单击（替换选择）
• Shift+单击（追加选择）
• Ctrl+单击（切换选择）
• 框选（屏幕空间）
• 半径选择（世界空间）
• 连通选择（洪泛填充）

集成

// Full integration example
function setupBuildingUX(scene, buildingSystem) {
  const history = new CommandHistory({
    maxSize: 100,
    onChange: (status) => updateUndoRedoButtons(status)
  });
  
  const ghost = new GhostPreview(scene, {
    validColor: 0x00ff00,
    invalidColor: 0xff0000,
    snapGrid: 2,
    snapRotation: Math.PI / 4
  });
  
  const selection = new SelectionManager({
    maxSelection: 200,
    onSelectionChanged: (pieces) => updateSelectionUI(pieces)
  });
  
  const blueprints = new BlueprintManager({
    storage: localStorage,
    maxBlueprints: 50
  });
  
  // Keyboard shortcuts
  document.addEventListener('keydown', (e) => {
    if (e.ctrlKey && e.key === 'z') history.undo();
    if (e.ctrlKey && e.key === 'y') history.redo();
    if (e.ctrlKey && e.key === 'c') copySelection();
    if (e.ctrlKey && e.key === 'v') pasteBlueprint();
    if (e.key === 'r') ghost.rotate(Math.PI / 4);
  });
  
  return { history, ghost, selection, blueprints };
}

设计理念

建造 UX 将意图与执行分离。幽灵预览显示将要发生的操作，命令负责执行，历史记录则支持撤销。这种分离支持蓝图放置（预览整个结构）、批量撤销（撤销多项操作）和联网建造（序列化命令以便传输）。