Scripting API
Scripting API
WorldParticles
Struct in Abyss.Core, from Abyss.Core.
Particles, as a game plays them from its code: an entity's ParticleEmitter played, stopped and asked to emit, and asked how it is.
public readonly struct WorldParticlesRemarks
An emitter plays as it says: as play starts if it plays on awake, or as it is spawned while the game plays, sending particles out cycle after cycle while it loops. What is asked here is done on the next frame the game plays, in the order it was asked.
In the editor, a game's particles move only while it plays, hold still while it is paused, and are all gone as it stops. While it is edited, the editor plays what is picked instead (Preview).
Constructors
WorldParticles
public WorldParticles(World world)Particles, as a game plays them from its code: an entity's ParticleEmitter played, stopped and asked to emit, and asked how it is.
Parameters
world: The world they are in.
An emitter plays as it says: as play starts if it plays on awake, or as it is spawned while the game plays, sending particles out cycle after cycle while it loops. What is asked here is done on the next frame the game plays, in the order it was asked.
In the editor, a game's particles move only while it plays, hold still while it is paused, and are all gone as it stops. While it is edited, the editor plays what is picked instead (Preview).
Properties
PreviewState
public ParticlePreviewState PreviewState { get; }How what the editor plays was as of the last frame; see Preview.
Colliders
public IReadOnlyList<ParticleColliderProvider> Colliders { get; }The providers of particle colliders registered, in the order they were.
Methods
Play
public void Play(ulong entity)Starts the emitter on an entity on a cycle, unless it is in one.
Parameters
entity
Exceptions
AbyssException: The id packs no entity, or the world has no particles.
Stop
public void Stop(ulong entity, bool clear = false)Stops the emitter on an entity sending particles out; those out live out their lives, or, with clear, go at once.
Parameters
entityclear
Exceptions
AbyssException: The id packs no entity, or the world has no particles.
Emit
public void Emit(ulong entity, int count)Sends count particles out of the emitter on an entity at once, playing or not, as far as its most allows.
Parameters
entitycount
Exceptions
ArgumentOutOfRangeException:countis below zero.AbyssException: The id packs no entity, or the world has no particles.
StateOf
public ParticleState StateOf(ulong entity)How the emitter on an entity was as of the last frame: none out and not playing for one that has not moved yet.
Parameters
entity
Exceptions
AbyssException: The id packs no entity.
Preview
public void Preview(IReadOnlyList<ulong> picked, bool paused)Has the editor play the emitters on and under picked while the game is edited, each from its start whatever its Play On Awake says, held where they are while paused: from their start as what is picked changes, and none for none. What a game's code asks is not done meanwhile.
Parameters
pickedpaused
Exceptions
AbyssException: An id packs no entity.
RestartPreview
public void RestartPreview()Starts what the editor plays again from nothing on the next frame; see Preview.
RegisterColliders
public void RegisterColliders(string id, string name, bool flat, delegate* unmanaged[Cdecl]<nint, ParticleCast*, uint, uint, ParticleHit*, int> cast, nint context)Registers a physics package's colliders for particles to meet, in place of a provider with the same id: an emitter whose Collision module is in World mode, naming id or on Auto suiting it (2D for one drawn flat, 3D for one that is not), has its particles' moves cast against them once a frame. cast is called on the engine's thread with context, the moves and as many hits to write, and the layers they meet, one bit a layer; it returns 0, or a negative number where it could not cast. Native to native, or an UnmanagedCallersOnly method's address.
Parameters
id: Its stable id: its package's,abyss.physics2d.name: What it is shown as:Physics 2D.flat: Whether it is 2D, reading X and Y alone.cast: Its function:int (nint context, ParticleCast* casts, uint count, uint layers, ParticleHit* hits), called with the C convention.context: What its function is handed back each call.
Exceptions
AbyssException: Another version of the contract, or no id. Nothing in a world with no particles, which nothing meets in.
UnregisterColliders
public bool UnregisterColliders(string id)Unregisters the provider of particle colliders id, whose function is called no more: whether there was one.
Parameters
id
None once the frame loop has ended, which took the world and every provider with it: a package's plugin stopped as the editor closes lets go of its own after that, and is told there was nothing to unregister rather than that the world is gone; see World.LoopEnded.
SubEmitters
public IReadOnlyList<ParticleSubEmitter> SubEmitters(ulong entity)The sub-emitters of the emitter on entity, in the order they are under it: each emitter under it with a Sub Emitter module whose nearest emitter above is it, as the engine fires them. None where it carries no emitter.
Parameters
entity
Read
public int Read(ulong entity, Span<Particle> into)Reads the particles of the emitter on an entity as of the last frame into into, in the world, as many as it holds: how many there are, which may be more. None for an emitter with none out.
Parameters
entityinto
Exceptions
AbyssException: The id packs no entity.
Read
public Particle[] Read(ulong entity)The particles of the emitter on an entity as of the last frame, in the world; none for an emitter with none out.
Parameters
entity
Exceptions
AbyssException: The id packs no entity.
Constants
CollidersVersion
public const uint CollidersVersion = 1The version of the particle colliders' contract this binding was written against: ParticleCast, ParticleHit and the function RegisterColliders takes. A provider registers with it.
