Skip to content
modkitv0.2

particles.h

#include <modkit/particles.h>45 functions · 24 structs · 14 enums · 41 typedefs · 2 macros

Deterministic, explicit-world 2D/3D particle simulation.

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.

ParameterTypeDescription
worldconst mk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
drawstruct 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
countuint32_tNumber of entries.

mk_particle_effect_createfunction

mk_particle_effect_t mk_particle_effect_create(const mk_particle_effect_desc *desc)

Create an immutable effect.

ParameterTypeDescription
descconst 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.

ParameterTypeDescription
effectmk_particle_effect_tValue 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.

ParameterTypeDescription
effectmk_particle_effect_tValue for effect.
emitter_indexuint32_tValue for emitter index.
typemk_particle_reference_typeValue for type.
out_handle_iduint32_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.

ParameterTypeDescription
effectmk_particle_effect_tValue for effect.
emitter_indexuint32_tValue for emitter index.
out_stylemk_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.

ParameterTypeDescription
asset_idconst char *Value for asset ID.
resolvermk_particle_reference_resolver_fnValue for resolver.
resolver_user_datavoid *Value for resolver user data.
errormk_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.

ParameterTypeDescription
jsonconst char *Value for JSON.
resolvermk_particle_reference_resolver_fnValue for resolver.
resolver_user_datavoid *Value for resolver user data.
errormk_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.

ParameterTypeDescription
effectmk_particle_effect_tValue 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.

ParameterTypeDescription
worldconst mk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
selectionmk_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.

ParameterTypeDescription
worldconst mk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
min_boundsmk_vec3 *Value for min bounds.
max_boundsmk_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.

ParameterTypeDescription
worldconst mk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
fallbacksmk_particle_fallback *Value for fallbacks.
capacityuint32_tValue 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
view_positionmk_vec3Value for view position.
view_forwardmk_vec3Value for view forward.
viewmk_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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
view_positionmk_vec3Value for view position.
view_forwardmk_vec3Value for view forward.
viewmk_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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
viewmk_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.

ParameterTypeDescription
worldconst mk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
viewmk_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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
effectmk_particle_effect_tValue 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue 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.

ParameterTypeDescription
worldconst mk_particle_world_t *Value for world.
instancemk_particle_instance_tValue 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.

ParameterTypeDescription
worldconst mk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
typemk_particle_reference_typeValue for type.
out_handle_iduint32_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.

ParameterTypeDescription
worldconst mk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
out_stylemk_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.

ParameterTypeDescription
worldconst mk_particle_world_t *Value for world.
instancemk_particle_instance_tValue 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.

mk_particle_playfunction

void mk_particle_play(mk_particle_world_t *world, mk_particle_instance_t instance)

Play particle.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
durationfloatValue for duration.

mk_particle_restartfunction

void mk_particle_restart(mk_particle_world_t *world, mk_particle_instance_t instance)

Perform the particle restart operation.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
replacementmk_particle_effect_tValue 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
timefloatValue 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
callbackmk_particle_collision_callback_fnCompletion callback.
user_datavoid *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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
forcemk_vec3Value 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
opacityfloatValue 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
ratefloatValue 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
view_positionmk_vec3Value for view position.
view_forwardmk_vec3Value 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
time_scalefloatValue 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
tintmk_vec4Value 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
widthfloatValue 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
emitter_indexuint32_tValue for emitter index.
transformconst 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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
instancemk_particle_instance_tValue for instance.
clearboolValue for clear.

mk_particle_world_createfunction

mk_particle_world_t * mk_particle_world_create(const mk_particle_world_desc *desc)

Create particle world.

ParameterTypeDescription
descconst 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.

ParameterTypeDescription
worldmk_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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
eventsmk_particle_event *Value for events.
capacityuint32_tValue 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.

ParameterTypeDescription
worldconst mk_particle_world_t *Value for world.
statsmk_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.

ParameterTypeDescription
worldmk_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.

ParameterTypeDescription
worldmk_particle_world_t *Value for world.
dtfloatValue for dt.

Structs

mk_particle_aabb_colliderstruct

Data for particle aabb collider.

