# dotLottie C API Reference
Complete reference for the dotLottie native C API - player lifecycle, loading, playback, render targets, theming, slots, events, and state machines.

Every declaration here comes from the generated `dotlottie_player.h`. Functions are grouped by area, with the build feature noted wherever one is required.

Two naming rules apply throughout. Function names are unprefixed beyond `dotlottie_`; type names carry a `dotlottie` prefix, so the Rust `DotLottieResult` becomes `dotlottieDotLottieResult`. The header also defines the aliases `DotLottiePlayer` and `DOTLOTTIE_SUCCESS` for the two you use most.

<Callout type="warning" title="Enum constants are emitted without a prefix">
  Values such as `Success`, `Error`, `None`, `Loop`, `Stop`, `Play`, `Frame`, `Idle`, and `Surface` enter the global
  namespace unqualified. Watch for collisions with your own macros, and ignore the prefixed spellings that appear in a
  few of the header's doc comments — identifiers like `DotLottiePlayerEventType_Load` do not exist.
</Callout>

## Types

### dotlottieDotLottieResult

The return type of every fallible function. `DOTLOTTIE_SUCCESS` is defined as `0`.

| Constant                | Value | Meaning                                             |
| ----------------------- | ----- | --------------------------------------------------- |
| `Success`               | 0     | The call succeeded                                  |
| `Error`                 | 1     | A general failure                                   |
| `InvalidParameter`      | 2     | Null or out-of-range argument, or an invalid handle |
| `ManifestNotAvailable`  | 3     | The loaded file has no manifest                     |
| `AnimationNotLoaded`    | 4     | The call requires a loaded animation                |
| `InsufficientCondition` | 5     | The player is not in a valid state for the call     |
| `FeatureNotEnabled`     | 6     | The library was built without the required feature  |

### dotlottieStatus

| Constant   | Value | Meaning                          |
| ---------- | ----- | -------------------------------- |
| `Idle`     | 0     | Created, nothing loaded          |
| `Playing`  | 1     | Advancing on each tick           |
| `Paused`   | 2     | Holding the current frame        |
| `Stopped`  | 3     | Reset to the start               |
| `Tweening` | 4     | Interpolating between two frames |

### dotlottieMode

| Constant        | Value | Playback direction           |
| --------------- | ----- | ---------------------------- |
| `Forward`       | 0     | Start to end                 |
| `Reverse`       | 1     | End to start                 |
| `Bounce`        | 2     | Forward then back, repeating |
| `ReverseBounce` | 3     | Back then forward, repeating |

### dotlottieFit

| Constant    | Value | Behavior                                                |
| ----------- | ----- | ------------------------------------------------------- |
| `Contain`   | 0     | Fit entirely inside the target, preserving aspect ratio |
| `Fill`      | 1     | Stretch to the target, ignoring aspect ratio            |
| `Cover`     | 2     | Fill the target, preserving aspect ratio and cropping   |
| `FitWidth`  | 3     | Match the target width                                  |
| `FitHeight` | 4     | Match the target height                                 |
| `None`      | 5     | Draw at intrinsic size, unscaled                        |

### dotlottieLayout

```c
typedef struct dotlottieLayout {
  dotlottieFit fit;
  float align[2];
} dotlottieLayout;
```

`align[0]` is horizontal and `align[1]` vertical, each from `0.0` to `1.0`. The default is `Contain` with `{0.5, 0.5}`.

### dotlottieColorSpace

How eight-bit channels pack into each 32-bit pixel, most significant byte first.

| Constant    | Value | Layout       | Alpha             |
| ----------- | ----- | ------------ | ----------------- |
| `ABGR8888`  | 0     | `0xAABBGGRR` | Premultiplied     |
| `ABGR8888S` | 1     | `0xAABBGGRR` | Not premultiplied |
| `ARGB8888`  | 2     | `0xAARRGGBB` | Premultiplied     |
| `ARGB8888S` | 3     | `0xAARRGGBB` | Not premultiplied |

### dotlottieDotLottieWgpuTargetType

| Constant  | Value | `target` points to |
| --------- | ----- | ------------------ |
| `Surface` | 0     | A `WGPUSurface`    |
| `Texture` | 1     | A `WGPUTexture`    |

### dotlottieDotLottiePlayerEvent

