# terrain-schematic

**Repository Path**: ifishcool/terrain-schematic

## Basic Information

- **Project Name**: terrain-schematic
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-06
- **Last Updated**: 2025-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TerrainSchematic - 适用于神岛的地形蓝图库

一个功能强大的 TypeScript 库，用于在游戏中以程序化的方式创建、操作和导入 3D 结构（蓝图）。它提供了流畅的链式 API，使你能够轻松地组合复杂的操作。

![](https://static.codemao.cn/pickduck/Bk84TwjHel.png?hash=FkdWjxa8ZvHnIfyJqEyfsDi6BiMB)

地图演示：https://dao3.fun/exp/experience/detail/100478935

地图示例代码：https://codecopy.cn/post/a1z0k3

## 核心特性

- **程序化形状生成**: 快速创建球体、长方体、圆柱、金字塔、圆环、棱柱等多种几何形状。
- **文字生成**: 支持从字符串生成 3D 文字。
- **路径构建**: 能够沿着自定义路径（支持贝塞尔平滑）创建复杂的结构，如墙壁和管道。
- **流畅的链式 API**: 所有修改操作都会返回实例本身，让你可以像 `schematic.rotate(...).flip(...).import()` 这样进行链式调用。
- **高级变换**: 支持围绕自定义轴心点进行旋转、缩放、翻转和镜像。
- **布尔运算**: 支持对两个蓝图进行并集 (`add`)、差集 (`subtract`) 和交集 (`intersect`) 操作。
- **强大的特效滤镜**: 内置侵蚀、平滑、锐化、腐朽、线框、外壳等多种效果。
- **高级方块替换**: 不仅可以进行简单的 1:1 替换，还支持基于权重的模式匹配替换，轻松创造自然纹理。
- **与游戏世界交互**: 支持从游戏世界中导出地形，或将蓝图异步/同步地导入到世界中。
- **分析与导出**: 可以获取蓝图的尺寸、计算所需材料，或将其导出为 JSON 数据。

## 安装

```bash
npm install @dao3fun/terrain-schematic
```

## 快速上手

下面是一个简单的例子，创建一个半径为 10 的空心石球，然后将其放置在世界坐标 `(0, 100, 0)` 处。

```typescript
import { TerrainSchematic, SphereOptions } from "@dao3fun/terrain-schematic";

// 定义球体的选项
const options: SphereOptions = {
  isHollow: true,
  thickness: 2,
};

// 使用静态方法创建蓝图，然后链式调用导入方法
TerrainSchematic.fromSphere(10, 1, 0, options) // 半径10, 方块ID 1 (石头), 旋转0
  .import(new GameVector3(0, 100, 0));
```

## API 概览

### 1. 导出与导入

你可以轻松地将地形蓝图导出为可序列化的 JavaScript 对象，以便存储或传输，然后再从该对象导入，恢复为 `TerrainSchematic` 实例。

**导出为数据对象:**

```typescript
// 捕获一个 32x64x32 区域的地形
const bounds = new GameBounds3(
  new GameVector3(1, 1, 1),
  new GameVector3(32, 64, 32)
);
// 创建蓝图
const schematic = new TerrainSchematic(bounds);

// 当玩家加入时，将蓝图数据复制到玩家的剪贴板
world.onPlayerJoin(({ entity }) => {
  schematic.copyJSON(entity);
});
```

**从数据对象导入:**

```typescript
// 导入蓝图JSON数据
import map from "map.json";

// 从数据创建实例
const newSchematic = TerrainSchematic.fromData(map);

// 导入地形到地图中
newSchematic.import(new GameVector3(1, 1, 1));
```

### 2. 创建蓝图

有多种方式可以创建 `TerrainSchematic` 实例。

**从游戏世界中捕获:**

```typescript
// 捕获一个 32x64x32 区域的地形
const bounds = new GameBounds3(
  new GameVector3(1, 1, 1),
  new GameVector3(32, 64, 32)
);
const schematic = new TerrainSchematic(bounds);
```

**从预设几何体创建 (静态方法):**

```typescript
// 创建一个长方体
const wall = TerrainSchematic.fromCuboid(new GameVector3(10, 5, 1), 1);

// 创建一个圆锥
const cone = TerrainSchematic.fromCone(8, 12, 45); // 半径8, 高度12, 方块ID 45

// 创建一个六棱柱
const pillar = TerrainSchematic.fromPrism(6, 5, 20, 1); // 6条边, 半径5, 高度20
```

_支持的静态创建方法包括: `fromSphere`, `fromCylinder`, `fromPyramid`, `fromCuboid`, `fromTorus`, `fromPipe`, `fromCapsule`, `fromCone`, `fromPrism`, `fromText`_

### 2. 操作蓝图 (链式方法)

几乎所有的操作方法都会返回 `this`，方便进行链式调用。

**变换:**

```typescript
schematic
  .rotate("y", 90) // 绕Y轴旋转90度
  .scale(new GameVector3(1, 2, 1)) // 在Y轴上拉伸2倍
  .flip("x"); // 沿X轴翻转
```

**布尔运算:**

```typescript
const wall = TerrainSchematic.fromCuboid(new GameVector3(20, 10, 3), 1);
const window = TerrainSchematic.fromCuboid(new GameVector3(5, 5, 3), 0);

// 在墙上开一个窗户
const wallWithWindow = wall.subtract(window, new GameVector3(7, 2, 0));
wallWithWindow.import();
```

**方块替换:**

```typescript
// 1. 简单替换：将所有石头(ID=1)替换为草方块(ID=2)
schematic.replaceBlocks(new Map([[1, 2]]));

// 2. 高级模式替换：创建更自然的纹理混合
const pattern: PatternMap = new Map([
  [
    1,
    [
      // 当遇到方块ID为 1 (石头) 时
      { id: 1, weight: 80 }, // 80% 几率保持为石头
      { id: 4, weight: 15 }, // 15% 几率变为圆石
      { id: 169, weight: 5 }, // 5% 几率变为苔石
    ],
  ],
]);
schematic.replaceByPattern(pattern);
```

**特效:**

```typescript
// 对一个山脉蓝图应用侵蚀效果，然后平滑，最后挖空
mountain
  .erode({ iterations: 50, erosion: 0.1 })
  .smooth({ iterations: 2 })
  .shell(3)
  .import();
```

### 3. 导入与导出

**导入到世界:**

```typescript
// 同步导入
schematic.import(new GameVector3(50, 20, 50));

// 异步导入，防止卡顿
schematic.importAsync(new GameVector3(50, 20, 50), 500); // 每tick处理500个方块
```

**数据序列化:**

```typescript
// 将蓝图转换为可序列化的JS对象
const data = schematic.getData();
const jsonString = JSON.stringify(data);

// 从数据中恢复蓝图
const loadedSchematic = TerrainSchematic.fromData(JSON.parse(jsonString));
```

## 高级示例

### 建造一座蜿蜒的城墙

使用 `fromPathWall` 和贝塞尔平滑来创建一道沿着曲线路径的城墙。

```typescript
import { TerrainSchematic } from "@dao3fun/terrain-schematic";

const path = [
  new GameVector3(0, 0, 0),
  new GameVector3(20, 5, 40),
  new GameVector3(-10, 8, 80),
  new GameVector3(30, 2, 120),
];

TerrainSchematic.fromPathWall(path, 10, 3, 4, 0, {
  useBezier: true, // 路径平滑
  bezierSampleCount: 40,
}).import(new GameVector3(100, 64, 100));
```

### 创建一个空心的圆顶

组合使用布尔运算来创建一个空心的圆顶。

```typescript
import { TerrainSchematic, SphereOptions } from "@dao3fun/terrain-schematic";

// 创建一个大球
const outerSphere = TerrainSchematic.fromSphere(20, 1);

// 创建一个小一点的球，用于挖空
const innerSphere = TerrainSchematic.fromSphere(18, 0); // 使用空气方块

// 创建一个巨大的长方体，用于切掉下半部分
const cutter = TerrainSchematic.fromCuboid(new GameVector3(50, 21, 50), 0);

// 最终操作
outerSphere
  .subtract(innerSphere) // 挖空
  .subtract(cutter, new GameVector3(-25, -20, -25)) // 切掉底部
  .import(new GameVector3(0, 80, 0));
```