FieldTypeDescription
minmk_vec3The min.
maxmk_vec3The max.
bouncefloatThe bounce.
frictionfloatThe friction.
responsemk_particle_collision_responseThe response.

mk_particle_burst_descstruct

Data for particle burst desc.

FieldTypeDescription
timefloatThe time.
countuint32_tThe count.

mk_particle_collision_infostruct

Data for particle collision info.

FieldTypeDescription
emitter_indexuint32_tThe emitter index.
emission_indexuint64_tThe emission index.
collider_typemk_particle_collider_typeThe collider type.
collider_indexuint32_tThe collider index.
positionmk_vec3Simulation-space contact position.
velocitymk_vec3Simulation-space incoming velocity.
normalmk_vec3The normal.
penetration_depthfloatThe penetration depth.

mk_particle_effectstruct

Data for particle effect.

FieldTypeDescription
iduint32_tThe ID.

mk_particle_effect_descstruct

Data for particle effect desc.

FieldTypeDescription
emittersconst mk_particle_emitter_desc *The emitters.
emitter_countuint32_tThe emitter count.

mk_particle_emitter_descstruct

Data for particle emitter desc.

FieldTypeDescription
capacityuint32_tThe capacity.
seeduint64_tThe seed.
backendmk_particle_backendThe backend.
spacemk_particle_spaceThe space.
renderermk_particle_renderer_typeThe renderer.
referencesmk_particle_emitter_referencesThe references.
render_stylemk_particle_render_styleThe render style.
sortingmk_particle_sort_modeGPU view depth requires mk_particle_set_sort_view before preparation.
overflowmk_particle_overflow_policyThe overflow.
ratefloatThe rate.
distance_ratefloatParticles per unit of emitter travel.
durationfloatThe duration.
loopboolThe loop.
prewarmfloatThe prewarm.
fixed_stepfloat0 selects 1/60.
max_steps_per_calluint32_t0 selects 8.
shapemk_particle_shape_descThe shape.
lifetimemk_scalar_distributionThe lifetime.
speedmk_scalar_distributionThe speed.
sizemk_scalar_distributionThe size.
rotationmk_scalar_distributionThe rotation.
angular_velocitymk_scalar_distributionThe angular velocity.
directionmk_vec3The direction.
gravitymk_vec3The gravity.
constant_forcemk_vec3The constant force.
force_centermk_vec3Center in the emitter's simulation space.
radial_forcefloatThe radial force.
vortex_axismk_vec3The vortex axis.
vortex_forcefloatThe vortex force.
noise_strengthfloatThe noise strength.
noise_frequencyfloatDeterministic noise samples per second.
dragfloatThe drag.
velocity_over_lifemk_curve_tThe velocity over life.
size_over_lifemk_curve_tThe size over life.
rotation_over_lifemk_curve_tThe rotation over life.
color_over_lifemk_gradient_tThe color over life.
trail_historyuint32_t0 selects 16 for trail renderers.
trail_min_distancefloatThe trail min distance.
trail_widthfloat0 selects 1.
trail_width_over_trailmk_curve_tThe trail width over trail.
trail_color_over_trailmk_gradient_tThe trail color over trail.
trail_uv_tilingfloat0 selects 1 repeat per simulation unit.
trail_segment_limituint32_t0 selects trail_history - 1.
trail_smoothingfloat[0, 1] neighbor smoothing; endpoints remain fixed.
initial_colormk_vec4The initial color.
initial_color_distributionmk_color_distributionThe initial color distribution.
use_initial_color_distributionboolThe use initial color distribution.
burstsconst mk_particle_burst_desc *The bursts.
burst_countuint32_tThe burst count.
sub_emittersconst mk_particle_sub_emitter_desc *The sub emitters.
sub_emitter_countuint32_tThe sub emitter count.
plane_collidersconst mk_particle_plane_collider *The plane colliders.
plane_collider_countuint32_tThe plane collider count.
aabb_collidersconst mk_particle_aabb_collider *The aabb colliders.
aabb_collider_countuint32_tThe aabb collider count.
sphere_collidersconst mk_particle_sphere_collider *The sphere colliders.
sphere_collider_countuint32_tThe sphere collider count.
birth_eventsboolThe birth events.
death_eventsboolThe death events.
collision_eventsboolThe 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.

