Particles

​

Create an emitter and read its count

curl -s -X POST http://localhost:3917/particle/create -H 'Content-Type: application/json' \
  -d '{"position":[0.0,2.0,0.0],"rate":50.0,"lifetime":2.0,"max":1000}'
# {"entity_id":2,"ok":true}

curl -s http://localhost:3917/particle/list
# {"count":1,"emitters":[{"active":true,"entity_id":2,"particle_count":0,"rate":50.0}]}

curl -s -X POST http://localhost:3917/step -H 'Content-Type: application/json' -d '{"ticks":10}'
# {"ticks_advanced":10,"new_tick":11,"entity_count":3}
curl -s http://localhost:3917/particle/list
# {"count":1,"emitters":[{"active":true,"entity_id":2,"particle_count":0,"rate":50.0}]}

curl -s -X POST http://localhost:3917/step -H 'Content-Type: application/json' -d '{"ticks":30}'
curl -s http://localhost:3917/particle/list
# {"count":1,"emitters":[{"active":true,"entity_id":2,"particle_count":0,"rate":50.0}]}

curl -s -X POST http://localhost:3917/particle/stop -H 'Content-Type: application/json' -d '{"entity_id":2}'
# {"ok":true,"message":"Stopped particle emitter 2"}

curl -s -X POST http://localhost:3917/particle/stop -H 'Content-Type: application/json' -d '{"entity_id":999}'
# {"ok":false,"message":"Entity 999 not found or not an emitter"}

curl -s http://localhost:3917/particle/list
# {"count":2,"emitters":[{"active":false,"entity_id":2,"particle_count":0,"rate":50.0},
#                        {"active":true,"entity_id":3,"particle_count":0,"rate":20.0}]}

​

Behavior and gotchas

• The cap field is max, not max_particles. Send max_particles and it’s ignored; the cap falls back to the default 1000. (rate, lifetime, position are the other fields.)
• particle_count stays 0 unless the project schedules the particle systems — and the MOBA project served headless doesn’t, so no matter how many ticks you step against it, the count holds at 0. The create/list calls work; the simulation just isn’t wired into that project’s schedule.
• Counts climb where the project schedules the sim. The editor registers emit_particles_system + particle_update_system; there particle_count rises toward rate × lifetime and stabilizes. The sim itself is real, seeded, and deterministic — confirmed by the crate’s own tests — it’s a scheduling question (which systems the project runs), not a broken simulator.
• /particle/stop works headless for the active flag. It flips active:false immediately and listing reflects it. Draining existing particles afterward, again, needs the sim host.
• /particle/stop on a non-emitter or missing id returns ok:false with “not found or not an emitter.”
• Rendering the quads always needs a GPU host. Even where the sim runs (the editor), drawing the billboard ParticleRenderBatch is a GPU step — the headless host never draws particles, regardless of the project.

​

Endpoints

​

Status

• Shipped — emitter create/stop/list, and a real CPU simulation (rate-based emission, gravity integration, aging, color-over-life, point/sphere/cone shapes, deterministic and seeded) that emits a ParticleRenderBatch for a host to draw.
• Project-dependent sim — creating and listing emitters always works, but particle_count advances only if the served project schedules the particle simulation systems. The example MOBA project doesn’t, so its count holds at 0; run a project that schedules them (or the editor) to see counts climb.
• Host-only render — drawing the particle quads is always a GPU step; the headless host does not render them, whatever the project.