builder-ux

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Builder UX

Builder UX

Prefabs, blueprints, undo/redo, selection, and preview systems for building mechanics.
适用于建筑机制的预制件、蓝图、撤销/重做、选择及预览系统。

Quick Start

快速开始

javascript
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();
javascript
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();

Reference

参考资料

See
references/builder-ux-advanced.md
for:
  • Command pattern with PlaceCommand, RemoveCommand, UpgradeCommand, BatchCommand
  • Blueprint serialization format and versioning
  • Ghost preview rendering with pulse animation
  • Selection systems: single, additive, box, radius, connected
  • Copy/paste and blueprint sharing
请查看
references/builder-ux-advanced.md
获取以下内容:
  • 包含PlaceCommand、RemoveCommand、UpgradeCommand、BatchCommand的命令模式
  • 蓝图序列化格式与版本控制
  • 带脉冲动画的虚影预览渲染
  • 选择系统:单选、累加选、框选、半径选、关联选
  • 复制/粘贴及蓝图共享

Scripts

脚本文件

FileLinesPurpose
blueprint-manager.js
~450Save, load, export/import building designs
command-history.js
~400Undo/redo stack with command pattern
ghost-preview.js
~380Transparent placement preview with snapping
selection-manager.js
~420Multi-select, box select, group operations
文件行数用途
blueprint-manager.js
~450保存、加载、导出/导入建筑设计
command-history.js
~400基于命令模式的撤销/重做栈
ghost-preview.js
~380带吸附功能的半透明放置预览
selection-manager.js
~420多选、框选、组操作管理

Key Patterns

核心模式

Command Pattern

命令模式

Every building action becomes a command with
execute()
and
undo()
. This enables:
  • Undo/redo for free
  • Network replication (serialize command, send to server)
  • Macro recording (save command sequences)
  • Validation before execution
每个建筑操作都成为带有
execute()
undo()
方法的命令。这实现了:
  • 原生支持撤销/重做
  • 网络同步(序列化命令并发送至服务器)
  • 宏录制(保存命令序列)
  • 执行前验证

Blueprint System

蓝图系统

Blueprints store relative positions, making them position and rotation independent. Key features:
  • Auto-centering on save
  • Rotation support on load
  • Export/import for sharing
  • Thumbnail generation
蓝图存储相对位置,使其与绝对位置和旋转无关。核心特性:
  • 保存时自动居中
  • 加载时支持旋转
  • 导出/导入以实现共享
  • 缩略图生成

Ghost Preview

虚影预览

Shows placement intent before commitment:
  • Green = valid placement
  • Red = invalid (collision, no support)
  • Orange = blocked (permissions)
  • Pulse animation for visibility
  • Grid/rotation snapping
在确认操作前展示放置意图:
  • 绿色 = 有效放置
  • 红色 = 无效(碰撞、无支撑)
  • 橙色 = 受限(权限问题)
  • 脉冲动画提升可见性
  • 网格/旋转吸附

Selection Manager

选择管理器

Supports multiple selection modes:
  • Single click (replace selection)
  • Shift+click (additive)
  • Ctrl+click (toggle)
  • Box select (screen space)
  • Radius select (world space)
  • Connected select (flood fill)
支持多种选择模式:
  • 单击(替换当前选择)
  • Shift+单击(累加选择)
  • Ctrl+单击(切换选择状态)
  • 框选(屏幕空间)
  • 半径选(世界空间)
  • 关联选(泛洪填充)

Integration

集成示例

javascript
// 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 };
}
javascript
// 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 };
}

Design Philosophy

设计理念

Building UX separates intent from execution. The ghost preview shows what will happen, the command executes it, and the history allows reversal. This separation enables blueprint placement (preview entire structure), batch undo (reverse multiple operations), and networked building (commands serialize for transmission).
建筑操作用户体验系统将操作意图与执行分离。虚影预览展示操作结果,命令执行操作,历史记录支持撤销。这种分离实现了蓝图放置(预览整个结构)、批量撤销(反转多项操作)以及联网建筑(命令可序列化以传输)。