FieldTypeDescription
textureuint32_tThe texture.
spriteuint32_tThe sprite.
geometryuint32_tThe geometry.
materialuint32_tThe material.
sub_effectuint32_tThe sub effect.
graphuint32_tThe graph.
audiouint32_tThe audio.

mk_particle_eventstruct

Data for particle event.

FieldTypeDescription
instancemk_particle_instance_tThe instance.
emitter_indexuint32_tThe emitter index.
emission_indexuint64_tThe emission index.
typemk_particle_event_typeThe type.
positionmk_vec3The position.
velocitymk_vec3The velocity.

mk_particle_fallbackstruct

Data for particle fallback.

FieldTypeDescription
emitter_indexuint32_tThe emitter index.
requestedmk_particle_backendThe requested.
selectedmk_particle_backendThe selected.
reasonmk_particle_fallback_reasonThe reason.

mk_particle_instancestruct

Data for particle instance.

FieldTypeDescription
iduint32_tThe ID.

mk_particle_json_errorstruct

Data for particle JSON error.

FieldTypeDescription
offsetsize_tThe offset.
messagecharThe message.

mk_particle_plane_colliderstruct

Data for particle plane collider.

FieldTypeDescription
normalmk_vec3The normal.
distancefloatdot(normal, position) + distance = 0
bouncefloatThe bounce.
frictionfloatThe friction.
responsemk_particle_collision_responseThe response.

mk_particle_render_instancestruct

Data for particle render instance.

FieldTypeDescription
positionmk_vec3Interpolated world-space position.
velocitymk_vec3World-space velocity.
scalemk_vec3World-space absolute scale.
colormk_vec4The color.
rotationfloatThe rotation.
normalized_agefloatThe normalized age.
emission_indexuint64_tThe 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.

FieldTypeDescription
blendmk_particle_blend_modeThe blend.
billboardmk_particle_billboard_modeThe billboard.
billboard_axismk_vec3Zero selects +Y.
velocity_stretchfloatZero selects 1.
uv_rectmk_vec4All-zero selects 0,0,1,1.
atlas_columnsuint16_tZero selects 1.
atlas_rowsuint16_tZero selects 1.
atlas_framesuint32_tZero selects every atlas cell.
alpha_cutofffloatMasked only; zero selects 0.5.

mk_particle_render_viewstruct

Data for particle render view.

FieldTypeDescription
instancesconst mk_particle_render_instance *The instances.
countuint32_tThe count.
renderermk_particle_renderer_typeThe renderer.

mk_particle_shape_descstruct

Data for particle shape desc.

FieldTypeDescription
typemk_particle_shape_typeThe type.
extentsmk_vec3The extents.
radiusfloatThe radius.
anglefloatCone half-angle, radians.

mk_particle_sphere_colliderstruct

Data for particle sphere collider.

FieldTypeDescription
centermk_vec3The center.
radiusfloatThe radius.
bouncefloatThe bounce.
frictionfloatThe friction.
responsemk_particle_collision_responseThe response.
circle_2dboolThe circle 2D.

mk_particle_statsstruct

Data for particle stats.

FieldTypeDescription
spawneduint64_tCPU births plus GPU spawn requests dispatched.
dieduint64_tThe died.
droppeduint64_tExact on CPU; GPU reports only drops known before dispatch.
fixed_stepsuint64_tThe fixed steps.
allocation_failuresuint64_tThe allocation failures.
events_droppeduint64_tThe events dropped.
sub_emissions_droppeduint64_tThe sub emissions dropped.
draw_callsuint64_tThe draw calls.
dispatch_callsuint64_tThe dispatch calls.
cpu_update_nsuint64_tCumulative host time spent in world_step.
cpu_sort_nsuint64_tCumulative host time spent in exact CPU sorts.
gpu_prepare_nsuint64_tCumulative host time encoding GPU preparation.
gpu_upload_bytesuint64_tBytes uploaded while synchronizing GPU emitters.
transient_bytesuint64_tCumulative frame-scoped instance/ribbon bytes requested.
cpu_sorted_particlesuint64_tThe CPU sorted particles.
cpu_simulated_particlesuint64_tThe CPU simulated particles.
gpu_scheduled_ticksuint64_tThe GPU scheduled ticks.
gpu_sorted_capacityuint64_tSort-key capacity processed by GPU sorting passes.
transient_failuresuint64_tThe transient failures.
fallback_emittersuint64_tCurrent live emitters running on a fallback backend.
gpu_authoritative_emittersuint64_tThe GPU authoritative emitters.
aliveuint32_tExact on CPU; conservative upper bound for GPU-authoritative emitters.

