extension

Public extension API for Tiramisu.

External libraries register extensions at startup via tiramisu.register([my_library.extension()]).

Attribute hooks into the lifecycle of any tiramisu-managed node. Node handles a custom HTML element tag with full lifecycle.

Most users do not need this module. It exists for extension authors that want to define custom nodes or cross-cutting attribute behaviour.

Types

AttributeChange

</>

The semantic change recorded for one attribute between two reconciliations.

pub type AttributeChange {
  Added(String)
  Removed
  Updated(String)
}

Constructors

```
Added(String)
```
```
Removed
```
```
Updated(String)
```

AttributeChanges

</>

Semantic attribute changes for one node update.

pub type AttributeChanges =
  dict.Dict(String, AttributeChange)

Extension

opaque </>

A compiled extension definition.

Extensions are either custom nodes or cross-cutting attribute handlers.

pub opaque type Extension

Msg

</>

Messages understood by the renderer’s extension runtime.

Extension authors usually interact with this type indirectly through request/3 and runtime actions instead of constructing messages manually.

pub type Msg {
  NotifyResolved(String, String, savoiardi.Object3D)
  Spawn(
    owner: RequestOwner,
    key: RequestKey,
    task: promise.Promise(List(RuntimeAction)),
  )
}

Constructors

NotifyResolved(String, String, savoiardi.Object3D)

Spawn(
  owner: RequestOwner,
  key: RequestKey,
  task: promise.Promise(List(RuntimeAction)),
)

RequestKey

opaque </>

pub opaque type RequestKey

RequestOwner

</>

Identifies which part of the scene owns an async request.

Tiramisu uses this to decide whether async results should still be applied after later reconciliations.

pub type RequestOwner {
  SceneOwner
  NodeOwner(String)
  CustomOwner(String)
}

Constructors

```
SceneOwner
```
```
NodeOwner(String)
```
```
CustomOwner(String)
```

RuntimeAction

opaque </>

A deferred runtime mutation produced by an extension.

Runtime actions are returned from async work such as model or texture loading, then applied later by the renderer once the owning node still exists and the request is still current.

pub opaque type RuntimeAction

Values

action

</>

pub fn action(
  run: fn(runtime.Runtime) -> #(
    runtime.Runtime,
    effect.Effect(Msg),
  ),
) -> RuntimeAction

Wrap a runtime mutation as a RuntimeAction.

attribute_extension

</>

pub fn attribute_extension(
  observed_attributes observed_attributes: List(String),
  on_create on_create: fn(
    runtime.Runtime,
    String,
    String,
    option.Option(savoiardi.Object3D),
    dict.Dict(String, String),
  ) -> effect.Effect(Msg),
  on_update on_update: fn(
    runtime.Runtime,
    String,
    String,
    option.Option(savoiardi.Object3D),
    dict.Dict(String, String),
    dict.Dict(String, AttributeChange),
  ) -> effect.Effect(Msg),
  on_remove on_remove: fn(
    runtime.Runtime,
    String,
    String,
    savoiardi.Object3D,
  ) -> effect.Effect(Msg),
  on_resolved on_resolved: fn(
    runtime.Runtime,
    String,
    String,
    savoiardi.Object3D,
    dict.Dict(String, String),
  ) -> effect.Effect(Msg),
) -> Extension

Construct a cross-cutting attribute extension.

Attribute extensions observe attributes across existing node types and react when matching attributes are created, updated, removed, or resolved.

bool_change

</>

pub fn bool_change(
  changes: dict.Dict(String, AttributeChange),
  key: String,
) -> Result(Bool, Nil)

Interpret an attribute change as a boolean toggle.

Removed attributes become False, while added or updated attributes become True.

change

</>

pub fn change(
  changes: dict.Dict(String, AttributeChange),
  key: String,
) -> Result(AttributeChange, Nil)

Get the semantic change for a specific attribute.

get

</>

pub fn get(
  attributes attributes: dict.Dict(String, String),
  key key: String,
  default default: a,
  parse_fn parse_fn: fn(String) -> Result(a, Nil),
) -> a

Read and parse an attribute, falling back to a default value on failure.

get_bool

</>

pub fn get_bool(
  attributes: dict.Dict(String, String),
  key: String,
) -> Bool

Check whether a boolean-style attribute is currently present.

This is useful for attributes encoded using HTML presence semantics such as hidden, active, or cast-shadow.

has_any_change

</>

pub fn has_any_change(
  changes: dict.Dict(String, AttributeChange),
  keys: List(String),
) -> Bool

Check whether any of the given attributes changed.

has_change

</>

pub fn has_change(
  changes: dict.Dict(String, AttributeChange),
  key: String,
) -> Bool

Check whether a given attribute changed in any way.

node_extension

</>

pub fn node_extension(
  tag tag: String,
  observed_attributes observed_attributes: List(String),
  create create: fn(
    runtime.Runtime,
    String,
    String,
    dict.Dict(String, String),
  ) -> #(runtime.Runtime, effect.Effect(Msg)),
  update update: fn(
    runtime.Runtime,
    String,
    String,
    option.Option(savoiardi.Object3D),
    dict.Dict(String, String),
    dict.Dict(String, AttributeChange),
  ) -> #(runtime.Runtime, effect.Effect(Msg)),
  remove remove: fn(
    runtime.Runtime,
    String,
    String,
    savoiardi.Object3D,
  ) -> #(runtime.Runtime, effect.Effect(Msg)),
) -> Extension

Construct a custom node extension.

Use node extensions when you want to introduce a new scene element tag with full create, update, and remove lifecycle hooks.

parse_number

</>

pub fn parse_number(number: String) -> Result(Float, Nil)

Parse a number attribute as either a float literal or an integer literal.

register_object

</>

pub fn register_object(
  id: String,
  parent_id: String,
  tag: String,
  object: savoiardi.Object3D,
) -> RuntimeAction

Extension authors typically return this from async loaders once an object is ready to be inserted into the scene graph.

remove_object

</>

pub fn remove_object(
  id: String,
  parent_id: String,
  object: savoiardi.Object3D,
) -> RuntimeAction

Remove an object from the runtime.

replace_object

</>

pub fn replace_object(
  id: String,
  object: savoiardi.Object3D,
) -> RuntimeAction

Replace an existing runtime object and emit NotifyResolved for the new one.

request

</>

pub fn request(
  owner: RequestOwner,
  key: RequestKey,
  task: promise.Promise(List(RuntimeAction)),
) -> effect.Effect(Msg)

Schedule async work that will eventually yield runtime actions.

The owner and key pair lets Tiramisu drop stale results after later reconciliations or attribute changes.

request_key

</>

pub fn request_key(value: String) -> RequestKey

Construct a logical key for an async request.

Owners can have multiple independent in-flight requests as long as they use different keys.

request_key_to_string

</>

pub fn request_key_to_string(key: RequestKey) -> String

Convert a request key back into its raw string representation.

set_background_cube_texture

</>

pub fn set_background_cube_texture(
  texture: savoiardi.CubeTexture,
) -> RuntimeAction

Set the scene background to a cube texture.

set_background_texture

</>

pub fn set_background_texture(
  texture: savoiardi.Texture,
) -> RuntimeAction

Set the scene background to a 2D texture.

was_removed

</>

pub fn was_removed(
  changes: dict.Dict(String, AttributeChange),
  key: String,
) -> Bool

Check whether an attribute was removed.