Software-rasterised 3D as a render pass: meshes, a perspective camera and .obj import, sharing one framebuffer with 2D
Repository: github.com/dekiengine/deki-3d · Latest release: 0.19.0 · Needs engine 0.19.0+ · Requires: deki-rendering
Install with DekiEditor --packages-add deki-3d <project>, or from the Package Manager. The engine's own components and C++ API are in the Deki docs.
Shown in the editor as 3D.
Components
| Component | Category | Description |
|---|---|---|
| Mesh3DSettings | 3D | How the 3D pass draws: tiles, texture and vertex switches, light and threads. |
| MeshComponent | 3D | Draws a 3D mesh. The object's transform places it, and the scene camera must be Perspective to see it. |
Feature flags
Parts you can leave out of a build. A feature with a define is switched there; the rest are stripped with their components.
| Feature | Define | Default |
|---|---|---|
| Software rasteriser | DEKI_FEATURE_3D_SOFTWARE | on |
Component reference
Mesh3DSettings
How the 3D pass draws: tiles, texture and vertex switches, light and threads.
Inspector name: Mesh3D Settings · Category: 3D · Type: Deki3D::Mesh3DSettings
| Property | Type | Default | Constraints | Description |
|---|---|---|---|---|
| tileSize | int32 | 32 | 8 to 512 | Tile edge in pixels. The depth buffer is one tile, so 32 costs 2 KB and suits a microcontroller, while a desktop can afford 128 or more. |
| perspectiveCorrect | bool | true | Correct texture perspective. Turning it off gives the warping of PlayStation-era hardware, and saves about a tenth of the fill cost. | |
| vertexSnap | bool | false | Round projected vertices to whole pixels, for the jitter of fixed-point era hardware. | |
| lightYaw | float | -25 | -180 to 180 | Direction the scene light comes from, swept around the vertical axis. 0 puts it behind the camera, 90 to the right. |
| lightPitch | float | 55 | -90 to 90 | How high the scene light sits. 90 is directly overhead, 0 level with the horizon. |
| ambient | float | 0.25 | 0 to 1 | How lit the faces turned away from the light still are. 0 leaves them black, which is dramatic; higher flattens the shading out. |
| fillThreads | int32 | 1 | 1 to 16 | How many threads fill the screen on a device or simulator build. Tiles are independent, so this is the one part that scales with cores: 1 starts no threads at all, 2 suits a dual-core board, and above the core count it stops helping. The editor always previews with one thread, since it loads packages as unloadable DLLs; the picture is identical either way. |
MeshComponent
Draws a 3D mesh. The object's transform places it, and the scene camera must be Perspective to see it.
Inspector name: Mesh Component · Category: 3D · Type: Deki3D::MeshComponent
| Property | Type | Default | Constraints | Description |
|---|---|---|---|---|
| mesh | AssetRef (MeshAsset) | "" | A compiled mesh asset. Assign an imported model here; leave it empty to draw the primitive below instead. | |
| primitive | enum | "Cube" | Cube, Quad, Pyramid | Which built-in shape to draw while no mesh asset is assigned. |
| tintColor | Color | "#000000FF" | Multiplies the mesh's own colours. White leaves them alone. | |
| shading | enum | "VertexLit" | Unlit, VertexLit, Flat | Unlit is flat colour. Vertex lit shades each vertex against the scene light. Flat shades whole triangles, which is the faceted look. |
| doubleSided | bool | false | Draw the inside of the mesh as well as the outside. Costs roughly double the fill. |
Inherits sortingOrder, ignoreClip, pixelSnap, alphaMode from RendererComponent.
Changelog
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.0
Changed
- minEngine 0.18.0. Reflection ABI 21: the package must be rebuilt.
- Names follow the code style (deki-engine/docs/codestyle): types, functions and enum values are PascalCase, constants kPascalCase, members m_PascalCase, locals and parameters camelCase. The code is formatted with clang-format 22.
- The functions the editor finds by name are PascalCase: Deki3DRegisterComponents, Deki3DGetAutoComponentCount, Deki3DEnsureRegistered and the rest. Built against engine ABI 21; a build of this package from before does not load and is rebuilt.
- Renamed: MeshAttribute_Position and the other mesh flags are MeshAttributePosition, ...; MeshMaterial_AlphaTest is MeshMaterialAlphaTest; AssetTypeName is kAssetTypeName.
Removed
- Reading version 3 mesh files (before 0.17.0). The editor builds them again.
- The loader for Camera3DComponent, the 3D camera of scenes saved before 0.17.0. Open and save such a scene with 0.17 first.
- The former names from before 0.16.0 (bare class names, and deki-gpio's DekiEsp32::ESP32PinSetup). A scene that old is upgraded with 0.17 first.
Earlier releases: CHANGELOG.md.
Generated from the package's reflection data (engine 0.19.0). Property names are the keys used in scene files. Renames keep an alias (compatibility).
