Functions
mk_particle_alive_countfunction
uint32_t mk_particle_alive_count(const mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index)
Return the exact CPU alive count.
GPU-authoritative emitters return a conservative upper bound because simulation counters remain device-local.
| Parameter | Type | Description |
|---|
world | const mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
Returns The resulting value.
mk_particle_apply_gpu_drawfunction
mk_result mk_particle_apply_gpu_draw(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, struct mk_draw_desc *draw)
Attach a prepared GPU sprite, billboard, mesh, or trail emitter to a custom draw descriptor.
For sprites and billboards, the caller supplies a particle-compatible shader or pipeline plus a valid indexed or non-indexed quad in draw->geometry. The shader reads a_position/a_texcoord0 for the corner and UV. The adapter fills the dynamic instance source and indirect draw fields. Its 64-byte instance ABI is: i_data0 = simulation-space position.xyz, age i_data1 = velocity.xyz, lifetime i_data2 = color i_data3 = size, rotation, initial size, angular velocity Trail renderers instead fill the ordinary dynamic vertex stream. Their 64-byte vertex ABI (TEXCOORD7 through TEXCOORD4) is: data0 = simulation-space center.xyz, side (-1 or +1) data1 = normalized trail tangent.xyz, distance-based u data2 = particle color * color-over-trail data3 = width, normalized trail coordinate, reserved, reserved The graphics shader expands center along side using its camera basis. Mesh emitters use geometry previously registered through mk_particle_mesh_set_geometry(); the adapter fills its retained vertex/index streams. Call only after mk_particle_world_prepare_gpu() in the current open frame. Existing raw vertex/index, instance, or indirect fields are rejected; geometry is accepted only for sprites and billboards. GPU trail sorting is intrinsic oldest-to-newest and requires MK_PARTICLE_SORT_NONE.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
draw | struct mk_draw_desc * | Value for draw. |
Returns MK_SUCCESS or an error result.
mk_particle_burstfunction
void mk_particle_burst(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, uint32_t count)
Perform the particle burst operation.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
count | uint32_t | Number of entries. |
mk_particle_effect_createfunction
mk_particle_effect_t mk_particle_effect_create(const mk_particle_effect_desc *desc)
Create an immutable effect.
| Parameter | Type | Description |
|---|
desc | const mk_particle_effect_desc * | Configuration descriptor. |
Returns The resulting handle or value.
mk_particle_effect_destroyfunction
void mk_particle_effect_destroy(mk_particle_effect_t effect)
Destroy the particle effect.
| Parameter | Type | Description |
|---|
effect | mk_particle_effect_t | Value for effect. |
mk_particle_effect_get_referencefunction
bool mk_particle_effect_get_reference(mk_particle_effect_t effect, uint32_t emitter_index, mk_particle_reference_type type, uint32_t *out_handle_id)
Query one non-curve emitter reference resolved at effect creation.
| Parameter | Type | Description |
|---|
effect | mk_particle_effect_t | Value for effect. |
emitter_index | uint32_t | Value for emitter index. |
type | mk_particle_reference_type | Value for type. |
out_handle_id | uint32_t * | Receives the handle ID. |
Returns True when the operation succeeds.
mk_particle_effect_get_render_stylefunction
bool mk_particle_effect_get_render_style(mk_particle_effect_t effect, uint32_t emitter_index, mk_particle_render_style *out_style)
Get render style from the particle effect.
| Parameter | Type | Description |
|---|
effect | mk_particle_effect_t | Value for effect. |
emitter_index | uint32_t | Value for emitter index. |
out_style | mk_particle_render_style * | Receives the style. |
Returns True when the operation succeeds.
mk_particle_effect_load_assetfunction
mk_particle_effect_t mk_particle_effect_load_asset(const char *asset_id, mk_particle_reference_resolver_fn resolver, void *resolver_user_data, mk_particle_json_error *error)
Load a loose path or mounted logical JSON asset through the asset system.
| Parameter | Type | Description |
|---|
asset_id | const char * | Value for asset ID. |
resolver | mk_particle_reference_resolver_fn | Value for resolver. |
resolver_user_data | void * | Value for resolver user data. |
error | mk_particle_json_error * | Value for error. |
Returns The resulting handle or value.
mk_particle_effect_load_jsonfunction
mk_particle_effect_t mk_particle_effect_load_json(const char *json, mk_particle_reference_resolver_fn resolver, void *resolver_user_data, mk_particle_json_error *error)
Load JSON for the particle effect.
| Parameter | Type | Description |
|---|
json | const char * | Value for JSON. |
resolver | mk_particle_reference_resolver_fn | Value for resolver. |
resolver_user_data | void * | Value for resolver user data. |
error | mk_particle_json_error * | Value for error. |
Returns The resulting handle or value.
mk_particle_effect_validfunction
bool mk_particle_effect_valid(mk_particle_effect_t effect)
Perform the particle effect valid operation.
| Parameter | Type | Description |
|---|
effect | mk_particle_effect_t | Value for effect. |
Returns True when the operation succeeds.
mk_particle_get_backendfunction
bool mk_particle_get_backend(const mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, mk_particle_fallback *selection)
Query the requested backend, selected backend, and fallback reason for one emitter.
| Parameter | Type | Description |
|---|
world | const mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
selection | mk_particle_fallback * | Value for selection. |
Returns True when the operation succeeds.
mk_particle_get_boundsfunction
bool mk_particle_get_bounds(const mk_particle_world_t *world, mk_particle_instance_t instance, mk_vec3 *min_bounds, mk_vec3 *max_bounds)
CPU bounds are exact; GPU-authoritative bounds conservatively cover the authored motion envelope.
| Parameter | Type | Description |
|---|
world | const mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
min_bounds | mk_vec3 * | Value for min bounds. |
max_bounds | mk_vec3 * | Value for max bounds. |
Returns True when the operation succeeds.
mk_particle_get_fallbacksfunction
uint32_t mk_particle_get_fallbacks(const mk_particle_world_t *world, mk_particle_instance_t instance, mk_particle_fallback *fallbacks, uint32_t capacity)
Get fallbacks from the particle.
| Parameter | Type | Description |
|---|
world | const mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
fallbacks | mk_particle_fallback * | Value for fallbacks. |
capacity | uint32_t | Value for capacity. |
Returns The resulting value.
mk_particle_get_render_viewfunction
bool mk_particle_get_render_view(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, mk_vec3 view_position, mk_vec3 view_forward, mk_particle_render_view *view)
Build allocation-free interpolated world-space instances in the emitter's configured stable sort order.
Trail emitters use mk_particle_get_trail_view.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
view_position | mk_vec3 | Value for view position. |
view_forward | mk_vec3 | Value for view forward. |
view | mk_particle_render_view * | Value for view. |
Returns True when the operation succeeds.
mk_particle_get_sorted_viewfunction
bool mk_particle_get_sorted_view(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, mk_vec3 view_position, mk_vec3 view_forward, mk_particle_view *view)
Build a stable renderer order without allocating.
Age sorting is oldest first; view depth is back-to-front along view_forward.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
view_position | mk_vec3 | Value for view position. |
view_forward | mk_vec3 | Value for view forward. |
view | mk_particle_view * | Value for view. |
Returns True when the operation succeeds.
mk_particle_get_trail_viewfunction
bool mk_particle_get_trail_view(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, mk_particle_trail_view *view)
Flatten a trail emitter into oldest-to-newest world-space renderer spans.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
view | mk_particle_trail_view * | Value for view. |
Returns True when the operation succeeds.
mk_particle_get_viewfunction
bool mk_particle_get_view(const mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, mk_particle_view *view)
Return false after an emitter becomes GPU-authoritative; no readback shadow is maintained.
| Parameter | Type | Description |
|---|
world | const mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
view | mk_particle_view * | Value for view. |
Returns True when the operation succeeds.
mk_particle_instance_createfunction
mk_particle_instance_t mk_particle_instance_create(mk_particle_world_t *world, mk_particle_effect_t effect)
Create particle instance.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
effect | mk_particle_effect_t | Value for effect. |
Returns The resulting handle or value.
mk_particle_instance_destroyfunction
void mk_particle_instance_destroy(mk_particle_world_t *world, mk_particle_instance_t instance)
Destroy the particle instance.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
mk_particle_instance_emitter_countfunction
uint32_t mk_particle_instance_emitter_count(const mk_particle_world_t *world, mk_particle_instance_t instance)
Perform the particle instance emitter count operation.
| Parameter | Type | Description |
|---|
world | const mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
Returns The resulting value.
mk_particle_instance_get_referencefunction
bool mk_particle_instance_get_reference(const mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, mk_particle_reference_type type, uint32_t *out_handle_id)
Query immutable emitter metadata through a live instance.
This remains valid when the public effect handle has been destroyed but the instance retains its original immutable generation.
| Parameter | Type | Description |
|---|
world | const mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
type | mk_particle_reference_type | Value for type. |
out_handle_id | uint32_t * | Receives the handle ID. |
Returns True when the operation succeeds.
mk_particle_instance_get_render_stylefunction
bool mk_particle_instance_get_render_style(const mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, mk_particle_render_style *out_style)
Get render style from the particle instance.
| Parameter | Type | Description |
|---|
world | const mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
out_style | mk_particle_render_style * | Receives the style. |
Returns True when the operation succeeds.
mk_particle_instance_validfunction
bool mk_particle_instance_valid(const mk_particle_world_t *world, mk_particle_instance_t instance)
Perform the particle instance valid operation.
| Parameter | Type | Description |
|---|
world | const mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
Returns True when the operation succeeds.
mk_particle_pausefunction
void mk_particle_pause(mk_particle_world_t *world, mk_particle_instance_t instance)
Pause the particle.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
mk_particle_playfunction
void mk_particle_play(mk_particle_world_t *world, mk_particle_instance_t instance)
Play particle.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
mk_particle_prewarmfunction
void mk_particle_prewarm(mk_particle_world_t *world, mk_particle_instance_t instance, float duration)
Advance immediately using fixed ticks, retaining any fractional time in the emitter accumulator.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
duration | float | Value for duration. |
mk_particle_restartfunction
void mk_particle_restart(mk_particle_world_t *world, mk_particle_instance_t instance)
Perform the particle restart operation.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
mk_particle_restart_with_effectfunction
mk_result mk_particle_restart_with_effect(mk_particle_world_t *world, mk_particle_instance_t instance, mk_particle_effect_t replacement)
Transactionally replace an instance's immutable definition and restart it.
Matching emitter transforms are preserved; other mutable controls reset.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
replacement | mk_particle_effect_t | Value for replacement. |
Returns MK_SUCCESS or an error result.
mk_particle_seekfunction
void mk_particle_seek(mk_particle_world_t *world, mk_particle_instance_t instance, float time)
Restart and advance by complete fixed ticks, retaining the fractional time for interpolation.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
time | float | Value for time. |
mk_particle_set_collision_callbackfunction
void mk_particle_set_collision_callback(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, mk_particle_collision_callback_fn callback, void *user_data)
Installing a CPU collision callback on a device-authoritative GPU emitter selects the CPU backend and clears its unreadable device-local particles.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
callback | mk_particle_collision_callback_fn | Completion callback. |
user_data | void * | Caller-provided context. |
mk_particle_set_forcefunction
void mk_particle_set_force(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, mk_vec3 force)
Set force on the particle.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
force | mk_vec3 | Value for force. |
mk_particle_set_opacityfunction
void mk_particle_set_opacity(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, float opacity)
Set opacity on the particle.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
opacity | float | Value for opacity. |
mk_particle_set_ratefunction
void mk_particle_set_rate(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, float rate)
Set rate on the particle.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
rate | float | Value for rate. |
mk_particle_set_sort_viewfunction
mk_result mk_particle_set_sort_view(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, mk_vec3 view_position, mk_vec3 view_forward)
Set the world-space camera used by a view-depth sorted emitter's GPU sort.
Set this after camera updates and before mk_particle_world_prepare_gpu(). AUTO emitters that otherwise support GPU simulation remain on CPU until a valid non-zero view direction is supplied. Updating the view after this world's GPU work was prepared for the open frame is rejected.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
view_position | mk_vec3 | Value for view position. |
view_forward | mk_vec3 | Value for view forward. |
Returns MK_SUCCESS or an error result.
mk_particle_set_time_scalefunction
void mk_particle_set_time_scale(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, float time_scale)
Set time scale on the particle.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
time_scale | float | Value for time scale. |
mk_particle_set_tintfunction
void mk_particle_set_tint(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, mk_vec4 tint)
Set tint on the particle.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
tint | mk_vec4 | Value for tint. |
mk_particle_set_trail_widthfunction
void mk_particle_set_trail_width(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, float width)
Set a trail emitter's non-negative base width.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
width | float | Value for width. |
mk_particle_set_transformfunction
void mk_particle_set_transform(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, const mk_transform *transform)
Set transform on the particle.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
emitter_index | uint32_t | Value for emitter index. |
transform | const mk_transform * | Value for transform. |
mk_particle_stopfunction
void mk_particle_stop(mk_particle_world_t *world, mk_particle_instance_t instance, bool clear)
Stop new emission.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
instance | mk_particle_instance_t | Value for instance. |
clear | bool | Value for clear. |
mk_particle_world_createfunction
mk_particle_world_t * mk_particle_world_create(const mk_particle_world_desc *desc)
Create particle world.
| Parameter | Type | Description |
|---|
desc | const mk_particle_world_desc * | Configuration descriptor. |
Returns A borrowed pointer, or NULL when unavailable.
mk_particle_world_destroyfunction
void mk_particle_world_destroy(mk_particle_world_t *world)
Destroy the particle world.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
mk_particle_world_drain_eventsfunction
uint32_t mk_particle_world_drain_events(mk_particle_world_t *world, mk_particle_event *events, uint32_t capacity)
Drain explicitly enabled birth, death, and collision events from CPU emitters.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
events | mk_particle_event * | Value for events. |
capacity | uint32_t | Value for capacity. |
Returns The resulting value.
mk_particle_world_get_statsfunction
void mk_particle_world_get_stats(const mk_particle_world_t *world, mk_particle_stats *stats)
Get stats from the particle world.
| Parameter | Type | Description |
|---|
world | const mk_particle_world_t * | Value for world. |
stats | mk_particle_stats * | Value for stats. |
mk_particle_world_prepare_gpufunction
mk_result mk_particle_world_prepare_gpu(mk_particle_world_t *world)
Encode accumulated GPU simulation ticks once in the currently open frame.
Call after mk_frame_begin() and before particle graphics submissions. A successfully initialized GPU emitter then becomes device-authoritative; later world steps enqueue fixed-tick commands without a CPU particle shadow.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
Returns MK_SUCCESS or an error result.
mk_particle_world_stepfunction
void mk_particle_world_step(mk_particle_world_t *world, float dt)
Perform the particle world step operation.
| Parameter | Type | Description |
|---|
world | mk_particle_world_t * | Value for world. |
dt | float | Value for dt. |
Structs
mk_particle_aabb_colliderstruct
Data for particle aabb collider.
| Field | Type | Description |
|---|
min | mk_vec3 | The min. |
max | mk_vec3 | The max. |
bounce | float | The bounce. |
friction | float | The friction. |
response | mk_particle_collision_response | The response. |
mk_particle_burst_descstruct
Data for particle burst desc.
| Field | Type | Description |
|---|
time | float | The time. |
count | uint32_t | The count. |
mk_particle_collision_infostruct
Data for particle collision info.
| Field | Type | Description |
|---|
emitter_index | uint32_t | The emitter index. |
emission_index | uint64_t | The emission index. |
collider_type | mk_particle_collider_type | The collider type. |
collider_index | uint32_t | The collider index. |
position | mk_vec3 | Simulation-space contact position. |
velocity | mk_vec3 | Simulation-space incoming velocity. |
normal | mk_vec3 | The normal. |
penetration_depth | float | The penetration depth. |
mk_particle_effectstruct
Data for particle effect.
| Field | Type | Description |
|---|
id | uint32_t | The ID. |
mk_particle_effect_descstruct
Data for particle effect desc.
| Field | Type | Description |
|---|
emitters | const mk_particle_emitter_desc * | The emitters. |
emitter_count | uint32_t | The emitter count. |
mk_particle_emitter_descstruct
Data for particle emitter desc.
| Field | Type | Description |
|---|
capacity | uint32_t | The capacity. |
seed | uint64_t | The seed. |
backend | mk_particle_backend | The backend. |
space | mk_particle_space | The space. |
renderer | mk_particle_renderer_type | The renderer. |
references | mk_particle_emitter_references | The references. |
render_style | mk_particle_render_style | The render style. |
sorting | mk_particle_sort_mode | GPU view depth requires mk_particle_set_sort_view before preparation. |
overflow | mk_particle_overflow_policy | The overflow. |
rate | float | The rate. |
distance_rate | float | Particles per unit of emitter travel. |
duration | float | The duration. |
loop | bool | The loop. |
prewarm | float | The prewarm. |
fixed_step | float | 0 selects 1/60. |
max_steps_per_call | uint32_t | 0 selects 8. |
shape | mk_particle_shape_desc | The shape. |
lifetime | mk_scalar_distribution | The lifetime. |
speed | mk_scalar_distribution | The speed. |
size | mk_scalar_distribution | The size. |
rotation | mk_scalar_distribution | The rotation. |
angular_velocity | mk_scalar_distribution | The angular velocity. |
direction | mk_vec3 | The direction. |
gravity | mk_vec3 | The gravity. |
constant_force | mk_vec3 | The constant force. |
force_center | mk_vec3 | Center in the emitter's simulation space. |
radial_force | float | The radial force. |
vortex_axis | mk_vec3 | The vortex axis. |
vortex_force | float | The vortex force. |
noise_strength | float | The noise strength. |
noise_frequency | float | Deterministic noise samples per second. |
drag | float | The drag. |
velocity_over_life | mk_curve_t | The velocity over life. |
size_over_life | mk_curve_t | The size over life. |
rotation_over_life | mk_curve_t | The rotation over life. |
color_over_life | mk_gradient_t | The color over life. |
trail_history | uint32_t | 0 selects 16 for trail renderers. |
trail_min_distance | float | The trail min distance. |
trail_width | float | 0 selects 1. |
trail_width_over_trail | mk_curve_t | The trail width over trail. |
trail_color_over_trail | mk_gradient_t | The trail color over trail. |
trail_uv_tiling | float | 0 selects 1 repeat per simulation unit. |
trail_segment_limit | uint32_t | 0 selects trail_history - 1. |
trail_smoothing | float | [0, 1] neighbor smoothing; endpoints remain fixed. |
initial_color | mk_vec4 | The initial color. |
initial_color_distribution | mk_color_distribution | The initial color distribution. |
use_initial_color_distribution | bool | The use initial color distribution. |
bursts | const mk_particle_burst_desc * | The bursts. |
burst_count | uint32_t | The burst count. |
sub_emitters | const mk_particle_sub_emitter_desc * | The sub emitters. |
sub_emitter_count | uint32_t | The sub emitter count. |
plane_colliders | const mk_particle_plane_collider * | The plane colliders. |
plane_collider_count | uint32_t | The plane collider count. |
aabb_colliders | const mk_particle_aabb_collider * | The aabb colliders. |
aabb_collider_count | uint32_t | The aabb collider count. |
sphere_colliders | const mk_particle_sphere_collider * | The sphere colliders. |
sphere_collider_count | uint32_t | The sphere collider count. |
birth_events | bool | The birth events. |
death_events | bool | The death events. |
collision_events | bool | The collision events. |
mk_particle_emitter_referencesstruct
Application-resolved, immutable emitter resource IDs.
These remain opaque to the simulation core so particles do not depend on renderer, sprite, animation-graph, or audio modules. The built-in renderer recognizes valid Modkit texture and geometry handle IDs; applications can query every type for their own registries and integrations.
| Field | Type | Description |
|---|
texture | uint32_t | The texture. |
sprite | uint32_t | The sprite. |
geometry | uint32_t | The geometry. |
material | uint32_t | The material. |
sub_effect | uint32_t | The sub effect. |
graph | uint32_t | The graph. |
audio | uint32_t | The audio. |
mk_particle_eventstruct
Data for particle event.
| Field | Type | Description |
|---|
instance | mk_particle_instance_t | The instance. |
emitter_index | uint32_t | The emitter index. |
emission_index | uint64_t | The emission index. |
type | mk_particle_event_type | The type. |
position | mk_vec3 | The position. |
velocity | mk_vec3 | The velocity. |
mk_particle_fallbackstruct
Data for particle fallback.
| Field | Type | Description |
|---|
emitter_index | uint32_t | The emitter index. |
requested | mk_particle_backend | The requested. |
selected | mk_particle_backend | The selected. |
reason | mk_particle_fallback_reason | The reason. |
mk_particle_instancestruct
Data for particle instance.
| Field | Type | Description |
|---|
id | uint32_t | The ID. |
mk_particle_json_errorstruct
Data for particle JSON error.
| Field | Type | Description |
|---|
offset | size_t | The offset. |
message | char | The message. |
mk_particle_plane_colliderstruct
Data for particle plane collider.
| Field | Type | Description |
|---|
normal | mk_vec3 | The normal. |
distance | float | dot(normal, position) + distance = 0 |
bounce | float | The bounce. |
friction | float | The friction. |
response | mk_particle_collision_response | The response. |
mk_particle_render_instancestruct
Data for particle render instance.
| Field | Type | Description |
|---|
position | mk_vec3 | Interpolated world-space position. |
velocity | mk_vec3 | World-space velocity. |
scale | mk_vec3 | World-space absolute scale. |
color | mk_vec4 | The color. |
rotation | float | The rotation. |
normalized_age | float | The normalized age. |
emission_index | uint64_t | The emission index. |
mk_particle_render_stylestruct
Immutable renderer defaults that remain independent of renderer resources.
All-zero selects alpha blending, camera-facing billboards, a full UV rectangle, one atlas frame, unit velocity stretch, and a 0.5 mask cutoff.
| Field | Type | Description |
|---|
blend | mk_particle_blend_mode | The blend. |
billboard | mk_particle_billboard_mode | The billboard. |
billboard_axis | mk_vec3 | Zero selects +Y. |
velocity_stretch | float | Zero selects 1. |
uv_rect | mk_vec4 | All-zero selects 0,0,1,1. |
atlas_columns | uint16_t | Zero selects 1. |
atlas_rows | uint16_t | Zero selects 1. |
atlas_frames | uint32_t | Zero selects every atlas cell. |
alpha_cutoff | float | Masked only; zero selects 0.5. |
mk_particle_render_viewstruct
Data for particle render view.
| Field | Type | Description |
|---|
instances | const mk_particle_render_instance * | The instances. |
count | uint32_t | The count. |
renderer | mk_particle_renderer_type | The renderer. |
mk_particle_shape_descstruct
Data for particle shape desc.
| Field | Type | Description |
|---|
type | mk_particle_shape_type | The type. |
extents | mk_vec3 | The extents. |
radius | float | The radius. |
angle | float | Cone half-angle, radians. |
mk_particle_sphere_colliderstruct
Data for particle sphere collider.
| Field | Type | Description |
|---|
center | mk_vec3 | The center. |
radius | float | The radius. |
bounce | float | The bounce. |
friction | float | The friction. |
response | mk_particle_collision_response | The response. |
circle_2d | bool | The circle 2D. |
mk_particle_statsstruct
Data for particle stats.
| Field | Type | Description |
|---|
spawned | uint64_t | CPU births plus GPU spawn requests dispatched. |
died | uint64_t | The died. |
dropped | uint64_t | Exact on CPU; GPU reports only drops known before dispatch. |
fixed_steps | uint64_t | The fixed steps. |
allocation_failures | uint64_t | The allocation failures. |
events_dropped | uint64_t | The events dropped. |
sub_emissions_dropped | uint64_t | The sub emissions dropped. |
draw_calls | uint64_t | The draw calls. |
dispatch_calls | uint64_t | The dispatch calls. |
cpu_update_ns | uint64_t | Cumulative host time spent in world_step. |
cpu_sort_ns | uint64_t | Cumulative host time spent in exact CPU sorts. |
gpu_prepare_ns | uint64_t | Cumulative host time encoding GPU preparation. |
gpu_upload_bytes | uint64_t | Bytes uploaded while synchronizing GPU emitters. |
transient_bytes | uint64_t | Cumulative frame-scoped instance/ribbon bytes requested. |
cpu_sorted_particles | uint64_t | The CPU sorted particles. |
cpu_simulated_particles | uint64_t | The CPU simulated particles. |
gpu_scheduled_ticks | uint64_t | The GPU scheduled ticks. |
gpu_sorted_capacity | uint64_t | Sort-key capacity processed by GPU sorting passes. |
transient_failures | uint64_t | The transient failures. |
fallback_emitters | uint64_t | Current live emitters running on a fallback backend. |
gpu_authoritative_emitters | uint64_t | The GPU authoritative emitters. |
alive | uint32_t | Exact on CPU; conservative upper bound for GPU-authoritative emitters. |
mk_particle_sub_emitter_descstruct
Data for particle sub emitter desc.
| Field | Type | Description |
|---|
event | mk_particle_sub_emitter_event | The event. |
target_emitter | uint32_t | The target emitter. |
count | uint32_t | The count. |
interval | float | Required for timer events; ignored otherwise. |
mk_particle_trail_pointstruct
Data for particle trail point.
| Field | Type | Description |
|---|
position | mk_vec3 | The position. |
color | mk_vec4 | The color. |
width | float | The width. |
u | float | The u. |
emission_index | uint64_t | The emission index. |
mk_particle_trail_spanstruct
Data for particle trail span.
| Field | Type | Description |
|---|
first | uint32_t | The first. |
count | uint32_t | The count. |
mk_particle_trail_viewstruct
Data for particle trail view.
| Field | Type | Description |
|---|
points | const mk_particle_trail_point * | The points. |
spans | const mk_particle_trail_span * | The spans. |
point_count | uint32_t | The point count. |
span_count | uint32_t | The span count. |
mk_particle_viewstruct
Data for particle view.
| Field | Type | Description |
|---|
positions | const mk_vec3 * | The positions. |
previous_positions | const mk_vec3 * | Previous fixed-tick positions. |
velocities | const mk_vec3 * | The velocities. |
colors | const mk_vec4 * | The colors. |
ages | const float * | The ages. |
lifetimes | const float * | The lifetimes. |
sizes | const float * | The sizes. |
rotations | const float * | The rotations. |
emission_indices | const uint64_t * | The emission indices. |
order | const uint32_t * | Optional indices into the arrays above. |
count | uint32_t | The count. |
interpolation_alpha | float | Accumulator / fixed step, clamped to [0, 1]. |
mk_particle_world_descstruct
Data for particle world desc.
| Field | Type | Description |
|---|
instance_capacity | uint32_t | 0 selects 128. |
event_capacity | uint32_t | 0 selects 1024. |
sub_emission_capacity | uint32_t | 0 selects event_capacity. |
compute_supported | bool | The compute supported. |
indirect_supported | bool | The indirect supported. |
instancing_supported | bool | The instancing supported. |
Typedefs
mk_particle_aabb_collidertypedef
typedef struct mk_particle_aabb_collider mk_particle_aabb_collider
Data for particle aabb collider.
mk_particle_backendtypedef
typedef enum mk_particle_backend mk_particle_backend
Values for particle backend.
mk_particle_billboard_modetypedef
typedef enum mk_particle_billboard_mode mk_particle_billboard_mode
Values for particle billboard mode.
mk_particle_blend_modetypedef
typedef enum mk_particle_blend_mode mk_particle_blend_mode
Values for particle blend mode.
mk_particle_burst_desctypedef
typedef struct mk_particle_burst_desc mk_particle_burst_desc
Data for particle burst desc.
mk_particle_collider_typetypedef
typedef enum mk_particle_collider_type mk_particle_collider_type
Values for particle collider type.
mk_particle_collision_callback_fntypedef
typedef void(*) mk_particle_collision_callback_fn(void *user_data, const mk_particle_collision_info *collision, mk_particle_collision_response *response, float *bounce, float *friction)
Synchronous CPU collision response hook.
response, bounce, and friction are initialized from the collider and may be overridden. Invalid outputs are ignored. The callback must not mutate or destroy its particle world.
mk_particle_collision_infotypedef
typedef struct mk_particle_collision_info mk_particle_collision_info
Data for particle collision info.
mk_particle_collision_responsetypedef
typedef enum mk_particle_collision_response mk_particle_collision_response
Values for particle collision response.
mk_particle_effect_desctypedef
typedef struct mk_particle_effect_desc mk_particle_effect_desc
Data for particle effect desc.
mk_particle_effect_ttypedef
typedef struct mk_particle_effect mk_particle_effect_t
Data for particle effect.
mk_particle_emitter_desctypedef
typedef struct mk_particle_emitter_desc mk_particle_emitter_desc
Data for particle emitter desc.
mk_particle_emitter_referencestypedef
typedef struct mk_particle_emitter_references mk_particle_emitter_references
Application-resolved, immutable emitter resource IDs.
These remain opaque to the simulation core so particles do not depend on renderer, sprite, animation-graph, or audio modules. The built-in renderer recognizes valid Modkit texture and geometry handle IDs; applications can query every type for their own registries and integrations.
mk_particle_eventtypedef
typedef struct mk_particle_event mk_particle_event
Data for particle event.
mk_particle_event_typetypedef
typedef enum mk_particle_event_type mk_particle_event_type
Values for particle event type.
mk_particle_fallbacktypedef
typedef struct mk_particle_fallback mk_particle_fallback
Data for particle fallback.
mk_particle_fallback_reasontypedef
typedef enum mk_particle_fallback_reason mk_particle_fallback_reason
Values for particle fallback reason.
mk_particle_instance_ttypedef
typedef struct mk_particle_instance mk_particle_instance_t
Data for particle instance.
mk_particle_json_errortypedef
typedef struct mk_particle_json_error mk_particle_json_error
Data for particle JSON error.
mk_particle_overflow_policytypedef
typedef enum mk_particle_overflow_policy mk_particle_overflow_policy
Values for particle overflow policy.
mk_particle_plane_collidertypedef
typedef struct mk_particle_plane_collider mk_particle_plane_collider
Data for particle plane collider.
mk_particle_reference_resolver_fntypedef
typedef bool(*) mk_particle_reference_resolver_fn(void *user_data, mk_particle_reference_type type, const char *name, uint32_t *out_handle_id)
Resolve a logical authored name to a type-specific ID.
Curve and gradient IDs are strongly retained by the immutable effect. Other IDs remain application-owned opaque metadata; valid Modkit texture and geometry IDs are consumed by the batteries-included renderer.
mk_particle_reference_typetypedef
typedef enum mk_particle_reference_type mk_particle_reference_type
Values for particle reference type.
mk_particle_render_instancetypedef
typedef struct mk_particle_render_instance mk_particle_render_instance
Data for particle render instance.
mk_particle_render_styletypedef
typedef struct mk_particle_render_style mk_particle_render_style
Immutable renderer defaults that remain independent of renderer resources.
All-zero selects alpha blending, camera-facing billboards, a full UV rectangle, one atlas frame, unit velocity stretch, and a 0.5 mask cutoff.
mk_particle_render_viewtypedef
typedef struct mk_particle_render_view mk_particle_render_view
Data for particle render view.
mk_particle_renderer_typetypedef
typedef enum mk_particle_renderer_type mk_particle_renderer_type
Values for particle renderer type.
mk_particle_shape_desctypedef
typedef struct mk_particle_shape_desc mk_particle_shape_desc
Data for particle shape desc.
mk_particle_shape_typetypedef
typedef enum mk_particle_shape_type mk_particle_shape_type
Values for particle shape type.
mk_particle_sort_modetypedef
typedef enum mk_particle_sort_mode mk_particle_sort_mode
Values for particle sort mode.
mk_particle_spacetypedef
typedef enum mk_particle_space mk_particle_space
Values for particle space.
mk_particle_sphere_collidertypedef
typedef struct mk_particle_sphere_collider mk_particle_sphere_collider
Data for particle sphere collider.
mk_particle_statstypedef
typedef struct mk_particle_stats mk_particle_stats
Data for particle stats.
mk_particle_sub_emitter_desctypedef
typedef struct mk_particle_sub_emitter_desc mk_particle_sub_emitter_desc
Data for particle sub emitter desc.
mk_particle_sub_emitter_eventtypedef
typedef enum mk_particle_sub_emitter_event mk_particle_sub_emitter_event
Values for particle sub emitter event.
mk_particle_trail_pointtypedef
typedef struct mk_particle_trail_point mk_particle_trail_point
Data for particle trail point.
mk_particle_trail_spantypedef
typedef struct mk_particle_trail_span mk_particle_trail_span
Data for particle trail span.
mk_particle_trail_viewtypedef
typedef struct mk_particle_trail_view mk_particle_trail_view
Data for particle trail view.
mk_particle_viewtypedef
typedef struct mk_particle_view mk_particle_view
Data for particle view.
mk_particle_world_desctypedef
typedef struct mk_particle_world_desc mk_particle_world_desc
Data for particle world desc.
mk_particle_world_ttypedef
typedef struct mk_particle_world mk_particle_world_t
Type used for particle world.