```c
typedef union dotlottieDotLottiePlayerEventData {
  float frame_no;        /* Frame and Render events */
  uint32_t loop_count;   /* Loop events */
} dotlottieDotLottiePlayerEventData;

typedef struct dotlottieDotLottiePlayerEvent {
  dotlottieDotLottiePlayerEventType event_type;
  dotlottieDotLottiePlayerEventData data;
} dotlottieDotLottiePlayerEvent;
```

| Event type  | Value | Fires when                    | Payload      |
| ----------- | ----- | ----------------------------- | ------------ |
| `Load`      | 0     | An animation finished loading | —            |
| `LoadError` | 1     | An animation failed to load   | —            |
| `Play`      | 2     | Playback started              | —            |
| `Pause`     | 3     | Playback paused               | —            |
| `Stop`      | 4     | Playback stopped and reset    | —            |
| `Frame`     | 5     | The current frame advanced    | `frame_no`   |
| `Render`    | 6     | A frame was drawn             | `frame_no`   |
| `Loop`      | 7     | A loop iteration completed    | `loop_count` |
| `Complete`  | 8     | Playback finished             | —            |

Read only the union member matching `event_type`.

### dotlottieStateMachineEvent

```c
typedef struct dotlottieStateMachineEvent {
  dotlottieStateMachineEventType event_type;
  dotlottieStateMachineEventData data;
} dotlottieStateMachineEvent;
```

| Event type                       | Value | Payload member  |
| -------------------------------- | ----- | --------------- |
| `StateMachineStart`              | 0     | —               |
| `StateMachineStop`               | 1     | —               |
| `StateMachineTransition`         | 2     | `transition`    |
| `StateMachineStateEntered`       | 3     | `state`         |
| `StateMachineStateExit`          | 4     | `state`         |
| `StateMachineCustomEvent`        | 5     | `message`       |
| `StateMachineError`              | 6     | `message`       |
| `StateMachineStringInputChange`  | 7     | `string_input`  |
| `StateMachineNumericInputChange` | 8     | `numeric_input` |
| `StateMachineBooleanInputChange` | 9     | `boolean_input` |
| `StateMachineInputFired`         | 10    | `input_fired`   |

The payload members are:

| Member          | Fields                                                      |
| --------------- | ----------------------------------------------------------- |
| `transition`    | `previous_state`, `new_state` — `const char *`              |
| `state`         | `state` — `const char *`                                    |
| `message`       | `message` — `const char *`                                  |
| `string_input`  | `name`, `old_value`, `new_value` — `const char *`           |
| `numeric_input` | `name` — `const char *`; `old_value`, `new_value` — `float` |
| `boolean_input` | `name` — `const char *`; `old_value`, `new_value` — `bool`  |
| `input_fired`   | `name` — `const char *`                                     |

`dotlottieStateMachineInternalEvent` contains a single `message` field.

<Callout type="warning" title="Event strings are only valid until the next poll">
  Every `const char *` in a state machine event points into memory the library reuses on the following poll call. Copy
  anything you need to retain.
</Callout>

### Opaque handles

| Type                                         | Created by                                          | Released by                         |
| -------------------------------------------- | --------------------------------------------------- | ----------------------------------- |
| `dotlottiePlayer`, aliased `DotLottiePlayer` | `dotlottie_new_player()`                            | `dotlottie_destroy()`               |
| `dotlottieDotLottieStateMachine`             | `dotlottie_state_machine_load()`, `..._load_data()` | `dotlottie_state_machine_release()` |

`DotLottieConfig` also appears in the header as a typedef to an undefined struct. It is unused — ignore it.

### Interaction bitmask

Returned by `dotlottie_state_machine_get_framework_setup()` as a `uint16_t`. The type itself is internal and not emitted into the header, so these values are the reference.

| Bit      | Value | Interaction      |
| -------- | ----- | ---------------- |
| `1 << 0` | 1     | Pointer up       |
| `1 << 1` | 2     | Pointer down     |
| `1 << 2` | 4     | Pointer enter    |
| `1 << 3` | 8     | Pointer exit     |
| `1 << 4` | 16    | Pointer move     |
| `1 << 5` | 32    | Click            |
| `1 << 6` | 64    | On complete      |
| `1 << 7` | 128   | On loop complete |

## Lifecycle

| Function                                     | Returns                    | Description                                                                                                          |
| -------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `dotlottie_new_player(uint32_t threads)`     | `DotLottiePlayer *`        | Creates a player. `threads` sizes the renderer's worker pool; `0` uses the calling thread. Returns `NULL` on failure |
| `dotlottie_destroy(DotLottiePlayer *player)` | `dotlottieDotLottieResult` | Destroys the player. Release any state machine first                                                                 |

