builder-ux
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseBuilder 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 for:
references/builder-ux-advanced.md- 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
脚本文件
| File | Lines | Purpose |
|---|---|---|
| ~450 | Save, load, export/import building designs |
| ~400 | Undo/redo stack with command pattern |
| ~380 | Transparent placement preview with snapping |
| ~420 | Multi-select, box select, group operations |
| 文件 | 行数 | 用途 |
|---|---|---|
| ~450 | 保存、加载、导出/导入建筑设计 |
| ~400 | 基于命令模式的撤销/重做栈 |
| ~380 | 带吸附功能的半透明放置预览 |
| ~420 | 多选、框选、组操作管理 |
Key Patterns
核心模式
Command Pattern
命令模式
Every building action becomes a command with and . This enables:
execute()undo()- 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).
建筑操作用户体验系统将操作意图与执行分离。虚影预览展示操作结果,命令执行操作,历史记录支持撤销。这种分离实现了蓝图放置(预览整个结构)、批量撤销(反转多项操作)以及联网建筑(命令可序列化以传输)。