sapdon 3.2.2 → 3.3.3

package/doc/user/tutorials/block.md

@@ -0,0 +1,463 @@
+# 方块创建教程
+
+本文档介绍如何使用 sapdon 框架创建各类 Minecraft 方块。
+
+> 开始前请确保已完成[快速入门](../quick-start.md)中的环境搭建。
+
+## 导入
+
+所有方块相关 API 均从 `@sapdon/core` 导入：
+
+```typescript
+import { BlockAPI, registry, BlockComponent, RotationTypes, Permutation } from '@sapdon/core'
+```
+
+完成后调用 `registry.submit()` 提交所有注册数据。
+
+---
+
+## 1. 基础方块
+
+`BlockAPI.createBasicBlock()` 创建具有 6 个面纹理的基础方块。
+
+```typescript
+import { BlockAPI, registry } from '@sapdon/core'
+
+const myBlock = BlockAPI.createBasicBlock(
+  'sapdon:my_basic_block',
+  'nature',
+  [
+    'stone',   // down
+    'stone',   // up
+    'stone',   // north
+    'stone',   // south
+    'stone',   // west
+    'stone'    // east
+  ],
+  {
+    group: 'construction',
+    hide_in_command: false
+  }
+)
+
+registry.submit()
+```
+
+### 关于 material_instances
+
+`createBasicBlock` 内部自动将 6 个纹理映射为 `minecraft:material_instances` 组件：
+
+```typescript
+// 等效的手动写法
+BlockComponent.setMaterialInstances({
+  down:  { texture: 'stone_down' },
+  up:    { texture: 'stone_up' },
+  north: { texture: 'stone_north' },
+  south: { texture: 'stone_south' },
+  west:  { texture: 'stone_west' },
+  east:  { texture: 'stone_east' }
+})
+```
+
+每个材质实例可以额外指定渲染属性：
+
+```typescript
+BlockComponent.setMaterialInstances({
+  '*': {
+    texture: 'my_texture',
+    ambient_occlusion: true,
+    face_dimming: true,
+    render_method: 'opaque'  // opaque | blend | alpha_test | double_sided | alpha_test_single_sided
+  }
+})
+```
+
+---
+
+## 2. 多变体方块
+
+`BlockAPI.createBlock()` 创建带有多个变体的方块，每个变体对应一个 `sapdon:block_variant_tag` 状态值。
+
+```typescript
+import { BlockAPI, registry, BlockComponent } from '@sapdon/core'
+
+const multiBlock = BlockAPI.createBlock(
+  'sapdon:multi_block',
+  'nature',
+  [
+    {
+      stateTag: 0,
+      textures: ['stone', 'stone', 'stone', 'stone', 'stone', 'stone']
+    },
+    {
+      stateTag: 1,
+      textures: ['cobblestone', 'cobblestone', 'cobblestone', 'cobblestone', 'cobblestone', 'cobblestone']
+    },
+    {
+      stateTag: 2,
+      textures: ['mossy_cobblestone', 'mossy_cobblestone', 'mossy_cobblestone', 'mossy_cobblestone', 'mossy_cobblestone', 'mossy_cobblestone']
+    }
+  ],
+  {
+    group: 'nature',
+    ambient_occlusion: false,
+    face_dimming: false,
+    render_method: 'alpha_test'
+  }
+)
+
+registry.submit()
+```
+
+### 变体工作原理
+
+框架自动注册状态 `sapdon:block_variant_tag`（值为 0 到变体数-1），并为每个变体生成 permutation：
+
+```typescript
+// 每个变体对应条件
+condition: "q.block_state('sapdon:block_variant_tag') == 0"
+condition: "q.block_state('sapdon:block_variant_tag') == 1"
+// ...
+```
+
+### 为特定变体添加额外组件
+
+```typescript
+// 为变体 2 添加自定义组件
+multiBlock.addVariantComponent(2, BlockComponent.setLightEmission(15))
+```
+
+---
+
+## 3. 可旋转方块
+
+`BlockAPI.createRotatableBlock()` 创建支持多方向放置的方块。
+
+```typescript
+import { BlockAPI, registry, RotationTypes } from '@sapdon/core'
+
+// CARDINAL — 北/南/东/西 四个方向
+const pillar = BlockAPI.createRotatableBlock(
+  'sapdon:pillar',
+  'construction',
+  ['oak_log_top', 'oak_log_top', 'oak_log', 'oak_log', 'oak_log', 'oak_log'],
+  {
+    rotationType: RotationTypes.CARDINAL,
+    yRotationOffset: 180
+  }
+)
+
+// FACING — 上/下/北/南/东/西 六个方向
+const machine = BlockAPI.createRotatableBlock(
+  'sapdon:machine',
+  'construction',
+  ['stone', 'stone', 'furnace_front', 'stone', 'stone', 'stone'],
+  {
+    rotationType: RotationTypes.FACING
+  }
+)
+
+// LOG — 原木式旋转（X/Y/Z 轴）
+const customLog = BlockAPI.createRotatableBlock(
+  'sapdon:custom_log',
+  'nature',
+  ['oak_log_top', 'oak_log_top', 'oak_log', 'oak_log', 'oak_log', 'oak_log'],
+  {
+    rotationType: RotationTypes.LOG
+  }
+)
+
+registry.submit()
+```
+
+### RotationTypes 说明
+
+| 类型 | 方向 | 适用场景 |
+|------|------|----------|
+| `CARDINAL` | 北、南、东、西 | 柱子、竖纹方块 |
+| `FACING` | 上、下、北、南、东、西 | 熔炉、发射器类 |
+| `BLOCK_FACE` | 上、下、北、南、东、西 | 附着型方块 |
+| `LOG` | X/Y/Z 轴对齐 | 原木、横纹方块 |
+
+---
+
+## 4. 几何方块
+
+`BlockAPI.createGeometryBlock()` 创建使用自定义几何模型的方块。
+
+```typescript
+import { BlockAPI, registry } from '@sapdon/core'
+
+const chair = BlockAPI.createGeometryBlock(
+  'sapdon:chair',
+  'construction',
+  'geometry.chair',
+  {
+    '*': {
+      texture: 'oak_planks',
+      render_method: 'opaque'
+    }
+  }
+)
+
+registry.submit()
+```
+
+多材质实例示例：
+
+```typescript
+const table = BlockAPI.createGeometryBlock(
+  'sapdon:table',
+  'construction',
+  'geometry.table',
+  {
+    'wood': {
+      texture: 'oak_planks',
+      render_method: 'opaque'
+    },
+    'metal': {
+      texture: 'iron_block',
+      render_method: 'opaque'
+    }
+  }
+)
+
+registry.submit()
+```
+
+---
+
+## 5. 作物方块
+
+`BlockAPI.createCropBlock()` 创建具有生长阶段的作物方块。
+
+```typescript
+import { BlockAPI, registry } from '@sapdon/core'
+
+const tomato = BlockAPI.createCropBlock(
+  'sapdon:tomato',
+  'nature',
+  [
+    { stateTag: 0, textures: ['wheat_stage_0', 'wheat_stage_0', 'wheat_stage_0', 'wheat_stage_0', 'wheat_stage_0', 'wheat_stage_0'] },
+    { stateTag: 1, textures: ['wheat_stage_1', 'wheat_stage_1', 'wheat_stage_1', 'wheat_stage_1', 'wheat_stage_1', 'wheat_stage_1'] },
+    { stateTag: 2, textures: ['wheat_stage_2', 'wheat_stage_2', 'wheat_stage_2', 'wheat_stage_2', 'wheat_stage_2', 'wheat_stage_2'] },
+    { stateTag: 3, textures: ['wheat_stage_3', 'wheat_stage_3', 'wheat_stage_3', 'wheat_stage_3', 'wheat_stage_3', 'wheat_stage_3'] }
+  ],
+  {
+    group: 'nature',
+    render_method: 'alpha_test'
+  }
+)
+
+registry.submit()
+```
+
+### 自动添加的组件
+
+作物方块会自动设置：
+- **碰撞箱禁用** — `minecraft:collision_box` 设为 `false`
+- **几何模型** — 使用 `geometry.crop`
+- **放置过滤** — 只能放置在耕地上方
+- **选择框** — 每阶段自动调整高度
+
+---
+
+## 6. 矿物方块
+
+`BlockAPI.createOreBlock()` 自动创建方块 + 矿脉特征 + 特征规则。
+
+```typescript
+import { BlockAPI, registry } from '@sapdon/core'
+
+const rubyOre = BlockAPI.createOreBlock(
+  'sapdon:ruby_ore',
+  'nature',
+  ['diamond_ore', 'diamond_ore', 'diamond_ore', 'diamond_ore', 'diamond_ore', 'diamond_ore'],
+  {
+    group: 'nature'
+  }
+)
+
+registry.submit()
+```
+
+### 自动生成的内容
+
+| 内容 | 标识符 |
+|------|--------|
+| 方块 (BasicBlock) | `sapdon:ruby_ore` |
+| 矿脉特征 (OreFeature) | `sapdon:ruby_ore_ore_feature` |
+| 特征规则 (FeatureRule) | `sapdon:ruby_ore_orefeatre_rule` |
+
+生成的矿石会在 Y 0-64 层之间以 10 次/区块的频率生成，替换石头。
+
+---
+
+## 7. 方块组件
+
+使用 `BlockComponent` 的静态方法为方块添加各种行为。
+
+```typescript
+import { BlockAPI, registry, BlockComponent } from '@sapdon/core'
+
+const componentBlock = BlockAPI.createBasicBlock(
+  'sapdon:component_demo',
+  'construction',
+  ['stone', 'stone', 'stone', 'stone', 'stone', 'stone']
+)
+
+// 材质实例
+componentBlock.addComponent(
+  BlockComponent.setMaterialInstances({
+    '*': { texture: 'demo', render_method: 'opaque' }
+  })
+)
+
+// 几何模型
+componentBlock.addComponent(
+  BlockComponent.setGeometry('geometry.demo', { 'bone1': true })
+)
+
+// 碰撞箱 — 启用/禁用
+componentBlock.addComponent(BlockComponent.setCollisionBoxEnabled(true))
+// 碰撞箱 — 自定义尺寸
+componentBlock.addComponent(BlockComponent.setCollisionBoxCustom([-8, 0, -8], [16, 16, 16]))
+
+// 选择框 — 启用/禁用
+componentBlock.addComponent(BlockComponent.setSelectionBoxEnabled(true))
+// 选择框 — 自定义尺寸
+componentBlock.addComponent(BlockComponent.setSelectionBoxCustom([-8, 0, -8], [16, 16, 16]))
+
+// 爆炸抗性 — 启用/禁用
+componentBlock.addComponent(BlockComponent.setDestructibleByExplosionEnabled(true))
+// 爆炸抗性 — 自定义值
+componentBlock.addComponent(BlockComponent.setDestructibleByExplosionCustom(5.0))
+
+// 挖掘抗性 — 启用/禁用
+componentBlock.addComponent(BlockComponent.setDestructibleByMiningEnabled(true))
+// 挖掘抗性 — 自定义值（带工具速度）
+componentBlock.addComponent(
+  BlockComponent.setDestructibleByMiningCustom(2.0, [
+    { item: 'minecraft:diamond_pickaxe', destroy_speed: 0.5 }
+  ])
+)
+
+// 显示名称
+componentBlock.addComponent(BlockComponent.setDisplayName('组件演示方块'))
+
+// 易燃性
+componentBlock.addComponent(BlockComponent.setFlammableEnabled(true))
+componentBlock.addComponent(BlockComponent.setFlammableCustom(0.5, 0.3))
+
+// 摩擦力
+componentBlock.addComponent(BlockComponent.setFriction(0.6))
+
+// 遮光值
+componentBlock.addComponent(BlockComponent.setLightDampening(15))
+// 发光值
+componentBlock.addComponent(BlockComponent.setLightEmission(0))
+
+// 战利品表
+componentBlock.addComponent(BlockComponent.setLoot('loot_tables/demo.json'))
+
+// 地图颜色
+componentBlock.addComponent(BlockComponent.setMapColor('#FF0000'))
+// 或 RGB 数组
+componentBlock.addComponent(BlockComponent.setMapColor([255, 0, 0]))
+
+// 变换
+componentBlock.addComponent(
+  BlockComponent.setTransformation([0, 0, 0], [1, 1, 1], [0, 0, 0], [0, 0, 0], [0, 0, 0])
+)
+
+// 放置过滤
+componentBlock.addComponent(
+  BlockComponent.setPlacementFilter([
+    { allowed_faces: ['up'], block_filter: ['minecraft:grass'] }
+  ])
+)
+
+// 红石导电性
+componentBlock.addComponent(
+  BlockComponent.setRedstoneConductivity(false, true)
+)
+
+// 合成台
+componentBlock.addComponent(
+  BlockComponent.setCraftingTable(['crafting_table'], '演示工作台')
+)
+
+// Tick
+componentBlock.addComponent(BlockComponent.setTick([10, 20], true))
+
+// 自定义组件 (Script API)
+componentBlock.addComponent(BlockComponent.setCustomComponents(['sapdon:custom_component']))
+// 自定义组件 V2
+componentBlock.addComponent(
+  BlockComponent.setCustomComponentV2('sapdon:custom_v2', { enabled: true })
+)
+
+// 破坏粒子
+componentBlock.addComponent(BlockComponent.setDestructionParticles('particle_texture', 'none'))
+
+// 物品视觉
+componentBlock.addComponent(
+  BlockComponent.setItemVisual('geometry.item', { '*': { texture: 'item_tex', render_method: 'opaque' } })
+)
+
+// 液体检测
+componentBlock.addComponent(
+  BlockComponent.setLiquidDetection(true, 'water', 'blocking', ['down'])
+)
+
+// 呼吸性
+componentBlock.addComponent(BlockComponent.setBreathability('solid'))
+
+registry.submit()
+```
+
+### 合并多个组件
+
+```typescript
+componentBlock.addComponent(
+  BlockComponent.combineComponents(
+    BlockComponent.setDisplayName('合并示例'),
+    BlockComponent.setLightEmission(10),
+    BlockComponent.setFriction(0.5)
+  )
+)
+```
+
+---
+
+## 8. TileBlock
+
+`TileBlock` 将方块与实体结合，实现方块实体效果。
+
+```typescript
+import { TileBlock, registry } from '@sapdon/core'
+
+const chestBlock = new TileBlock(
+  'sapdon:tile_chest',
+  'construction',
+  ['stone', 'stone', 'stone', 'stone', 'stone', 'stone']
+)
+
+// 自定义几何模型
+chestBlock.setGeometry('geometry.chest')
+
+// 添加动画
+chestBlock.addAnimation('open', 'animation.chest.open')
+
+// 自定义脚本属性
+chestBlock.setScript('animate', 'open')
+
+registry.submit()
+```
+
+### TileBlock 工作原理
+
+1. 创建 `BasicBlock`（带有 `sapdon:block_or_entity` 状态）
+2. 创建 `Entity`（带有容器、无敌、不可推动等组件）
+3. 方块状态为 0 时显示普通方块，状态为 1 时通过 tick 切换为实体容器
+4. 实体使用 `block_sensor` 监听方块破坏事件以触发消失