3D Engine
Source section: `https://appsudo.com/doc#engine3d`

The 3D Engine reference covers the Canvas3D foundation and every public name exported by `components.extras.engine3d`. The example guides link here for exact signatures and member lists.

## Canvas3D Foundation

`Canvas3D()` owns the drawing surface. `GameWindow3D` receives creation, resize, draw, input, pause, resume, and destruction callbacks. The `Device` creates resources and `Frame` records drawing. See [Canvas3D Game](https://appsudo.com/doc#canvas3d-game) for the complete CubeGfx example.

### Canvas3D

Use `Canvas3D()` with no documented constructor parameters. Set MSAA, depth bits, stencil, transparency, debug mode, and the app directory before the canvas is first shown. Target FPS can change later. `close()` releases the canvas and it must not be used again.

### GameWindow3D

Create resources in `on_create`, rebuild projection state in `on_resize`, record at most one frame block in `on_draw`, and release resources in `on_destroy`. `on_enable` and `start` hooks on engine components run during `scene.update(dt)`, not when `scene.create(...)` is called.

### Device, Frame, resources, shaders, and math

Pipelines and file textures resolve asynchronously. Buffer input must be `array.array`, `bytes`, or `bytearray`. Projection builders must receive `zero_to_one=gfx.clip_zero_to_one`. Render-target signatures include their sample count. Compressed texture formats are `etc2_rgb8`, `etc2_rgba8`, `astc_4x4`, `astc_6x6`, `astc_8x8`, `bc1`, `bc3`, and `bc7`. Supply RGBA fallback pixels when a format cannot be decoded directly.

## Feature Guide

### Environment effects

`Water` uses four Gerstner waves. `shallow`, `deep`, `amplitude`, `speed`, and `foam` control its appearance. `Terrain` builds a sampled surface. A changed `ProceduralSky` regenerates its environment cube, so update it at a controlled interval. Scene fog uses `none`, `linear`, or `exp2`; linear fog uses `fog_start` and `fog_end`, while exp2 uses `fog_density`.

```python
from components.extras.engine3d import ProceduralSky, Water

engine.scene.skybox = ProceduralSky(sun_dir=(0.4, 0.8, 0.3), env_size=16)
water = Water(size=(560.0, 560.0), cells=150, shallow="#2fa6b8", deep="#07324f", amplitude=0.16, speed=0.9, foam=0.06)
engine.scene.create("water", None, (32.0, 7.0, 32.0), water)
```

### Particles, instancing, and decals

`GPUParticles` supports looping effects and one-shot effects started with `play()`. Configure start and end color, start and end size, gravity, drag, spin, emission shape, and alpha or additive blending. `InstancedMeshRenderer.set_transforms` accepts position, rotation, and scale triples. Instance batches are split into chunks of 128. `Decal` projects onto static geometry and uses `max_angle` as its surface cutoff. Call `rebake()` after affected geometry moves.

```python
from components.extras.engine3d import Decal, GPUParticles, InstancedMeshRenderer

rain = GPUParticles(count=1600, lifetime=1.0, speed=(0.2, 0.6), size=(0.07, 0.07), shape="box", radius=13.0, gravity=(0.0, -34.0, 0.0), blend="additive")
clouds = InstancedMeshRenderer(mesh, material, cast_shadows=False, receive_shadows=False)
clouds.set_transforms([((0.0, 12.0, 0.0), None, (8.0, 1.6, 5.0))])
ring = Decal(texture, size=(4.0, 4.0, 3.0), max_angle=70.0)
```

### Post-processing and quality

`PostStack` owns ordered effects. `SSAO` uses scene depth and can run with its depth-aware blur. `CustomEffect` reads vec4 parameters named `p0`, `p1`, and later names in sequence. `QualitySettings` levels are `low`, `medium`, `high`, and `ultra`. They change shadows, shadow maps, lights, cascades, render scale, post effects, LOD, occlusion, shadow distance, particle scale, and MSAA.

```python
from components.extras.engine3d import CustomEffect, PostStack, QualitySettings, SSAO

post = PostStack.standard(bloom=True, vignette=True, fxaa=True)
post.add(SSAO(radius=0.8, bias=0.04, intensity=1.1, strength=0.9))
post.add(CustomEffect("world/underwater", "ldr", params={"p0": (0.0, 0.0, 0.0, 0.0), "p1": (0.25, 0.6, 0.75, 0.0)}))
QualitySettings("high").apply(engine)
```

### Shader packages

Shader package JSON uses `kind` values `shader`, `post`, or `chunk`, and shader bases `pbr`, `unlit`, or `custom`. Surface packages can define blocks, material fields, properties, samplers, varyings, defines, includes, keywords, render queue, shadow program, and hook text. Hook points include `vertex_hook`, `vertex_post`, `surface`, `color`, `color_post`, and `fragment`. A custom post package reads `p0`, `p1`, and later vec4 parameters supplied by `CustomEffect`.

```python
import json
from components.extras.engine3d import load_shader_text

package = {
    "kind": "post",
    "name": "game/tint",
    "samplers": ["src"],
    "fragment": "float3 c = SAMPLE2D(src, fin.uv).rgb; return float4(c * post.p0.rgb, 1.0);",
}
load_shader_text(json.dumps(package))
```

### Audio

Create audio output through `AudioOutput` from `components.extras.audio`. Attach the returned object to `engine.audio`. Use engine audio for buses, filters, effects, spatial modes, music, and positioned clips. `ReverbZone` supplies size, blend distance, priority, decay, damping, room size, wet level, and send level. The worldgfx underwater pattern applies low-pass filters of 600 Hz to music and 900 Hz to effects, then clears both filters when leaving the water.

```python
from components.extras.audio import AudioOutput

output = AudioOutput(canvas)
engine.audio.attach(output.start())
engine.audio.set_spatial_mode("hrtf")
engine.audio.set_bus_filter("music", lowpass=600.0)
engine.audio.set_bus_filter("sfx", lowpass=900.0)
```

### Haptics, sensors, and input

`Sensors.enable("gyro", rate_hz=60)` starts angular velocity sampling. Sensor events provide the sensor name, values, and a millisecond timestamp. Gyroscope values are radians per second. `disable("gyro")` stops it. worldgfx converts the first two gyro values to degrees and scales them by `engine.time.delta_time` for tilt look. `Haptics` exposes named feedback patterns and `buzz`.

```python
engine.sensors.enable("gyro", rate_hz=60)
gx, gy, gz = engine.sensors.gyroscope
engine.sensors.disable("gyro")
```

### Text overlay

GUI callbacks record text and sprites after scene cameras and post effects. Use `engine.add_gui`, `engine.ui`, `UI`, `SpriteBatch`, and `BitmapFont`. Coordinates are pixels with the origin at the top left, and y increases downward. UI may claim a pointer so gameplay does not process the same input.

### Confirmed lifecycle rules

- `scene.create(...)` returns a `Node`. Retrieve a component with `node.get_component(Type)`.
- Component `on_enable` and `start` run during `scene.update(dt)`, not during creation.
- Read time deltas from `engine.time.delta_time` and `engine.time.unscaled_delta_time`.
- Render-target signatures include their sample count.
- Throttle `ProceduralSky` changes because each changed environment key regenerates its cube.
- A camera must exclude the layer containing a surface that samples that camera's render target.

## Core, Scenes, and Components
### Bounds

Public core class.

Import: `from components.extras.engine3d import Bounds`

Signature: `Bounds(mn=(0.0, 0.0, 0.0), mx=(0.0, 0.0, 0.0))`

| Parameter | Type | Default |
| --- | --- | --- |
| mn | Value | (0.0, 0.0, 0.0) |
| mx | Value | (0.0, 0.0, 0.0) |

| Member | Kind |
| --- | --- |
| center | property |
| extents | property |
| radius | property |
| transformed(self, m: 'Mat4') -> "'Bounds'" | method |
| union(self, o: "'Bounds'") -> "'Bounds'" | method |
| intersects(self, o: "'Bounds'") -> 'bool' | method |
| contains_point(self, p) -> 'bool' | method |

```python
from components.extras.engine3d import Bounds
```

### Color

Public core class.

Import: `from components.extras.engine3d import Color`

Signature: `Color(r: 'float' = 1.0, g: 'float' = 1.0, b: 'float' = 1.0, a: 'float' = 1.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| r | 'float' | 1.0 |
| g | 'float' | 1.0 |
| b | 'float' | 1.0 |
| a | 'float' | 1.0 |

| Member | Kind |
| --- | --- |
| from_hex(value: 'str') -> "'Color'" | method |
| of(value) -> "'Color'" | method |
| srgb_to_linear(self) -> "'Color'" | method |
| scaled(self, s: 'float') -> "'Color'" | method |
| to_tuple(self) -> 'Tuple[float, float, float, float]' | method |

```python
from components.extras.engine3d import Color
```

### Frustum

Public core class.

Import: `from components.extras.engine3d import Frustum`

Signature: `Frustum(planes: 'List[Tuple[float, float, float, float]]')`

| Parameter | Type | Default |
| --- | --- | --- |
| planes | 'List[Tuple[float, float, float, float]]' | Required |

| Member | Kind |
| --- | --- |
| from_matrix(vp: 'Mat4', zero_to_one: 'bool' = False) -> "'Frustum'" | method |
| contains_sphere(self, cx: 'float', cy: 'float', cz: 'float', r: 'float') -> 'bool' | method |
| contains_aabb(self, mn: 'Sequence[float]', mx: 'Sequence[float]') -> 'bool' | method |

```python
from components.extras.engine3d import Frustum
```

### GpuContext

Public core class.

Import: `from components.extras.engine3d import GpuContext`

Signature: `GpuContext()`

| Member | Kind |
| --- | --- |
| attach(self, gfx) -> 'None' | method |
| detach(self) -> 'None' | method |
| ready | property |

```python
from components.extras.engine3d import GpuContext
```

### Engine

Owns the active scene, rendering, physics, input, audio, time, assets, and UI services.

Import: `from components.extras.engine3d import Engine`

Signature: `Engine(root: 'str' = '', fixed_dt: 'float' = 0.016666666666666666, max_fixed_steps: 'int' = 5, max_delta: 'float' = 0.1)`

| Parameter | Type | Default |
| --- | --- | --- |
| root | 'str' | '' |
| fixed_dt | 'float' | 0.016666666666666666 |
| max_fixed_steps | 'int' | 5 |
| max_delta | 'float' | 0.1 |

| Member | Kind |
| --- | --- |
| new_scene(self, name: 'str' = 'Scene') -> 'Scene' | method |
| load_scene(self, path: 'str') -> 'Scene' | method |
| load_scene_text(self, text: 'str') -> 'Scene' | method |
| load_scene_additive(self, source: 'str', parent: 'Optional[Node]' = None, offset=None) | method |
| instantiate(self, prefab, position=None, parent: 'Optional[Node]' = None, overrides=None) -> 'Node' | method |
| attach(self, gfx) -> 'None' | method |
| detach(self) -> 'None' | method |
| resize(self, width: 'int', height: 'int') -> 'None' | method |
| add_gui(self, fn: "Callable[['Engine'], None]") -> 'None' | method |
| spawn(self, name: 'str' = 'Node', position=(0.0, 0.0, 0.0), *components, parent: 'Optional[Node]' = None) -> 'Node' | method |
| tick(self, gfx, dt: 'float') -> 'None' | method |

```python
from components.extras.engine3d import Engine
```

### EngineWindow

Connects a Canvas3D to an Engine and provides the setup and per-tick hooks used by a game.

Import: `from components.extras.engine3d import EngineWindow`

Signature: `EngineWindow(canvas, setup: 'Optional[Callable[[Engine], None]]' = None, root: 'str' = '', **engine_kwargs)`

| Parameter | Type | Default |
| --- | --- | --- |
| canvas | Value | Required |
| setup | 'Optional[Callable[[Engine], None]]' | None |
| root | 'str' | '' |
| **engine_kwargs | Values | Optional |

| Member | Kind |
| --- | --- |
| setup(self, engine: 'Engine') -> 'None' | method |
| on_gui(self, engine: 'Engine') -> 'None' | method |
| on_create(self, gfx) | method |
| on_resize(self, gfx, width, height) | method |
| on_draw(self, gfx, dt) | method |
| on_touch_event(self, ev: 'TouchEvent') | method |
| on_gamepad_button(self, pad, button, value) | method |
| on_gamepad_axis(self, pad, axis, value) | method |
| on_gamepad_connection(self, pad, connected, name) | method |
| on_pause(self) | method |
| on_resume(self) | method |
| on_destroy(self, gfx) | method |

```python
from components.extras.engine3d import EngineWindow
```

### Time

Reports scaled and unscaled frame timing, fixed-step timing, frame count, and FPS.

Import: `from components.extras.engine3d import Time`

Signature: `Time(fixed_delta: 'float' = 0.016666666666666666)`

| Parameter | Type | Default |
| --- | --- | --- |
| fixed_delta | 'float' | 0.016666666666666666 |

```python
from components.extras.engine3d import Time
```

### Behaviour

Component base with an enabled state.

Import: `from components.extras.engine3d import Behaviour`

Signature: `Behaviour()`

| Member | Kind |
| --- | --- |
| scene | property |
| engine | property |
| transform | property |
| awake(self) | method |
| on_enable(self) | method |
| on_disable(self) | method |
| start(self) | method |
| update(self, dt: 'float') | method |
| late_update(self, dt: 'float') | method |
| fixed_update(self, dt: 'float') | method |
| on_destroy(self) | method |
| on_collision_enter(self, other: "'Node'") | method |
| on_collision_stay(self, other: "'Node'") | method |
| on_collision_exit(self, other: "'Node'") | method |
| on_trigger_enter(self, other: "'Node'") | method |
| on_trigger_exit(self, other: "'Node'") | method |
| on_draw_gizmos(self, gizmos) | method |
| to_dict(self) -> 'dict' | method |

```python
from components.extras.engine3d import Behaviour
```

### Component

Base class for reusable behavior attached to a node.

Import: `from components.extras.engine3d import Component`

Signature: `Component()`

| Member | Kind |
| --- | --- |
| scene | property |
| engine | property |
| transform | property |
| awake(self) | method |
| on_enable(self) | method |
| on_disable(self) | method |
| start(self) | method |
| update(self, dt: 'float') | method |
| late_update(self, dt: 'float') | method |
| fixed_update(self, dt: 'float') | method |
| on_destroy(self) | method |
| on_collision_enter(self, other: "'Node'") | method |
| on_collision_stay(self, other: "'Node'") | method |
| on_collision_exit(self, other: "'Node'") | method |
| on_trigger_enter(self, other: "'Node'") | method |
| on_trigger_exit(self, other: "'Node'") | method |
| on_draw_gizmos(self, gizmos) | method |
| to_dict(self) -> 'dict' | method |

```python
from components.extras.engine3d import Component
```

### Node

Stores a transform, hierarchy position, layer, active state, and attached components.

Import: `from components.extras.engine3d import Node`

Signature: `Node(name: 'str' = 'Node', position=(0.0, 0.0, 0.0), rotation: 'Optional[Quat]' = None, scale=1.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'str' | 'Node' |
| position | Value | (0.0, 0.0, 0.0) |
| rotation | 'Optional[Quat]' | None |
| scale | Value | 1.0 |

| Member | Kind |
| --- | --- |
| touch(self) -> 'None' | method |
| position | property |
| rotation | property |
| scale | property |
| world_matrix | property |
| world_version | property |
| local_matrix | property |
| world_position | property |
| world_rotation | property |
| world_scale | property |
| forward | property |
| right | property |
| up | property |
| set_world_position(self, p: 'Vec3') -> 'None' | method |
| set_world_rotation(self, q: 'Quat') -> 'None' | method |
| path(self) -> 'str' | method |
| set_world_matrix(self, m: 'Mat4') -> 'None' | method |
| translate(self, x: 'float', y: 'float', z: 'float', local: 'bool' = False) -> 'None' | method |

```python
from components.extras.engine3d import Node
```

### Scene

Owns the node hierarchy and scene-wide environment settings.

Import: `from components.extras.engine3d import Scene`

Signature: `Scene(name: 'str' = 'Scene', engine=None)`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'str' | 'Scene' |
| engine | Value | None |

| Member | Kind |
| --- | --- |
| add(self, node: 'Node', parent: 'Optional[Node]' = None) -> 'Node' | method |
| create(self, name: 'str' = 'Node', parent: 'Optional[Node]' = None, position=(0.0, 0.0, 0.0), *components) -> 'Node' | method |
| nodes(self) -> 'List[Node]' | method |
| find(self, name: 'str') -> 'Optional[Node]' | method |
| main_camera(self) | method |
| find_with_tag(self, tag: 'str') -> 'List[Node]' | method |
| find_components(self, cls: 'Type[T]') -> 'List[T]' | method |
| begin_frame(self) -> 'None' | method |
| update(self, dt: 'float') -> 'None' | method |
| fixed_update(self, dt: 'float') -> 'None' | method |
| flush_destroyed(self) -> 'None' | method |
| clear(self) -> 'None' | method |

```python
from components.extras.engine3d import Scene
```

### register_component

Public core function.

Import: `from components.extras.engine3d import register_component`

Signature: `register_component(cls: 'Type[Component]', name: 'Optional[str]' = None) -> 'Type[Component]'`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'Optional[str]' | None |

```python
from components.extras.engine3d import register_component
```

### PrefabLibrary

Public core class.

Import: `from components.extras.engine3d import PrefabLibrary`

Signature: `PrefabLibrary(reader=None)`

| Parameter | Type | Default |
| --- | --- | --- |
| reader | Value | None |

| Member | Kind |
| --- | --- |
| register(self, ref: 'str', doc: 'dict') -> 'None' | method |
| resolved(self, ref: 'str', _stack: 'Optional[Set[str]]' = None) -> 'dict' | method |
| expand(self, d: 'dict', _stack: 'Optional[Set[str]]' = None) -> 'dict' | method |
| invalidate(self, ref: 'Optional[str]' = None) -> 'None' | method |

```python
from components.extras.engine3d import PrefabLibrary
```

### apply_overrides

Public core function.

Import: `from components.extras.engine3d import apply_overrides`

Signature: `apply_overrides(root: 'dict', ops: 'List[dict]') -> 'dict'`

| Parameter | Type | Default |
| --- | --- | --- |
| root | 'dict' | Required |
| ops | 'List[dict]' | Required |

```python
from components.extras.engine3d import apply_overrides
```

### diff_overrides

Public core function.

Import: `from components.extras.engine3d import diff_overrides`

Signature: `diff_overrides(base: 'dict', mod: 'dict') -> 'List[dict]'`

| Parameter | Type | Default |
| --- | --- | --- |
| base | 'dict' | Required |
| mod | 'dict' | Required |

```python
from components.extras.engine3d import diff_overrides
```

### instance_node

Public core function.

Import: `from components.extras.engine3d import instance_node`

Signature: `instance_node(ref: 'str', name: 'Optional[str]' = None, position=None, rotation=None, scale=None, overrides: 'Optional[List[dict]]' = None) -> 'dict'`

| Parameter | Type | Default |
| --- | --- | --- |
| ref | 'str' | Required |
| name | 'Optional[str]' | None |
| position | Value | None |
| rotation | Value | None |
| scale | Value | None |
| overrides | 'Optional[List[dict]]' | None |

```python
from components.extras.engine3d import instance_node
```

### make_variant

Public core function.

Import: `from components.extras.engine3d import make_variant`

Signature: `make_variant(base_ref: 'str', base_node: 'dict', modified_node: 'dict') -> 'dict'`

| Parameter | Type | Default |
| --- | --- | --- |
| base_ref | 'str' | Required |
| base_node | 'dict' | Required |
| modified_node | 'dict' | Required |

```python
from components.extras.engine3d import make_variant
```

### SceneHandle

Public core class.

Import: `from components.extras.engine3d import SceneHandle`

Signature: `SceneHandle(name: 'str', source: 'str')`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'str' | Required |
| source | 'str' | Required |

| Member | Kind |
| --- | --- |
| nodes | property |

```python
from components.extras.engine3d import SceneHandle
```

### SceneManager

Public core class.

Import: `from components.extras.engine3d import SceneManager`

Signature: `SceneManager(engine)`

| Parameter | Type | Default |
| --- | --- | --- |
| engine | Value | Required |

| Member | Kind |
| --- | --- |
| load(self, source: 'str', additive: 'bool' = False, parent: 'Optional[Node]' = None, offset=None, apply_scene_settings: 'Optional[bool]' = None) -> 'SceneHandle' | method |
| unload(self, handle: 'SceneHandle') -> 'None' | method |
| get(self, name: 'str') -> 'Optional[SceneHandle]' | method |
| ready(self) -> 'bool' | method |
| progress(self) -> 'float' | method |

```python
from components.extras.engine3d import SceneManager
```

## Rendering and Geometry
### Mesh

Public rendering class.

Import: `from components.extras.engine3d import Mesh`

Signature: `Mesh(data: 'MeshData', name: 'str' = 'mesh', dynamic: 'bool' = False)`

| Parameter | Type | Default |
| --- | --- | --- |
| data | 'MeshData' | Required |
| name | 'str' | 'mesh' |
| dynamic | 'bool' | False |

| Member | Kind |
| --- | --- |
| submeshes | property |
| skinned | property |
| ensure(self, attributes) -> 'bool' | method |
| layout(self) -> 'VertexLayout' | method |
| sync(self, ctx: 'GpuContext') -> 'bool' | method |
| update_vertices(self, ctx: 'GpuContext') -> 'None' | method |
| update_range(self, ctx: 'GpuContext', vertex_count: 'int') -> 'bool' | method |
| release(self) -> 'None' | method |

```python
from components.extras.engine3d import Mesh
```

### MeshData

Public rendering class.

Import: `from components.extras.engine3d import MeshData`

Signature: `MeshData()`

| Member | Kind |
| --- | --- |
| vertex_count | property |
| index_count | property |
| attributes(self) -> 'List[str]' | method |
| validate(self) -> 'None' | method |
| bounds(self) -> 'Bounds' | method |
| compute_normals(self) -> 'None' | method |
| compute_tangents(self) -> 'None' | method |
| orient_to_normals(self) -> 'None' | method |
| flip_winding(self) -> 'None' | method |
| append(self, other: "'MeshData'", transform=None) -> 'None' | method |

```python
from components.extras.engine3d import MeshData
```

### Gizmos

Public rendering class.

Import: `from components.extras.engine3d import Gizmos`

Signature: `Gizmos(capacity: 'int' = 3072, depth_test: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| capacity | 'int' | 3072 |
| depth_test | 'bool' | True |

| Member | Kind |
| --- | --- |
| clear(self) -> 'None' | method |
| line(self, a, b, color='#ffffff') -> 'None' | method |
| ray(self, origin, direction, length: 'float' = 1.0, color='#ffff00') -> 'None' | method |
| polyline(self, pts: 'Sequence', color='#ffffff', closed: 'bool' = False) -> 'None' | method |
| box(self, center, size, color='#00ff88', matrix: 'Mat4' = None) -> 'None' | method |
| circle(self, center, radius: 'float', normal_axis: 'str' = 'y', color='#00aaff', segments: 'int' = 24) -> 'None' | method |
| sphere(self, center, radius: 'float', color='#00aaff') -> 'None' | method |
| capsule(self, bottom, top, radius: 'float', color='#00aaff') -> 'None' | method |
| axes(self, origin, length: 'float' = 1.0) -> 'None' | method |
| grid(self, half: 'int' = 10, step: 'float' = 1.0, y: 'float' = 0.0, color='#404040') -> 'None' | method |
| prepare_view(self, view, renderer) -> 'None' | method |

```python
from components.extras.engine3d import Gizmos
```

### DynamicMesh

Public rendering class.

Import: `from components.extras.engine3d import DynamicMesh`

Signature: `DynamicMesh(capacity_quads: 'int', name: 'str' = 'dynamic', attributes=('position', 'uv', 'color'))`

| Parameter | Type | Default |
| --- | --- | --- |
| capacity_quads | 'int' | Required |
| name | 'str' | 'dynamic' |
| attributes | Value | ('position', 'uv', 'color') |

| Member | Kind |
| --- | --- |
| data | property |
| commit(self, ctx, quads: 'int') -> 'None' | method |

```python
from components.extras.engine3d import DynamicMesh
```

### DynamicRenderer

Public rendering class.

Import: `from components.extras.engine3d import DynamicRenderer`

Signature: `DynamicRenderer(material: 'Optional[Material]' = None)`

| Parameter | Type | Default |
| --- | --- | --- |
| material | 'Optional[Material]' | None |

| Member | Kind |
| --- | --- |
| prepare_view(self, view, renderer) -> 'None' | method |

```python
from components.extras.engine3d import DynamicRenderer
```

### MeshRenderer

Public rendering class.

Import: `from components.extras.engine3d import MeshRenderer`

Signature: `MeshRenderer(mesh: 'Optional[Mesh]' = None, material: 'Optional[Material]' = None, materials: 'Optional[Sequence[Material]]' = None, cast_shadows: 'bool' = True, receive_shadows: 'bool' = True, cull: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| mesh | 'Optional[Mesh]' | None |
| material | 'Optional[Material]' | None |
| materials | 'Optional[Sequence[Material]]' | None |
| cast_shadows | 'bool' | True |
| receive_shadows | 'bool' | True |
| cull | 'bool' | True |

| Member | Kind |
| --- | --- |
| material | property |
| is_skinned | property |
| palette(self) | method |
| world_bounds(self) -> 'Bounds' | method |
| material_for(self, submesh: 'int') -> 'Optional[Material]' | method |
| on_destroy(self) | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import MeshRenderer
```

### Renderer

Public rendering class.

Import: `from components.extras.engine3d import Renderer`

Signature: `Renderer(ctx: 'GpuContext')`

| Parameter | Type | Default |
| --- | --- | --- |
| ctx | 'GpuContext' | Required |

| Member | Kind |
| --- | --- |
| draw_view(self, frame, view: 'View') -> 'None' | method |
| prepare(self, scene, gfx, width: 'int', height: 'int', dt: 'float' = 0.016) -> 'RenderPlan' | method |
| submit(self, plan: 'RenderPlan', gfx, overlay: 'Optional[Callable]' = None) -> 'None' | method |
| render(self, scene, gfx, width: 'int', height: 'int', dt: 'float' = 0.016, overlay: 'Optional[Callable]' = None) -> 'RenderPlan' | method |
| pending_pipeline_count(self) -> 'int' | method |
| take_created_pipelines(self) -> 'List[Any]' | method |
| invalidate_bindings(self) -> 'None' | method |

```python
from components.extras.engine3d import Renderer
```

### LodGroup

Public rendering class.

Import: `from components.extras.engine3d import LodGroup`

Signature: `LodGroup(levels: 'Sequence[LodLevel]' = (), mode: 'str' = 'distance', cull_distance: 'float' = 0.0, hysteresis: 'float' = 0.05, bias: 'float' = 1.0, interval: 'float' = 0.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| levels | 'Sequence[LodLevel]' | () |
| mode | 'str' | 'distance' |
| cull_distance | 'float' | 0.0 |
| hysteresis | 'float' | 0.05 |
| bias | 'float' | 1.0 |
| interval | 'float' | 0.0 |

| Member | Kind |
| --- | --- |
| add_level(self, threshold: 'float', renderers: 'Sequence[MeshRenderer]') -> 'LodLevel' | method |
| apply(self, level: 'int', hide_all: 'bool' = False) -> 'None' | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |
| update(self, dt: 'float') | method |
| on_disable(self) | method |
| on_destroy(self) | method |

```python
from components.extras.engine3d import LodGroup
```

### LodLevel

Public rendering class.

Import: `from components.extras.engine3d import LodLevel`

Signature: `LodLevel(threshold: 'float', renderers: 'Sequence[MeshRenderer]' = ())`

| Parameter | Type | Default |
| --- | --- | --- |
| threshold | 'float' | Required |
| renderers | 'Sequence[MeshRenderer]' | () |

```python
from components.extras.engine3d import LodLevel
```

### TrailRenderer

Public rendering class.

Import: `from components.extras.engine3d import TrailRenderer`

Signature: `TrailRenderer(width: 'float' = 0.3, width_end: 'float' = 0.0, lifetime: 'float' = 0.6, min_distance: 'float' = 0.05, max_points: 'int' = 64, color: 'Optional[Gradient]' = None, texture: 'Optional[TextureAsset]' = None, blend: 'str' = 'additive', emitting: 'bool' = True, material: 'Optional[Material]' = None, face_camera: 'bool' = True, up=(0.0, 1.0, 0.0))`

| Parameter | Type | Default |
| --- | --- | --- |
| width | 'float' | 0.3 |
| width_end | 'float' | 0.0 |
| lifetime | 'float' | 0.6 |
| min_distance | 'float' | 0.05 |
| max_points | 'int' | 64 |
| color | 'Optional[Gradient]' | None |
| texture | 'Optional[TextureAsset]' | None |
| blend | 'str' | 'additive' |
| emitting | 'bool' | True |
| material | 'Optional[Material]' | None |
| face_camera | 'bool' | True |
| up | Value | (0.0, 1.0, 0.0) |

| Member | Kind |
| --- | --- |
| clear(self) -> 'None' | method |
| update(self, dt: 'float') | method |
| prepare_view(self, view, renderer) -> 'None' | method |
| to_dict(self) -> 'dict' | method |

```python
from components.extras.engine3d import TrailRenderer
```

### InstancedMeshRenderer

Draws many transforms with one mesh and material in bounded instance chunks.

Import: `from components.extras.engine3d import InstancedMeshRenderer`

Signature: `InstancedMeshRenderer(mesh=None, material=None, matrices: 'Optional[Sequence[Mat4]]' = None, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| mesh | Value | None |
| material | Value | None |
| matrices | 'Optional[Sequence[Mat4]]' | None |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| instance_count | property |
| matrices | property |
| set_instances(self, matrices: 'Sequence[Mat4]') -> 'None' | method |
| set_transforms(self, items) -> 'None' | method |
| add_instance(self, position=(0.0, 0.0, 0.0), rotation: 'Optional[Quat]' = None, scale=1.0) -> 'int' | method |
| update_instance(self, i: 'int', position=None, rotation=None, scale=None) -> 'None' | method |
| chunk_count(self) -> 'int' | method |
| chunk(self, i: 'int') -> 'List[Mat4]' | method |
| world_bounds(self) -> 'Bounds' | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import InstancedMeshRenderer
```

### StaticBatch

Bakes many static MeshRenderers that share a material into one world-space mesh (one draw call, one frustum test).

Import: `from components.extras.engine3d import StaticBatch`

Signature: `StaticBatch(renderers: 'Sequence[MeshRenderer]', name: 'str' = 'batch')`

| Parameter | Type | Default |
| --- | --- | --- |
| renderers | 'Sequence[MeshRenderer]' | Required |
| name | 'str' | 'batch' |

| Member | Kind |
| --- | --- |
| build(scene, renderers: 'Optional[Sequence[MeshRenderer]]' = None, name: 'str' = 'batch') -> "List['StaticBatch']" | method |
| bake(self, scene) -> 'MeshRenderer' | method |
| release(self) -> 'None' | method |

```python
from components.extras.engine3d import StaticBatch
```

### merge_mesh_data

Concatenate meshes with identical attribute sets into one (single submesh).

Import: `from components.extras.engine3d import merge_mesh_data`

Signature: `merge_mesh_data(parts: 'Sequence[MeshData]') -> 'MeshData'`

| Parameter | Type | Default |
| --- | --- | --- |
| parts | 'Sequence[MeshData]' | Required |

```python
from components.extras.engine3d import merge_mesh_data
```

### transform_mesh_data

A copy of `data` baked into the space of `m` (positions, normals, tangents).

Import: `from components.extras.engine3d import transform_mesh_data`

Signature: `transform_mesh_data(data: 'MeshData', m: 'Mat4') -> 'MeshData'`

| Parameter | Type | Default |
| --- | --- | --- |
| data | 'MeshData' | Required |
| m | 'Mat4' | Required |

```python
from components.extras.engine3d import transform_mesh_data
```

### trs

Public rendering function.

Import: `from components.extras.engine3d import trs`

Signature: `trs(position, rotation: 'Optional[Quat]' = None, scale=1.0) -> 'Mat4'`

| Parameter | Type | Default |
| --- | --- | --- |
| position | Value | Required |
| rotation | 'Optional[Quat]' | None |
| scale | Value | 1.0 |

```python
from components.extras.engine3d import trs
```

### Occluder

Marks a solid box (local `center`/`size`, transformed by the node) as able to hide other renderers.

Import: `from components.extras.engine3d import Occluder`

Signature: `Occluder(size=(1.0, 1.0, 1.0), center=(0.0, 0.0, 0.0))`

| Parameter | Type | Default |
| --- | --- | --- |
| size | Value | (1.0, 1.0, 1.0) |
| center | Value | (0.0, 0.0, 0.0) |

| Member | Kind |
| --- | --- |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import Occluder
```

### OcclusionCuller

Public rendering class.

Import: `from components.extras.engine3d import OcclusionCuller`

Signature: `OcclusionCuller(enabled: 'bool' = True, max_occluders: 'int' = 8, min_screen_size: 'float' = 0.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| enabled | 'bool' | True |
| max_occluders | 'int' | 8 |
| min_screen_size | 'float' | 0.0 |

| Member | Kind |
| --- | --- |
| hidden(self, cam_pos, rends: 'Sequence', occluders: 'Sequence[Occluder]') -> 'Set[int]' | method |

```python
from components.extras.engine3d import OcclusionCuller
```

## Cameras, Lights, and Environment
### Camera

Defines a view, projection, clear behavior, culling mask, target, and post stack.

Import: `from components.extras.engine3d import Camera`

Signature: `Camera(fov: 'float' = 60.0, near: 'float' = 0.1, far: 'float' = 500.0, orthographic: 'bool' = False, ortho_size: 'float' = 5.0, clear: 'str' = 'skybox', background=(0.04, 0.05, 0.07, 1.0), culling_mask: 'int' = -1, depth: 'int' = 0, viewport=(0.0, 0.0, 1.0, 1.0), target: 'Optional[RenderTexture]' = None, post=None, hdr: 'bool' = True, exposure: 'float' = 1.0, aspect: 'Optional[float]' = None, msaa_hint: 'bool' = False)`

| Parameter | Type | Default |
| --- | --- | --- |
| fov | 'float' | 60.0 |
| near | 'float' | 0.1 |
| far | 'float' | 500.0 |
| orthographic | 'bool' | False |
| ortho_size | 'float' | 5.0 |
| clear | 'str' | 'skybox' |
| background | Value | (0.04, 0.05, 0.07, 1.0) |
| culling_mask | 'int' | -1 |
| depth | 'int' | 0 |
| viewport | Value | (0.0, 0.0, 1.0, 1.0) |
| target | 'Optional[RenderTexture]' | None |
| post | Value | None |
| hdr | 'bool' | True |
| exposure | 'float' | 1.0 |
| aspect | 'Optional[float]' | None |
| msaa_hint | 'bool' | False |

| Member | Kind |
| --- | --- |
| sees(self, layer: 'int') -> 'bool' | method |
| view_matrix(self) -> 'Mat4' | method |
| projection_matrix(self, aspect: 'float', zero_to_one: 'bool' = False, flip_y: 'bool' = False) -> 'Mat4' | method |
| view_projection(self, aspect: 'float', zero_to_one: 'bool' = False, flip_y: 'bool' = False) -> 'Mat4' | method |
| frustum(self, aspect: 'float', zero_to_one: 'bool' = False) -> 'Frustum' | method |
| screen_point_to_ray(self, x: 'float', y: 'float', width: 'float', height: 'float') -> 'Ray' | method |
| world_to_screen(self, p: 'Vec3', width: 'float', height: 'float') -> 'Optional[Tuple[float, float, float]]' | method |
| screen_to_world(self, x: 'float', y: 'float', depth: 'float', width: 'float', height: 'float') -> 'Vec3' | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import Camera
```

### Ray

Public environment class.

Import: `from components.extras.engine3d import Ray`

Signature: `Ray(origin: 'Vec3', direction: 'Vec3')`

| Parameter | Type | Default |
| --- | --- | --- |
| origin | 'Vec3' | Required |
| direction | 'Vec3' | Required |

| Member | Kind |
| --- | --- |
| at(self, t: 'float') -> 'Vec3' | method |

```python
from components.extras.engine3d import Ray
```

### Bob

Public environment class.

Import: `from components.extras.engine3d import Bob`

Signature: `Bob(amplitude: 'float' = 0.25, frequency: 'float' = 1.0, axis=(0.0, 1.0, 0.0))`

| Parameter | Type | Default |
| --- | --- | --- |
| amplitude | 'float' | 0.25 |
| frequency | 'float' | 1.0 |
| axis | Value | (0.0, 1.0, 0.0) |

| Member | Kind |
| --- | --- |
| start(self) | method |
| update(self, dt: 'float') | method |

```python
from components.extras.engine3d import Bob
```

### FlyCamera

Public environment class.

Import: `from components.extras.engine3d import FlyCamera`

Signature: `FlyCamera(speed: 'float' = 6.0, look_sensitivity: 'float' = 0.2, joystick=None, pad_speed: 'float' = 120.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| speed | 'float' | 6.0 |
| look_sensitivity | 'float' | 0.2 |
| joystick | Value | None |
| pad_speed | 'float' | 120.0 |

| Member | Kind |
| --- | --- |
| update(self, dt: 'float') | method |

```python
from components.extras.engine3d import FlyCamera
```

### FollowCamera

Public environment class.

Import: `from components.extras.engine3d import FollowCamera`

Signature: `FollowCamera(target: 'Optional[Node]' = None, offset=(0.0, 4.0, 8.0), smooth: 'float' = 6.0, look_offset=(0.0, 1.0, 0.0))`

| Parameter | Type | Default |
| --- | --- | --- |
| target | 'Optional[Node]' | None |
| offset | Value | (0.0, 4.0, 8.0) |
| smooth | 'float' | 6.0 |
| look_offset | Value | (0.0, 1.0, 0.0) |

| Member | Kind |
| --- | --- |
| late_update(self, dt: 'float') | method |

```python
from components.extras.engine3d import FollowCamera
```

### OrbitCamera

Public environment class.

Import: `from components.extras.engine3d import OrbitCamera`

Signature: `OrbitCamera(target=(0.0, 0.0, 0.0), distance: 'float' = 6.0, yaw: 'float' = 30.0, pitch: 'float' = 20.0, min_distance: 'float' = 1.0, max_distance: 'float' = 60.0, sensitivity: 'float' = 0.25, zoom_speed: 'float' = 0.02, smooth: 'float' = 12.0, target_node: 'Optional[Node]' = None, input_enabled: 'bool' = True, pad_speed: 'float' = 120.0, pad_zoom: 'float' = 8.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| target | Value | (0.0, 0.0, 0.0) |
| distance | 'float' | 6.0 |
| yaw | 'float' | 30.0 |
| pitch | 'float' | 20.0 |
| min_distance | 'float' | 1.0 |
| max_distance | 'float' | 60.0 |
| sensitivity | 'float' | 0.25 |
| zoom_speed | 'float' | 0.02 |
| smooth | 'float' | 12.0 |
| target_node | 'Optional[Node]' | None |
| input_enabled | 'bool' | True |
| pad_speed | 'float' | 120.0 |
| pad_zoom | 'float' | 8.0 |

| Member | Kind |
| --- | --- |
| late_update(self, dt: 'float') | method |

```python
from components.extras.engine3d import OrbitCamera
```

### Spin

Public environment class.

Import: `from components.extras.engine3d import Spin`

Signature: `Spin(axis=(0.0, 1.0, 0.0), speed: 'float' = 45.0, local: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| axis | Value | (0.0, 1.0, 0.0) |
| speed | 'float' | 45.0 |
| local | 'bool' | True |

| Member | Kind |
| --- | --- |
| update(self, dt: 'float') | method |
| to_dict(self) | method |
| from_dict(self, d) | method |

```python
from components.extras.engine3d import Spin
```

### Light

Adds directional, point, or spot lighting and optional shadows.

Import: `from components.extras.engine3d import Light`

Signature: `Light(kind: 'str' = 'directional', color='#ffffff', intensity: 'float' = 1.0, range: 'float' = 15.0, spot_angle: 'float' = 45.0, spot_inner: 'float' = 0.0, shadows: 'bool' = False, shadow_size: 'int' = 1024, shadow_bias: 'float' = 0.0015, normal_bias: 'float' = 0.04, shadow_distance: 'float' = 40.0, shadow_strength: 'float' = 1.0, shadow_softness: 'float' = 1.0, culling_mask: 'int' = -1, radius: 'float' = 0.0, cascades: 'int' = 1, cascade_lambda: 'float' = 0.65, shadow_caster_range: 'float' = 40.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| kind | 'str' | 'directional' |
| color | Value | '#ffffff' |
| intensity | 'float' | 1.0 |
| range | 'float' | 15.0 |
| spot_angle | 'float' | 45.0 |
| spot_inner | 'float' | 0.0 |
| shadows | 'bool' | False |
| shadow_size | 'int' | 1024 |
| shadow_bias | 'float' | 0.0015 |
| normal_bias | 'float' | 0.04 |
| shadow_distance | 'float' | 40.0 |
| shadow_strength | 'float' | 1.0 |
| shadow_softness | 'float' | 1.0 |
| culling_mask | 'int' | -1 |
| radius | 'float' | 0.0 |
| cascades | 'int' | 1 |
| cascade_lambda | 'float' | 0.65 |
| shadow_caster_range | 'float' | 40.0 |

| Member | Kind |
| --- | --- |
| casts_shadows | property |
| color | property |
| linear_color(self) -> 'Tuple[float, float, float]' | method |
| direction(self) -> 'Vec3' | method |
| gpu_record(self) | method |
| shadow_view_proj(self, camera, aspect: 'float', zero_to_one: 'bool') -> 'Optional[Tuple[Mat4, float]]' | method |
| cascade_view_projs(self, camera, aspect: 'float', zero_to_one: 'bool', tile: 'int') -> 'List[Tuple[Mat4, float, float, float]]' | method |
| cube_view_projs(self, zero_to_one: 'bool') -> 'List[Mat4]' | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import Light
```

### ProceduralSky

Generates sky colors, a sun, and an environment cube for scene lighting.

Import: `from components.extras.engine3d import ProceduralSky`

Signature: `ProceduralSky(top='#2f61d9', horizon='#b8ccea', bottom='#38332e', sun_dir=(0.4, 0.55, 0.3), sun_color='#fff0cc', sun_intensity: 'float' = 1.0, intensity: 'float' = 1.0, env_size: 'int' = 32)`

| Parameter | Type | Default |
| --- | --- | --- |
| top | Value | '#2f61d9' |
| horizon | Value | '#b8ccea' |
| bottom | Value | '#38332e' |
| sun_dir | Value | (0.4, 0.55, 0.3) |
| sun_color | Value | '#fff0cc' |
| sun_intensity | 'float' | 1.0 |
| intensity | 'float' | 1.0 |
| env_size | 'int' | 32 |

| Member | Kind |
| --- | --- |
| environment_cube(self) -> 'CubeAsset' | method |
| shader_values(self) -> 'dict' | method |

```python
from components.extras.engine3d import ProceduralSky
```

### LightProbeGroup

A cloud of baked SH probes.

Import: `from components.extras.engine3d import LightProbeGroup`

Signature: `LightProbeGroup(positions: 'Sequence[Tuple[float, float, float]]' = (), neighbors: 'int' = 4, intensity: 'float' = 1.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| positions | 'Sequence[Tuple[float, float, float]]' | () |
| neighbors | 'int' | 4 |
| intensity | 'float' | 1.0 |

| Member | Kind |
| --- | --- |
| grid(origin, size, counts, **kw) -> "'LightProbeGroup'" | method |
| world_position_of(self, i: 'int') | method |
| set_probe(self, i: 'int', sh) -> 'None' | method |
| bake(self, radiance: 'Callable', samples: 'int' = 96) -> 'None' | method |
| bake_ambient(self, scene=None, samples: 'int' = 96) -> 'None' | method |
| bake_scene(self, scene=None, samples: 'int' = 128, bounce: 'float' = 0.6, max_dist: 'float' = 60.0) -> 'None' | method |
| sample(self, world_pos) -> 'Optional[tuple]' | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import LightProbeGroup
```

### ReflectionProbe

Box-projected cubemap reflections for renderers inside `size`.

Import: `from components.extras.engine3d import ReflectionProbe`

Signature: `ReflectionProbe(size=(10.0, 10.0, 10.0), intensity: 'float' = 1.0, blend_distance: 'float' = 1.0, resolution: 'int' = 128, importance: 'int' = 0, cube=None, near: 'float' = 0.1, far: 'float' = 100.0, mask: 'int' = -1)`

| Parameter | Type | Default |
| --- | --- | --- |
| size | Value | (10.0, 10.0, 10.0) |
| intensity | 'float' | 1.0 |
| blend_distance | 'float' | 1.0 |
| resolution | 'int' | 128 |
| importance | 'int' | 0 |
| cube | Value | None |
| near | 'float' | 0.1 |
| far | 'float' | 100.0 |
| mask | 'int' | -1 |

| Member | Kind |
| --- | --- |
| capture(self) -> 'None' | method |
| contains(self, p) -> 'bool' | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import ReflectionProbe
```

### sh_project

samples: [(direction, rgb radiance)] distributed uniformly over the sphere.

Import: `from components.extras.engine3d import sh_project`

Signature: `sh_project(samples: 'Sequence[Tuple[Tuple[float, float, float], Tuple[float, float, float]]]', convolve: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| samples | 'Sequence[Tuple[Tuple[float, float, float], Tuple[float, float, float]]]' | Required |
| convolve | 'bool' | True |

```python
from components.extras.engine3d import sh_project
```

### sh_eval

Public environment function.

Import: `from components.extras.engine3d import sh_eval`

Signature: `sh_eval(sh, n) -> 'Tuple[float, float, float]'`

| Parameter | Type | Default |
| --- | --- | --- |
| sh | Value | Required |
| n | Value | Required |

```python
from components.extras.engine3d import sh_eval
```

### sh_constant

Public environment function.

Import: `from components.extras.engine3d import sh_constant`

Signature: `sh_constant(rgb) -> 'tuple'`

| Parameter | Type | Default |
| --- | --- | --- |
| rgb | Value | Required |

```python
from components.extras.engine3d import sh_constant
```

### ambient_radiance

CPU radiance of the scene's sky / ambient colours by direction (linear).

Import: `from components.extras.engine3d import ambient_radiance`

Signature: `ambient_radiance(scene) -> 'Callable[[Tuple[float, float, float]], Tuple[float, float, float]]'`

| Parameter | Type | Default |
| --- | --- | --- |
| scene | Value | Required |

```python
from components.extras.engine3d import ambient_radiance
```

### Terrain

Builds terrain geometry from height data and supports height sampling.

Import: `from components.extras.engine3d import Terrain`

Signature: `Terrain(heights: 'Optional[Sequence[Sequence[float]]]' = None, size=(100.0, 100.0), height: 'float' = 20.0, chunk_cells: 'int' = 32, layers: 'Sequence' = (), tiling=(16.0, 16.0, 16.0, 16.0), roughness: 'float' = 0.9, collider: 'bool' = True, collider_step: 'int' = 2)`

| Parameter | Type | Default |
| --- | --- | --- |
| heights | 'Optional[Sequence[Sequence[float]]]' | None |
| size | Value | (100.0, 100.0) |
| height | 'float' | 20.0 |
| chunk_cells | 'int' | 32 |
| layers | 'Sequence' | () |
| tiling | Value | (16.0, 16.0, 16.0, 16.0) |
| roughness | 'float' | 0.9 |
| collider | 'bool' | True |
| collider_step | 'int' | 2 |

| Member | Kind |
| --- | --- |
| from_function(fn: 'Callable[[float, float], float]', res: 'int' = 65, **kw) -> "'Terrain'" | method |
| noise_heights(res: 'int' = 65, seed: 'int' = 1, octaves: 'int' = 4, scale: 'float' = 4.0) -> 'List[List[float]]' | method |
| resolution | property |
| height_at(self, x: 'float', z: 'float') -> 'float' | method |
| normal_at(self, x: 'float', z: 'float') -> 'Tuple[float, float, float]' | method |
| slope_at(self, x: 'float', z: 'float') -> 'float' | method |
| modify(self, x: 'float', z: 'float', radius: 'float', delta: 'float', falloff: 'float' = 2.0) -> 'None' | method |
| auto_splat(self, size: 'int' = 128, rules=None) -> 'TextureAsset' | method |
| build(self) -> 'None' | method |
| refresh_collider(self) -> 'None' | method |
| start(self) | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import Terrain
```

### Water

Draws a tessellated water surface with four Gerstner waves, color depth, reflection, and foam controls.

Import: `from components.extras.engine3d import Water`

Signature: `Water(size=(40.0, 40.0), cells: 'int' = 96, shallow='#1a7380', deep='#031a33', amplitude: 'float' = 0.35, speed: 'float' = 1.0, foam: 'float' = 0.0, material: 'Optional[Material]' = None)`

| Parameter | Type | Default |
| --- | --- | --- |
| size | Value | (40.0, 40.0) |
| cells | 'int' | 96 |
| shallow | Value | '#1a7380' |
| deep | Value | '#031a33' |
| amplitude | 'float' | 0.35 |
| speed | 'float' | 1.0 |
| foam | 'float' | 0.0 |
| material | 'Optional[Material]' | None |

| Member | Kind |
| --- | --- |
| wave_height_at(self, x: 'float', z: 'float', time: 'float') -> 'float' | method |
| to_dict(self) -> 'dict' | method |

```python
from components.extras.engine3d import Water
```

## Materials, Textures, Assets, and Shaders
### AssetManager

Public assets class.

Import: `from components.extras.engine3d import AssetManager`

Signature: `AssetManager(ctx: 'GpuContext', root: 'str' = '', registry: 'ShaderRegistry' = default_registry)`

| Member | Kind |
| --- | --- |
| set_root(self, root: 'str') -> 'None' | method |
| prefab(self, ref: 'str') -> 'dict' | method |
| primitive(self, kind: 'str', **args) -> 'Mesh' | method |
| texture(self, path: 'str', mipmaps: 'bool' = True, filter: 'str' = 'linear', wrap: 'str' = 'repeat') -> 'TextureAsset' | method |
| cube(self, faces: 'Sequence[str]', mipmaps: 'bool' = True) -> 'CubeAsset' | method |
| model(self, path: 'str') -> 'ModelAsset' | method |
| material(self, path: 'str') -> 'Material' | method |
| resolve_texture(self, ref: 'str') -> 'TextureAsset' | method |
| shader(self, path: 'str', watch: 'bool' = False) | method |
| shader_dir(self, path: 'str', watch: 'bool' = False) -> 'List[str]' | method |
| shader_text(self, text: 'str') | method |
| update(self, dt: 'float') -> 'None' | method |
| pending_textures(self) -> 'int' | method |
| progress(self, renderer=None) -> 'float' | method |
| ready(self, renderer=None) -> 'bool' | method |

```python
from components.extras.engine3d import AssetManager
```

### ModelAsset

Public assets class.

Import: `from components.extras.engine3d import ModelAsset`

Signature: `ModelAsset(name: 'str')`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'str' | Required |

| Member | Kind |
| --- | --- |
| instantiate(self, scene: 'Optional[Scene]' = None, parent: 'Optional[Node]' = None, name: 'Optional[str]' = None, position=(0.0, 0.0, 0.0), scale=1.0, animator: 'bool' = True, lights: 'bool' = True, cameras: 'bool' = True, light_scale: 'float' = 1.0) -> 'Node' | method |

```python
from components.extras.engine3d import ModelAsset
```

### load_gltf

Public assets function.

Import: `from components.extras.engine3d import load_gltf`

Signature: `load_gltf(data: 'bytes', name: 'str' = 'model', reader: 'Optional[FileReader]' = None, base_dir: 'str' = '') -> 'ModelAsset'`

| Parameter | Type | Default |
| --- | --- | --- |
| data | 'bytes' | Required |
| name | 'str' | 'model' |
| reader | 'Optional[FileReader]' | None |
| base_dir | 'str' | '' |

```python
from components.extras.engine3d import load_gltf
```

### load_obj

Public assets function.

Import: `from components.extras.engine3d import load_obj`

Signature: `load_obj(text: 'str', name: 'str' = 'obj', reader: 'Optional[FileReader]' = None, base_dir: 'str' = '') -> 'ModelAsset'`

| Parameter | Type | Default |
| --- | --- | --- |
| text | 'str' | Required |
| name | 'str' | 'obj' |
| reader | 'Optional[FileReader]' | None |
| base_dir | 'str' | '' |

```python
from components.extras.engine3d import load_obj
```

### Material

Stores shader selection, properties, textures, keywords, and render state.

Import: `from components.extras.engine3d import Material`

Signature: `Material(shader='c3d/pbr', name: 'Optional[str]' = None, **props)`

| Parameter | Type | Default |
| --- | --- | --- |
| shader | Value | 'c3d/pbr' |
| name | 'Optional[str]' | None |
| **props | Values | Optional |

| Member | Kind |
| --- | --- |
| program | property |
| set(self, name: 'str', value) -> "'Material'" | method |
| set_field(self, field: 'str', value) -> "'Material'" | method |
| get(self, name: 'str') | method |
| set_texture(self, sampler: 'str', asset) -> "'Material'" | method |
| enable(self, keyword: 'str') -> "'Material'" | method |
| disable(self, keyword: 'str') -> "'Material'" | method |
| set_alpha_mode(self, mode: 'str', cutoff: 'Optional[float]' = None) -> "'Material'" | method |
| double_sided | property |
| transparent | property |
| writes_depth | property |
| blend_state(self) -> 'Optional[Blend]' | method |
| state_key(self) -> 'tuple' | method |
| material_keywords(self) -> 'FrozenSet[str]' | method |
| variant_for(self, extra: 'Iterable[str]' = ()) -> 'Variant' | method |
| upload(self, gfx, epoch: 'int', variant: 'Variant') -> 'Dict[str, Any]' | method |
| textures_for(self, ctx, variant: 'Variant', extra: 'Dict[str, Any]') -> 'Tuple[Dict[str, Any], bool]' | method |
| clone(self, name: 'Optional[str]' = None) -> "'Material'" | method |

```python
from components.extras.engine3d import Material
```

### HotReloader

Public assets class.

Import: `from components.extras.engine3d import HotReloader`

Signature: `HotReloader(reader: 'Optional[FileReader]' = None, registry: 'ShaderRegistry' = default_registry, interval: 'float' = 0.5)`

| Member | Kind |
| --- | --- |
| watch(self, path: 'str') -> 'None' | method |
| poll(self, dt: 'float') -> 'List[str]' | method |

```python
from components.extras.engine3d import HotReloader
```

### load_shader_dict

Public assets function.

Import: `from components.extras.engine3d import load_shader_dict`

Signature: `load_shader_dict(d: 'dict', reader=None, base_dir: 'str' = '', registry: 'ShaderRegistry' = default_registry)`

```python
from components.extras.engine3d import load_shader_dict
```

### load_shader_file

Public assets function.

Import: `from components.extras.engine3d import load_shader_file`

Signature: `load_shader_file(path: 'str', reader: 'Optional[FileReader]' = None, registry: 'ShaderRegistry' = default_registry)`

```python
from components.extras.engine3d import load_shader_file
```

### load_shader_text

Public assets function.

Import: `from components.extras.engine3d import load_shader_text`

Signature: `load_shader_text(text: 'str', reader=None, base_dir: 'str' = '', registry: 'ShaderRegistry' = default_registry)`

```python
from components.extras.engine3d import load_shader_text
```

### shaders

Public assets value.

Import: `from components.extras.engine3d import shaders`

Type: `value`

```python
from components.extras.engine3d import shaders
```

### CubeAsset

Public assets class.

Import: `from components.extras.engine3d import CubeAsset`

Signature: `CubeAsset(name: 'str' = 'cube', settings: 'Optional[TextureSettings]' = None)`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'str' | 'cube' |
| settings | 'Optional[TextureSettings]' | None |

| Member | Kind |
| --- | --- |
| from_faces_raw(size: 'int', faces: 'Sequence[bytes]', fmt: 'str' = 'rgba8', mipmaps: 'bool' = True, name='cube') -> "'CubeAsset'" | method |
| from_encoded(faces: 'Sequence[bytes]', mipmaps: 'bool' = True, name='cube') -> "'CubeAsset'" | method |
| solid(color=(0.5, 0.5, 0.5, 1.0), name='cube_solid') -> "'CubeAsset'" | method |
| procedural_sky(size: 'int' = 32, sun_dir=(0.4, 0.55, 0.3), sky_top=(0.18, 0.38, 0.85), horizon=(0.72, 0.8, 0.9), ground=(0.22, 0.2, 0.18), sun_color=(1.0, 0.93, 0.8), sun_intensity: 'float' = 40.0, hdr: 'bool' = True, name='procedural_sky') -> "'CubeAsset'" | method |
| gpu(self, ctx: 'GpuContext') | method |

```python
from components.extras.engine3d import CubeAsset
```

### RenderTexture

Public assets class.

Import: `from components.extras.engine3d import RenderTexture`

Signature: `RenderTexture(width: 'int', height: 'int', hdr: 'bool' = False, depth: 'bool' = True, name: 'str' = 'rendertexture', samples: 'int' = 0)`

| Parameter | Type | Default |
| --- | --- | --- |
| width | 'int' | Required |
| height | 'int' | Required |
| hdr | 'bool' | False |
| depth | 'bool' | True |
| name | 'str' | 'rendertexture' |
| samples | 'int' | 0 |

| Member | Kind |
| --- | --- |
| sync(self, ctx: 'GpuContext') -> 'bool' | method |
| resize(self, width: 'int', height: 'int') -> 'None' | method |
| color | property |
| gpu(self, ctx: 'GpuContext') | method |
| is_ready(self, ctx) -> 'bool' | method |
| on_ready(self, cb) -> 'None' | method |
| release(self) -> 'None' | method |

```python
from components.extras.engine3d import RenderTexture
```

### TextureAsset

Public assets class.

Import: `from components.extras.engine3d import TextureAsset`

Signature: `TextureAsset(name: 'str' = 'texture', settings: 'Optional[TextureSettings]' = None)`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'str' | 'texture' |
| settings | 'Optional[TextureSettings]' | None |

| Member | Kind |
| --- | --- |
| from_pixels(width: 'int', height: 'int', data, fmt: 'str' = 'rgba8', settings=None, name='pixels') -> "'TextureAsset'" | method |
| from_file(path: 'str', settings=None) -> "'TextureAsset'" | method |
| from_encoded(data: 'bytes', settings=None, name='image') -> "'TextureAsset'" | method |
| solid(color=(1.0, 1.0, 1.0, 1.0), settings=None, name='solid') -> "'TextureAsset'" | method |
| checker(size: 'int' = 64, cells: 'int' = 8, a=(0.9, 0.9, 0.9, 1.0), b=(0.25, 0.25, 0.28, 1.0), settings=None) -> "'TextureAsset'" | method |
| gradient(width: 'int', stops: 'Sequence[Tuple[float, Tuple[float, float, float, float]]]', settings=None) -> "'TextureAsset'" | method |
| value_noise(size: 'int' = 64, seed: 'int' = 1, octaves: 'int' = 4, settings=None) -> "'TextureAsset'" | method |
| flat_normal() -> "'TextureAsset'" | method |
| on_ready(self, cb: "Callable[['TextureAsset'], None]") -> 'None' | method |
| is_ready(self, ctx: 'Optional[GpuContext]') -> 'bool' | method |
| gpu(self, ctx: 'GpuContext') | method |
| release(self) -> 'None' | method |

```python
from components.extras.engine3d import TextureAsset
```

### TextureSettings

Public assets class.

Import: `from components.extras.engine3d import TextureSettings`

Signature: `TextureSettings(mipmaps: 'bool' = True, filter: 'str' = 'linear', wrap: 'str' = 'repeat')`

| Parameter | Type | Default |
| --- | --- | --- |
| mipmaps | 'bool' | True |
| filter | 'str' | 'linear' |
| wrap | 'str' | 'repeat' |

| Member | Kind |
| --- | --- |
| min_filter(self) | method |
| mag_filter(self) | method |
| wrap_mode(self) | method |

```python
from components.extras.engine3d import TextureSettings
```

## Effects, Post-Processing, and Quality
### Gradient

Public effects class.

Import: `from components.extras.engine3d import Gradient`

Signature: `Gradient(stops: 'Sequence[Tuple[float, Tuple[float, float, float, float]]]')`

| Parameter | Type | Default |
| --- | --- | --- |
| stops | 'Sequence[Tuple[float, Tuple[float, float, float, float]]]' | Required |

| Member | Kind |
| --- | --- |
| at(self, t: 'float') -> 'Tuple[float, float, float, float]' | method |

```python
from components.extras.engine3d import Gradient
```

### ParticleSystem

Public effects class.

Import: `from components.extras.engine3d import ParticleSystem`

Signature: `ParticleSystem(max_particles: 'int' = 256, rate: 'float' = 30.0, lifetime=(0.8, 1.4), speed=(1.0, 3.0), size=(0.2, 0.3), size_end: 'float' = 0.0, color: 'Optional[Gradient]' = None, gravity=(0.0, 0.0, 0.0), drag: 'float' = 0.0, shape: 'str' = 'cone', angle: 'float' = 25.0, radius: 'float' = 0.1, texture: 'Optional[TextureAsset]' = None, blend: 'str' = 'additive', world_space: 'bool' = True, loop: 'bool' = True, duration: 'float' = 5.0, sheet=(1, 1), sheet_fps: 'float' = 0.0, spin=(0.0, 0.0), stretch: 'float' = 0.0, seed: 'int' = 1, play_on_start: 'bool' = True, material: 'Optional[Material]' = None)`

| Parameter | Type | Default |
| --- | --- | --- |
| max_particles | 'int' | 256 |
| rate | 'float' | 30.0 |
| lifetime | Value | (0.8, 1.4) |
| speed | Value | (1.0, 3.0) |
| size | Value | (0.2, 0.3) |
| size_end | 'float' | 0.0 |
| color | 'Optional[Gradient]' | None |
| gravity | Value | (0.0, 0.0, 0.0) |
| drag | 'float' | 0.0 |
| shape | 'str' | 'cone' |
| angle | 'float' | 25.0 |
| radius | 'float' | 0.1 |
| texture | 'Optional[TextureAsset]' | None |
| blend | 'str' | 'additive' |
| world_space | 'bool' | True |
| loop | 'bool' | True |
| duration | 'float' | 5.0 |
| sheet | Value | (1, 1) |
| sheet_fps | 'float' | 0.0 |
| spin | Value | (0.0, 0.0) |
| stretch | 'float' | 0.0 |
| seed | 'int' | 1 |
| play_on_start | 'bool' | True |
| material | 'Optional[Material]' | None |

| Member | Kind |
| --- | --- |
| play(self) -> 'None' | method |
| stop(self, clear: 'bool' = False) -> 'None' | method |
| alive | property |
| emit(self, n: 'int') -> 'None' | method |
| emit_at(self, position, n: 'int' = 1, velocity=None) -> 'None' | method |
| update(self, dt: 'float') | method |
| prepare_view(self, view, renderer) -> 'None' | method |
| to_dict(self) -> 'dict' | method |

```python
from components.extras.engine3d import ParticleSystem
```

### Bloom

Public effects class.

Import: `from components.extras.engine3d import Bloom`

Signature: `Bloom(threshold: 'float' = 1.0, knee: 'float' = 0.5, intensity: 'float' = 0.6, blur_passes: 'int' = 2, enabled: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| threshold | 'float' | 1.0 |
| knee | 'float' | 0.5 |
| intensity | 'float' | 0.6 |
| blur_passes | 'int' | 2 |
| enabled | 'bool' | True |

| Member | Kind |
| --- | --- |
| steps(self, ctx) | method |
| result | property |

```python
from components.extras.engine3d import Bloom
```

### ColorGrade

Public effects class.

Import: `from components.extras.engine3d import ColorGrade`

Signature: `ColorGrade(saturation: 'float' = 1.0, contrast: 'float' = 1.0, tint=(1.0, 1.0, 1.0), enabled: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| saturation | 'float' | 1.0 |
| contrast | 'float' | 1.0 |
| tint | Value | (1.0, 1.0, 1.0) |
| enabled | 'bool' | True |

```python
from components.extras.engine3d import ColorGrade
```

### CustomEffect

Runs a registered post shader with named vec4 parameters and optional inputs.

Import: `from components.extras.engine3d import CustomEffect`

Signature: `CustomEffect(program: 'str', stage: 'str' = 'ldr', params: 'Optional[Dict[str, Sequence[float]]]' = None, inputs: 'Optional[Dict[str, object]]' = None, keywords: 'Sequence[str]' = (), scale: 'float' = 1.0, enabled: 'bool' = True, name: 'Optional[str]' = None, needs_depth: 'bool' = False, camera: 'bool' = False)`

| Parameter | Type | Default |
| --- | --- | --- |
| program | 'str' | Required |
| stage | 'str' | 'ldr' |
| params | 'Optional[Dict[str, Sequence[float]]]' | None |
| inputs | 'Optional[Dict[str, object]]' | None |
| keywords | 'Sequence[str]' | () |
| scale | 'float' | 1.0 |
| enabled | 'bool' | True |
| name | 'Optional[str]' | None |
| needs_depth | 'bool' | False |
| camera | 'bool' | False |

| Member | Kind |
| --- | --- |
| steps(self, ctx) | method |

```python
from components.extras.engine3d import CustomEffect
```

### DepthOfField

Gather depth of field.

Import: `from components.extras.engine3d import DepthOfField`

Signature: `DepthOfField(focus_distance: 'float' = 8.0, focus_range: 'float' = 2.0, max_blur: 'float' = 8.0, falloff: 'float' = 0.6, enabled: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| focus_distance | 'float' | 8.0 |
| focus_range | 'float' | 2.0 |
| max_blur | 'float' | 8.0 |
| falloff | 'float' | 0.6 |
| enabled | 'bool' | True |

| Member | Kind |
| --- | --- |
| steps(self, ctx) | method |

```python
from components.extras.engine3d import DepthOfField
```

### FXAA

Public effects class.

Import: `from components.extras.engine3d import FXAA`

Signature: `FXAA(enabled: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| enabled | 'bool' | True |

```python
from components.extras.engine3d import FXAA
```

### MotionBlur

Camera motion blur by reprojecting depth with the previous frame's view-projection (objects that move on their own are not blurred).

Import: `from components.extras.engine3d import MotionBlur`

Signature: `MotionBlur(strength: 'float' = 1.0, max_pixels: 'float' = 24.0, blur_sky: 'bool' = False, enabled: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| strength | 'float' | 1.0 |
| max_pixels | 'float' | 24.0 |
| blur_sky | 'bool' | False |
| enabled | 'bool' | True |

| Member | Kind |
| --- | --- |
| steps(self, ctx) | method |

```python
from components.extras.engine3d import MotionBlur
```

### PostStack

Orders and configures post-processing effects for a camera.

Import: `from components.extras.engine3d import PostStack`

Signature: `PostStack(bloom: 'Optional[Bloom]' = None, tonemap: 'Optional[Tonemap]' = None, vignette: 'Optional[Vignette]' = None, grade: 'Optional[ColorGrade]' = None, fxaa: 'Optional[FXAA]' = None, effects: 'Sequence[Effect]' = (), enabled: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| bloom | 'Optional[Bloom]' | None |
| tonemap | 'Optional[Tonemap]' | None |
| vignette | 'Optional[Vignette]' | None |
| grade | 'Optional[ColorGrade]' | None |
| fxaa | 'Optional[FXAA]' | None |
| effects | 'Sequence[Effect]' | () |
| enabled | 'bool' | True |

| Member | Kind |
| --- | --- |
| standard(bloom: 'bool' = True, vignette: 'bool' = True, fxaa: 'bool' = True) -> "'PostStack'" | method |
| needs_depth | property |
| add(self, effect: 'Effect') -> "'PostStack'" | method |
| remove(self, effect: 'Effect') -> 'None' | method |
| steps(self, ctx: 'StackContext') -> 'List[Step]' | method |

```python
from components.extras.engine3d import PostStack
```

### SSAO

Adds a depth-based ambient occlusion pass.

Import: `from components.extras.engine3d import SSAO`

Signature: `SSAO(radius: 'float' = 0.6, bias: 'float' = 0.03, intensity: 'float' = 1.0, strength: 'float' = 1.0, blur: 'bool' = True, enabled: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| radius | 'float' | 0.6 |
| bias | 'float' | 0.03 |
| intensity | 'float' | 1.0 |
| strength | 'float' | 1.0 |
| blur | 'bool' | True |
| enabled | 'bool' | True |

| Member | Kind |
| --- | --- |
| steps(self, ctx) | method |

```python
from components.extras.engine3d import SSAO
```

### SSR

Screen-space reflections by marching the depth buffer.

Import: `from components.extras.engine3d import SSR`

Signature: `SSR(max_distance: 'float' = 20.0, thickness: 'float' = 0.6, steps: 'int' = 48, reflectivity: 'float' = 0.6, enabled: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| max_distance | 'float' | 20.0 |
| thickness | 'float' | 0.6 |
| steps | 'int' | 48 |
| reflectivity | 'float' | 0.6 |
| enabled | 'bool' | True |

| Member | Kind |
| --- | --- |
| steps(self, ctx) | method |

```python
from components.extras.engine3d import SSR
```

### Tonemap

Public effects class.

Import: `from components.extras.engine3d import Tonemap`

Signature: `Tonemap(mode: 'str' = 'aces', exposure: 'float' = 1.0, enabled: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| mode | 'str' | 'aces' |
| exposure | 'float' | 1.0 |
| enabled | 'bool' | True |

```python
from components.extras.engine3d import Tonemap
```

### Vignette

Public effects class.

Import: `from components.extras.engine3d import Vignette`

Signature: `Vignette(strength: 'float' = 0.35, falloff: 'float' = 1.2, enabled: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| strength | 'float' | 0.35 |
| falloff | 'float' | 1.2 |
| enabled | 'bool' | True |

```python
from components.extras.engine3d import Vignette
```

### ParticleCollision

Public effects class.

Import: `from components.extras.engine3d import ParticleCollision`

Signature: `ParticleCollision(planes: 'Sequence' = (), spheres: 'Sequence' = (), world: 'bool' = False, bounce: 'float' = 0.4, friction: 'float' = 0.1, lifetime_loss: 'float' = 0.0, kill: 'bool' = False, radius_scale: 'float' = 0.5, mask: 'int' = -1, max_world_checks: 'int' = 48)`

| Parameter | Type | Default |
| --- | --- | --- |
| planes | 'Sequence' | () |
| spheres | 'Sequence' | () |
| world | 'bool' | False |
| bounce | 'float' | 0.4 |
| friction | 'float' | 0.1 |
| lifetime_loss | 'float' | 0.0 |
| kill | 'bool' | False |
| radius_scale | 'float' | 0.5 |
| mask | 'int' | -1 |
| max_world_checks | 'int' | 48 |

| Member | Kind |
| --- | --- |
| floor(y: 'float' = 0.0, **kw) -> "'ParticleCollision'" | method |

```python
from components.extras.engine3d import ParticleCollision
```

### SubEmitter

Public effects class.

Import: `from components.extras.engine3d import SubEmitter`

Signature: `SubEmitter(system: "'ParticleSystem'", trigger: 'str' = 'death', count: 'int' = 3, inherit_velocity: 'float' = 0.0, probability: 'float' = 1.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| system | "'ParticleSystem'" | Required |
| trigger | 'str' | 'death' |
| count | 'int' | 3 |
| inherit_velocity | 'float' | 0.0 |
| probability | 'float' | 1.0 |

```python
from components.extras.engine3d import SubEmitter
```

### Decal

Projects a texture onto static scene geometry inside a box volume.

Import: `from components.extras.engine3d import Decal`

Signature: `Decal(texture: 'Optional[TextureAsset]' = None, size=(1.0, 1.0, 1.0), color=(1.0, 1.0, 1.0, 1.0), max_angle: 'float' = 75.0, offset: 'float' = 0.005, material: 'Optional[Material]' = None, mask: 'int' = -1)`

| Parameter | Type | Default |
| --- | --- | --- |
| texture | 'Optional[TextureAsset]' | None |
| size | Value | (1.0, 1.0, 1.0) |
| color | Value | (1.0, 1.0, 1.0, 1.0) |
| max_angle | 'float' | 75.0 |
| offset | 'float' | 0.005 |
| material | 'Optional[Material]' | None |
| mask | 'int' | -1 |

| Member | Kind |
| --- | --- |
| start(self) | method |
| on_disable(self) | method |
| rebake(self) -> 'int' | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import Decal
```

### GPUParticles

Runs a stateless particle effect from deterministic particle data with looping or one-shot playback.

Import: `from components.extras.engine3d import GPUParticles`

Signature: `GPUParticles(count: 'int' = 2000, lifetime: 'float' = 1.5, speed=(1.0, 3.0), size=(0.2, 0.0), cone_angle: 'float' = 25.0, shape: 'str' = 'cone', radius: 'float' = 0.2, gravity=(0.0, -2.0, 0.0), drag: 'float' = 0.0, spin: 'float' = 0.0, color_start=(1.0, 1.0, 1.0, 1.0), color_end=(1.0, 1.0, 1.0, 0.0), texture: 'Optional[TextureAsset]' = None, blend: 'str' = 'additive', loop: 'bool' = True, seed: 'int' = 1, time_scale: 'float' = 1.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| count | 'int' | 2000 |
| lifetime | 'float' | 1.5 |
| speed | Value | (1.0, 3.0) |
| size | Value | (0.2, 0.0) |
| cone_angle | 'float' | 25.0 |
| shape | 'str' | 'cone' |
| radius | 'float' | 0.2 |
| gravity | Value | (0.0, -2.0, 0.0) |
| drag | 'float' | 0.0 |
| spin | 'float' | 0.0 |
| color_start | Value | (1.0, 1.0, 1.0, 1.0) |
| color_end | Value | (1.0, 1.0, 1.0, 0.0) |
| texture | 'Optional[TextureAsset]' | None |
| blend | 'str' | 'additive' |
| loop | 'bool' | True |
| seed | 'int' | 1 |
| time_scale | 'float' | 1.0 |

| Member | Kind |
| --- | --- |
| configure(self, **props) -> 'None' | method |
| play(self) -> 'None' | method |
| to_dict(self) -> 'dict' | method |

```python
from components.extras.engine3d import GPUParticles
```

### QualitySettings

Applies a named group of shadow, resolution, post, LOD, particle, and MSAA settings.

Import: `from components.extras.engine3d import QualitySettings`

Signature: `QualitySettings(level: 'str' = 'high')`

| Parameter | Type | Default |
| --- | --- | --- |
| level | 'str' | 'high' |

| Member | Kind |
| --- | --- |
| set_level(self, level: 'str') -> "'QualitySettings'" | method |
| set(self, **kw) -> "'QualitySettings'" | method |
| auto(engine=None, mobile: 'bool' = True) -> "'QualitySettings'" | method |
| step(self, delta: 'int') -> "'QualitySettings'" | method |
| apply(self, engine) -> 'None' | method |
| to_dict(self) -> 'dict' | method |

```python
from components.extras.engine3d import QualitySettings
```

## Physics and Simulation
### BoxCollider

Public physics class.

Import: `from components.extras.engine3d import BoxCollider`

Signature: `BoxCollider(size=(1.0, 1.0, 1.0), **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| size | Value | (1.0, 1.0, 1.0) |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| local(self, p) | method |
| raycast(self, o, d, max_dist) | method |

```python
from components.extras.engine3d import BoxCollider
```

### CapsuleCollider

Public physics class.

Import: `from components.extras.engine3d import CapsuleCollider`

Signature: `CapsuleCollider(radius: 'float' = 0.5, height: 'float' = 2.0, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| radius | 'float' | 0.5 |
| height | 'float' | 2.0 |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| raycast(self, o, d, max_dist) | method |

```python
from components.extras.engine3d import CapsuleCollider
```

### CharacterController

Public physics class.

Import: `from components.extras.engine3d import CharacterController`

Signature: `CharacterController(radius: 'float' = 0.35, height: 'float' = 1.8, step_offset: 'float' = 0.3, slope_limit: 'float' = 50.0, skin: 'float' = 0.02, use_gravity: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| radius | 'float' | 0.35 |
| height | 'float' | 1.8 |
| step_offset | 'float' | 0.3 |
| slope_limit | 'float' | 50.0 |
| skin | 'float' | 0.02 |
| use_gravity | 'bool' | True |

| Member | Kind |
| --- | --- |
| move(self, delta, dt: 'Optional[float]' = None) -> 'Tuple[float, float, float]' | method |
| simple_move(self, velocity, dt: 'float') -> 'None' | method |
| jump(self, speed: 'float') -> 'None' | method |

```python
from components.extras.engine3d import CharacterController
```

### Collider

Public physics class.

Import: `from components.extras.engine3d import Collider`

Signature: `Collider(is_trigger: 'bool' = False, center=(0.0, 0.0, 0.0), friction: 'float' = 0.5, bounciness: 'float' = 0.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| is_trigger | 'bool' | False |
| center | Value | (0.0, 0.0, 0.0) |
| friction | 'float' | 0.5 |
| bounciness | 'float' | 0.0 |

| Member | Kind |
| --- | --- |
| body | property |
| is_static | property |
| refresh(self) -> 'None' | method |
| raycast(self, o, d, max_dist: 'float') | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import Collider
```

### MeshCollider

Public physics class.

Import: `from components.extras.engine3d import MeshCollider`

Signature: `MeshCollider(mesh: 'Optional[Mesh]' = None, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| mesh | 'Optional[Mesh]' | None |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| candidates(self, lo, hi) -> 'Set[int]' | method |
| raycast(self, o, d, max_dist) | method |

```python
from components.extras.engine3d import MeshCollider
```

### PhysicsWorld

Public physics class.

Import: `from components.extras.engine3d import PhysicsWorld`

Signature: `PhysicsWorld(gravity=(0.0, -9.81, 0.0), iterations: 'int' = 8, cell_size: 'float' = 4.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| gravity | Value | (0.0, -9.81, 0.0) |
| iterations | 'int' | 8 |
| cell_size | 'float' | 4.0 |

| Member | Kind |
| --- | --- |
| set_layer_collision(self, a: 'int', b: 'int', enabled: 'bool') -> 'None' | method |
| raycast(self, origin, direction, max_distance: 'float' = 1000.0, mask: 'int' = -1, include_triggers: 'bool' = False) -> 'Optional[Hit]' | method |
| raycast_all(self, origin, direction, max_distance: 'float' = 1000.0, mask: 'int' = -1, include_triggers: 'bool' = False) -> 'List[Hit]' | method |
| overlap_sphere(self, center, radius: 'float', mask: 'int' = -1) -> 'List[Collider]' | method |
| overlap_box(self, center, half, rotation=None, mask: 'int' = -1, include_triggers: 'bool' = True) -> 'List[Collider]' | method |
| overlap_capsule(self, a, b, radius: 'float', mask: 'int' = -1, include_triggers: 'bool' = True) -> 'List[Collider]' | method |
| sphere_cast(self, origin, radius: 'float', direction, max_distance: 'float' = 1000.0, mask: 'int' = -1, include_triggers: 'bool' = False) -> 'Optional[Hit]' | method |
| sphere_cast_all(self, origin, radius: 'float', direction, max_distance: 'float' = 1000.0, mask: 'int' = -1, include_triggers: 'bool' = False) -> 'List[Hit]' | method |
| capsule_cast(self, a, b, radius: 'float', direction, max_distance: 'float' = 1000.0, mask: 'int' = -1, include_triggers: 'bool' = False) -> 'Optional[Hit]' | method |
| capsule_cast_all(self, a, b, radius: 'float', direction, max_distance: 'float' = 1000.0, mask: 'int' = -1, include_triggers: 'bool' = False) -> 'List[Hit]' | method |
| box_cast(self, center, half, direction, max_distance: 'float' = 1000.0, rotation=None, mask: 'int' = -1, include_triggers: 'bool' = False) -> 'Optional[Hit]' | method |
| box_cast_all(self, center, half, direction, max_distance: 'float' = 1000.0, rotation=None, mask: 'int' = -1, include_triggers: 'bool' = False) -> 'List[Hit]' | method |
| add_constraint(self, c) -> 'None' | method |
| remove_constraint(self, c) -> 'None' | method |
| step(self, dt: 'float') -> 'None' | method |

```python
from components.extras.engine3d import PhysicsWorld
```

### PlaneCollider

Public physics class.

Import: `from components.extras.engine3d import PlaneCollider`

Signature: `PlaneCollider(normal=(0.0, 1.0, 0.0), offset: 'float' = 0.0, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| normal | Value | (0.0, 1.0, 0.0) |
| offset | 'float' | 0.0 |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| raycast(self, o, d, max_dist) | method |

```python
from components.extras.engine3d import PlaneCollider
```

### Rigidbody

Public physics class.

Import: `from components.extras.engine3d import Rigidbody`

Signature: `Rigidbody(mass: 'float' = 1.0, use_gravity: 'bool' = True, drag: 'float' = 0.05, angular_drag: 'float' = 0.5, kinematic: 'bool' = False, freeze_rotation: 'bool' = True, freeze_position=(False, False, False), can_sleep: 'bool' = True, continuous: 'bool' = False)`

| Parameter | Type | Default |
| --- | --- | --- |
| mass | 'float' | 1.0 |
| use_gravity | 'bool' | True |
| drag | 'float' | 0.05 |
| angular_drag | 'float' | 0.5 |
| kinematic | 'bool' | False |
| freeze_rotation | 'bool' | True |
| freeze_position | Value | (False, False, False) |
| can_sleep | 'bool' | True |
| continuous | 'bool' | False |

| Member | Kind |
| --- | --- |
| kind_static | property |
| inv_mass | property |
| add_force(self, f) -> 'None' | method |
| add_impulse(self, j) -> 'None' | method |
| set_velocity(self, v) -> 'None' | method |
| wake(self) -> 'None' | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import Rigidbody
```

### SphereCollider

Public physics class.

Import: `from components.extras.engine3d import SphereCollider`

Signature: `SphereCollider(radius: 'float' = 0.5, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| radius | 'float' | 0.5 |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| raycast(self, o, d, max_dist) | method |

```python
from components.extras.engine3d import SphereCollider
```

### ForceField

Public physics class.

Import: `from components.extras.engine3d import ForceField`

Signature: `ForceField(kind: 'str' = 'point', strength: 'float' = 5.0, radius: 'float' = 10.0, falloff: 'str' = 'linear', direction=(1.0, 0.0, 0.0), axis=(0.0, 1.0, 0.0), pull: 'float' = 0.0, noise_scale: 'float' = 0.5, noise_speed: 'float' = 1.0, affect_particles: 'bool' = True, affect_bodies: 'bool' = False)`

| Parameter | Type | Default |
| --- | --- | --- |
| kind | 'str' | 'point' |
| strength | 'float' | 5.0 |
| radius | 'float' | 10.0 |
| falloff | 'str' | 'linear' |
| direction | Value | (1.0, 0.0, 0.0) |
| axis | Value | (0.0, 1.0, 0.0) |
| pull | 'float' | 0.0 |
| noise_scale | 'float' | 0.5 |
| noise_speed | 'float' | 1.0 |
| affect_particles | 'bool' | True |
| affect_bodies | 'bool' | False |

| Member | Kind |
| --- | --- |
| acceleration_at(self, x: 'float', y: 'float', z: 'float') -> 'Tuple[float, float, float]' | method |
| update(self, dt: 'float') | method |
| fixed_update(self, dt: 'float') | method |
| to_dict(self) -> 'dict' | method |

```python
from components.extras.engine3d import ForceField
```

### BallJoint

Public physics class.

Import: `from components.extras.engine3d import BallJoint`

Signature: `BallJoint(*a, swing_limit: 'float' = 0.0, axis=(0.0, 1.0, 0.0), **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| *a | Values | Optional |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| constrain(self, dt: 'float') -> 'None' | method |

```python
from components.extras.engine3d import BallJoint
```

### DistanceJoint

Public physics class.

Import: `from components.extras.engine3d import DistanceJoint`

Signature: `DistanceJoint(*a, length: 'Optional[float]' = None, min_length: 'float' = 0.0, max_length: 'Optional[float]' = None, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| *a | Values | Optional |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| setup(self) -> 'None' | method |
| constrain(self, dt: 'float') -> 'None' | method |

```python
from components.extras.engine3d import DistanceJoint
```

### FixedJoint

Public physics class.

Import: `from components.extras.engine3d import FixedJoint`

Signature: `FixedJoint(*a, lock_rotation: 'bool' = True, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| *a | Values | Optional |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| setup(self) -> 'None' | method |
| constrain(self, dt: 'float') -> 'None' | method |
| post(self, dt: 'float') -> 'None' | method |

```python
from components.extras.engine3d import FixedJoint
```

### HingeJoint

Public physics class.

Import: `from components.extras.engine3d import HingeJoint`

Signature: `HingeJoint(*a, axis=(0.0, 1.0, 0.0), use_limits: 'bool' = False, min_angle: 'float' = -45.0, max_angle: 'float' = 45.0, motor_speed: 'float' = 0.0, motor_enabled: 'bool' = False, update_rotation: 'bool' = True, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| *a | Values | Optional |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| world_axis(self) | method |
| setup(self) -> 'None' | method |
| constrain(self, dt: 'float') -> 'None' | method |
| post(self, dt: 'float') -> 'None' | method |

```python
from components.extras.engine3d import HingeJoint
```

### Joint

Public physics class.

Import: `from components.extras.engine3d import Joint`

Signature: `Joint(connected: 'Optional[Node]' = None, anchor=(0.0, 0.0, 0.0), connected_anchor=None, break_distance: 'float' = 0.0, collide_connected: 'bool' = False)`

| Parameter | Type | Default |
| --- | --- | --- |
| connected | 'Optional[Node]' | None |
| anchor | Value | (0.0, 0.0, 0.0) |
| connected_anchor | Value | None |
| break_distance | 'float' | 0.0 |
| collide_connected | 'bool' | False |

| Member | Kind |
| --- | --- |
| alive(self) -> 'bool' | method |
| body | property |
| other | property |
| bodies(self) | method |
| anchor_a(self) | method |
| anchor_b(self) | method |
| setup(self) -> 'None' | method |
| solve(self, dt: 'float') -> 'None' | method |
| constrain(self, dt: 'float') -> 'None' | method |
| post(self, dt: 'float') -> 'None' | method |
| error(self) -> 'float' | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |
| start(self) -> 'None' | method |

```python
from components.extras.engine3d import Joint
```

### SpringJoint

Public physics class.

Import: `from components.extras.engine3d import SpringJoint`

Signature: `SpringJoint(*a, rest_length: 'Optional[float]' = None, stiffness: 'float' = 80.0, damping: 'float' = 4.0, min_length: 'float' = 0.0, max_length: 'float' = 1000000000.0, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| *a | Values | Optional |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| setup(self) -> 'None' | method |
| constrain(self, dt: 'float') -> 'None' | method |

```python
from components.extras.engine3d import SpringJoint
```

### Cloth

Public physics class.

Import: `from components.extras.engine3d import Cloth`

Signature: `Cloth(width: 'float' = 2.0, height: 'float' = 2.0, columns: 'int' = 16, rows: 'int' = 16, pin: 'str' = 'top', pins: 'Optional[Sequence[Tuple[int, int]]]' = None, stiffness: 'float' = 1.0, bend_stiffness: 'float' = 0.3, iterations: 'int' = 6, damping: 'float' = 0.6, thickness: 'float' = 0.03, collide: 'bool' = True, wind=(0.0, 0.0, 0.0), use_force_fields: 'bool' = True, mass: 'float' = 1.0, material: 'Optional[Material]' = None, friction: 'float' = 0.4, tear_ratio: 'float' = 0.0, double_sided: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| width | 'float' | 2.0 |
| height | 'float' | 2.0 |
| columns | 'int' | 16 |
| rows | 'int' | 16 |
| pin | 'str' | 'top' |
| pins | 'Optional[Sequence[Tuple[int, int]]]' | None |
| stiffness | 'float' | 1.0 |
| bend_stiffness | 'float' | 0.3 |
| iterations | 'int' | 6 |
| damping | 'float' | 0.6 |
| thickness | 'float' | 0.03 |
| collide | 'bool' | True |
| wind | Value | (0.0, 0.0, 0.0) |
| use_force_fields | 'bool' | True |
| mass | 'float' | 1.0 |
| material | 'Optional[Material]' | None |
| friction | 'float' | 0.4 |
| tear_ratio | 'float' | 0.0 |
| double_sided | 'bool' | True |

| Member | Kind |
| --- | --- |
| index(self, i: 'int', j: 'int') -> 'int' | method |
| build(self) -> 'None' | method |
| pin_to(self, i: 'int', j: 'int', pinned: 'bool' = True) -> 'None' | method |
| cut(self, i: 'int', j: 'int') -> 'None' | method |
| fixed_update(self, dt: 'float') | method |
| prepare_view(self, view, renderer) -> 'None' | method |
| to_dict(self) -> 'dict' | method |

```python
from components.extras.engine3d import Cloth
```

### ParticleSolver

Public physics class.

Import: `from components.extras.engine3d import ParticleSolver`

Signature: `ParticleSolver()`

| Member | Kind |
| --- | --- |
| add(self, p, mass: 'float' = 1.0, radius: 'float' = 0.0) -> 'int' | method |
| link(self, a: 'int', b: 'int', rest: 'Optional[float]' = None, stiffness: 'float' = 1.0, min_ratio: 'Optional[float]' = None, max_ratio: 'Optional[float]' = None) -> 'None' | method |
| pin(self, i: 'int') -> 'None' | method |
| integrate(self, dt: 'float', accel, damping: 'float', forces: 'Optional[Callable]' = None) -> 'None' | method |
| solve_links(self, iterations: 'int') -> 'None' | method |
| collide(self, colliders: 'Sequence[Collider]', friction: 'float' = 0.3) -> 'None' | method |
| bounds(self) | method |

```python
from components.extras.engine3d import ParticleSolver
```

### Ragdoll

Public physics class.

Import: `from components.extras.engine3d import Ragdoll`

Signature: `Ragdoll(bones: 'Optional[Sequence[Node]]' = None, radius: 'float' = 0.07, max_bend: 'float' = 100.0, damping: 'float' = 0.8, iterations: 'int' = 8, friction: 'float' = 0.5, mass: 'float' = 1.0, animator_name: 'str' = 'Animator', auto_activate: 'bool' = False)`

| Parameter | Type | Default |
| --- | --- | --- |
| bones | 'Optional[Sequence[Node]]' | None |
| radius | 'float' | 0.07 |
| max_bend | 'float' | 100.0 |
| damping | 'float' | 0.8 |
| iterations | 'int' | 8 |
| friction | 'float' | 0.5 |
| mass | 'float' | 1.0 |
| animator_name | 'str' | 'Animator' |
| auto_activate | 'bool' | False |

| Member | Kind |
| --- | --- |
| start(self) | method |
| activate(self, impulse=None) -> 'None' | method |
| deactivate(self, restore_pose: 'bool' = False) -> 'None' | method |
| add_impulse(self, impulse, bone: 'Optional[Node]' = None) -> 'None' | method |
| fixed_update(self, dt: 'float') | method |
| late_update(self, dt: 'float') | method |
| to_dict(self) -> 'dict' | method |

```python
from components.extras.engine3d import Ragdoll
```

### Vehicle

Public physics class.

Import: `from components.extras.engine3d import Vehicle`

Signature: `Vehicle(wheels: 'Sequence[Wheel]' = (), engine_force: 'float' = 14000.0, brake_force: 'float' = 22000.0, max_steer: 'float' = 32.0, spring: 'float' = 38000.0, damper: 'float' = 4200.0, grip: 'float' = 7.0, drag: 'float' = 0.4, rolling: 'float' = 0.02, max_speed: 'float' = 45.0, wheelbase: 'Optional[float]' = None, align_speed: 'float' = 6.0, mask: 'int' = -1, downforce: 'float' = 0.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| wheels | 'Sequence[Wheel]' | () |
| engine_force | 'float' | 14000.0 |
| brake_force | 'float' | 22000.0 |
| max_steer | 'float' | 32.0 |
| spring | 'float' | 38000.0 |
| damper | 'float' | 4200.0 |
| grip | 'float' | 7.0 |
| drag | 'float' | 0.4 |
| rolling | 'float' | 0.02 |
| max_speed | 'float' | 45.0 |
| wheelbase | 'Optional[float]' | None |
| align_speed | 'float' | 6.0 |
| mask | 'int' | -1 |
| downforce | 'float' | 0.0 |

| Member | Kind |
| --- | --- |
| drive_input(self, throttle: 'float' = 0.0, steer: 'float' = 0.0, brake: 'float' = 0.0, handbrake: 'bool' = False) -> 'None' | method |
| body | property |
| fixed_update(self, dt: 'float') | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import Vehicle
```

### Wheel

Public physics class.

Import: `from components.extras.engine3d import Wheel`

Signature: `Wheel(offset=(0.0, 0.0, 0.0), radius: 'float' = 0.35, suspension: 'float' = 0.3, steer: 'bool' = False, drive: 'bool' = True, node: 'Optional[Node]' = None)`

| Parameter | Type | Default |
| --- | --- | --- |
| offset | Value | (0.0, 0.0, 0.0) |
| radius | 'float' | 0.35 |
| suspension | 'float' | 0.3 |
| steer | 'bool' | False |
| drive | 'bool' | True |
| node | 'Optional[Node]' | None |

```python
from components.extras.engine3d import Wheel
```

## Animation and Characters
### AnimationClip

Public animation class.

Import: `from components.extras.engine3d import AnimationClip`

Signature: `AnimationClip(name: 'str', channels: 'Sequence[Channel]', loop: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'str' | Required |
| channels | 'Sequence[Channel]' | Required |
| loop | 'bool' | True |

| Member | Kind |
| --- | --- |
| add_event(self, time: 'float', callback: 'Callable[[], None]') -> 'None' | method |

```python
from components.extras.engine3d import AnimationClip
```

### Animator

Public animation class.

Import: `from components.extras.engine3d import Animator`

Signature: `Animator(clips: 'Sequence[AnimationClip]' = (), default: 'Optional[str]' = None, play_on_start: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| clips | 'Sequence[AnimationClip]' | () |
| default | 'Optional[str]' | None |
| play_on_start | 'bool' | True |

| Member | Kind |
| --- | --- |
| states | property |
| add_clip(self, clip: 'AnimationClip') -> 'None' | method |
| add_motion(self, name: 'str', motion: 'Motion') -> 'Motion' | method |
| add_layer(self, name: 'str', weight: 'float' = 1.0, mask: 'Optional[AvatarMask]' = None, additive: 'bool' = False) -> 'AnimLayer' | method |
| layer(self, ref) -> 'AnimLayer' | method |
| set_layer_weight(self, ref, weight: 'float') -> 'None' | method |
| start(self) | method |
| play(self, name: 'str', loop: 'Optional[bool]' = None, fade: 'float' = 0.0, speed: 'float' = 1.0, restart: 'bool' = True, layer=0) -> 'None' | method |
| stop(self, layer=None) -> 'None' | method |
| current | property |
| is_playing(self, name: 'Optional[str]' = None) -> 'bool' | method |
| normalized_time(self) -> 'float' | method |
| set(self, name: 'str', value) -> 'None' | method |
| get(self, name: 'str', default=None) | method |
| set_trigger(self, name: 'str') -> 'None' | method |
| consume(self, name: 'str') -> 'bool' | method |
| update(self, dt: 'float') | method |

```python
from components.extras.engine3d import Animator
```

### AnimLayer

Public animation class.

Import: `from components.extras.engine3d import AnimLayer`

Signature: `AnimLayer(name: 'str', weight: 'float' = 1.0, mask: 'Optional[AvatarMask]' = None, additive: 'bool' = False)`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'str' | Required |
| weight | 'float' | 1.0 |
| mask | 'Optional[AvatarMask]' | None |
| additive | 'bool' | False |

```python
from components.extras.engine3d import AnimLayer
```

### AvatarMask

Public animation class.

Import: `from components.extras.engine3d import AvatarMask`

Signature: `AvatarMask(ids=(), weights: 'Optional[Dict[str, float]]' = None)`

| Parameter | Type | Default |
| --- | --- | --- |
| ids | Value | () |
| weights | 'Optional[Dict[str, float]]' | None |

| Member | Kind |
| --- | --- |
| from_nodes(nodes, include_children: 'bool' = True) -> "'AvatarMask'" | method |
| from_paths(root: 'Node', paths: 'Sequence[str]', include_children: 'bool' = True) -> "'AvatarMask'" | method |
| weight(self, target: 'str') -> 'float' | method |

```python
from components.extras.engine3d import AvatarMask
```

### BlendTree1D

Public animation class.

Import: `from components.extras.engine3d import BlendTree1D`

Signature: `BlendTree1D(parameter: 'str', entries: 'Sequence[Tuple[float, object]]')`

| Parameter | Type | Default |
| --- | --- | --- |
| parameter | 'str' | Required |
| entries | 'Sequence[Tuple[float, object]]' | Required |

| Member | Kind |
| --- | --- |
| weights(self, params) -> 'List[Tuple[Motion, float]]' | method |
| samples(self, params) | method |

```python
from components.extras.engine3d import BlendTree1D
```

### BlendTree2D

Public animation class.

Import: `from components.extras.engine3d import BlendTree2D`

Signature: `BlendTree2D(parameter_x: 'str', parameter_y: 'str', entries: 'Sequence[Tuple[Tuple[float, float], object]]', power: 'float' = 2.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| parameter_x | 'str' | Required |
| parameter_y | 'str' | Required |
| entries | 'Sequence[Tuple[Tuple[float, float], object]]' | Required |
| power | 'float' | 2.0 |

| Member | Kind |
| --- | --- |
| weights(self, params) -> 'List[Tuple[Motion, float]]' | method |
| samples(self, params) | method |

```python
from components.extras.engine3d import BlendTree2D
```

### BlendTreeDirect

Public animation class.

Import: `from components.extras.engine3d import BlendTreeDirect`

Signature: `BlendTreeDirect(entries: 'Sequence[Tuple[str, object]]')`

| Parameter | Type | Default |
| --- | --- | --- |
| entries | 'Sequence[Tuple[str, object]]' | Required |

| Member | Kind |
| --- | --- |
| samples(self, params) | method |

```python
from components.extras.engine3d import BlendTreeDirect
```

### Channel

Public animation class.

Import: `from components.extras.engine3d import Channel`

Signature: `Channel(target: 'str', prop: 'str', times: 'Sequence[float]', values: 'Sequence[float]', interpolation: 'str' = 'LINEAR', width: 'Optional[int]' = None)`

| Parameter | Type | Default |
| --- | --- | --- |
| target | 'str' | Required |
| prop | 'str' | Required |
| times | 'Sequence[float]' | Required |
| values | 'Sequence[float]' | Required |
| interpolation | 'str' | 'LINEAR' |
| width | 'Optional[int]' | None |

| Member | Kind |
| --- | --- |
| sample(self, t: 'float') | method |

```python
from components.extras.engine3d import Channel
```

### ClipMotion

Public animation class.

Import: `from components.extras.engine3d import ClipMotion`

Signature: `ClipMotion(clip: 'AnimationClip')`

| Parameter | Type | Default |
| --- | --- | --- |
| clip | 'AnimationClip' | Required |

| Member | Kind |
| --- | --- |
| duration | property |
| samples(self, params) | method |

```python
from components.extras.engine3d import ClipMotion
```

### Cond

Public animation class.

Import: `from components.extras.engine3d import Cond`

Signature: `Cond()`

| Member | Kind |
| --- | --- |
| greater(name: 'str', value: 'float') | method |
| less(name: 'str', value: 'float') | method |
| equals(name: 'str', value) | method |
| flag(name: 'str', value: 'bool' = True) | method |
| trigger(name: 'str') | method |
| finished(min_normalized: 'float' = 0.95) | method |
| all(*conds) | method |
| any(*conds) | method |

```python
from components.extras.engine3d import Cond
```

### Motion

Public animation class.

Import: `from components.extras.engine3d import Motion`

Signature: `Motion()`

| Member | Kind |
| --- | --- |
| samples(self, params: 'Dict[str, object]') -> 'List[Tuple[AnimationClip, float]]' | method |
| clips(self) -> 'List[AnimationClip]' | method |
| length(self, params: 'Dict[str, object]') -> 'float' | method |

```python
from components.extras.engine3d import Motion
```

### SkinnedMeshRenderer

Public animation class.

Import: `from components.extras.engine3d import SkinnedMeshRenderer`

Signature: `SkinnedMeshRenderer(mesh=None, material=None, bones: 'Sequence[Node]' = (), inverse_bind: 'Sequence[Mat4]' = (), materials=None, cast_shadows: 'bool' = True, receive_shadows: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| mesh | Value | None |
| material | Value | None |
| bones | 'Sequence[Node]' | () |
| inverse_bind | 'Sequence[Mat4]' | () |
| materials | Value | None |
| cast_shadows | 'bool' | True |
| receive_shadows | 'bool' | True |

| Member | Kind |
| --- | --- |
| is_skinned | property |
| palette(self) | method |
| to_dict(self) -> 'dict' | method |

```python
from components.extras.engine3d import SkinnedMeshRenderer
```

### StateMachine

Public animation class.

Import: `from components.extras.engine3d import StateMachine`

Signature: `StateMachine(initial: 'str', fade: 'float' = 0.15, layer=0)`

| Parameter | Type | Default |
| --- | --- | --- |
| initial | 'str' | Required |
| fade | 'float' | 0.15 |
| layer | Value | 0 |

| Member | Kind |
| --- | --- |
| add(self, source: 'Optional[str]', target: 'str', condition: 'Callable[[Animator], bool]', fade: 'Optional[float]' = None) -> "'StateMachine'" | method |
| evaluate(self, animator: 'Animator') -> 'None' | method |

```python
from components.extras.engine3d import StateMachine
```

### FootIK

Public animation class.

Import: `from components.extras.engine3d import FootIK`

Signature: `FootIK(legs=(), pelvis: 'Optional[Node]' = None, foot_height: 'float' = 0.08, ray_up: 'float' = 0.6, ray_down: 'float' = 0.9, weight: 'float' = 1.0, smooth: 'float' = 14.0, mask: 'int' = -1, align_foot: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| legs | Value | () |
| pelvis | 'Optional[Node]' | None |
| foot_height | 'float' | 0.08 |
| ray_up | 'float' | 0.6 |
| ray_down | 'float' | 0.9 |
| weight | 'float' | 1.0 |
| smooth | 'float' | 14.0 |
| mask | 'int' | -1 |
| align_foot | 'bool' | True |

| Member | Kind |
| --- | --- |
| late_update(self, dt: 'float') | method |

```python
from components.extras.engine3d import FootIK
```

### LookAtIK

Public animation class.

Import: `from components.extras.engine3d import LookAtIK`

Signature: `LookAtIK(bone: 'Optional[Node]' = None, target: 'Optional[Node]' = None, weight: 'float' = 1.0, forward=(0.0, 0.0, -1.0), max_angle: 'float' = 70.0, speed: 'float' = 8.0, target_position=None, up=(0.0, 1.0, 0.0))`

| Parameter | Type | Default |
| --- | --- | --- |
| bone | 'Optional[Node]' | None |
| target | 'Optional[Node]' | None |
| weight | 'float' | 1.0 |
| forward | Value | (0.0, 0.0, -1.0) |
| max_angle | 'float' | 70.0 |
| speed | 'float' | 8.0 |
| target_position | Value | None |
| up | Value | (0.0, 1.0, 0.0) |

| Member | Kind |
| --- | --- |
| late_update(self, dt: 'float') | method |

```python
from components.extras.engine3d import LookAtIK
```

### TwoBoneIK

Public animation class.

Import: `from components.extras.engine3d import TwoBoneIK`

Signature: `TwoBoneIK(root: 'Optional[Node]' = None, mid: 'Optional[Node]' = None, tip: 'Optional[Node]' = None, target: 'Optional[Node]' = None, pole: 'Optional[Node]' = None, weight: 'float' = 1.0, target_position=None, pole_position=None, match_rotation: 'bool' = False, soft: 'float' = 0.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| root | 'Optional[Node]' | None |
| mid | 'Optional[Node]' | None |
| tip | 'Optional[Node]' | None |
| target | 'Optional[Node]' | None |
| pole | 'Optional[Node]' | None |
| weight | 'float' | 1.0 |
| target_position | Value | None |
| pole_position | Value | None |
| match_rotation | 'bool' | False |
| soft | 'float' | 0.0 |

| Member | Kind |
| --- | --- |
| late_update(self, dt: 'float') | method |

```python
from components.extras.engine3d import TwoBoneIK
```

### solve_two_bone

Public animation function.

Import: `from components.extras.engine3d import solve_two_bone`

Signature: `solve_two_bone(root: 'Node', mid: 'Node', tip: 'Node', target, pole=None, weight: 'float' = 1.0, soft: 'float' = 0.0) -> 'None'`

| Parameter | Type | Default |
| --- | --- | --- |
| root | 'Node' | Required |
| mid | 'Node' | Required |
| tip | 'Node' | Required |
| target | Value | Required |
| pole | Value | None |
| weight | 'float' | 1.0 |
| soft | 'float' | 0.0 |

```python
from components.extras.engine3d import solve_two_bone
```

### MorphController

Public animation class.

Import: `from components.extras.engine3d import MorphController`

Signature: `MorphController(morphs: 'Optional[MorphSet]' = None)`

| Parameter | Type | Default |
| --- | --- | --- |
| morphs | 'Optional[MorphSet]' | None |

| Member | Kind |
| --- | --- |
| set_weights(self, values: 'Sequence[float]') -> 'None' | method |
| set_weight(self, key, value: 'float') -> 'None' | method |
| get_weight(self, key) -> 'float' | method |
| start(self) | method |
| late_update(self, dt: 'float') | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import MorphController
```

### MorphSet

Public animation class.

Import: `from components.extras.engine3d import MorphSet`

Signature: `MorphSet(targets: 'Sequence[MorphTarget]', default_weights: 'Optional[Sequence[float]]' = None)`

| Parameter | Type | Default |
| --- | --- | --- |
| targets | 'Sequence[MorphTarget]' | Required |
| default_weights | 'Optional[Sequence[float]]' | None |

| Member | Kind |
| --- | --- |
| index(self, name: 'str') -> 'int' | method |

```python
from components.extras.engine3d import MorphSet
```

### MorphTarget

Public animation class.

Import: `from components.extras.engine3d import MorphTarget`

Signature: `MorphTarget(name: 'str', indices: 'Sequence[int]', dpos: 'Sequence[float]', dnormal: 'Optional[Sequence[float]]' = None)`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'str' | Required |
| indices | 'Sequence[int]' | Required |
| dpos | 'Sequence[float]' | Required |
| dnormal | 'Optional[Sequence[float]]' | None |

| Member | Kind |
| --- | --- |
| from_dense(name: 'str', dpos: 'Sequence[float]', dnormal: 'Optional[Sequence[float]]' = None) -> "'MorphTarget'" | method |

```python
from components.extras.engine3d import MorphTarget
```

### auto_map

Public animation function.

Import: `from components.extras.engine3d import auto_map`

Signature: `auto_map(src_nodes: 'Iterable[Node]', dst_nodes: 'Iterable[Node]') -> 'Dict[str, str]'`

| Parameter | Type | Default |
| --- | --- | --- |
| src_nodes | 'Iterable[Node]' | Required |
| dst_nodes | 'Iterable[Node]' | Required |

```python
from components.extras.engine3d import auto_map
```

### humanoid_slot

Public animation function.

Import: `from components.extras.engine3d import humanoid_slot`

Signature: `humanoid_slot(name: 'str') -> 'Optional[str]'`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'str' | Required |

```python
from components.extras.engine3d import humanoid_slot
```

### rest_pose

Public animation function.

Import: `from components.extras.engine3d import rest_pose`

Signature: `rest_pose(root: 'Node') -> 'Dict[str, Tuple[Tuple[float, float, float], Tuple[float, float, float, float], Tuple[float, float, float]]]'`

| Parameter | Type | Default |
| --- | --- | --- |
| root | 'Node' | Required |

```python
from components.extras.engine3d import rest_pose
```

### retarget_clip

Public animation function.

Import: `from components.extras.engine3d import retarget_clip`

Signature: `retarget_clip(clip: 'AnimationClip', mapping: 'Dict[str, str]', src_rest: 'dict', dst_rest: 'dict', hips_source: 'Optional[str]' = None, name: 'Optional[str]' = None, scale: 'Optional[float]' = None) -> 'AnimationClip'`

| Parameter | Type | Default |
| --- | --- | --- |
| clip | 'AnimationClip' | Required |
| mapping | 'Dict[str, str]' | Required |
| src_rest | 'dict' | Required |
| dst_rest | 'dict' | Required |
| hips_source | 'Optional[str]' | None |
| name | 'Optional[str]' | None |
| scale | 'Optional[float]' | None |

```python
from components.extras.engine3d import retarget_clip
```

### ActivationTrack

Public animation class.

Import: `from components.extras.engine3d import ActivationTrack`

Signature: `ActivationTrack(node: 'Node', spans: 'Sequence[Tuple[float, float]]', name: 'Optional[str]' = None, restore: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| node | 'Node' | Required |
| spans | 'Sequence[Tuple[float, float]]' | Required |
| name | 'Optional[str]' | None |
| restore | 'bool' | True |

| Member | Kind |
| --- | --- |
| end_time(self) | method |
| evaluate(self, time, prev, playing) | method |

```python
from components.extras.engine3d import ActivationTrack
```

### AnimationTrack

Public animation class.

Import: `from components.extras.engine3d import AnimationTrack`

Signature: `AnimationTrack(animator, clips: 'Sequence[Tuple[float, str]]', name: 'str' = 'animation', fade: 'float' = 0.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| animator | Value | Required |
| clips | 'Sequence[Tuple[float, str]]' | Required |
| name | 'str' | 'animation' |
| fade | 'float' | 0.0 |

| Member | Kind |
| --- | --- |
| end_time(self) | method |
| reset(self) | method |
| evaluate(self, time, prev, playing) | method |

```python
from components.extras.engine3d import AnimationTrack
```

### AudioTrack

Public animation class.

Import: `from components.extras.engine3d import AudioTrack`

Signature: `AudioTrack(source, start: 'float', name: 'str' = 'audio', stop_at: 'Optional[float]' = None)`

| Parameter | Type | Default |
| --- | --- | --- |
| source | Value | Required |
| start | 'float' | Required |
| name | 'str' | 'audio' |
| stop_at | 'Optional[float]' | None |

| Member | Kind |
| --- | --- |
| end_time(self) | method |
| reset(self) | method |
| evaluate(self, time, prev, playing) | method |

```python
from components.extras.engine3d import AudioTrack
```

### CameraTrack

Public animation class.

Import: `from components.extras.engine3d import CameraTrack`

Signature: `CameraTrack(cuts: 'Sequence[Tuple[float, Any]]', name: 'str' = 'cameras')`

| Parameter | Type | Default |
| --- | --- | --- |
| cuts | 'Sequence[Tuple[float, Any]]' | Required |
| name | 'str' | 'cameras' |

| Member | Kind |
| --- | --- |
| end_time(self) | method |
| evaluate(self, time, prev, playing) | method |

```python
from components.extras.engine3d import CameraTrack
```

### PlayableDirector

Public animation class.

Import: `from components.extras.engine3d import PlayableDirector`

Signature: `PlayableDirector(tracks: 'Sequence[Track]' = (), duration: 'Optional[float]' = None, wrap: 'str' = 'none', play_on_start: 'bool' = False, speed: 'float' = 1.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| tracks | 'Sequence[Track]' | () |
| duration | 'Optional[float]' | None |
| wrap | 'str' | 'none' |
| play_on_start | 'bool' | False |
| speed | 'float' | 1.0 |

| Member | Kind |
| --- | --- |
| duration | property |
| add_track(self, t: 'Track') -> 'Track' | method |
| start(self) | method |
| play(self, from_start: 'bool' = True) -> 'None' | method |
| pause(self) -> 'None' | method |
| stop(self) -> 'None' | method |
| seek(self, time: 'float') -> 'None' | method |
| update(self, dt: 'float') | method |

```python
from components.extras.engine3d import PlayableDirector
```

### PropertyTrack

Public animation class.

Import: `from components.extras.engine3d import PropertyTrack`

Signature: `PropertyTrack(target: 'Any', attribute: 'str', keys: 'Sequence[Tuple[float, Any]]', ease: 'str' = 'linear', name: 'Optional[str]' = None)`

| Parameter | Type | Default |
| --- | --- | --- |
| target | 'Any' | Required |
| attribute | 'str' | Required |
| keys | 'Sequence[Tuple[float, Any]]' | Required |
| ease | 'str' | 'linear' |
| name | 'Optional[str]' | None |

| Member | Kind |
| --- | --- |
| end_time(self) -> 'float' | method |
| evaluate(self, time, prev, playing) | method |

```python
from components.extras.engine3d import PropertyTrack
```

### SignalTrack

Public animation class.

Import: `from components.extras.engine3d import SignalTrack`

Signature: `SignalTrack(events: 'Sequence[Tuple[float, Callable[[], None]]]', name: 'str' = 'signals')`

| Parameter | Type | Default |
| --- | --- | --- |
| events | 'Sequence[Tuple[float, Callable[[], None]]]' | Required |
| name | 'str' | 'signals' |

| Member | Kind |
| --- | --- |
| end_time(self) | method |
| evaluate(self, time, prev, playing) | method |

```python
from components.extras.engine3d import SignalTrack
```

### Track

Public animation class.

Import: `from components.extras.engine3d import Track`

Signature: `Track(name: 'str' = 'track')`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'str' | 'track' |

| Member | Kind |
| --- | --- |
| evaluate(self, time: 'float', prev: 'float', playing: 'bool') -> 'None' | method |
| reset(self) -> 'None' | method |
| end_time(self) -> 'float' | method |

```python
from components.extras.engine3d import Track
```

### TransformTrack

Public animation class.

Import: `from components.extras.engine3d import TransformTrack`

Signature: `TransformTrack(node: 'Node', position: 'Sequence[Tuple[float, Any]]' = (), rotation: 'Sequence[Tuple[float, Any]]' = (), scale: 'Sequence[Tuple[float, Any]]' = (), ease: 'str' = 'smooth', name: 'Optional[str]' = None)`

| Parameter | Type | Default |
| --- | --- | --- |
| node | 'Node' | Required |
| position | 'Sequence[Tuple[float, Any]]' | () |
| rotation | 'Sequence[Tuple[float, Any]]' | () |
| scale | 'Sequence[Tuple[float, Any]]' | () |
| ease | 'str' | 'smooth' |
| name | 'Optional[str]' | None |

| Member | Kind |
| --- | --- |
| end_time(self) | method |
| evaluate(self, time, prev, playing) | method |

```python
from components.extras.engine3d import TransformTrack
```

## Input and Device Services
### ActionMap

Public input class.

Import: `from components.extras.engine3d import ActionMap`

Signature: `ActionMap(name: 'str')`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'str' | Required |

| Member | Kind |
| --- | --- |
| add(self, name: 'str', type: 'str' = 'button', bindings: 'Iterable[str]' = (), threshold: 'float' = 0.5) -> 'InputAction' | method |
| get(self, name: 'str') -> 'Optional[InputAction]' | method |

```python
from components.extras.engine3d import ActionMap
```

### InputAction

Public input class.

Import: `from components.extras.engine3d import InputAction`

Signature: `InputAction(name: 'str', type: 'str' = 'button', bindings: 'Iterable[str]' = (), threshold: 'float' = 0.5)`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'str' | Required |
| type | 'str' | 'button' |
| bindings | 'Iterable[str]' | () |
| threshold | 'float' | 0.5 |

| Member | Kind |
| --- | --- |
| set_bindings(self, bindings: 'Iterable[str]') -> 'None' | method |
| rebind(self, index: 'int', spec: 'str') -> 'None' | method |
| reset(self) -> 'None' | method |
| update(self, inp: 'Input') -> 'None' | method |

```python
from components.extras.engine3d import InputAction
```

### InputActions

Public input class.

Import: `from components.extras.engine3d import InputActions`

Signature: `InputActions(input_: 'Input')`

| Parameter | Type | Default |
| --- | --- | --- |
| input_ | 'Input' | Required |

| Member | Kind |
| --- | --- |
| create_map(self, name: 'str') -> 'ActionMap' | method |
| remove_map(self, name: 'str') -> 'None' | method |
| enable(self, name: 'str', enabled: 'bool' = True) -> 'None' | method |
| get(self, name: 'str') -> 'Optional[InputAction]' | method |
| pressed(self, name: 'str') -> 'bool' | method |
| held(self, name: 'str') -> 'bool' | method |
| released(self, name: 'str') -> 'bool' | method |
| value(self, name: 'str') -> 'float' | method |
| vector(self, name: 'str') -> 'Tuple[float, float]' | method |
| start_rebind(self, action: 'str', index: 'int' = 0, kinds: 'Tuple[str, ...]' = ('key', 'button'), on_done: 'Optional[Callable[[InputAction, str], None]]' = None, cancel_key: 'str' = 'escape') -> 'None' | method |
| cancel_rebind(self) -> 'None' | method |
| rebinding | property |
| update(self) -> 'None' | method |
| overrides(self) -> 'dict' | method |
| save_overrides(self) -> 'str' | method |
| load_overrides(self, text_or_dict) -> 'None' | method |
| reset_all(self) -> 'None' | method |

```python
from components.extras.engine3d import InputActions
```

### Haptics

Provides the public feedback patterns exposed by the engine.

Import: `from components.extras.engine3d import Haptics`

Signature: `Haptics(engine)`

| Parameter | Type | Default |
| --- | --- | --- |
| engine | Value | Required |

| Member | Kind |
| --- | --- |
| available | property |
| light(self) -> 'bool' | method |
| medium(self) -> 'bool' | method |
| heavy(self) -> 'bool' | method |
| selection(self) -> 'bool' | method |
| success(self) -> 'bool' | method |
| warning(self) -> 'bool' | method |
| error(self) -> 'bool' | method |
| buzz(self, duration_ms: 'int' = 40, intensity: 'float' = 1.0) -> 'bool' | method |

```python
from components.extras.engine3d import Haptics
```

### Sensors

Samples acceleration, angular velocity, attitude, and derived tilt values.

Import: `from components.extras.engine3d import Sensors`

Signature: `Sensors(engine)`

| Parameter | Type | Default |
| --- | --- | --- |
| engine | Value | Required |

| Member | Kind |
| --- | --- |
| available(self, name: 'str') -> 'bool' | method |
| enable(self, name: 'str', rate_hz: 'int' = 60) -> 'bool' | method |
| disable(self, name: 'str') -> 'None' | method |
| reapply(self) -> 'None' | method |
| accelerometer | property |
| gyroscope | property |
| attitude | property |
| tilt(self) -> 'Optional[Tuple[float, float]]' | method |

```python
from components.extras.engine3d import Sensors
```

### Gamepad

Public input class.

Import: `from components.extras.engine3d import Gamepad`

Signature: `Gamepad(index: 'int')`

| Parameter | Type | Default |
| --- | --- | --- |
| index | 'int' | Required |

| Member | Kind |
| --- | --- |
| button(self, button) -> 'bool' | method |
| button_down(self, button) -> 'bool' | method |
| button_up(self, button) -> 'bool' | method |
| value(self, button) -> 'float' | method |
| stick(self, side: 'str' = 'left') -> 'Tuple[float, float]' | method |
| dpad(self) -> 'Tuple[float, float]' | method |

```python
from components.extras.engine3d import Gamepad
```

### Input

Public input class.

Import: `from components.extras.engine3d import Input`

Signature: `Input()`

| Member | Kind |
| --- | --- |
| feed_scroll(self, dx: 'float', dy: 'float') -> 'None' | method |
| released_pointers | property |
| feed_text(self, text: 'str') -> 'None' | method |
| request_keyboard(self, show: 'bool') -> 'None' | method |
| keys_pressed | property |
| feed_touch(self, action: 'int', pointer_id: 'int', x: 'float', y: 'float') -> 'None' | method |
| feed_gamepad_button(self, pad: 'int', button: 'int', value: 'float') -> 'None' | method |
| feed_gamepad_axis(self, pad: 'int', axis: 'int', value: 'float') -> 'None' | method |
| feed_gamepad_connection(self, pad: 'int', connected: 'bool', name: 'str' = '') -> 'None' | method |
| gamepad(self, index: 'int' = 0) -> 'Gamepad' | method |
| connected_gamepads | property |
| get_button(self, button, pad: 'Optional[int]' = None) -> 'bool' | method |
| get_button_down(self, button, pad: 'Optional[int]' = None) -> 'bool' | method |
| get_button_up(self, button, pad: 'Optional[int]' = None) -> 'bool' | method |
| get_trigger(self, button, pad: 'Optional[int]' = None) -> 'float' | method |
| get_stick(self, side: 'str' = 'left', pad: 'Optional[int]' = None) -> 'Tuple[float, float]' | method |
| feed_key(self, key: 'str', down: 'bool') -> 'None' | method |
| pressed_pointers(self) -> 'List[Pointer]' | method |

```python
from components.extras.engine3d import Input
```

### VirtualButton

Public input class.

Import: `from components.extras.engine3d import VirtualButton`

Signature: `VirtualButton(x: 'float', y: 'float', w: 'float', h: 'float')`

| Parameter | Type | Default |
| --- | --- | --- |
| x | 'float' | Required |
| y | 'float' | Required |
| w | 'float' | Required |
| h | 'float' | Required |

| Member | Kind |
| --- | --- |
| contains(self, x: 'float', y: 'float') -> 'bool' | method |
| update(self, inp: "'Input'") -> 'None' | method |

```python
from components.extras.engine3d import VirtualButton
```

### VirtualJoystick

Public input class.

Import: `from components.extras.engine3d import VirtualJoystick`

Signature: `VirtualJoystick(x: 'float', y: 'float', radius: 'float' = 80.0, dead_zone: 'float' = 0.12, region=None)`

| Parameter | Type | Default |
| --- | --- | --- |
| x | 'float' | Required |
| y | 'float' | Required |
| radius | 'float' | 80.0 |
| dead_zone | 'float' | 0.12 |
| region | Value | None |

| Member | Kind |
| --- | --- |
| contains(self, x: 'float', y: 'float') -> 'bool' | method |
| update(self, inp: "'Input'") -> 'None' | method |

```python
from components.extras.engine3d import VirtualJoystick
```

## Audio
### AudioOutput

Starts and closes audio output for an engine game.

Import: `from components.extras.audio import AudioOutput`

Signature: `AudioOutput(canvas=None)`

| Parameter | Type | Default |
| --- | --- | --- |
| `canvas` | `Canvas3D` or `None` | `None` |

| Member | Return |
| --- | --- |
| `start()` | Audio output handle |
| `close()` | `None` |

```python
from components.extras.audio import AudioOutput

output = AudioOutput(canvas)
engine.audio.attach(output.start())
```

### AudioListener

Marks the scene node used as the spatial listener.

Import: `from components.extras.engine3d import AudioListener`

Signature: `AudioListener()`

| Member | Kind |
| --- | --- |
| on_enable(self) | method |
| on_disable(self) | method |
| on_destroy(self) | method |

```python
from components.extras.engine3d import AudioListener
```

### AudioManager

Controls buses, playback, music, spatial sound, filters, effects, reverb, and voice limits.

Import: `from components.extras.engine3d import AudioManager`

Signature: `AudioManager(engine)`

| Parameter | Type | Default |
| --- | --- | --- |
| engine | Value | Required |

| Member | Kind |
| --- | --- |
| caps | property |
| native_spatial(self) -> 'bool' | method |
| set_spatial_mode(self, mode: 'str') -> 'None' | method |
| set_bus_filter(self, bus: 'str', lowpass: 'Optional[float]' = None, highpass: 'Optional[float]' = None, lowpass_q: 'float' = 0.707, highpass_q: 'float' = 0.707) -> 'None' | method |
| set_bus_reverb(self, bus: 'str', amount: 'float') -> 'None' | method |
| set_reverb(self, decay_s: 'float' = 1.5, damping: 'float' = 0.5, predelay_ms: 'float' = 10.0, room_size: 'float' = 0.5, wet: 'float' = 0.3, diffusion: 'float' = 0.8) -> 'None' | method |
| available | property |
| attach(self, device: 'AudioDevice') -> 'None' | method |
| detach(self) -> 'None' | method |
| shutdown(self) -> 'None' | method |
| clip(self, path: 'str', stream: 'bool' = False) -> 'AudioClip' | method |
| preload(self, *clips: 'AudioClip') -> 'None' | method |
| set_volume(self, bus: 'str', value: 'float') -> 'None' | method |
| get_volume(self, bus: 'str' = 'master') -> 'float' | method |
| set_muted(self, muted: 'bool') -> 'None' | method |
| add_ducker(self, source_bus: 'str' = 'sfx', target_bus: 'str' = 'music', amount: 'float' = 0.4, attack: 'float' = 0.08, release: 'float' = 0.5, min_voices: 'int' = 1, include_loops: 'bool' = False) -> 'dict' | method |
| remove_ducker(self, rule: 'dict') -> 'None' | method |
| duck(self, target_bus: 'str' = 'music', amount: 'float' = 0.3, attack: 'float' = 0.1, hold: 'float' = 1.0, release: 'float' = 0.6) -> 'None' | method |

```python
from components.extras.engine3d import AudioManager
```

### AudioSource

Plays an audio clip from a scene node.

Import: `from components.extras.engine3d import AudioSource`

Signature: `AudioSource(clip: 'Optional[AudioClip]' = None, volume: 'float' = 1.0, pitch: 'float' = 1.0, loop: 'bool' = False, play_on_awake: 'bool' = False, spatial: 'bool' = False, min_distance: 'float' = 1.0, max_distance: 'float' = 25.0, rolloff: 'str' = 'linear', bus: 'str' = 'sfx', pan: 'float' = 0.0, pan_strength: 'float' = 0.8, stream: 'bool' = False, doppler: 'float' = 0.0, occlude: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| clip | 'Optional[AudioClip]' | None |
| volume | 'float' | 1.0 |
| pitch | 'float' | 1.0 |
| loop | 'bool' | False |
| play_on_awake | 'bool' | False |
| spatial | 'bool' | False |
| min_distance | 'float' | 1.0 |
| max_distance | 'float' | 25.0 |
| rolloff | 'str' | 'linear' |
| bus | 'str' | 'sfx' |
| pan | 'float' | 0.0 |
| pan_strength | 'float' | 0.8 |
| stream | 'bool' | False |
| doppler | 'float' | 0.0 |
| occlude | 'bool' | True |

| Member | Kind |
| --- | --- |
| is_playing | property |
| awake(self) | method |
| on_enable(self) | method |
| on_disable(self) | method |
| on_destroy(self) | method |
| play(self, clip: 'Optional[AudioClip]' = None, offset: 'float' = 0.0) -> 'bool' | method |
| play_one_shot(self, clip: 'AudioClip', volume: 'float' = 1.0) -> 'None' | method |
| stop(self) -> 'None' | method |
| pause(self) -> 'None' | method |
| resume(self) -> 'None' | method |
| fade_out(self, seconds: 'float') -> 'None' | method |
| fade_in(self, seconds: 'float') -> 'None' | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import AudioSource
```

### ReverbZone

Blends reverb settings while the listener is inside or near a box-shaped zone.

Import: `from components.extras.engine3d import ReverbZone`

Signature: `ReverbZone(size=(10.0, 5.0, 10.0), center=(0.0, 0.0, 0.0), blend_distance: 'float' = 2.0, priority: 'int' = 0, decay_s: 'float' = 1.8, damping: 'float' = 0.5, predelay_ms: 'float' = 15.0, room_size: 'float' = 0.6, wet: 'float' = 0.4, diffusion: 'float' = 0.8, send: 'float' = 0.4)`

| Parameter | Type | Default |
| --- | --- | --- |
| size | Value | (10.0, 5.0, 10.0) |
| center | Value | (0.0, 0.0, 0.0) |
| blend_distance | 'float' | 2.0 |
| priority | 'int' | 0 |
| decay_s | 'float' | 1.8 |
| damping | 'float' | 0.5 |
| predelay_ms | 'float' | 15.0 |
| room_size | 'float' | 0.6 |
| wet | 'float' | 0.4 |
| diffusion | 'float' | 0.8 |
| send | 'float' | 0.4 |

| Member | Kind |
| --- | --- |
| params(self) -> 'dict' | method |
| weight_at(self, p) -> 'float' | method |
| on_enable(self) | method |
| on_disable(self) | method |
| on_destroy(self) | method |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import ReverbZone
```

### AudioClip

Public audio class.

Import: `from components.extras.engine3d import AudioClip`

Signature: `AudioClip(data: 'bytes', name: 'str' = 'clip', stream: 'bool' = False, source: 'Optional[str]' = None)`

| Parameter | Type | Default |
| --- | --- | --- |
| data | 'bytes' | Required |
| name | 'str' | 'clip' |
| stream | 'bool' | False |
| source | 'Optional[str]' | None |

| Member | Kind |
| --- | --- |
| from_bytes(cls, data: 'bytes', name: 'str' = 'clip', stream: 'bool' = False) -> "'AudioClip'" | method |
| from_samples(cls, samples, rate: 'int' = 22050, channels: 'int' = 1, name: 'str' = 'clip', stream: 'bool' = False) -> "'AudioClip'" | method |
| from_file(cls, path: 'str', reader=None, stream: 'bool' = False) -> "'AudioClip'" | method |

```python
from components.extras.engine3d import AudioClip
```

### AudioDevice

`AudioDevice` is the root-exported handle returned by `AudioOutput.start()`. Do not construct it directly. Use `AudioOutput` for setup and `engine.audio` for playback, buses, spatial sound, filters, effects, and music.

### synth_audio

Public audio value.

Import: `from components.extras.engine3d import synth_audio`

Type: `value`

```python
from components.extras.engine3d import synth_audio
```

## UI, Text, and Overlays
### NativeText

Public engine API.

Import: `from components.extras.engine3d import NativeText`

Signature: `NativeText(engine)`

| Parameter | Type | Default |
| --- | --- | --- |
| engine | Value | Required |

| Member | Kind |
| --- | --- |
| available | property |
| begin(self, field, ctx) -> 'bool' | method |
| end(self, field) -> 'None' | method |
| sync_rect(self) -> 'None' | method |
| on_event(self, field_id: 'int', kind: 'str', text: 'str', caret: 'int') -> 'None' | method |
| on_keyboard(self, visible: 'bool', height: 'float') -> 'None' | method |

```python
from components.extras.engine3d import NativeText
```

### BitmapFont

Stores bitmap glyph metrics and texture data for text drawing.

Import: `from components.extras.engine3d import BitmapFont`

Signature: `BitmapFont(texture: 'TextureAsset', glyphs: 'Dict[str, Tuple[float, float, float, float, float, float, float]]', line_height: 'float', base: 'float', size: 'float')`

| Parameter | Type | Default |
| --- | --- | --- |
| texture | 'TextureAsset' | Required |
| glyphs | 'Dict[str, Tuple[float, float, float, float, float, float, float]]' | Required |
| line_height | 'float' | Required |
| base | 'float' | Required |
| size | 'float' | Required |

| Member | Kind |
| --- | --- |
| default() -> "'BitmapFont'" | method |
| from_bmfont(fnt_text: 'str', texture: 'TextureAsset') -> "'BitmapFont'" | method |
| measure(self, text: 'str', size: 'float') -> 'Tuple[float, float]' | method |
| wrap(self, text: 'str', size: 'float', max_width: 'float') -> 'str' | method |

```python
from components.extras.engine3d import BitmapFont
```

### SpriteBatch

Records sprites and bitmap text for the overlay pass.

Import: `from components.extras.engine3d import SpriteBatch`

Signature: `SpriteBatch(ctx: 'GpuContext', max_sprites: 'int' = 2048)`

| Parameter | Type | Default |
| --- | --- | --- |
| ctx | 'GpuContext' | Required |
| max_sprites | 'int' | 2048 |

| Member | Kind |
| --- | --- |
| begin(self, width: 'int', height: 'int') -> 'None' | method |
| draw(self, tex, x: 'float', y: 'float', w: 'float', h: 'float', color=(1.0, 1.0, 1.0, 1.0), uv=(0.0, 0.0, 1.0, 1.0), rotation: 'float' = 0.0, pivot=(0.5, 0.5)) -> 'None' | method |
| rect(self, x, y, w, h, color=(1.0, 1.0, 1.0, 1.0)) -> 'None' | method |
| border(self, x, y, w, h, thickness: 'float', color) -> 'None' | method |
| text(self, font: 'Optional[BitmapFont]', text: 'str', x: 'float', y: 'float', size: 'float' = 18.0, color=(1.0, 1.0, 1.0, 1.0), align: 'str' = 'left', shadow: 'Optional[Tuple[float, float, float, float]]' = None) -> 'None' | method |
| flush(self, frame) -> 'None' | method |

```python
from components.extras.engine3d import SpriteBatch
```

### UI

Provides immediate labels, panels, controls, measurement, and pointer hit testing.

Import: `from components.extras.engine3d import UI`

Signature: `UI(batch: 'SpriteBatch', input_, font: 'Optional[BitmapFont]' = None, scale: 'float' = 1.0)`

| Parameter | Type | Default |
| --- | --- | --- |
| batch | 'SpriteBatch' | Required |
| input_ | Value | Required |
| font | 'Optional[BitmapFont]' | None |
| scale | 'float' | 1.0 |

| Member | Kind |
| --- | --- |
| panel(self, x, y, w, h, color=None) -> 'None' | method |
| label(self, text: 'str', x, y, size: 'float' = 18.0, color=None, align: 'str' = 'left', shadow: 'bool' = True) -> 'None' | method |
| button(self, text: 'str', x, y, w, h, size: 'float' = 18.0) -> 'bool' | method |
| bar(self, x, y, w, h, value: 'float', color=None) -> 'None' | method |
| toggle(self, text: 'str', x, y, value: 'bool', size: 'float' = 18.0) -> 'bool' | method |

```python
from components.extras.engine3d import UI
```

### Box

Public ui class.

Import: `from components.extras.engine3d import Box`

Signature: `Box(*children: 'Widget', vertical: 'bool' = True, spacing: 'float' = 6.0, padding=0.0, align: 'str' = 'stretch', justify: 'str' = 'start', **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| *children | Values | Optional |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| content_size(self, ctx, avail_w) | method |
| layout_children(self, ctx) | method |

```python
from components.extras.engine3d import Box
```

### Button

Public ui class.

Import: `from components.extras.engine3d import Button`

Signature: `Button(text: 'TextSource' = '', on_click: "Optional[Callable[['Button'], None]]" = None, size: 'float' = 18.0, padding=(14.0, 8.0), **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| text | 'TextSource' | '' |
| on_click | "Optional[Callable[['Button'], None]]" | None |
| size | 'float' | 18.0 |
| padding | Value | (14.0, 8.0) |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| content_size(self, ctx, avail_w) | method |
| on_press(self, ctx, p) | method |
| on_release(self, ctx, p, inside) | method |
| on_cancel(self, ctx, p) | method |
| draw(self, ctx) | method |

```python
from components.extras.engine3d import Button
```

### Grid

Public ui class.

Import: `from components.extras.engine3d import Grid`

Signature: `Grid(*children: 'Widget', columns: 'int' = 2, spacing: 'float' = 6.0, padding=0.0, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| *children | Values | Optional |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| content_size(self, ctx, avail_w) | method |
| layout_children(self, ctx) | method |

```python
from components.extras.engine3d import Grid
```

### HBox

Public ui class.

Import: `from components.extras.engine3d import HBox`

Signature: `HBox(*children, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| *children | Values | Optional |
| **kw | Values | Optional |

```python
from components.extras.engine3d import HBox
```

### Image

Public ui class.

Import: `from components.extras.engine3d import Image`

Signature: `Image(texture=None, uv=(0.0, 0.0, 1.0, 1.0), tint=(1.0, 1.0, 1.0, 1.0), native_size=(64.0, 64.0), keep_aspect: 'bool' = True, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| texture | Value | None |
| uv | Value | (0.0, 0.0, 1.0, 1.0) |
| tint | Value | (1.0, 1.0, 1.0, 1.0) |
| native_size | Value | (64.0, 64.0) |
| keep_aspect | 'bool' | True |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| content_size(self, ctx, avail_w) | method |
| draw(self, ctx) | method |

```python
from components.extras.engine3d import Image
```

### Label

Public ui class.

Import: `from components.extras.engine3d import Label`

Signature: `Label(text: 'TextSource' = '', size: 'float' = 18.0, color=None, align: 'str' = 'left', wrap: 'bool' = False, rich: 'bool' = False, shadow: 'bool' = True, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| text | 'TextSource' | '' |
| size | 'float' | 18.0 |
| color | Value | None |
| align | 'str' | 'left' |
| wrap | 'bool' | False |
| rich | 'bool' | False |
| shadow | 'bool' | True |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| content_size(self, ctx, avail_w) | method |
| draw(self, ctx) | method |

```python
from components.extras.engine3d import Label
```

### Panel

Public ui class.

Import: `from components.extras.engine3d import Panel`

Signature: `Panel(*children: 'Widget', color=None, border=None, border_width: 'float' = 1.0, padding=8.0, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| *children | Values | Optional |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| content_size(self, ctx, avail_w) | method |
| layout_children(self, ctx) | method |
| draw(self, ctx) | method |

```python
from components.extras.engine3d import Panel
```

### ProgressBar

Public ui class.

Import: `from components.extras.engine3d import ProgressBar`

Signature: `ProgressBar(value: 'float' = 0.0, color=None, length: 'float' = 160.0, thickness: 'float' = 14.0, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| value | 'float' | 0.0 |
| color | Value | None |
| length | 'float' | 160.0 |
| thickness | 'float' | 14.0 |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| content_size(self, ctx, avail_w) | method |
| draw(self, ctx) | method |

```python
from components.extras.engine3d import ProgressBar
```

### ScrollView

Public ui class.

Import: `from components.extras.engine3d import ScrollView`

Signature: `ScrollView(child: 'Optional[Widget]' = None, vertical: 'bool' = True, horizontal: 'bool' = False, scrollbars: 'bool' = True, inertia: 'bool' = True, drag_threshold: 'float' = 10.0, max_height: 'float' = 240.0, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| child | 'Optional[Widget]' | None |
| vertical | 'bool' | True |
| horizontal | 'bool' | False |
| scrollbars | 'bool' | True |
| inertia | 'bool' | True |
| drag_threshold | 'float' | 10.0 |
| max_height | 'float' | 240.0 |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| child | property |
| content_size(self, ctx, avail_w) | method |
| layout_children(self, ctx) | method |
| scroll_by(self, dx: 'float', dy: 'float') -> 'None' | method |
| scroll_to_top(self) -> 'None' | method |
| hit(self, x, y) | method |
| wants_drag(self, dx, dy) | method |
| on_press(self, ctx, p) | method |
| on_drag(self, ctx, p) | method |
| on_release(self, ctx, p, inside) | method |
| on_cancel(self, ctx, p) | method |
| update(self, ctx, dt) | method |
| draw(self, ctx) | method |

```python
from components.extras.engine3d import ScrollView
```

### Slider

Public ui class.

Import: `from components.extras.engine3d import Slider`

Signature: `Slider(value: 'float' = 0.0, minimum: 'float' = 0.0, maximum: 'float' = 1.0, step: 'float' = 0.0, on_change: 'Optional[Callable[[float], None]]' = None, vertical: 'bool' = False, length: 'float' = 160.0, thickness: 'float' = 24.0, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| value | 'float' | 0.0 |
| minimum | 'float' | 0.0 |
| maximum | 'float' | 1.0 |
| step | 'float' | 0.0 |
| on_change | 'Optional[Callable[[float], None]]' | None |
| vertical | 'bool' | False |
| length | 'float' | 160.0 |
| thickness | 'float' | 24.0 |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| content_size(self, ctx, avail_w) | method |
| set_value(self, v: 'float', notify: 'bool' = True) -> 'None' | method |
| on_press(self, ctx, p) | method |
| on_drag(self, ctx, p) | method |
| on_release(self, ctx, p, inside) | method |
| on_cancel(self, ctx, p) | method |
| draw(self, ctx) | method |

```python
from components.extras.engine3d import Slider
```

### Spacer

Public ui class.

Import: `from components.extras.engine3d import Spacer`

Signature: `Spacer(width=None, height=None, flex: 'float' = 0.0, margin=0.0, min_width: 'float' = 0.0, min_height: 'float' = 0.0, visible: 'bool' = True, enabled: 'bool' = True, name: 'str' = '')`

| Parameter | Type | Default |
| --- | --- | --- |
| width | Value | None |
| height | Value | None |
| flex | 'float' | 0.0 |
| margin | Value | 0.0 |
| min_width | 'float' | 0.0 |
| min_height | 'float' | 0.0 |
| visible | 'bool' | True |
| enabled | 'bool' | True |
| name | 'str' | '' |

```python
from components.extras.engine3d import Spacer
```

### Stack

Public ui class.

Import: `from components.extras.engine3d import Stack`

Signature: `Stack(*children: 'Widget', **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| *children | Values | Optional |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| place(self, widget: 'Widget', anchor: 'str' = 'top-left', offset=(0.0, 0.0)) -> 'Widget' | method |
| content_size(self, ctx, avail_w) | method |
| layout_children(self, ctx) | method |

```python
from components.extras.engine3d import Stack
```

### TextField

Public ui class.

Import: `from components.extras.engine3d import TextField`

Signature: `TextField(text: 'str' = '', placeholder: 'str' = '', on_change: 'Optional[Callable[[str], None]]' = None, on_submit: 'Optional[Callable[[str], None]]' = None, max_length: 'int' = 128, size: 'float' = 18.0, password: 'bool' = False, length: 'float' = 220.0, keyboard: 'str' = 'text', return_key: 'str' = 'done', **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| text | 'str' | '' |
| placeholder | 'str' | '' |
| on_change | 'Optional[Callable[[str], None]]' | None |
| on_submit | 'Optional[Callable[[str], None]]' | None |
| max_length | 'int' | 128 |
| size | 'float' | 18.0 |
| password | 'bool' | False |
| length | 'float' | 220.0 |
| keyboard | 'str' | 'text' |
| return_key | 'str' | 'done' |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| content_size(self, ctx, avail_w) | method |
| on_focus(self, ctx) | method |
| on_blur(self, ctx) | method |
| on_press(self, ctx, p) | method |
| on_release(self, ctx, p, inside) | method |
| on_cancel(self, ctx, p) | method |
| update(self, ctx, dt) | method |
| draw(self, ctx) | method |

```python
from components.extras.engine3d import TextField
```

### Toggle

Public ui class.

Import: `from components.extras.engine3d import Toggle`

Signature: `Toggle(text: 'TextSource' = '', value: 'bool' = False, on_change: 'Optional[Callable[[bool], None]]' = None, size: 'float' = 18.0, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| text | 'TextSource' | '' |
| value | 'bool' | False |
| on_change | 'Optional[Callable[[bool], None]]' | None |
| size | 'float' | 18.0 |
| **kw | Values | Optional |

| Member | Kind |
| --- | --- |
| content_size(self, ctx, avail_w) | method |
| on_press(self, ctx, p) | method |
| on_release(self, ctx, p, inside) | method |
| on_cancel(self, ctx, p) | method |
| draw(self, ctx) | method |

```python
from components.extras.engine3d import Toggle
```

### UIContext

Public ui class.

Import: `from components.extras.engine3d import UIContext`

Signature: `UIContext(root: "'UIRoot'", engine)`

| Parameter | Type | Default |
| --- | --- | --- |
| root | "'UIRoot'" | Required |
| engine | Value | Required |

| Member | Kind |
| --- | --- |
| font | property |
| color(self, name_or_value) | method |
| measure(self, text: 'str', size: 'float') -> 'Tuple[float, float]' | method |
| push_clip(self, x: 'float', y: 'float', w: 'float', h: 'float') | method |
| pop_clip(self, prev) -> 'None' | method |

```python
from components.extras.engine3d import UIContext
```

### UIRoot

Public ui class.

Import: `from components.extras.engine3d import UIRoot`

Signature: `UIRoot(engine, scale: 'float' = 1.0, auto: 'bool' = True)`

| Parameter | Type | Default |
| --- | --- | --- |
| engine | Value | Required |
| scale | 'float' | 1.0 |
| auto | 'bool' | True |

| Member | Kind |
| --- | --- |
| add(self, widget: 'Widget', anchor: 'str' = 'top-left', offset=(0.0, 0.0), size=None, modal: 'bool' = False) -> 'Widget' | method |
| remove(self, widget: 'Widget') -> 'None' | method |
| clear(self) -> 'None' | method |
| set_focus(self, widget: 'Optional[Widget]') -> 'None' | method |
| layout(self) -> 'None' | method |
| hit_test(self, x: 'float', y: 'float') -> 'Optional[Widget]' | method |
| frame(self, engine=None) -> 'None' | method |

```python
from components.extras.engine3d import UIRoot
```

### VBox

Public ui class.

Import: `from components.extras.engine3d import VBox`

Signature: `VBox(*children, **kw)`

| Parameter | Type | Default |
| --- | --- | --- |
| *children | Values | Optional |
| **kw | Values | Optional |

```python
from components.extras.engine3d import VBox
```

### Widget

Public ui class.

Import: `from components.extras.engine3d import Widget`

Signature: `Widget(width=None, height=None, flex: 'float' = 0.0, margin=0.0, min_width: 'float' = 0.0, min_height: 'float' = 0.0, visible: 'bool' = True, enabled: 'bool' = True, name: 'str' = '')`

| Parameter | Type | Default |
| --- | --- | --- |
| width | Value | None |
| height | Value | None |
| flex | 'float' | 0.0 |
| margin | Value | 0.0 |
| min_width | 'float' | 0.0 |
| min_height | 'float' | 0.0 |
| visible | 'bool' | True |
| enabled | 'bool' | True |
| name | 'str' | '' |

| Member | Kind |
| --- | --- |
| content_size(self, ctx: 'UIContext', avail_w: 'Optional[float]') -> 'Tuple[float, float]' | method |
| preferred(self, ctx: 'UIContext', avail_w: 'Optional[float]', avail_h: 'Optional[float]' = None) -> 'Tuple[float, float]' | method |
| arrange(self, ctx: 'UIContext', x: 'float', y: 'float', w: 'float', h: 'float') -> 'None' | method |
| layout_children(self, ctx: 'UIContext') -> 'None' | method |
| add(self, *widgets: "'Widget'") -> "'Widget'" | method |
| remove(self, widget: "'Widget'") -> 'None' | method |
| clear(self) -> 'None' | method |
| contains(self, x: 'float', y: 'float') -> 'bool' | method |
| hit(self, x: 'float', y: 'float') -> "Optional['Widget']" | method |
| update(self, ctx: 'UIContext', dt: 'float') -> 'None' | method |
| draw(self, ctx: 'UIContext') -> 'None' | method |
| on_press(self, ctx, p) -> 'None' | method |
| on_drag(self, ctx, p) -> 'None' | method |
| on_release(self, ctx, p, inside: 'bool') -> 'None' | method |
| on_cancel(self, ctx, p) -> 'None' | method |
| on_focus(self, ctx) -> 'None' | method |
| on_blur(self, ctx) -> 'None' | method |
| wants_drag(self, dx: 'float', dy: 'float') -> 'bool' | method |

```python
from components.extras.engine3d import Widget
```

## Scheduling, Data, Localization, and Utilities
### DATA_TYPES

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list.

Import: `from components.extras.engine3d import DATA_TYPES`

Type: `value`

```python
from components.extras.engine3d import DATA_TYPES
```

### DataAsset

Public utilities class.

Import: `from components.extras.engine3d import DataAsset`

Signature: `DataAsset(name: 'str' = '', **values)`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'str' | '' |
| **values | Values | Optional |

| Member | Kind |
| --- | --- |
| to_dict(self) -> 'dict' | method |
| from_dict(self, d: 'dict') -> 'None' | method |

```python
from components.extras.engine3d import DataAsset
```

### DataStore

Public utilities class.

Import: `from components.extras.engine3d import DataStore`

Signature: `DataStore(reader=None)`

| Parameter | Type | Default |
| --- | --- | --- |
| reader | Value | None |

| Member | Kind |
| --- | --- |
| create(self, type_name: 'str', name: 'str' = '', **values) -> 'DataAsset' | method |
| load(self, path: 'str') -> 'DataAsset' | method |
| get(self, name: 'str') -> 'Optional[DataAsset]' | method |
| dump(self, asset: 'DataAsset', extends: 'Optional[str]' = None) -> 'str' | method |
| reload(self, path: 'Optional[str]' = None) -> 'None' | method |

```python
from components.extras.engine3d import DataStore
```

### register_data_type

Public utilities function.

Import: `from components.extras.engine3d import register_data_type`

Signature: `register_data_type(cls: "Type['DataAsset']", name: 'Optional[str]' = None) -> "Type['DataAsset']"`

| Parameter | Type | Default |
| --- | --- | --- |
| name | 'Optional[str]' | None |

```python
from components.extras.engine3d import register_data_type
```

### Localization

Public utilities class.

Import: `from components.extras.engine3d import Localization`

Signature: `Localization(default: 'str' = 'en')`

| Parameter | Type | Default |
| --- | --- | --- |
| default | 'str' | 'en' |

| Member | Kind |
| --- | --- |
| add_strings(self, language: 'str', strings: 'Dict[str, str]') -> 'None' | method |
| load_text(self, text: 'str') -> 'None' | method |
| load(self, reader, path: 'str') -> 'None' | method |
| languages | property |
| set_language(self, language: 'str') -> 'bool' | method |
| has(self, key: 'str') -> 'bool' | method |
| tr(self, key: 'str', count=None, **values) -> 'str' | method |
| text(self, key: 'str', count=None, **values) -> 'LocalizedText' | method |

```python
from components.extras.engine3d import Localization
```

### LocalizedText

Public utilities class.

Import: `from components.extras.engine3d import LocalizedText`

Signature: `LocalizedText(loc: "'Localization'", key: 'str', count=None, **values)`

| Parameter | Type | Default |
| --- | --- | --- |
| loc | "'Localization'" | Required |
| key | 'str' | Required |
| count | Value | None |
| **values | Values | Optional |

```python
from components.extras.engine3d import LocalizedText
```

## 2D Overview

The 2D layer uses the same Scene, Node, Component, Camera, input, audio, and UI services as the rest of the engine. It adds packed sprites, animated sprites, chunked tilemaps, 2D physics, point and spot lights, hard-edged shadows, masks, and pixel-camera utilities. World positions and physics distances use world units. Sprite source sizes use pixels and convert through pixels per unit. UI coordinates use pixels from the top-left.

A typical scene creates `World2D.of(scene)` and `Physics2D.of(scene)`, sets named sorting layers, creates tilemap and actor nodes, then uses an orthographic Camera. `scene.create` returns a Node. Read components with `node.get_component(Type)`. Component `on_enable` and `start` hooks run during `scene.update(dt)`.

The rpg2d example sets up its services like this:

```python
sc = e.new_scene("RPG")
SortingLayers.set(["Ground", "Actors", "Fx"])
self.world = World2D.of(sc)
self.world.y_sort = True
self.physics = Physics2D.of(sc)
self.physics.gravity = (0.0, 0.0)
```

<a id="engine3d-api-world2d"></a>
### `World2D`

Collects 2D render items and lights for a scene, applies y-sorting and ambient lighting, and prepares visible lights and shadows.

Import from `components.extras.engine3d`.

```python
World2D()
```

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| items | set | set() | Registered SpriteRenderer and TilemapRenderer components. |
| lights | set | set() | Registered Light2D components. |
| casters | set | set() | Registered 2D shadow casters. |
| ambient | tuple[float, float, float] | (1.0, 1.0, 1.0) | Ambient RGB multiplier. |
| y_sort | bool | False | Sorts render items by their world y value. |
| focus | tuple[float, float] | (0.0, 0.0) | Point used when selecting the most relevant lights. |
| clock | float | 0.0 | Animated tile time in seconds. |
| cull_enabled | bool | True | Enables view-rectangle culling. |
| stats_quads | int | 0 | Quads collected for the last prepared view. |
| stats_draws | int | 0 | Draw groups for the last prepared view. |
| shadows_enabled | bool | True | Enables visibility-atlas shadows. |
| stats_shadow_polys | int | 0 | Shadow polygons produced for the prepared view. |

#### Public methods

- `World2D.of(scene) -> World2D`: Returns the scene service, creating its internal node when needed.
- `update(dt: float) -> None`: Advances animated tile time in seconds.
- `prepare_view(view, renderer) -> None`: Collects visible 2D items, selects lights, and prepares shadow data.

#### Notes

- A scene can select up to eight lit lights and up to eight shadowing lights.
- Component on_enable and start hooks run during scene.update(dt), not when scene.create returns.

#### rpg2d excerpt

```python
self.world = World2D.of(sc)
self.world.y_sort = True
```

## Sprites and Atlases

<a id="engine3d-api-sortinglayers"></a>
### `SortingLayers`

Maps sorting-layer names to stable numeric indices.

Import from `components.extras.engine3d`.

```python
SortingLayers
```

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| names | list[str] | ["Default"] | Current layer order. |

#### Public methods

- `SortingLayers.index(name) -> int`: Returns an integer unchanged, or returns and registers a named layer index.
- `SortingLayers.set(names: Sequence[str]) -> None`: Replaces the layer order. An empty sequence restores Default.

#### rpg2d excerpt

```python
SortingLayers.set(["Ground", "Actors", "Fx"])
```

<a id="engine3d-api-sprite"></a>
### `Sprite`

Describes a rectangular region on an AtlasPage.

Import from `components.extras.engine3d`.

```python
Sprite(name, page, x, y, w, h, ppu=100.0, pivot=(0.5, 0.5), border=None)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| name | str | Required | Sprite key. |
| page | AtlasPage | Required | Owning page. |
| x, y | number | Required | Region origin in pixels. |
| w, h | number | Required | Region size in pixels. |
| ppu | float | 100.0 | Pixels per world unit. |
| pivot | tuple[float, float] | (0.5, 0.5) | Normalized pivot. |
| border | tuple \| None | None | Left, bottom, right, and top 9-slice borders in pixels. |

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| name | str | constructor value | Sprite key. |
| uv | tuple[float, float, float, float] | computed | Texture coordinates. |
| size | tuple[float, float] | computed | World size, w / ppu by h / ppu. |
| extra | Any | None | Optional caller data. |

<a id="engine3d-api-atlaspage"></a>
### `AtlasPage`

Stores packed sprite pixels or wraps an existing texture.

Import from `components.extras.engine3d`.

```python
AtlasPage(size: int, texture: Optional[TextureAsset] = None, pixel: bool = True)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| size | int | Required | Square page size in pixels. |
| texture | TextureAsset \| None | None | Existing texture to wrap. |
| pixel | bool | True | Uses nearest sampling when true and linear sampling when false. |

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| w, h | int | size | Page dimensions in pixels. |
| pixel | bool | constructor value | Sampling mode. |
| texture | TextureAsset | lazy | Current page texture. |

#### Public methods

- `fit(w: int, h: int) -> Optional[tuple[int, int]]`: Reserves a padded region, or returns None when it does not fit.
- `blit(x: int, y: int, w: int, h: int, rgba) -> None`: Copies RGBA pixels and extends edge pixels into the packing border.
- `material(lit: bool = False, shader: Optional[str] = None, mask: int = 0) -> Material`: Returns a cached material for this page and state.

<a id="engine3d-api-spriteatlas"></a>
### `SpriteAtlas`

Packs generated images into pages and returns named Sprite records.

Import from `components.extras.engine3d`.

```python
SpriteAtlas(page_size: int = 1024, pixel: bool = True, ppu: float = 16.0)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| page_size | int | 1024 | Default square page size in pixels. |
| pixel | bool | True | Nearest sampling when true. |
| ppu | float | 16.0 | Default pixels per world unit. |

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| pages | list[AtlasPage] | [] | Allocated pages. |
| sprites | dict[str, Sprite] | {} | Sprites by name. |

#### Public methods

- `add(name: str, w: int, h: int, rgba, ppu: Optional[float] = None, pivot=(0.5, 0.5), border=None) -> Sprite`: Packs one RGBA image.
- `add_grid(name: str, w: int, h: int, rgba, cell_w: int, cell_h: int, ppu: Optional[float] = None, pivot=(0.5, 0.5)) -> list[Sprite]`: Slices a sheet into fixed cells named name_0, name_1, and so on.
- `wrap(name: str, texture: TextureAsset, w: int, h: int, rect=None, ppu: float = 100.0, pivot=(0.5, 0.5), border=None) -> Sprite`: Creates a sprite over an existing texture region.
- `get(name: str) -> Sprite`: Returns a named sprite.

#### rpg2d excerpt

```python
at = SpriteAtlas(512, True, 16.0)
S = {}
```

<a id="engine3d-api-spriterenderer"></a>
### `SpriteRenderer`

Renders a sprite as a simple, sliced, or tiled quad group.

Import from `components.extras.engine3d`.

```python
SpriteRenderer(sprite=None, color=(1, 1, 1, 1), flip_x=False, flip_y=False, sorting_layer="Default", order=0, draw_mode="simple", size=None, lit=False, material=None, sort_offset=0.0, mask_interaction="none")
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| sprite | Sprite \| None | None | Sprite to draw. |
| color | tuple | (1, 1, 1, 1) | RGBA multiplier. |
| flip_x, flip_y | bool | False | Mirror the sprite. |
| sorting_layer | str \| int | "Default" | Sorting layer. |
| order | int | 0 | Order within the layer. |
| draw_mode | str | "simple" | simple, sliced, or tiled. |
| size | tuple \| None | None | Requested world size for sliced or tiled drawing. |
| lit | bool | False | Uses the lit-sprite program. |
| material | Material \| None | None | Material override. |
| sort_offset | float | 0.0 | Offset added to the y-sort key. |
| mask_interaction | str | "none" | none, inside, or outside. |

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| sprite | Sprite \| None | constructor value | Current sprite. |
| color | tuple | constructor value | RGBA multiplier. |
| enabled | bool | True | Inherited component state. |

#### Public methods

- `bounds2d() -> tuple`: Returns world-space 2D bounds.
- `emit(pos: list[float], uv: list[float], col: list[float]) -> int`: Appends generated quad data and returns the quad count.
- `to_dict() -> dict`: Serializes public renderer state.

#### Notes

- Y-sorting is controlled by World2D.y_sort.
- Sliced drawing uses Sprite.border. Tiled drawing repeats the center region.

## Sprite Animation and Masks

<a id="engine3d-api-spriteanimation"></a>
### `SpriteAnimation`

Defines a named frame sequence.

Import from `components.extras.engine3d`.

```python
SpriteAnimation(name, frames, fps=8.0, loop=True)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| name | str | Required | Clip name. |
| frames | Sequence[Sprite] | Required | Animation frames. |
| fps | float | 8.0 | Frames per second. |
| loop | bool | True | Restarts at the end when true. |

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| events | dict[int, Any] | {} | Values dispatched when a frame index is entered. |

<a id="engine3d-api-spriteanimator"></a>
### `SpriteAnimator`

Updates the SpriteRenderer on the same node from named SpriteAnimation clips.

Import from `components.extras.engine3d`.

```python
SpriteAnimator()
```

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| clips | dict[str, SpriteAnimation] | {} | Registered clips. |
| current | SpriteAnimation \| None | None | Active clip. |
| speed | float | 1.0 | Playback multiplier. |
| playing | bool | True | Playback state. |
| on_end | Callable \| None | None | Called when a non-looping clip finishes. |
| on_event | Callable \| None | None | Called with an event value when its frame is entered. |

#### Public methods

- `add(clip: SpriteAnimation) -> SpriteAnimator`: Registers a clip and returns the animator.
- `play(name: str, restart: bool = False) -> None`: Starts a named clip. The current clip continues unless restart is true.
- `finished -> bool`: Reports completion of a non-looping clip.
- `update(dt: float) -> None`: Advances playback by seconds.

#### rpg2d excerpt

```python
an.add(SpriteAnimation("idle_" + d, [fr[0]], 1.0))
an.add(SpriteAnimation("walk_" + d, [fr[1], fr[0], fr[2], fr[0]], 9.0))
```

<a id="engine3d-api-spritemask"></a>
### `SpriteMask`

Writes a sprite shape into stencil without writing color.

Import from `components.extras.engine3d`.

```python
SpriteMask(sprite=None, **kw)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| sprite | Sprite \| None | None | Mask shape. |
| **kw | SpriteRenderer options | Optional | Forwarded renderer options. |

#### Notes

- SpriteRenderer mask_interaction="inside" draws where the mask equals 1. "outside" draws where it does not equal 1.

## Tilemaps and Pixel Cameras

<a id="engine3d-api-tile"></a>
### `Tile`

Defines visual, animation, collision, and shadow data for a tile cell.

Import from `components.extras.engine3d`.

```python
Tile(sprite=None, color=(1, 1, 1, 1), collider="none", frames=None, fps=8.0, name="", rule=None, shadow=None)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| sprite | Sprite \| None | None | Static frame. |
| color | tuple | (1, 1, 1, 1) | RGBA multiplier. |
| collider | str | "none" | Any value other than none marks the tile solid. |
| frames | Sequence[Sprite] \| None | None | Animated frames. |
| fps | float | 8.0 | Animation frames per second. |
| name | str | "" | Tile name. |
| rule | Callable \| None | None | Optional neighboring-cell rule. |
| shadow | bool \| None | None | Overrides whether the tile contributes shadow edges. |

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| flip_x, flip_y | bool | False | Per-tile mirroring. |

#### rpg2d excerpt

```python
Tile(frames=[S["water0"], S["water1"]], fps=2.0, collider="solid", name="water")
```

<a id="engine3d-api-tilemap"></a>
### `Tilemap`

Stores sparse tile cells in local coordinates and tracks dirty 16 by 16 chunks.

Import from `components.extras.engine3d`.

```python
Tilemap(cell_size=(1.0, 1.0))
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| cell_size | tuple[float, float] | (1.0, 1.0) | Cell width and height in world units. |

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| CHUNK | int | 16 | Cells per render chunk side. |
| cells | dict[tuple[int, int], Tile] | {} | Sparse cell table. |
| version | int | 0 | Increments when tiles change. |
| dirty_chunks | set[tuple[int, int]] | {} | Chunk coordinates that need rebuilding. |

#### Public methods

- `set_tile(x: int, y: int, tile: Optional[Tile]) -> None`: Sets or removes a cell and marks its chunk and neighboring chunks dirty.
- `get_tile(x: int, y: int) -> Optional[Tile]`: Returns a cell.
- `fill(x0: int, y0: int, x1: int, y1: int, tile: Tile) -> None`: Fills the half-open cell rectangle.
- `clear() -> None`: Removes every cell.
- `world_to_cell(x: float, y: float) -> tuple[int, int]`: Transforms a world point to local space, divides by cell size, and floors it.
- `cell_to_world(cx: int, cy: int, center: bool = True) -> tuple[float, float]`: Transforms the cell center or lower corner to world coordinates.
- `used_bounds() -> tuple[int, int, int, int]`: Returns half-open occupied cell bounds, or zeros when empty.
- `solid_cells() -> list[tuple[int, int]]`: Returns cells whose collider is not none.

<a id="engine3d-api-tilemaprenderer"></a>
### `TilemapRenderer`

Builds and submits visible tilemap chunks.

Import from `components.extras.engine3d`.

```python
TilemapRenderer(sorting_layer="Default", order=0, lit=False, color=(1, 1, 1, 1))
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| sorting_layer | str \| int | "Default" | Sorting layer. |
| order | int | 0 | Order within the layer. |
| lit | bool | False | Uses 2D lighting. |
| color | tuple | (1, 1, 1, 1) | RGBA multiplier. |

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| sorting_layer | str \| int | "Default" | Sorting layer. |
| order | int | 0 | Order within the layer. |
| lit | bool | False | Uses the lit-sprite program. |
| color | tuple | (1.0, 1.0, 1.0, 1.0) | RGBA multiplier. |
| visible | bool | True | Controls collection. |

#### Public methods

- `collect(t: float, view_rect=None)`: Rebuilds dirty chunks and returns visible chunk records at animation time t.

#### rpg2d excerpt

```python
node = self.scene.create(name, None, (ox, 0, 0), Tilemap(), TilemapRenderer("Ground", 0, True), TilemapCollider2D())
```

<a id="engine3d-api-ortho-for-pixels"></a>
### `ortho_for_pixels`

Returns the orthographic half-height that maps source pixels to an integer display scale.

Import from `components.extras.engine3d.sprites2d`.

```python
ortho_for_pixels(height_px: float, ppu: float = 16.0, scale: int = 3) -> float
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| height_px | float | Required | Viewport height in pixels. |
| ppu | float | 16.0 | Source pixels per world unit. |
| scale | int | 3 | Integer scale factor. |

<a id="engine3d-api-snap-to-pixel"></a>
### `snap_to_pixel`

Rounds a world coordinate to the nearest source-pixel step.

Import from `components.extras.engine3d.sprites2d`.

```python
snap_to_pixel(v: float, ppu: float = 16.0) -> float
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| v | float | Required | World coordinate. |
| ppu | float | 16.0 | Pixels per world unit. |

## 2D Physics

<a id="engine3d-api-hit2d"></a>
### `Hit2D`

Stores one ray or shape-cast hit.

Import from `components.extras.engine3d`.

```python
Hit2D(node, collider, point, normal, distance, fraction=0.0)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| node | Node | Required | Hit node. |
| collider | Collider2D | Required | Hit collider. |
| point | tuple[float, float] | Required | World-space hit point. |
| normal | tuple[float, float] | Required | Surface normal. |
| distance | float | Required | Travel distance in world units. |
| fraction | float | 0.0 | Distance divided by requested cast distance. |

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| node | Node | constructor value | Hit node. |
| collider | Collider2D | constructor value | Hit collider. |
| point | tuple[float, float] | constructor value | Hit point in world units. |
| normal | tuple[float, float] | constructor value | Surface normal. |
| distance | float | constructor value | Travel distance in world units. |
| fraction | float | 0.0 | Distance divided by requested cast distance. |

<a id="engine3d-api-shape"></a>
### `Shape`

Low-level world-space 2D shape record used by colliders and queries.

Import from `components.extras.engine3d.physics2d`.

```python
Shape(kind: str, pts: list[tuple[float, float]], r: float = 0.0)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| kind | str | Required | circle, capsule, or poly. |
| pts | list[tuple] | Required | Shape points in world units. |
| r | float | 0.0 | Radius for circle and capsule shapes. |

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| box | tuple[float, float, float, float] | computed | Axis-aligned bounds. |

#### Public methods

- `shifted(dx: float, dy: float) -> Shape`: Returns a translated copy.

<a id="engine3d-api-circle-shape"></a>
### `circle_shape`

Creates a circle Shape in world units.

Import from `components.extras.engine3d.physics2d`.

```python
circle_shape(cx, cy, r) -> Shape
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| cx, cy | float | Required | World-space center. |
| r | float | Required | Radius in world units. |

<a id="engine3d-api-poly-shape"></a>
### `poly_shape`

Creates a counterclockwise polygon Shape.

Import from `components.extras.engine3d.physics2d`.

```python
poly_shape(pts: Sequence[tuple[float, float]]) -> Shape
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| pts | Sequence[tuple[float, float]] | Required | World-space polygon points. |

<a id="engine3d-api-box-shape"></a>
### `box_shape`

Creates a rotated box Shape. The angle is in degrees.

Import from `components.extras.engine3d.physics2d`.

```python
box_shape(cx, cy, w, h, angle_deg: float = 0.0) -> Shape
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| cx, cy | float | Required | World-space center. |
| w, h | float | Required | Width and height in world units. |
| angle_deg | float | 0.0 | Rotation in degrees. |

<a id="engine3d-api-collide"></a>
### `collide`

Returns collision normal, penetration, and contact point, or None.

Import from `components.extras.engine3d.physics2d`.

```python
collide(a: Shape, b: Shape)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| a | Shape | Required | First world-space shape. |
| b | Shape | Required | Second world-space shape. |

<a id="engine3d-api-ray-shape"></a>
### `ray_shape`

Returns the nearest ray distance and normal for a Shape, or None.

Import from `components.extras.engine3d.physics2d`.

```python
ray_shape(ox, oy, dx, dy, sh: Shape, maxd: float)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| ox, oy | float | Required | Ray origin in world units. |
| dx, dy | float | Required | Ray direction. |
| sh | Shape | Required | Shape to test. |
| maxd | float | Required | Maximum distance in world units. |

<a id="engine3d-api-shape-contains"></a>
### `shape_contains`

Tests a world-space point against a Shape.

Import from `components.extras.engine3d.physics2d`.

```python
shape_contains(sh: Shape, x: float, y: float) -> bool
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| sh | Shape | Required | Shape to test. |
| x, y | float | Required | World-space point. |

<a id="engine3d-api-collider2d"></a>
### `Collider2D`

Base component for 2D collision shapes.

Import from `components.extras.engine3d`.

```python
Collider2D(is_trigger=False, offset=(0.0, 0.0), friction=0.4, bounciness=0.0, one_way=False)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| is_trigger | bool | False | Reports overlap callbacks without collision response. |
| offset | tuple[float, float] | (0.0, 0.0) | Local shape offset in world units. |
| friction | float | 0.4 | Contact friction. |
| bounciness | float | 0.0 | Restitution. |
| one_way | bool | False | Allows contact only from the supported side. |

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| body | Rigidbody2D \| None | resolved | Nearest Rigidbody2D on the node or parent chain. |
| shapes | list[Shape] | computed | Current world-space shapes. |

#### Public methods

- `invalidate() -> None`: Clears cached shapes after geometry changes.

<a id="engine3d-api-boxcollider2d"></a>
### `BoxCollider2D`

Creates a rectangular collider.

Import from `components.extras.engine3d`.

```python
BoxCollider2D(size=(1.0, 1.0), **kw)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| size | tuple[float, float] | (1.0, 1.0) | Width and height in world units. |
| **kw | Collider2D options | Optional | Base collider options. |

<a id="engine3d-api-circlecollider2d"></a>
### `CircleCollider2D`

Creates a circular collider.

Import from `components.extras.engine3d`.

```python
CircleCollider2D(radius=0.5, **kw)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| radius | float | 0.5 | Local radius in world units. |
| **kw | Collider2D options | Optional | Base collider options. |

<a id="engine3d-api-capsulecollider2d"></a>
### `CapsuleCollider2D`

Creates a vertical or horizontal capsule.

Import from `components.extras.engine3d`.

```python
CapsuleCollider2D(size=(0.5, 1.0), direction="vertical", **kw)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| size | tuple[float, float] | (0.5, 1.0) | Local width and height. |
| direction | str | "vertical" | vertical or horizontal. |
| **kw | Collider2D options | Optional | Base collider options. |

<a id="engine3d-api-polygoncollider2d"></a>
### `PolygonCollider2D`

Creates a polygon collider.

Import from `components.extras.engine3d`.

```python
PolygonCollider2D(points=((-0.5, -0.5), (0.5, -0.5), (0.0, 0.5)), **kw)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| points | Sequence[tuple] | triangle | Local polygon points. |
| **kw | Collider2D options | Optional | Base collider options. |

<a id="engine3d-api-edgecollider2d"></a>
### `EdgeCollider2D`

Creates separate line-segment shapes between consecutive points.

Import from `components.extras.engine3d`.

```python
EdgeCollider2D(points=((-0.5, 0.0), (0.5, 0.0)), **kw)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| points | Sequence[tuple] | two points | Local line points. |
| **kw | Collider2D options | Optional | Base collider options. |

<a id="engine3d-api-tilemapcollider2d"></a>
### `TilemapCollider2D`

Merges consecutive solid cells in each row into box shapes.

Import from `components.extras.engine3d`.

```python
TilemapCollider2D(**kw)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| **kw | Collider2D options | Optional | Base collider options. |

<a id="engine3d-api-rigidbody2d"></a>
### `Rigidbody2D`

Moves a node through Physics2D and receives collision response.

Import from `components.extras.engine3d`.

```python
Rigidbody2D(body_type="dynamic", mass=1.0, gravity_scale=1.0, linear_drag=0.0, angular_drag=0.05, freeze_rotation=False, freeze_x=False, freeze_y=False, simulated=True)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| body_type | str | "dynamic" | dynamic, kinematic, or static behavior. |
| mass | float | 1.0 | Mass used by forces and impulses. |
| gravity_scale | float | 1.0 | Gravity multiplier. |
| linear_drag | float | 0.0 | Linear damping. |
| angular_drag | float | 0.05 | Angular damping. |
| freeze_rotation | bool | False | Prevents rotation updates. |
| freeze_x, freeze_y | bool | False | Locks a position axis. |
| simulated | bool | True | Includes the body in simulation. |

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| velocity | tuple[float, float] | (0.0, 0.0) | World units per second. |
| angular_velocity | float | 0.0 | Radians per second. |
| contacts | list | [] | Current collider and normal pairs. |
| grounded | bool | computed | True when a contact normal has y greater than 0.6. |
| inv_mass | float | computed | Zero for non-dynamic or non-positive mass. |

#### Public methods

- `add_force(f: tuple[float, float]) -> None`: Accumulates force for the next step.
- `add_impulse(j: tuple[float, float]) -> None`: Changes velocity immediately by impulse times inverse mass.
- `move_position(x: float, y: float) -> None`: Sets world x and y while preserving z.

<a id="engine3d-api-collision2d"></a>
### `Collision2D`

Carries detailed data to the optional suffixed 2D callback.

Import from `components.extras.engine3d.physics2d`.

```python
Collision2D(collider, other, normal, point, rv)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| collider | Collider2D | Required | Receiver collider. |
| other | Collider2D | Required | Other collider. |
| normal | tuple[float, float] | Required | Contact normal. |
| point | tuple[float, float] | Required | Contact point. |
| rv | tuple[float, float] | Required | Relative velocity record. |

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| collider | Collider2D | constructor value | Receiver collider. |
| other_collider | Collider2D | constructor value | Other collider. |
| node | Node | other.node | Other node. |
| normal | tuple | constructor value | Contact normal. |
| point | tuple | constructor value | Contact point. |
| relative_velocity | tuple | constructor value | Relative velocity record. |

#### Notes

- The base callbacks are on_collision_enter(other), on_collision_stay(other), on_collision_exit(other), on_trigger_enter(other), and on_trigger_exit(other).
- When a component implements a base callback and the matching suffixed callback, on_collision_enter_2d(collision), on_collision_stay_2d(collision), on_collision_exit_2d(collision), on_trigger_enter_2d(collision), or on_trigger_exit_2d(collision) receives Collision2D. Trigger stay is not emitted.

<a id="engine3d-api-physics2d"></a>
### `Physics2D`

Owns 2D bodies, colliders, stepping, layers, contacts, queries, and casts.

Import from `components.extras.engine3d`.

```python
Physics2D()
```

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| gravity | tuple[float, float] | (0.0, -9.81) | World units per second squared. |
| iterations | int | 4 | Contact solver passes. |
| auto_step | bool | True | Runs from fixed_update when true. |
| stats_pairs | int | 0 | Candidate pairs from the last step. |

#### Public methods

- `Physics2D.of(scene) -> Physics2D`: Returns the scene service, creating it when needed.
- `set_layer_collision(a: int, b: int, enabled: bool) -> None`: Enables or disables a layer pair.
- `can_collide(a: Collider2D, b: Collider2D) -> bool`: Checks the layer matrix.
- `fixed_update(dt: float) -> None`: Calls step when auto_step is true.
- `step(dt: float) -> None`: Advances bodies, contacts, and callbacks by seconds.
- `raycast_all(origin, direction, distance=1e9, mask=-1, include_triggers=False, ignore=None) -> list[Hit2D]`: Returns sorted hits.
- `raycast(origin, direction, distance=1e9, mask=-1, include_triggers=False, ignore=None) -> Optional[Hit2D]`: Returns the nearest hit.
- `overlap_point(p, mask=-1, include_triggers=True) -> list[Collider2D]`: Returns colliders containing a point.
- `overlap_circle(center, radius, mask=-1, include_triggers=True) -> list[Collider2D]`: Returns colliders overlapping a circle.
- `overlap_box(center, size, angle=0.0, mask=-1, include_triggers=True) -> list[Collider2D]`: Returns colliders overlapping a degree-rotated box.
- `overlap_area(a, b, mask=-1, include_triggers=True) -> list[Collider2D]`: Returns colliders in an axis-aligned area.
- `overlap_collider(col, mask=-1, include_triggers=True) -> list[Collider2D]`: Returns colliders overlapping col.
- `circle_cast(origin, radius, direction, distance, mask=-1, include_triggers=False) -> Optional[Hit2D]`: Sweeps a circle.
- `box_cast(origin, size, angle, direction, distance, mask=-1, include_triggers=False) -> Optional[Hit2D]`: Sweeps a box.
- `collider_cast(col, direction, distance, mask=-1, include_triggers=False) -> Optional[Hit2D]`: Sweeps a collider.

#### rpg2d excerpt

```python
self.physics = Physics2D.of(sc)
self.physics.gravity = (0.0, 0.0)
```

## 2D Lights and Shadows

<a id="engine3d-api-light2d"></a>
### `Light2D`

Adds a point or spot light to World2D.

Import from `components.extras.engine3d`.

```python
Light2D(kind="point", color=(1, 1, 1), intensity=1.0, outer_radius=5.0, inner_ratio=0.0, falloff=1.0, angle=90.0, inner_angle=30.0, shadows=False, shadow_strength=1.0)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| kind | str | "point" | point or spot. |
| color | color | (1, 1, 1) | Light RGB. |
| intensity | float | 1.0 | Brightness multiplier. |
| outer_radius | float | 5.0 | Range in world units. |
| inner_ratio | float | 0.0 | Fraction of range before radial fade. |
| falloff | float | 1.0 | Attenuation exponent. |
| angle | float | 90.0 | Spot outer cone angle in degrees. |
| inner_angle | float | 30.0 | Spot inner cone angle in degrees. |
| shadows | bool | False | Enables caster occlusion. |
| shadow_strength | float | 1.0 | Mix between unshadowed and visibility-atlas result. |

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| kind | str | "point" | point or spot. |
| color | tuple | (1.0, 1.0, 1.0) | Light RGB. |
| intensity | float | 1.0 | Brightness multiplier. |
| outer_radius | float | 5.0 | Range in world units. |
| inner_ratio | float | 0.0 | Radial fade start ratio. |
| falloff | float | 1.0 | Attenuation exponent. |
| angle | float | 90.0 | Spot outer angle in degrees. |
| inner_angle | float | 30.0 | Spot inner angle in degrees. |
| shadows | bool | False | Caster occlusion state. |
| shadow_strength | float | 1.0 | Shadow mix. |

#### rpg2d excerpt

```python
Light2D("point", (1.0, 0.65, 0.3), 1.3, 5.5, 0.15, 1.2, shadows=True, shadow_strength=0.9)
```

<a id="engine3d-api-shadowcaster2d"></a>
### `ShadowCaster2D`

Supplies transformed shape edges to 2D shadows.

Import from `components.extras.engine3d`.

```python
ShadowCaster2D(points=((-0.5, -0.5), (0.5, -0.5), (0.5, 0.5), (-0.5, 0.5)), closed=True, two_sided=False)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| points | Sequence[tuple] | unit square | Local caster points. |
| closed | bool | True | Adds the final edge back to the first point. |
| two_sided | bool | False | Makes both edge directions available. |

#### Public methods

- `version_key()`: Returns a transform and shape key used for cached shadow geometry.
- `edges() -> list[tuple]`: Returns world-space edge endpoints.
- `contains(x: float, y: float) -> bool`: Tests a world point against a closed caster.

<a id="engine3d-api-tilemapshadowcaster2d"></a>
### `TilemapShadowCaster2D`

Builds merged exposed edges from shadow-casting tile cells.

Import from `components.extras.engine3d`.

```python
TilemapShadowCaster2D()
```

#### Public methods

- `version_key()`: Returns the tilemap version and transform key.
- `edges() -> list[tuple]`: Returns merged world-space horizontal and vertical boundary edges.
- `contains(x: float, y: float) -> bool`: Tests whether a point is inside a shadow-casting cell.

#### Notes

- Tile.shadow overrides the default rule. Otherwise a tile casts when its collider is not none.
- Put shadowing lights on open floor rather than inside a solid cell.

#### rpg2d excerpt

```python
node.add_component(TilemapShadowCaster2D())
```

## 2D Materials and Rendering

<a id="engine3d-api-new-sprite-material"></a>
### `new_sprite_material`

Creates the transparent 2D material state used by sprites and masks.

Import from `components.extras.engine3d.sprites2d`.

```python
new_sprite_material(tex: Optional[TextureAsset], lit: bool = False, shader: Optional[str] = None, mask: int = 0) -> Material
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| tex | TextureAsset \| None | Required | Base texture. |
| lit | bool | False | Selects c3d/sprite2d_lit instead of c3d/sprite2d. |
| shader | str \| None | None | Program override. |
| mask | int | 0 | MASK_NONE, MASK_WRITE, MASK_INSIDE, or MASK_OUTSIDE. |

#### Notes

- The result uses alpha blending, disables depth test and depth write, disables culling, uses the transparent queue, and does not cast or receive 3D shadows.

<a id="engine3d-api-sprite-programs"></a>
### `Sprite programs`

Public program names used by new_sprite_material.

Import from `components.extras.engine3d.programs`.

```python
c3d/sprite2d and c3d/sprite2d_lit
```

#### Notes

- The lit program applies World2D ambient light, radial attenuation, spot cones, and up to eight selected lights.
- When shadows are enabled, lit sprites sample the selected light visibility tiles.

<a id="engine3d-api-mask-constants"></a>
### `Mask constants`

Selects normal drawing, stencil writing, inside testing, or outside testing.

Import from `components.extras.engine3d.sprites2d`.

```python
MASK_NONE = 0; MASK_WRITE = 1; MASK_INSIDE = 2; MASK_OUTSIDE = 3
```

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| MASK_NONE | int | 0 | No stencil state. |
| MASK_WRITE | int | 1 | Writes stencil value 1 with color writes disabled. |
| MASK_INSIDE | int | 2 | Draws where stencil equals 1. |
| MASK_OUTSIDE | int | 3 | Draws where stencil does not equal 1. |

<a id="engine3d-api-stencil"></a>
### `Stencil`

Describes stencil comparison and operations used by SpriteMask.

Import from `components.extras.gfx`.

```python
Stencil(func=DepthFunc.ALWAYS, ref=0, read_mask=0xFF, write_mask=0xFF, fail=StencilOp.KEEP, zfail=StencilOp.KEEP, zpass=StencilOp.KEEP)
```

#### Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| func | DepthFunc | DepthFunc.ALWAYS | Stencil comparison. |
| ref | int | 0 | Reference value. |
| read_mask | int | 0xFF | Read bit mask. |
| write_mask | int | 0xFF | Write bit mask. |
| fail | StencilOp | StencilOp.KEEP | Operation when stencil fails. |
| zfail | StencilOp | StencilOp.KEEP | Operation when depth fails. |
| zpass | StencilOp | StencilOp.KEEP | Operation when both tests pass. |

#### Public methods

- `Stencil.write(ref=1) -> Stencil`: Creates state that replaces the stencil value after a passing fragment.
- `Stencil.test(ref=1, func=DepthFunc.EQUAL) -> Stencil`: Creates read-only stencil test state.
- `pack() -> bytes`: Packs the state for graphics commands.

<a id="engine3d-api-stencilop"></a>
### `StencilOp`

Stencil operation constants used by Stencil.

Import from `components.extras.gfx`.

```python
StencilOp
```

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| KEEP | int | 0 | Keeps the current value. |
| ZERO | int | 1 | Writes zero. |
| REPLACE | int | 2 | Writes the reference value. |
| INCR | int | 3 | Increments with clamping. |
| INCR_WRAP | int | 4 | Increments with wrapping. |
| DECR | int | 5 | Decrements with clamping. |
| DECR_WRAP | int | 6 | Decrements with wrapping. |
| INVERT | int | 7 | Inverts bits. |

## 2D Utilities

<a id="engine3d-api-max-lights"></a>
### `MAX_LIGHTS`

Maximum number of selected lit lights and shadowing lights prepared for one 2D view.

Import from `components.extras.engine3d.sprites2d`.

```python
MAX_LIGHTS = 8
```

#### Public attributes and properties

| Name | Type | Default | Meaning |
|---|---|---|---|
| MAX_LIGHTS | int | 8 | 2D light selection limit. |