mk_particle_sub_emitter_descstruct

Data for particle sub emitter desc.

FieldTypeDescription
eventmk_particle_sub_emitter_eventThe event.
target_emitteruint32_tThe target emitter.
countuint32_tThe count.
intervalfloatRequired for timer events; ignored otherwise.

mk_particle_trail_pointstruct

Data for particle trail point.

FieldTypeDescription
positionmk_vec3The position.
colormk_vec4The color.
widthfloatThe width.
ufloatThe u.
emission_indexuint64_tThe emission index.

mk_particle_trail_spanstruct

Data for particle trail span.

FieldTypeDescription
firstuint32_tThe first.
countuint32_tThe count.

mk_particle_trail_viewstruct

Data for particle trail view.

FieldTypeDescription
pointsconst mk_particle_trail_point *The points.
spansconst mk_particle_trail_span *The spans.
point_countuint32_tThe point count.
span_countuint32_tThe span count.

mk_particle_viewstruct

Data for particle view.

FieldTypeDescription
positionsconst mk_vec3 *The positions.
previous_positionsconst mk_vec3 *Previous fixed-tick positions.
velocitiesconst mk_vec3 *The velocities.
colorsconst mk_vec4 *The colors.
agesconst float *The ages.
lifetimesconst float *The lifetimes.
sizesconst float *The sizes.
rotationsconst float *The rotations.
emission_indicesconst uint64_t *The emission indices.
orderconst uint32_t *Optional indices into the arrays above.
countuint32_tThe count.
interpolation_alphafloatAccumulator / fixed step, clamped to [0, 1].

mk_particle_world_descstruct

Data for particle world desc.

FieldTypeDescription
instance_capacityuint32_t0 selects 128.
event_capacityuint32_t0 selects 1024.
sub_emission_capacityuint32_t0 selects event_capacity.
compute_supportedboolThe compute supported.
indirect_supportedboolThe indirect supported.
instancing_supportedboolThe instancing supported.

Enums

mk_particle_backendenum

Values for particle backend.

ValueDescription
MK_PARTICLE_BACKEND_AUTOSelects auto.
MK_PARTICLE_BACKEND_CPUSelects CPU.
MK_PARTICLE_BACKEND_GPUSelects GPU.

mk_particle_billboard_modeenum

Values for particle billboard mode.

ValueDescription
MK_PARTICLE_BILLBOARD_CAMERA_FACINGSelects camera facing.
MK_PARTICLE_BILLBOARD_AXIALSelects axial.
MK_PARTICLE_BILLBOARD_VELOCITY_STRETCHEDSelects velocity stretched.

mk_particle_blend_modeenum

Values for particle blend mode.

ValueDescription
MK_PARTICLE_BLEND_ALPHASelects alpha.
MK_PARTICLE_BLEND_ADDITIVESelects additive.
MK_PARTICLE_BLEND_MASKEDSelects masked.

mk_particle_collider_typeenum

Values for particle collider type.

ValueDescription
MK_PARTICLE_COLLIDER_PLANESelects plane.
MK_PARTICLE_COLLIDER_AABBSelects aabb.
MK_PARTICLE_COLLIDER_SPHERESelects sphere.

mk_particle_collision_responseenum

Values for particle collision response.

ValueDescription
MK_PARTICLE_COLLISION_BOUNCESelects bounce.
MK_PARTICLE_COLLISION_KILLSelects kill.

mk_particle_event_typeenum

Values for particle event type.

ValueDescription
MK_PARTICLE_EVENT_BIRTHSelects birth.
MK_PARTICLE_EVENT_DEATHSelects death.
MK_PARTICLE_EVENT_COLLISIONSelects collision.

