实体渲染组件

实体渲染组件使用 Minecraft 原版实体渲染表现，在页面中显示当前玩家、世界实体或页面专用虚拟实体。它支持透视或正交投影、整体旋转、名称、缩放、偏移和头部追踪鼠标。

适用场景

角色预览与玩家信息页
商店 NPC、任务目标和怪物图鉴
不加入世界的页面虚拟实体
与其他实体模型替换系统共享原版渲染结果

虚拟实体只存在于当前页面会话，不加入世界、不运行 AI，也不参与碰撞、伤害或服务端实体同步。

通用配置

配置项	编辑器名称	类型	默认值	可选值或格式	说明
`id`	ID	字符串	自动生成 `entity_N`	页面内唯一 ID	用于状态更新和运行时实体定位。
`type`	类型	只读字符串	`entity`	固定值	创建后不能修改。
`parent`	父级	字符串	空	布局组件 ID	为空表示根级元素。
`z`	层级	整数	`0`	任意整数	控制实体绘制顺序。
`visible`	显示	布尔值	`true`	`true`、`false`	静态显隐开关。
`enabled`	启用	布尔值	`true`	`true`、`false`	控制是否响应组件事件。
`pointerEvents`	指针处理	枚举	`auto`	`auto`、`block`、`pass`	配置事件或提示后 `auto` 命中；纯展示实体可用 `pass`。
`scale`	组件缩放	数字或公式	`1`	非负值	以组件中心缩放最终实体画面和命中范围，并与 `entity.scale` 相乘。
`visibleWhen`	显示条件	条件表达式	空	只读条件	条件为假时隐藏。
`enabledWhen`	启用条件	条件表达式	空	只读条件	条件为假时禁用。
`tooltip`	多行提示	字符串列表	空	最多 32 行，每行最多 256 字符	鼠标悬浮提示。
`containerBinding`	容器绑定	字符串	空	当前容器的语义槽位 ID	仅容器替换页面使用，可读取绑定物品信息。
`containerTooltip`	容器提示	布尔值	`true`	`true`、`false`	没有显式 `tooltip` 时是否显示绑定物品提示。
`layout.x`	X	数字或公式	创建时画布位置	合法布局公式	实体绘制区域左上角 X。
`layout.y`	Y	数字或公式	创建时画布位置	合法布局公式	实体绘制区域左上角 Y。
`layout.width`	宽	数字或公式	`64`	合法布局公式	实体适配区域宽度。
`layout.height`	高	数字或公式	`80`	合法布局公式	实体适配区域高度。
`events.leftPress` `/rightPress/middlePress`	按下脚本	ChaUI Script	空	多行脚本	对应按键按下时触发。
`events.leftRelease` `/rightRelease/middleRelease`	松开脚本	ChaUI Script	空	多行脚本	对应按键捕获仍有效并松开时触发。
`events.leftClick`	左键脚本	ChaUI Script	空	多行脚本	左键点击区域时触发。
`events.rightClick`	右键脚本	ChaUI Script	空	多行脚本	右键点击时触发。
`events.middleClick`	中键脚本	ChaUI Script	空	多行脚本	中键点击时触发。
`events.hoverEnter`	悬浮进入脚本	ChaUI Script	空	多行脚本	鼠标进入时触发。
`events.hoverLeave`	悬浮离开脚本	ChaUI Script	空	多行脚本	鼠标离开时触发。

专属配置

配置项	编辑器名称	类型	默认值	可选值或格式	说明
`entity.source`	来源	枚举	`self`	`self`、`uuid`、`entity_id`、`virtual`	决定实体从哪里取得。
`entity.uuid`	UUID	UUID 字符串	空	合法实体 UUID	仅 `source=uuid` 显示，用于查找当前客户端世界实体。
`entity.entityId`	实体ID	非负整数	空	当前世界网络实体 ID	仅 `source=entity_id` 显示。
`entity.entityType`	实体类型	命名空间 ID	virtual 时默认 `minecraft:zombie`	如 `minecraft:zombie`	仅 virtual 使用；没有合法 summon 时必须提供。
`entity.summon`	召唤输入	字符串	空	summon-like 字符串	仅 virtual 使用；可包含实体类型、坐标占位和 SNBT，类型优先于 entityType。
`entity.entityNbt`	实体NBT	SNBT 复合标签	空	以 `{` 开始、`}` 结束，最多 8192 字符	仅 virtual 使用；summon 内已有 SNBT 时以 summon 为准。
`entity.virtualUuid`	虚拟UUID	UUID 字符串	自动生成	合法 UUID	仅 virtual 使用；为空时按页面会话和组件生成稳定 UUID。
`entity.displayName`	显示名	字符串	空	无控制字符	设置实体自定义名称，也可供其他模型系统判断。
`entity.showName`	显示名称	布尔值	`false`	`true`、`false`	是否绘制头顶名牌。
`entity.yaw`	整体Yaw	有限数字	`0`	角度	旋转整个 GUI 实体结果。
`entity.pitch`	整体Pitch	有限数字	`0`	角度	旋转整个 GUI 实体结果。
`entity.roll`	整体Roll	有限数字	`0`	角度	绕屏幕 Z 轴旋转整个结果。
`entity.orthographic`	正交投影	布尔值	`false`	`true`、`false`	`false` 使用有近大远小效果的透视投影；`true` 使用没有透视缩短的正交投影。
`entity.trackMouse`	追踪鼠标	布尔值	`false`	`true`、`false`	仅控制头部追踪，不改变整体旋转。
`entity.autoYawRange`	头部Yaw范围	非负数字	`60`	`0` 或正数	仅 `trackMouse=true` 时允许配置。
`entity.autoPitchRange`	头部Pitch范围	非负数字	`30`	`0` 或正数	仅 `trackMouse=true` 时允许配置。
`entity.scale`	缩放	正数	`1.0`	正数	在自动适配组件区域的基础上调整大小。
`entity.offsetX`	偏移X	有限数字	`0`	任意有限数字	相对组件中心的横向绘制偏移。
`entity.offsetY`	偏移Y	有限数字	`0`	任意有限数字	相对组件中心的纵向绘制偏移。

