deki-2d
2D 内容组件：精灵、文本（BitmapFont + TTF 烘焙）、动画、渐变、按钮、滚动、裁剪和滚轮选择器。
仓库：github.com/dekiengine/deki-2d · 最新版本：0.19.0 · 需要引擎 0.19.0 或更高版本 · 依赖：deki-rendering, deki-input
使用 DekiEditor --packages-add deki-2d <project> 或通过包管理器安装。引擎自身的组件和 C++ API 见 Deki 文档。
在编辑器中显示为 **2D**。
组件
| 组件 | 类别 | 说明 |
|---|---|---|
| AnimationComponent | 2D | 在对象的精灵上播放帧动画资源。 |
| ButtonComponent | 2D | 使对象成为按钮：跟踪悬停和按下，并触发点击回调。 |
| ButtonStyleComponent | 2D | 为按钮的每种状态设置外观，可通过着色或替换精灵实现。 |
| ClipComponent | 核心 | 将子对象的渲染裁剪到一个矩形内。 |
| GradientComponent | 2D | 绘制程序化渐变：线性、径向或锥形。 |
| RollerComponent | 2D | 滚轮选择器：带惯性地滚过一列值，并停靠在其中一个上。 |
| ScrollComponent | 2D | 通过拖动滚动子对象，带有惯性。 |
| ScrollElement | 2D | 声明一个列表项的大小，以便其滚动组件排布列表。 |
| SortingGroupComponent | 2D | 让子对象作为一个整体，与场景中的其余部分一起排序。 |
| SpriteComponent | 2D | 绘制精灵，支持着色、翻转以及平铺或九宫格模式。 |
| TextComponent | 2D | 使用位图字体绘制文本，支持对齐和自动换行。 |
功能开关
可以从构建中去掉的部分。带有 define 的功能通过该 define 开关，其余的随其组件一起被剥离。
| 功能 | define | 默认值 |
|---|---|---|
| Sprites | DEKI_FEATURE_SPRITE | 开 |
| Text | DEKI_FEATURE_TEXT | 开 |
| Animation | DEKI_FEATURE_ANIMATION | 开 |
| Gradients | DEKI_FEATURE_GRADIENT | 开 |
| Buttons | DEKI_FEATURE_BUTTON | 开 |
| Scrolling | DEKI_FEATURE_SCROLL | 开 |
| Rollers | DEKI_FEATURE_ROLLER | 开 |
| Clipping | DEKI_FEATURE_CLIP | 开 |
| Sorting Groups | DEKI_FEATURE_SORTING_GROUP | 开 |
组件参考
AnimationComponent
在对象的精灵上播放帧动画资源。
检视器中的名称：动画组件 · 类别：2D · 类型：Deki2D::AnimationComponent
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| animation | AssetRef (FrameAnimationData) | "" | 帧动画资源，列出各帧及每帧停留的时长。 |
| currentSequence | int32 | 0 | 正在播放的命名序列的索引。序列是同一资源中的各段独立动画，例如待机和行走。 |
| currentFrame | int32 | 0 | 当前序列中的帧。设置它可以逐帧拖动查看；调试时读取它也很有用。 |
| isPlaying | bool | false | 动画是否在推进。取消勾选会将动画定格在当前帧，而不是重置。 |
| hasFinished | bool | false | 非循环序列到达最后一帧时置位。读取它即可知道何时进行下一步。 |
| playOnceOverride | bool | false | 即使资源将当前序列标记为循环，也只播放一次。序列改变时清除。 |
ButtonComponent
使对象成为按钮：跟踪悬停和按下，并触发点击回调。
检视器中的名称：按钮组件 · 类别：2D · 类型：Deki2D::ButtonComponent
| 属性 | 类型 | 默认值 | 约束 | 说明 |
|---|---|---|---|---|
| inputCollider | ObjectRef (InputCollider) | 0 | 让此按钮可被点击的点击区域。没有它，按钮无法察觉按下操作。 | |
| state | enum | "Normal" | Normal, Hovered, Pressed, Disabled | 正常、悬停、按下或禁用。由输入设置；样式组件会监视它来决定绘制什么。 |
| isEnabled | bool | true | 禁用的按钮会忽略输入并报告禁用状态，因此可以将其显示为灰色而不是隐藏。 |
ButtonStyleComponent
为按钮的每种状态设置外观，可通过着色或替换精灵实现。
检视器中的名称：按钮样式组件 · 类别：2D · 类型：Deki2D::ButtonStyleComponent
| 属性 | 类型 | 默认值 | 约束 | 说明 |
|---|---|---|---|---|
| button | ObjectRef (ButtonComponent) | 0 | 其状态驱动此样式的按钮。通常是同一对象上的按钮。 | |
| sprite | ObjectRef (SpriteComponent) | 0 | 此样式所修改的精灵。通常是同一对象上的精灵。 | |
| transition | enum | "ColorTint" | ColorTint, SpriteSwap | 按下时是切换着色颜色还是直接切换精灵。颜色开销更小；使用不同的精灵则可以改变形状。 |
| normalColor | Color | "#FFFFFFFF" | transition 允许时显示 | 按钮空闲时的着色。 |
| hoveredColor | Color | "#C8C8C8FF" | transition 允许时显示 | 指针位于其上方时的着色。在仅支持触摸的设备上很少看到。 |
| pressedColor | Color | "#A0A0A0FF" | transition 允许时显示 | 按住时的着色。这是告诉用户按下已生效的反馈。 |
| disabledColor | Color | "#80808080" | transition 允许时显示 | 按钮禁用时的着色。通常是变淡或降低饱和度。 |
| normalSprite | AssetRef (Sprite) | "" | transition 允许时显示 | 精灵切换模式下，空闲时的精灵。 |
| hoveredSprite | AssetRef (Sprite) | "" | transition 允许时显示 | 精灵切换模式下，悬停时的精灵。 |
| pressedSprite | AssetRef (Sprite) | "" | transition 允许时显示 | 精灵切换模式下，按住时的精灵。 |
| disabledSprite | AssetRef (Sprite) | "" | transition 允许时显示 | 精灵切换模式下，禁用时的精灵。 |
ClipComponent
将子对象的渲染裁剪到一个矩形内。
检视器中的名称：裁剪组件 · 类别：核心 · 类型：Deki2D::ClipComponent
| 属性 | 类型 | 默认值 | 约束 | 说明 |
|---|---|---|---|---|
| width | float | 6.25 | 单位 m | 裁剪窗口的宽度，单位为米。子对象在此边缘被裁掉。 |
| height | float | 6.25 | 单位 m | 裁剪窗口的高度，单位为米。 |
| sortingOrder | int32 | 0 | 整个被裁剪组相对于组外所有内容的绘制顺序。 |
GradientComponent
绘制程序化渐变：线性、径向或锥形。
检视器中的名称：渐变组件 · 类别：2D · 类型：Deki2D::GradientComponent
| 属性 | 类型 | 默认值 | 约束 | 说明 |
|---|---|---|---|---|
| gradientType | enum | "Linear" | Linear, Radial, Conical | 线性沿下方的角度排布颜色。径向从中心点向外排布颜色。 |
| tileMode | enum | "None" | None, Horizontal, Vertical, Both, Mirror | 超过最后一个色标之后的处理方式：保持末端颜色、重复渐变，或镜像折返。 |
| ditherMode | enum | "Ordered4x4" | None, Ordered2x2, Ordered4x4, Ordered8x8, Ordered16x16 | 抖动以细小的颗粒为代价，隐藏平滑渐变在 16 位显示屏上出现的色带。 |
| ditherScale | uint8 | 1 | 抖动图案的大小，以美术像素为单位。1 为逐像素抖动；2、4、8 或 16 会形成更粗的方块，呈现复古风格。 | |
| width | float | 0 | 单位 m | 渐变的宽度，单位为米。 |
| height | float | 0 | 单位 m | 渐变的高度，单位为米。 |
| angle | float | 0 | 单位 rad | 线性渐变的方向，单位为弧度。0 表示从左到右。 |
| centerX | float | 0.5 | 径向渐变在宽度方向上的中心，范围 0 到 1。0.5 为正中。 | |
| centerY | float | 0.5 | 径向渐变在高度方向上的中心，范围 0 到 1。 | |
| radius | float | 0.5 | 径向渐变到达最后一个色标前延伸的距离，相对于大小。 | |
| stopCount | uint8 | 2 | 使用四个色标中的几个。其余的会被忽略。 | |
| stop1Position | float | 0 | 第一个色标在渐变上的位置，范围 0 到 1。 | |
| stop1Color | Color | "#FFFFFFFF" | 第一个色标处的颜色。 | |
| stop2Position | float | 1 | stopCount 允许时显示 | 第二个色标在渐变上的位置，范围 0 到 1。 |
| stop2Color | Color | "#000000FF" | stopCount 允许时显示 | 第二个色标处的颜色。 |
| stop3Position | float | 0 | stopCount 允许时显示 | 第三个色标的位置，范围 0 到 1。色标数量为 3 或以上时使用。 |
| stop3Color | Color | "#000000FF" | stopCount 允许时显示 | 第三个色标处的颜色。 |
| stop4Position | float | 0 | stopCount 允许时显示 | 第四个色标的位置，范围 0 到 1。色标数量为 4 时使用。 |
| stop4Color | Color | "#000000FF" | stopCount 允许时显示 | 第四个色标处的颜色。 |
| tileWidth | float | 0 | 单位 m | 平铺模式为重复或镜像时，一次重复的宽度。 |
| tileHeight | float | 0 | 单位 m | 平铺模式为重复或镜像时，一次重复的高度。 |
从 RendererComponent 继承 sortingOrder, ignoreClip, pixelSnap, alphaMode。
RollerComponent
滚轮选择器：带惯性地滚过一列值，并停靠在其中一个上。
检视器中的名称：滚轮选择器组件 · 类别：2D · 类型：Deki2D::RollerComponent
| 属性 | 类型 | 默认值 | 约束 | 说明 |
|---|---|---|---|---|
| inputCollider | ObjectRef (InputCollider) | 0 | 接收拖动的点击区域。没有它，滚轮选择器无法转动。 | |
| width | float | 6.25 | 单位 m | 滚轮选择器的宽度，单位为米。 |
| itemHeight | float | 1.875 | 单位 m | 一个未选中行的高度，单位为米。 |
| visibleRows | int32 | 3 | 同时显示的行数，包括选中的行。奇数会使选中项居中。 | |
| infiniteScroll | bool | false | 从最后一个选项绕回第一个，使滚轮选择器可以无尽转动。 | |
| reverseDrag | bool | false | 反转拖动方向。 | |
| options | Array<string> | [] | 按顺序排列的选项列表。 | |
| selectedIndex | int32 | 0 | 当前选中的选项，从 0 开始计数。 | |
| deceleration | float | 0.95 | 快速滑动后减速的快慢。越高停得越快。 | |
| snapSpeed | float | 8 | 减速后滚轮选择器停到最近选项上的速度。越高吸附越果断。 | |
| selectedItemHeight | float | 2.5 | 单位 m | 选中行的高度，单位为米。让它比其他行更高，正是用来标示选中项的方式。 |
| selectedColor | Color | "#FFFFFFFF" | 选中行的文字颜色。 | |
| normalColor | Color | "#808080FF" | 两侧各行的文字颜色。 | |
| selectedFontSize | int32 | 24 | 选中行在编辑器中的预览字号。设备上按字体资源烘焙时的字号绘制。 | |
| normalFontSize | int32 | 16 | 未选中行在编辑器中的预览字号。 |
ScrollComponent
通过拖动滚动子对象，带有惯性。
检视器中的名称：滚动组件 · 类别：2D · 类型：Deki2D::ScrollComponent
| 属性 | 类型 | 默认值 | 约束 | 说明 |
|---|---|---|---|---|
| inputCollider | ObjectRef (InputCollider) | 0 | 接收拖动的点击区域。没有它就无法滚动。 | |
| mode | enum | "NonTemplate" | NonTemplate, Template | 项是来自已有的子对象，还是在需要时从下方的场景生成。 |
| itemScene | AssetRef (Scene) | "" | mode 允许时显示 | 在生成模式下，每个项生成一次的场景。每个副本在滚动进入视野时填充内容。 |
| direction | enum | "Vertical" | Vertical, Horizontal | 垂直或水平移动。 |
| itemSpacing | float | 0 | 单位 m | 项与项之间的间隙，单位为米。 |
| paddingTop | float | 0 | 单位 m | 第一个项之前的空白，单位为米。 |
| paddingBottom | float | 0 | 单位 m | 最后一个项之后的空白，单位为米。 |
| paddingLeft | float | 0 | 单位 m | 左边缘的空白，单位为米。 |
| paddingRight | float | 0 | 单位 m | 右边缘的空白，单位为米。 |
| deceleration | float | 0.95 | 快速滑动后减速的快慢。越高停得越快；越低滑行越久。 | |
| bounceStiffness | float | 0.15 | 列表被拖过末端后回弹的力度。越高弹回越快。 | |
| enableBounce | bool | true | 允许列表被拖过末端后再弹回。关闭时会在边缘处直接停住。 | |
| enableInertia | bool | true | 手指抬起后继续移动。关闭时列表在拖动结束的瞬间停止。 | |
| reverseDrag | bool | false | 反转拖动方向，使内容朝手指相反的方向移动。 |
ScrollElement
声明一个列表项的大小，以便其滚动组件排布列表。
检视器中的名称：滚动元素 · 类别：2D · 类型：Deki2D::ScrollElement
| 属性 | 类型 | 默认值 | 约束 | 说明 |
|---|---|---|---|---|
| width | float | 6.25 | 单位 m | 一个项的宽度，单位为米。滚动组件用它计算间距和可滚动的距离。 |
| height | float | 3.75 | 单位 m | 一个项的高度，单位为米。 |
SortingGroupComponent
让子对象作为一个整体，与场景中的其余部分一起排序。
检视器中的名称：排序组组件 · 类别：2D · 类型：Deki2D::SortingGroupComponent
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| sortingOrder | int32 | 0 | 将此对象的整个子树视为一个整体时的绘制顺序。子对象之间保持相对顺序，但整组一起移动，从而避免某个子对象被排到另一组的子对象之间。 |
SpriteComponent
绘制精灵，支持着色、翻转以及平铺或九宫格模式。
检视器中的名称：精灵组件 · 类别：2D · 类型：Deki2D::SpriteComponent
| 属性 | 类型 | 默认值 | 约束 | 说明 |
|---|---|---|---|---|
| sprite | AssetRef (Sprite) | "" | 要绘制的图像。精灵来自纹理资源，可以是整张图，也可以从精灵图集中切出。 | |
| tintColor | Color | "#FFFFFFFF" | 与每个像素相乘。白色则保持图像不变；较暗的颜色会使其变暗，Alpha 则使其淡出。 | |
| renderMode | enum | "Normal" | Normal, Tiled, NineSlice | 正常只绘制一次精灵。平铺会重复精灵以填满下方的大小。九宫格拉伸中间部分并保持四角不变，适合面板和按钮。 |
| flipHorizontal | bool | false | 左右镜像。比再用一个精灵更省，也是让角色转向另一侧的常用方法。 | |
| flipVertical | bool | false | 上下镜像。 | |
| width | float | 0 | 单位 m；renderMode 允许时显示 | 绘制大小，单位为米。保持为 0 时使用精灵自身的像素大小，并按项目的每米像素数换算。 |
| height | float | 0 | 单位 m；renderMode 允许时显示 | 绘制大小，单位为米。保持为 0 时使用精灵自身的像素大小，并按项目的每米像素数换算。 |
从 RendererComponent 继承 sortingOrder, ignoreClip, pixelSnap, alphaMode。
TextComponent
使用位图字体绘制文本，支持对齐和自动换行。
检视器中的名称：文本组件 · 类别：2D · 类型：Deki2D::TextComponent
| 属性 | 类型 | 默认值 | 约束 | 说明 |
|---|---|---|---|---|
| text | string | "" | 要绘制的字符串。换行符会另起一行；设置了宽度时，会在单词之间自动换行以适应宽度。 | |
| font | AssetRef (BitmapFont) | "" | 位图字体资源。字体按固定字号烘焙，因此请选择接近所需大小的字体，而不要大幅缩放。 | |
| fontSize | int32 | 16 | 仅用于编辑器预览的字号。设备上绘制的是字体资源烘焙时的字号。 | |
| width | float | 6.25 | 单位 m | 文本框的宽度，单位为米。对齐以此为基准，因此即使文字较短也有影响。 |
| height | float | 1.5 | 单位 m | 文本框的高度，单位为米。垂直对齐以此为基准。 |
| color | Color | "#FFFFFFFF" | 字形的颜色。 | |
| decorationColor | Color | "#000000FF" | 字体资源烘焙了描边或阴影时，描边或阴影的颜色。普通字体会忽略此项。 | |
| pixelScale | int32 | 1 | 整数倍放大。2 会把每个字形像素绘制为 2x2 的方块，使像素字体保持清晰而不模糊。 | |
| align | enum | "Left" | Left, Center, Right | 在上方宽度内的水平位置。 |
| verticalAlign | enum | "CapCenter" | Top, Middle, Bottom, CapCenter, XCenter, TypoCenter, Baseline | 在上方高度内的垂直位置。大写居中以大写字母为准对齐，通常在视觉上显得居中；真正的居中会把下伸部分也算在内。 |
从 RendererComponent 继承 sortingOrder, ignoreClip, pixelSnap, alphaMode。
更新日志
更新日志为英文。
0.19.0
Changed
- minEngine 0.19.0: built against engine 0.19.0, whose component metadata records the package each class is in. A build of this package from before does not load and is rebuilt.
Added
- Japanese, Simplified Chinese and Korean: editor/lang/ja.json, zh.json and ko.json translate the names, tooltips and enum values this package's components show in the Inspector.
- The package's editor text goes through the editor's translation (Tr), so it shows in the editor's language. Needs the editor release that adds Localization.h; raise minEngine to it when releasing.
0.18.2
Added
- sprite_nine_slice CLI and MCP tool: sets an image's 9-slice borders.
Changed
- A 9-slice or tiled sprite in RGB565 or RGB565A8 without a chroma key has its tint baked into the image it keeps of itself, baked again when the tint changes, and is drawn untinted: a copy of its opaque runs instead of a tint on every pixel, every frame. Tinted panels were most of the time in the T-Deck demo's GPS and LoRa screens, which went from 55 to 63 fps.
Fixed
- A dithered gradient kept its pattern only at whole-number zoom: in the editor's scene view its Bayer cells were laid out in screen pixels, rounded to whole ones, and drifted against the gradient's own pixels, so each zoom showed a different, uneven stipple. The pattern is now laid out on the art grid like the colour, and zooming in only magnifies it. Zoomed far in, the bake was also capped below the screen's density and scaled twice, which made some cells twice as wide as others: drawn at its own size or larger it is now baked at art size and magnified once, so every cell is the same size and zooming no longer re-bakes it. Drawn smaller than its own size, the pattern stays a regular stipple in screen pixels, as in 0.17. On the device at 1:1 the picture is unchanged.
更早的版本：CHANGELOG.md
由包的反射数据生成（引擎 0.19.0）。属性名就是场景文件中使用的键。重命名后会保留别名（兼容性）。