mk_particle_fallback_reasonenum

Values for particle fallback reason.

ValueDescription
MK_PARTICLE_FALLBACK_NONESelects none.
MK_PARTICLE_FALLBACK_COMPUTE_UNAVAILABLESelects compute unavailable.
MK_PARTICLE_FALLBACK_INDIRECT_UNAVAILABLESelects indirect unavailable.
MK_PARTICLE_FALLBACK_INSTANCING_UNAVAILABLESelects instancing unavailable.
MK_PARTICLE_FALLBACK_CPU_EVENTSSelects CPU events.
MK_PARTICLE_FALLBACK_CPU_CALLBACKSelects CPU callback.
MK_PARTICLE_FALLBACK_UNSUPPORTED_MODULESelects unsupported module.
MK_PARTICLE_FALLBACK_GPU_RESOURCE_FAILURESelects GPU resource failure.

mk_particle_overflow_policyenum

Values for particle overflow policy.

ValueDescription
MK_PARTICLE_OVERFLOW_DROP_NEWSelects drop new.
MK_PARTICLE_OVERFLOW_REPLACE_OLDESTSelects replace oldest.

mk_particle_reference_typeenum

Values for particle reference type.

ValueDescription
MK_PARTICLE_REFERENCE_CURVESelects curve.
MK_PARTICLE_REFERENCE_GRADIENTSelects gradient.
MK_PARTICLE_REFERENCE_TEXTURESelects texture.
MK_PARTICLE_REFERENCE_SPRITESelects sprite.
MK_PARTICLE_REFERENCE_GEOMETRYSelects geometry.
MK_PARTICLE_REFERENCE_MATERIALSelects material.
MK_PARTICLE_REFERENCE_SUB_EFFECTSelects sub effect.
MK_PARTICLE_REFERENCE_GRAPHSelects graph.
MK_PARTICLE_REFERENCE_AUDIOSelects audio.

mk_particle_renderer_typeenum

Values for particle renderer type.

ValueDescription
MK_PARTICLE_RENDERER_SPRITE_2DSelects sprite 2D.
MK_PARTICLE_RENDERER_BILLBOARD_3DSelects billboard 3D.
MK_PARTICLE_RENDERER_MESHSelects mesh.
MK_PARTICLE_RENDERER_TRAILSelects trail.

mk_particle_shape_typeenum

Values for particle shape type.

ValueDescription
MK_PARTICLE_SHAPE_POINTSelects point.
MK_PARTICLE_SHAPE_LINESelects line.
MK_PARTICLE_SHAPE_BOXSelects box.
MK_PARTICLE_SHAPE_CIRCLESelects circle.
MK_PARTICLE_SHAPE_DISCSelects disc.
MK_PARTICLE_SHAPE_SPHERESelects sphere.
MK_PARTICLE_SHAPE_HEMISPHERESelects hemisphere.
MK_PARTICLE_SHAPE_CONESelects cone.

mk_particle_sort_modeenum

Values for particle sort mode.

ValueDescription
MK_PARTICLE_SORT_NONESelects none.
MK_PARTICLE_SORT_EMISSIONSelects emission.
MK_PARTICLE_SORT_AGESelects age.
MK_PARTICLE_SORT_VIEW_DEPTHSelects view depth.

mk_particle_spaceenum

Values for particle space.

ValueDescription
MK_PARTICLE_SPACE_LOCALSelects local.
MK_PARTICLE_SPACE_WORLDSelects world.

mk_particle_sub_emitter_eventenum

Values for particle sub emitter event.

ValueDescription
MK_PARTICLE_SUB_EMIT_BIRTHSelects birth.
MK_PARTICLE_SUB_EMIT_DEATHSelects death.
MK_PARTICLE_SUB_EMIT_COLLISIONSelects collision.
MK_PARTICLE_SUB_EMIT_TIMERSelects timer.

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.

Macros

MK_PARTICLE_EFFECT_INVALIDdefine

MK_PARTICLE_EFFECT_INVALID

Invalid sentinel for particle effect.

MK_PARTICLE_INSTANCE_INVALIDdefine

MK_PARTICLE_INSTANCE_INVALID

Invalid sentinel for particle instance.