The thread count is fixed process-wide by the first player created; later values are ignored. Threading also needs the `tvg-threads` feature.

## Fonts

Fonts live in a process-wide registry, so these take no player handle. Requires `tvg-ttf` or `tvg-otf`.

| Function                                                                  | Description                                       |
| ------------------------------------------------------------------------- | ------------------------------------------------- |
| `dotlottie_load_font(const char *name, const uint8_t *data, size_t size)` | Registers a font under `name`. The data is copied |
| `dotlottie_unload_font(const char *name)`                                 | Removes a registered font                         |

## Loading

| Function                                                                          | Feature     | Description                                                          |
| --------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------- |
| `dotlottie_load_animation_path(DotLottiePlayer *, const char *path)`              | —           | Loads a `.json` or `.lottie` file from disk                          |
| `dotlottie_load_animation_data(DotLottiePlayer *, const char *json)`              | —           | Loads Lottie JSON from a null-terminated string                      |
| `dotlottie_load_dotlottie_data(DotLottiePlayer *, const char *data, size_t size)` | `dotlottie` | Loads a `.lottie` file from memory                                   |
| `dotlottie_load_animation(DotLottiePlayer *, const char *animation_id)`           | `dotlottie` | Switches to another animation inside the loaded `.lottie` file       |
| `dotlottie_get_manifest(DotLottiePlayer *, char *buffer, size_t *size_out)`       | `dotlottie` | Reads the manifest as JSON. Returns `ManifestNotAvailable` if absent |
| `dotlottie_get_animation_id(DotLottiePlayer *, char *buffer, size_t *size_out)`   | `dotlottie` | Reads the active animation's ID                                      |

Functions taking a `buffer` and `size_out` pair use the two-call pattern: pass `NULL` for `buffer` to learn the required size, then call again with an allocated buffer. The reported size includes the null terminator.

## Configuration

### Setters

| Function                                                                                  | Description                                            |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `dotlottie_set_mode(DotLottiePlayer *, dotlottieMode mode)`                               | Sets the playback direction                            |
| `dotlottie_set_speed(DotLottiePlayer *, float speed)`                                     | Sets the speed multiplier. `1.0` is normal             |
| `dotlottie_set_loop(DotLottiePlayer *, bool loop)`                                        | Enables or disables looping                            |
| `dotlottie_set_loop_count(DotLottiePlayer *, uint32_t count)`                             | Sets the loop repetition count. `0` means infinite     |
| `dotlottie_set_autoplay(DotLottiePlayer *, bool autoplay)`                                | Starts playback automatically on load                  |
| `dotlottie_set_use_frame_interpolation(DotLottiePlayer *, bool enabled)`                  | Enables sub-frame rendering                            |
| `dotlottie_set_background(DotLottiePlayer *, uint8_t r, uint8_t g, uint8_t b, uint8_t a)` | Sets the background color, channels `0`–`255`          |
| `dotlottie_set_segment(DotLottiePlayer *, const float (*segment)[2])`                     | Restricts playback to `[start, end]`. `NULL` clears it |
| `dotlottie_set_marker(DotLottiePlayer *, const char *marker)`                             | Plays a named marker's range. `NULL` clears it         |
| `dotlottie_set_layout(DotLottiePlayer *, dotlottieLayout layout)`                         | Sets fit mode and alignment                            |
| `dotlottie_set_viewport(DotLottiePlayer *, int32_t x, int32_t y, int32_t w, int32_t h)`   | Restricts drawing to a rectangle of the target         |

### Getters

These return `dotlottieDotLottieResult` and write through an output pointer.

| Function                                                                                      | Writes                         |
| --------------------------------------------------------------------------------------------- | ------------------------------ |
| `dotlottie_get_background(DotLottiePlayer *, uint8_t *r, uint8_t *g, uint8_t *b, uint8_t *a)` | The background color           |
| `dotlottie_get_segment(DotLottiePlayer *, float (*result)[2])`                                | The active segment             |
| `dotlottie_get_layout(DotLottiePlayer *, dotlottieLayout *result)`                            | The current layout             |
| `dotlottie_get_active_marker(DotLottiePlayer *, char *buffer, size_t *size_out)`              | The active marker name         |
| `dotlottie_get_total_frames(DotLottiePlayer *, float *result)`                                | The total frame count          |
| `dotlottie_get_duration(DotLottiePlayer *, float *result)`                                    | The duration in seconds        |
| `dotlottie_get_current_frame(DotLottiePlayer *, float *result)`                               | The current frame number       |
| `dotlottie_get_current_loop_count(DotLottiePlayer *, uint32_t *result)`                       | Completed loop iterations      |
| `dotlottie_get_animation_size(DotLottiePlayer *, float *width, float *height)`                | The animation's intrinsic size |

