用途:在 Decentraland SDK7 场景中构建 2D 屏幕空间 UI 覆盖层,基于 React-ECS 的 JSX 系统。适用于计分板、血条、对话框、背包、设置菜单等 2D 覆盖界面;3D 世界中的浮动文字应改用 TextShape + Billboard。
主要能力:提供 UiEntity(容器)、Label、Button、Input、Dropdown 等核心组件,支持 flex 布局、绝对/相对定位、背景色与图片、九宫格纹理、悬停事件、flexWrap 换行等。
使用方式:在 src/ui.tsx 中定义 UI 组件,通过 ReactEcsRenderer.setUiRenderer(MyUI, { virtualWidth: 1920, virtualHeight: 1080 }) 注册,务必传入 virtualWidth 与 virtualHeight 以适配不同分辨率。在 src/index.ts 的 main() 中调用 setupUi()。文件扩展名必须为 .tsx。
状态管理:不支持 React hooks(useState、useEffect 等),需使用模块级变量;渲染器每帧重渲染,状态变化即时反映。
多模块:每个场景只能调用一次 setUiRenderer;独立模块可用 ReactEcsRenderer.addUiRenderer(ownerEntity, ...) 挂载,删除 owner 实体即自动移除。
限制:UI 为 3D 场景之上的 2D 覆盖层;隐藏元素用 display: 'none';tsconfig.json 已由 /init 配置,不要修改。完整组件属性与响应式设计见 {baseDir}/references/ui-components.md。