sapdon 3.2.2 → 3.3.3

package/doc/user/api/biome.md

@@ -0,0 +1,558 @@
+# 生物群系与特征系统 API 参考
+
+---
+
+## BiomeAPI
+
+工厂函数，用于创建生物群系并自动注册到游戏系统。
+
+```typescript
+import { BiomeAPI, registry } from '@sapdon/core'
+```
+
+---
+
+### createBiome
+
+创建生物群系实例。
+
+```typescript
+BiomeAPI.createBiome(identifier: string): Biome
+```
+
+**参数**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `identifier` | `string` | 生物群系唯一标识符，格式 `命名空间:名称` |
+
+**示例**
+
+```typescript
+const biome = BiomeAPI.createBiome('sapdon:mystic_forest')
+registry.submit()
+```
+
+返回的 `Biome` 实例通过 `.addComponent()` 链式添加组件。
+
+---
+
+## Biome
+
+生物群系类，通过 `addComponent()` 添加组件后提交。
+
+```typescript
+import { Biome, BiomeComponent } from '@sapdon/core'
+```
+
+### addComponent
+
+```typescript
+biome.addComponent(componentMap: Map): this
+```
+
+**参数**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `componentMap` | `Map<string, any>` | 由 `BiomeComponent` 静态方法生成的组件 Map |
+
+**示例**
+
+```typescript
+const biome = BiomeAPI.createBiome('sapdon:mystic_forest')
+
+biome.addComponent(
+  BiomeComponent.setClimate(0.5, 0.1, 0.8)
+)
+biome.addComponent(
+  BiomeComponent.setOverworldHeight([0.1, 0.2])
+)
+
+registry.submit()
+```
+
+### 合并多个组件
+
+```typescript
+biome.addComponent(
+  BiomeComponent.combineComponents(
+    BiomeComponent.setClimate(0.5, 0.3, 0.7),
+    BiomeComponent.setOverworldHeight([0.1, 0.2])
+  )
+)
+```
+
+---
+
+## BiomeComponent
+
+静态工具方法集合，用于生成生物群系组件 Map。每个方法返回 `Map<string, any>`。
+
+```typescript
+import { BiomeComponent } from '@sapdon/core'
+```
+
+### setClimate
+
+设置生物群系的气候参数。
+
+```typescript
+static setClimate(
+  downfall: number,
+  snow_accumulation: number,
+  temperature: number
+): Map
+```
+
+**参数**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `downfall` | `number` | 降水量，范围通常 0 ~ 1 |
+| `snow_accumulation` | `number` | 积雪量，范围通常 0 ~ 1 |
+| `temperature` | `number` | 温度，范围通常 0 ~ 1 |
+
+**示例**
+
+```typescript
+BiomeComponent.setClimate(0.4, 0.0, 0.9)  // 温暖干燥
+BiomeComponent.setClimate(0.9, 0.5, 0.0)  // 寒冷多雪
+```
+
+### setOverworldHeight
+
+设置生物群系的世界高度参数，控制地形生成。
+
+```typescript
+static setOverworldHeight(noise_params: object): Map
+```
+
+**参数**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `noise_params` | `Array<number>` | 噪声参数，如 `[0.1, 0.2]` |
+
+**示例**
+
+```typescript
+// 平坦地形
+BiomeComponent.setOverworldHeight([0.05, 0.05])
+
+// 起伏山地
+BiomeComponent.setOverworldHeight([0.2, 0.4])
+```
+
+### setSurfaceParameters
+
+设置生物群系的表面方块参数。
+
+```typescript
+static setSurfaceParameters(params: {
+  sea_floor_depth: number
+  sea_floor_material: string
+  foundation_material: string
+  mid_material: string
+  top_material: string
+  sea_material: string
+}): Map
+```
+
+**参数**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `sea_floor_depth` | `number` | 海底深度 |
+| `sea_floor_material` | `string` | 海底材料，如 `"minecraft:sand"` |
+| `foundation_material` | `string` | 基础材料，如 `"minecraft:stone"` |
+| `mid_material` | `string` | 中间层材料，如 `"minecraft:dirt"` |
+| `top_material` | `string` | 顶层材料，如 `"minecraft:grass_block"` |
+| `sea_material` | `string` | 海洋材料，如 `"minecraft:water"` |
+
+**示例**
+
+```typescript
+BiomeComponent.setSurfaceParameters({
+  sea_floor_depth: 7,
+  sea_floor_material: 'minecraft:gravel',
+  foundation_material: 'minecraft:stone',
+  mid_material: 'minecraft:dirt',
+  top_material: 'minecraft:grass_block',
+  sea_material: 'minecraft:water'
+})
+```
+
+### setOverworldGenerationRules
+
+设置生物群系在主世界生成时的气候权重。
+
+```typescript
+static setOverworldGenerationRules(
+  medium_weight: number,
+  warm_weight: number,
+  cold_weight: number
+): Map
+```
+
+**参数**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `medium_weight` | `number` | 中等气候权重 |
+| `warm_weight` | `number` | 温暖气候权重 |
+| `cold_weight` | `number` | 寒冷气候权重 |
+
+**示例**
+
+```typescript
+// 仅生成于温暖气候
+BiomeComponent.setOverworldGenerationRules(0, 100, 0)
+
+// 均匀分布于所有气候
+BiomeComponent.setOverworldGenerationRules(100, 100, 100)
+```
+
+### combineComponents
+
+合并多个组件 Map。
+
+```typescript
+static combineComponents(...componentMaps: Map[]): Map
+```
+
+**示例**
+
+```typescript
+BiomeComponent.combineComponents(
+  BiomeComponent.setClimate(0.5, 0.3, 0.7),
+  BiomeComponent.setOverworldHeight([0.1, 0.2]),
+  BiomeComponent.setSurfaceParameters({
+    sea_floor_depth: 7,
+    sea_floor_material: 'minecraft:sand',
+    foundation_material: 'minecraft:stone',
+    mid_material: 'minecraft:dirt',
+    top_material: 'minecraft:grass_block',
+    sea_material: 'minecraft:water'
+  })
+)
+```
+
+### 完整示例
+
+```typescript
+import { BiomeAPI, registry, BiomeComponent } from '@sapdon/core'
+
+const biome = BiomeAPI.createBiome('sapdon:crystal_plains')
+
+biome.addComponent(
+  BiomeComponent.combineComponents(
+    BiomeComponent.setClimate(0.3, 0.0, 0.6),
+    BiomeComponent.setOverworldHeight([0.05, 0.1]),
+    BiomeComponent.setSurfaceParameters({
+      sea_floor_depth: 5,
+      sea_floor_material: 'minecraft:sand',
+      foundation_material: 'minecraft:stone',
+      mid_material: 'minecraft:dirt',
+      top_material: 'minecraft:grass_block',
+      sea_material: 'minecraft:water'
+    }),
+    BiomeComponent.setOverworldGenerationRules(50, 100, 30)
+  )
+)
+
+registry.submit()
+```
+
+---
+
+## FeatureAPI
+
+工厂函数，用于创建特征（如矿脉）和特征规则。
+
+```typescript
+import { FeatureAPI, registry } from '@sapdon/core'
+```
+
+---
+
+### createOreFeature
+
+创建矿脉特征。
+
+```typescript
+FeatureAPI.createOreFeature(
+  identifier: string,
+  count: number,
+  replace_rules: any[]
+): OreFeature
+```
+
+**参数**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `identifier` | `string` | 特征唯一标识符 |
+| `count` | `number` | 每区块矿石团块数量 |
+| `replace_rules` | `object[]` | 替换规则数组 |
+
+**示例**
+
+```typescript
+FeatureAPI.createOreFeature(
+  'sapdon:ruby_ore_feature',
+  8,
+  [
+    {
+      places_block: 'sapdon:ruby_ore',
+      may_replace: [{ name: 'minecraft:stone' }]
+    }
+  ]
+)
+
+registry.submit()
+```
+
+### createFeatureRules
+
+创建特征规则，控制特征如何在世界中生成。
+
+```typescript
+FeatureAPI.createFeatureRules(
+  identifier: string,
+  places_feature: string
+): FeatureRule
+```
+
+**参数**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `identifier` | `string` | 特征规则唯一标识符 |
+| `places_feature` | `string` | 要放置的特征标识符 |
+
+**示例**
+
+```typescript
+const rule = FeatureAPI.createFeatureRules(
+  'sapdon:ruby_ore_rule',
+  'sapdon:ruby_ore_feature'
+)
+
+rule.setPlacementPass('underground_pass')
+rule.setIterations(10)
+
+registry.submit()
+```
+
+---
+
+## FeatureRule
+
+特征规则类，控制特征的生成条件和分布方式。
+
+```typescript
+import { FeatureRule, BiomeFilter, CoordinateDistribution } from '@sapdon/core'
+```
+
+### setPlacementPass
+
+设置生成阶段。
+
+```typescript
+featureRule.setPlacementPass(pass: string): void
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `pass` | `string` | 生成阶段标识符，如 `"underground_pass"`、`"surface_pass"` |
+
+### setBiomeFilter
+
+设置生物群系过滤条件。
+
+```typescript
+featureRule.setBiomeFilter(biomeFilter: BiomeFilter): void
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `biomeFilter` | `BiomeFilter` | 生物群系过滤条件实例 |
+
+### setIterations
+
+设置每区块放置尝试次数。
+
+```typescript
+featureRule.setIterations(iterations: number): void
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `iterations` | `number` | 放置尝试次数 |
+
+### setAxisDistribution
+
+设置指定坐标轴的分布规则。
+
+```typescript
+featureRule.setAxisDistribution(
+  axis: 'x' | 'y' | 'z',
+  config: CoordinateDistribution
+): void
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `axis` | `string` | 坐标轴 `"x"` / `"y"` / `"z"` |
+| `config` | `CoordinateDistribution` | 分布配置 |
+
+### 完整示例
+
+```typescript
+import { FeatureAPI, registry, BiomeFilter, CoordinateDistribution } from '@sapdon/core'
+
+// 1. 创建矿脉特征
+FeatureAPI.createOreFeature(
+  'sapdon:ruby_ore_feature',
+  10,
+  [
+    {
+      places_block: 'sapdon:ruby_ore',
+      may_replace: [{ name: 'minecraft:stone' }]
+    }
+  ]
+)
+
+// 2. 创建特征规则
+const rule = FeatureAPI.createFeatureRules(
+  'sapdon:ruby_ore_rule',
+  'sapdon:ruby_ore_feature'
+)
+
+// 3. 配置生成条件
+rule.setPlacementPass('underground_pass')
+
+// 4. 设置生物群系过滤 — 仅主世界群系
+const biomeFilter = new BiomeFilter()
+biomeFilter.addSimpleCondition('has_biome_tag', '==', 'overworld')
+rule.setBiomeFilter(biomeFilter)
+
+// 5. 设置放置尝试次数
+rule.setIterations(10)
+
+// 6. 设置 Y 轴分布范围 (5 ~ 40 层)
+rule.setAxisDistribution('y', new CoordinateDistribution('uniform', [5, 40]))
+// X/Z 轴默认范围为 [0, 16]（单个区块范围）
+rule.setAxisDistribution('x', new CoordinateDistribution('uniform', [0, 16]))
+rule.setAxisDistribution('z', new CoordinateDistribution('uniform', [0, 16]))
+
+registry.submit()
+```
+
+---
+
+## BiomeFilter
+
+生物群系过滤条件类，用于指定特征在哪些群系中生成。
+
+```typescript
+import { BiomeFilter } from '@sapdon/core'
+```
+
+### 方法
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `addSimpleCondition(test, operator, value)` | `this` | 添加简单条件 |
+| `addLogicGroup(logicType, conditions)` | `this` | 添加逻辑组（`any_of` / `all_of`） |
+
+**示例**
+
+```typescript
+const filter = new BiomeFilter()
+
+// 仅主世界群系
+filter.addSimpleCondition('has_biome_tag', '==', 'overworld')
+
+// 排除特定群系
+filter.addLogicGroup('any_of', [
+  { test: 'has_biome_tag', operator: '!=', value: 'ocean' },
+  { test: 'has_biome_tag', operator: '!=', value: 'river' }
+])
+```
+
+---
+
+## CoordinateDistribution
+
+坐标轴分布规则类，控制特征在 X / Y / Z 轴上的分布范围。
+
+```typescript
+import { CoordinateDistribution } from '@sapdon/core'
+```
+
+### 构造函数
+
+```typescript
+new CoordinateDistribution(
+  distribution: 'uniform' | 'triangle' = 'uniform',
+  extent: [number, number] = [0, 16]
+)
+```
+
+**参数**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `distribution` | `string` | 分布类型：`"uniform"`（均匀）、`"triangle"`（三角） |
+| `extent` | `[number, number]` | 范围，如 `[0, 16]`、`[5, 40]` |
+
+**示例**
+
+```typescript
+// Y 轴 5-40 层均匀分布
+new CoordinateDistribution('uniform', [5, 40])
+
+// X 轴整区块均匀分布
+new CoordinateDistribution('uniform', [0, 16])
+
+// Y 轴三角分布（中间值附近概率更高）
+new CoordinateDistribution('triangle', [0, 64])
+```
+
+---
+
+## 类型汇总
+
+```typescript
+// 生物群系
+BiomeAPI.createBiome(identifier): Biome
+
+class Biome
+  addComponent(componentMap): this
+
+class BiomeComponent
+  static setClimate(downfall, snow, temp): Map
+  static setOverworldHeight(noise_params): Map
+  static setSurfaceParameters(params): Map
+  static setOverworldGenerationRules(medium, warm, cold): Map
+  static combineComponents(...maps): Map
+
+// 特征
+FeatureAPI.createOreFeature(id, count, replace_rules): OreFeature
+FeatureAPI.createFeatureRules(id, places_feature): FeatureRule
+
+class FeatureRule
+  setPlacementPass(pass): void
+  setBiomeFilter(filter): void
+  setIterations(count): void
+  setAxisDistribution(axis, config): void
+
+class BiomeFilter
+  addSimpleCondition(test, operator, value): this
+  addLogicGroup(type, conditions): this
+
+class CoordinateDistribution
+  constructor(distribution, extent)
+```