Craftium项目内置实体系统详解：坠落方块与掉落物品机制

前言

在Craftium项目中，内置实体系统是物理交互的重要组成部分。本文将深入解析项目中默认注册的两种核心实体类型：坠落方块(Falling Node)和掉落物品(Dropped Item)，帮助开发者理解其工作机制并掌握相关API的使用方法。

一、坠落方块实体(__builtin:falling_node)

1.1 基本概念与生成机制

坠落方块实体是Craftium中模拟重力效果的物理实体，当场景中的节点被标记为falling_node=1的特殊组时，系统会自动将其转换为坠落方块实体。开发者也可以通过API手动生成这类实体。

典型应用场景：

• 沙块、砾石等受重力影响的方块
• 需要动态下落的建筑元素
• 特殊机制中的物理效果

1.2 物理行为特性

坠落方块具有以下物理特性：

• 受重力影响垂直下落（重力值由movement_gravity设置决定）
• 与walkable节点发生碰撞
• 与除玩家外的所有物理对象碰撞
• 特殊处理：当节点组包含float=1时，还会与液体节点（liquidtype ~= "none"）发生碰撞

着地处理逻辑：

1. 当撞击到固体(walkable)节点时，会尝试在目标位置上方放置自身
2. 若无法替换目标节点，则转换为掉落物品
3. 特殊处理：当目标节点是相同名称的层级节点(paramtype2="leveled")时，会合并两者的层级值

1.3 API接口详解

初始化方法

set_node(self, node[, meta])

• node参数：包含name、param1、param2的节点表
• meta参数（可选）：节点元数据，将在实体放置为节点时使用

只读属性

• node：实体代表的节点信息（不可修改）
• meta：节点的元数据（不可修改）

1.4 渲染支持与限制

坠落方块会尽可能还原原始节点的视觉效果，但存在以下限制：

支持的绘制类型(drawtypes)：

• 常规类型：normal, signlike, torchlike等
• 特殊类型：mesh, fencelike, liquid等
• 注意：airlike类型不可选中

不完美支持的情况：

• 当节点使用scale>1的世界对齐纹理时，仅显示纹理左上部分
• 非常规绘制类型可能出现视觉异常

支持的参数类型(paramtype2)：

• 基础方向：wallmounted, facedir, 4dir
• 彩色变体：colorwallmounted, colorfacedir, color4dir, color

二、掉落物品实体(__builtin:item)

2.1 基本概念与生成场景

掉落物品实体代表可收集的物品堆栈，是物品在场景中的物理表现形式。

常见生成场景：

• 用户丢弃物品
• 附属节点(attached_node=1)的根节点被移除时
• 通过API直接添加物品

2.2 物理行为特性

掉落物品具有以下行为特点：

• 用户可通过击打收集
• 生命周期由item_entity_ttl设置决定
• 在slipry节点上会滑动
• 受重力影响（使用movement_gravity设置）
• 与walkable节点碰撞
• 不与物理对象碰撞
• 特殊处理：当陷入固体节点时，会尝试移动到相邻的非固体节点

2.3 API接口详解

初始化方法

set_item(self, item)

• item参数：ItemStack类型的物品堆栈

关键属性

• age：实体存在时间（秒），受item_entity_ttl设置影响
• itemstring：实体代表的物品字符串（只读）

三、开发实践建议

1. 性能优化：大量坠落方块实体会显著影响性能，建议合理使用falling_node组标记
2. 视觉一致性：为自定义节点设计坠落效果时，注意检查支持的绘制类型
3. 物品生命周期：根据需求调整item_entity_ttl设置，平衡体验与性能
4. 特殊交互：可利用坠落方块的层级合并特性实现特殊机制

结语

Craftium的内置实体系统为开发者提供了丰富的物理交互可能性。理解坠落方块和掉落物品的工作原理，能够帮助开发者创造更具沉浸感的体验。建议在实际开发中结合项目文档和API参考，充分发挥这些实体组件的潜力。