Client particles and movement queries

From Sunrise's modding bookead8a1e

Client particles

ClientHost::add_particle submits the API's ParticleOptions, a world position and velocity to the ordinary client particle queue. The client must have a loaded player and world. Non-finite numeric inputs are refused. A successful submission does not promise a visible particle: provider availability, sprite sets, distance and the player's particle settings apply. This method is not available on ServerHost.

Particle options carry a ParticleKey, not an engine particle enum or a provider name. Request the key with Registrar::particle_key during registration and retain it. The game resolves provider identities once when content loads. ParticleOptions::simple(key) handles both vanilla and custom sprite providers; custom providers require an assets/<namespace>/particles/<path>.json sprite set. All option constructors take the resolved key, including dust, item, trail, vibration, shriek, sculk_charge and dust_transition. Use the corresponding vanilla key for these parameter families. Sending an option performs no string parsing or registry scan.

For stack-derived breaking or eating particles, call ClientHost::item_particle_options(&stack) and pass the returned options to add_particle. This read resolves the ground model with seed 0, preserving all layer particle sprites and resource-pack and stack-component overrides. It returns None for invalid stacks or unavailable resources/provider. It is available in Setup, Reloading and World, on native and wasm. Resolve again after resource reloads. It allocates a sprite list only when called; it adds no per-tick work.

Client fireworks

ClientHost::create_fireworks draws a firework's explosions from a FireworksRequest: the position, the rocket's velocity carried by the sparks, a list of FireworkExplosions (shape, colours, fade colours, trail, twinkle) and audible. It uses the starter a bursting rocket uses, so the explosions follow each other every other tick as a rocket's do. With audible false the sparks and flash draw but the blast and twinkle sounds don't play, as for a silent rocket. Nothing reaches the server or other players: a mod's server half tells each client half to draw it. The request is refused on a server, without a loaded client player and world, for non-finite numbers and for more than 256 explosions.

Bot movement and block collisions

PlayerRef::simulate_move predicts one server player's movement tick from PlayerInput, using the game's movement implementation without replacing the live player's body. It returns SimulatedMove with position, velocity, ground, horizontal-collision and sprinting results. It refuses stale or inaccessible players, dead players, spectators, riders and invalid numeric input. A supplied velocity is input to the prediction, not a write to the player.

LevelRef::collision_boxes reads block collision boxes within a finite, ordered axis-aligned box. It excludes entity and border collisions. A refused level or a query covering more than 1,000,000 cells returns None; a valid query with no collisions returns Some containing an empty vector. Keep queries bounded rather than scanning a whole level each tick.

LevelRef::block_shape(host, state, pos, kind) reads an explicit BlockState's outline or collision boxes with an empty context at a position in that level. The supplied state can differ from the world's block, without changing it; level-dependent shape inputs come from the actual level. To query the stored block, first read level.block_state(host, pos) and pass that state. This server read returns block-local boxes, or None for a stale handle, closed level or client. Parked levels are supported.

Edit this page on GitHub · Spotted something wrong? Open an issue or ask on Discord.