These return the value directly and substitute a default when the handle is invalid — they cannot report an error.

| Function                                                   | Returns           | Default if invalid |
| ---------------------------------------------------------- | ----------------- | ------------------ |
| `dotlottie_get_mode(DotLottiePlayer *)`                    | `dotlottieMode`   | `Forward`          |
| `dotlottie_get_speed(DotLottiePlayer *)`                   | `float`           | `1.0`              |
| `dotlottie_get_loop(DotLottiePlayer *)`                    | `bool`            | `false`            |
| `dotlottie_get_loop_count(DotLottiePlayer *)`              | `uint32_t`        | `0`                |
| `dotlottie_get_autoplay(DotLottiePlayer *)`                | `bool`            | `false`            |
| `dotlottie_get_use_frame_interpolation(DotLottiePlayer *)` | `bool`            | `false`            |
| `dotlottie_status(DotLottiePlayer *)`                      | `dotlottieStatus` | `Idle`             |
| `dotlottie_is_complete(DotLottiePlayer *)`                 | `bool`            | `false`            |

## Playback

| Function                                                       | Feature | Description                                                                           |
| -------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `dotlottie_play(DotLottiePlayer *)`                            | —       | Starts or resumes playback                                                            |
| `dotlottie_pause(DotLottiePlayer *)`                           | —       | Pauses at the current frame                                                           |
| `dotlottie_stop(DotLottiePlayer *)`                            | —       | Stops and resets to the start                                                         |
| `dotlottie_set_frame(DotLottiePlayer *, float frame)`          | —       | Jumps to a frame. Fractional values are allowed                                       |
| `dotlottie_render(DotLottiePlayer *)`                          | —       | Draws the current frame without advancing time                                        |
| `dotlottie_tick(DotLottiePlayer *, float dt, bool *rendered)`  | —       | Advances by `dt` **seconds** and draws if the frame changed. `rendered` may be `NULL` |
| `dotlottie_set_audio_volume(DotLottiePlayer *, float volume)`  | `audio` | Sets volume from `0.0` to `1.0`                                                       |
| `dotlottie_get_audio_volume(DotLottiePlayer *, float *result)` | `audio` | Reads the current volume                                                              |

<Callout type="warning" title="dt is in seconds, not milliseconds">
  A 60 fps step is `0.0167`. The example in the header's `dotlottie_tick` doc comment derives `dt` from a millisecond
  clock without converting, which advances the animation 1000× too fast.
</Callout>

## Render targets

Exactly one target is attached per player.

| Function                                                                                                                                                         | Feature   | Description                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------- |
| `dotlottie_set_sw_target(DotLottiePlayer *, uint32_t *buffer, uint32_t width, uint32_t height, dotlottieColorSpace cs)`                                          | `tvg-cpu` | Renders into a caller-owned buffer of `width × height` pixels           |
| `dotlottie_set_gl_target(DotLottiePlayer *, void *display, void *surface, void *context, int32_t id, uint32_t width, uint32_t height)`                           | `tvg-gl`  | Renders into GL framebuffer `id`. `display` and `surface` may be `NULL` |
| `dotlottie_set_wg_target(DotLottiePlayer *, void *device, void *instance, void *target, uint32_t width, uint32_t height, dotlottieDotLottieWgpuTargetType type)` | `tvg-wg`  | Renders into a WebGPU surface or texture                                |

The software buffer belongs to you and must outlive the player.

## Theming

All require the `theming` feature.

| Function                                                                    | Description                                 |
| --------------------------------------------------------------------------- | ------------------------------------------- |
| `dotlottie_set_theme(DotLottiePlayer *, const char *theme_id)`              | Applies a theme packaged in the loaded file |
| `dotlottie_set_theme_data(DotLottiePlayer *, const char *theme_json)`       | Applies a theme from JSON you supply        |
| `dotlottie_reset_theme(DotLottiePlayer *)`                                  | Removes the active theme                    |
| `dotlottie_get_theme_id(DotLottiePlayer *, char *buffer, size_t *size_out)` | Reads the active theme's ID                 |

