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 WorldParticles

Remarks

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

  • entity
  • clear

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

  • entity
  • count

Exceptions

  • ArgumentOutOfRangeException: count is 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

  • picked
  • paused

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

  • entity
  • into

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 = 1

The version of the particle colliders' contract this binding was written against: ParticleCast, ParticleHit and the function RegisterColliders takes. A provider registers with it.