实体组件不使用根级 opacity。需要改变视觉大小时，根级 scale 负责整体组件缩放，entity.scale 负责实体在组件区域内的适配倍率，最终效果会把两者相乘。

透视与正交怎么选

默认的 orthographic: false 使用透视投影。靠近视点的部位会稍大、远离视点的部位会稍小，更接近游戏世界中看到实体时的立体感。ChaUI 会按组件宽高和实体包围范围自动安排观察距离，视野角固定为 30 度，不需要再配置其他参数。

把它改为 orthographic: true 后，实体前后部位不会因为距离产生大小变化。正交投影适合图鉴头像、固定比例对比和需要延续旧版显示效果的页面。

这个字段必须直接填写 YAML 布尔值 true 或 false，不能写成带引号的 "true"、数字 1 或其他文字。

四种来源

来源	使用字段	行为
`self`	无额外定位字段	显示当前打开页面的客户端玩家。
`uuid`	`uuid`	按 UUID 查找当前客户端世界中的实体。
`entity_id`	`entityId`	按当前客户端世界网络实体 ID 查找。
`virtual`	`entityType` 或 `summon`，可选 NBT 与 virtualUuid	创建页面私有实体，不加入真实世界。

真实实体在渲染过程中临时使用页面设置的显示名和名牌状态，渲染结束后会恢复，避免污染世界中的实体状态。无法找到实体、无法创建类型或 NBT 应用失败时会安全跳过或降级为基础实体。

配置示例

yaml

- id: preview_zombie
  type: entity
  parent: ""
  visible: true
  enabled: false
  pointerEvents: pass
  scale: 1
  z: 10
  layout:
    x: window.width * 0.5 - 32
    y: 30
    width: 64
    height: 80
  entity:
    source: virtual
    entityType: minecraft:zombie
    displayName: 示例实体
    showName: true
    yaw: 0
    pitch: 0
    roll: 0
    orthographic: false
    trackMouse: true
    autoYawRange: 45
    autoPitchRange: 25
    scale: 1.0
    offsetX: 0
    offsetY: 0
  tooltip:
    - 鼠标移动时观察头部
  events: {}

实体组件对象可以读取当前来源、显示名、朝向和投影模式。下面的创建事件会把当前显示名与投影模式保存到页面变量：

yaml

events:
  create: |-
    vars.previewName = component("preview_zombie").entity.displayName
    vars.previewYaw = component("preview_zombie").entity.yaw
    vars.previewOrthographic = component("preview_zombie").entity.orthographic

常见问题

virtual 保存时提示缺少实体类型

source=virtual 必须提供合法 entityType，或提供能够解析出实体类型的 summon。

关闭追踪鼠标后为什么不能保留范围字段

autoYawRange 和 autoPitchRange 只在 trackMouse=true 时合法。编辑器关闭追踪后会移除这两个字段。

为什么找不到 uuid 或 entity_id 实体

它们只能查找当前客户端世界已经知道的实体。实体不在当前维度、尚未同步或已经移除时不会渲染。

为什么写了 orthographic 仍然保存失败

orthographic 只接受真正的布尔值。请写 orthographic: true 或 orthographic: false，不要添加引号。新建实体组件会明确保存 orthographic: false，也就是默认透视投影。

创建事件

实体组件可在 events.create 中设置页面变量或调整实体显示字段。初始实体在页面 open 后执行一次，动态新增或复制的实体实例也会执行一次。页面关闭与 reload 会统一释放该作用域中的虚拟实体。

服务端配置文件 ↘

实体渲染组件 ​

适用场景 ​

通用配置 ​

专属配置 ​

透视与正交怎么选 ​

四种来源 ​

配置示例 ​

常见问题 ​

virtual 保存时提示缺少实体类型 ​

关闭追踪鼠标后为什么不能保留范围字段 ​

为什么找不到 uuid 或 entity_id 实体 ​

为什么写了 orthographic 仍然保存失败 ​

创建事件 ​