## Slots

| Function                                                                                          | Description                                                                                            |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `dotlottie_get_slot_ids_count(DotLottiePlayer *, uint32_t *count)`                                | Counts the slots the animation defines                                                                 |
| `dotlottie_get_slot_id(DotLottiePlayer *, uint32_t index, char *buffer, size_t *size_out)`        | Reads a slot ID by index                                                                               |
| `dotlottie_get_slot_type(DotLottiePlayer *, const char *slot_id, char *buffer, size_t *size_out)` | Reads a slot's type name, such as `color` or `text`                                                    |
| `dotlottie_set_color_slot(DotLottiePlayer *, const char *slot_id, float r, float g, float b)`     | Sets a color slot. Channels are `0.0`–`1.0`                                                            |
| `dotlottie_set_scalar_slot(DotLottiePlayer *, const char *slot_id, float value)`                  | Sets a scalar slot                                                                                     |
| `dotlottie_set_text_slot(DotLottiePlayer *, const char *slot_id, const char *text)`               | Sets a text slot                                                                                       |
| `dotlottie_set_vector_slot(DotLottiePlayer *, const char *slot_id, float x, float y)`             | Sets a 2D vector slot                                                                                  |
| `dotlottie_set_position_slot(DotLottiePlayer *, const char *slot_id, float x, float y)`           | Sets a 2D position slot                                                                                |
| `dotlottie_set_image_slot_src(DotLottiePlayer *, const char *slot_id, const char *src)`           | Sets an image slot from a `data:` URI, an `http(s)://` URL, or a filename in the package's `i/` folder |
| `dotlottie_set_slots_str(DotLottiePlayer *, const char *slots_json)`                              | Sets many slots from JSON, including gradients and keyframes                                           |
| `dotlottie_set_slot_str(DotLottiePlayer *, const char *slot_id, const char *json)`                | Sets one slot from JSON                                                                                |
| `dotlottie_get_slot_str(DotLottiePlayer *, const char *slot_id, char *buffer, size_t *size_out)`  | Reads one slot's value as JSON                                                                         |
| `dotlottie_get_slots_str(DotLottiePlayer *, char *buffer, size_t *size_out)`                      | Reads all slot values as JSON                                                                          |
| `dotlottie_reset_slot(DotLottiePlayer *, const char *slot_id)`                                    | Restores a slot to the animation's original value                                                      |
| `dotlottie_reset_slots(DotLottiePlayer *)`                                                        | Restores every slot to its original value                                                              |
| `dotlottie_clear_slot(DotLottiePlayer *, const char *slot_id)`                                    | Removes the override for a slot                                                                        |
| `dotlottie_clear_slots(DotLottiePlayer *)`                                                        | Removes all slot overrides                                                                             |

Slot colors are floats from `0.0` to `1.0`, unlike `dotlottie_set_background()`, which takes bytes.

## Markers

| Function                                                                                             | Description                                                                                     |
| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `dotlottie_get_markers_count(DotLottiePlayer *, uint32_t *count)`                                    | Counts the markers the animation defines                                                        |
| `dotlottie_get_marker(DotLottiePlayer *, uint32_t idx, const char **name, float *start, float *end)` | Reads a marker by index. `name` is library-owned — do not free. `start` and `end` may be `NULL` |

## Events

| Function                                                                        | Returns                                                             | Description                      |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------- |
| `dotlottie_poll_event(DotLottiePlayer *, dotlottieDotLottiePlayerEvent *event)` | `int32_t` — `1` wrote an event, `0` queue empty, `-1` null argument | Removes one event from the queue |

Drain the queue with a `while` loop each frame; unpolled events accumulate.

## State machines

All require the `state-machines` feature. The load functions return `NULL` without it, so you never hold a valid handle in a build that lacks it.

### Lifecycle

| Function                                                                                                                | Description                                                                                              |
| ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `dotlottie_state_machine_load(DotLottiePlayer *, const char *state_machine_id)`                                         | Loads a machine packaged in the file. Returns a handle or `NULL`                                         |
| `dotlottie_state_machine_load_data(DotLottiePlayer *, const char *definition)`                                          | Loads a machine from a JSON definition                                                                   |
| `dotlottie_state_machine_start(dotlottieDotLottieStateMachine *, const char *whitelist, bool require_user_interaction)` | Starts the machine. `whitelist` is a comma-separated list of permitted URL prefixes; `NULL` permits none |
| `dotlottie_state_machine_stop(dotlottieDotLottieStateMachine *)`                                                        | Stops the machine, keeping the handle valid                                                              |
| `dotlottie_state_machine_release(dotlottieDotLottieStateMachine *)`                                                     | Destroys the machine. Must be called **before** `dotlottie_destroy()`                                    |
| `dotlottie_state_machine_tick(dotlottieDotLottieStateMachine *, float dt, bool *rendered)`                              | Advances by `dt` seconds, evaluates transitions, and draws if the frame changed                          |
| `dotlottie_get_state_machine(DotLottiePlayer *, const char *id, char *buffer, size_t *size_out)`                        | Reads a machine's JSON definition without loading it                                                     |

Starting a machine resets playback to frame zero, forward mode, speed `1.0`, no looping, and no autoplay.

### Input

| Function                                                                    | Description                   |
| --------------------------------------------------------------------------- | ----------------------------- |
| `dotlottie_state_machine_post_click(sm, float x, float y)`                  | Posts a click                 |
| `dotlottie_state_machine_post_pointer_down(sm, float x, float y)`           | Posts a pointer-down          |
| `dotlottie_state_machine_post_pointer_up(sm, float x, float y)`             | Posts a pointer-up            |
| `dotlottie_state_machine_post_pointer_move(sm, float x, float y)`           | Posts a pointer-move          |
| `dotlottie_state_machine_post_pointer_enter(sm, float x, float y)`          | Posts a pointer-enter         |
| `dotlottie_state_machine_post_pointer_exit(sm, float x, float y)`           | Posts a pointer-exit          |
| `dotlottie_state_machine_post_event(sm, const dotlottiePlayerEvent *event)` | Posts a pre-built input event |
| `dotlottie_state_machine_fire_event(sm, const char *event_name)`            | Fires a named custom event    |

Coordinates are in pixels relative to the render target's top-left corner.

### Inputs and state

| Function                                                                                        | Description                               |
| ----------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `dotlottie_state_machine_set_numeric_input(sm, const char *key, float value)`                   | Sets a numeric input                      |
| `dotlottie_state_machine_set_string_input(sm, const char *key, const char *value)`              | Sets a string input                       |
| `dotlottie_state_machine_set_boolean_input(sm, const char *key, bool value)`                    | Sets a boolean input                      |
| `dotlottie_state_machine_get_numeric_input(sm, const char *key, float *result)`                 | Reads a numeric input                     |
| `dotlottie_state_machine_get_string_input(sm, const char *key, char *buffer, size_t *size_out)` | Reads a string input                      |
| `dotlottie_state_machine_get_boolean_input(sm, const char *key, bool *result)`                  | Reads a boolean input                     |
| `dotlottie_state_machine_get_current_state(sm, char *buffer, size_t *size_out)`                 | Reads the current state's name            |
| `dotlottie_state_machine_get_status(sm, char *buffer, size_t *size_out)`                        | Reads the engine's status                 |
| `dotlottie_state_machine_get_framework_setup(sm, uint16_t *result)`                             | Reads the interaction bitmask             |
| `dotlottie_state_machine_set_seed(sm, uint64_t seed)`                                           | Fixes the random seed for reproducibility |

### Events

| Function                                                                                     | Returns                       | Description                                    |
| -------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------- |
| `dotlottie_state_machine_poll_event(sm, dotlottieStateMachineEvent *event)`                  | `int32_t` — `1`, `0`, or `-1` | Polls transition and input-change events       |
| `dotlottie_state_machine_poll_internal_event(sm, dotlottieStateMachineInternalEvent *event)` | `int32_t` — `1`, `0`, or `-1` | Polls messages meant for platform integrations |

## Platform

| Function                                      | Description                                                                                                         |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `dotlottie_init_android(void *vm, void *ctx)` | Supplies the `JavaVM` and Android context needed for audio output. Call once before loading an animation with audio |

## Learn more

- [How the C API works](/en/runtimes/distributions/native/v0.x/how-the-c-api-works) — the design behind these signatures
- [Memory and safety rules](/en/runtimes/distributions/native/v0.x/memory-and-safety) — ownership and lifetimes
- [Build for your target architecture](/en/runtimes/distributions/native/v0.x/building) — enabling the features listed above