Scripting API

Scripting API

Physics3D

Class in Abyss.Physics3D, from Abyss.Physics3D.

Physics 3D, as a game's code reaches it: context.Services.Get<Physics3D>(). What it is asked to do to a body — a force, an impulse, a move to a place — is done at the next fixed step, before Jolt steps; a body's velocities are its Rigidbody3D's fields, set directly. What touched and what went into triggers, and what a ray, a swept shape or an overlap finds, it says of the world as the last step left it.

public sealed class Physics3D

Remarks

Safe from any system, parallel ones included: what is asked is queued, under a lock, and what is read is kept for every system to read alike. Asked of an entity with no Rigidbody3D by the next step, or a static one, it does nothing; a force or an impulse moves only a dynamic body.

Which contacts a system sees. The step runs alone, before the game's own fixed systems: a fixed system sees what touched in that step. A system of the frame sees what touched in every step since the frame before, which is none, one or several as the frame was long. Either way each is seen once, and every system sees the same. A body falling asleep where it rests is still touching what it rests on, and in a trigger it sleeps in.

Queries find colliders where the last step left them: an entity made or moved since is found where the next step puts it. A layer mask left out asks of every layer; the matrix of which layers meet has no say, nor do pairs asked not to meet. Physics3DSettings.QueriesHitTriggers says whether triggers are found. A ray or a shape that starts inside a collider hits it where it starts, at no distance, its normal back along the way it was going — unless Physics3DSettings.QueriesStartInColliders is off, and it passes over it to what is beyond, so a ray down from a body's middle finds what is under it.

Properties

CollisionsEntered

public IReadOnlyList<Collision3D> CollisionsEntered { get; }

The bodies whose colliders began touching, each pair once however many colliders of theirs did, with the colliders that touched first, where, along which normal, how fast and how hard. A trigger touches nothing; two bodies that do not move — ground, a static or a kinematic body — never do.

CollisionsExited

public IReadOnlyList<Collision3D> CollisionsExited { get; }

The bodies whose colliders stopped touching, the last pair of colliders of theirs parting: moved apart, or one taken away or no longer meeting the other's layer.

TriggersEntered

public IReadOnlyList<Trigger3D> TriggersEntered { get; }

The bodies that went into a trigger — a collider with Is Trigger ticked, named by its own entity whether it is a body's own or under one — each once however many colliders of theirs did, with the collider that went in first. A trigger finds what moves and what does not, but ground's finds no ground, and a body's trigger never finds that body.

TriggersExited

public IReadOnlyList<Trigger3D> TriggersExited { get; }

The bodies that came out of a trigger: moved out, or it or they taken away.

JointsBroken

public IReadOnlyList<JointBroken3D> JointsBroken { get; }

The joints that broke, each held harder than its Break Force or Break Torque in a step, and taken off its entity as the fixed systems end, before the next step.

CollisionsStaying

public IReadOnlyList<Collision3D> CollisionsStaying { get; }

The pairs of bodies whose colliders touch as the last step left them — those that began in it among them, and those asleep where they rest — each pair once, with a collider of each, a point, the normal and how fast they go against each other there: what is still touching, every step it is.

TriggersStaying

public IReadOnlyList<Trigger3D> TriggersStaying { get; }

The bodies inside a trigger as the last step left them, those that went in during it among them, each once a trigger.

Methods

TouchingOf

public ulong[] TouchingOf(ulong entity)

The bodies entity touches as the last step left it: for a body, or ground, those whose colliders touch its own, and the triggers it is inside; for a trigger, the bodies inside it.

Parameters

  • entity

IsTouching

public bool IsTouching(ulong a, ulong b)

Whether the bodies a and b touch, or one is in the other's trigger, named by the trigger's own entity, as the last step left them.

Parameters

  • a
  • b

IgnoreCollision

public void IgnoreCollision(ulong a, ulong b, bool ignore = true)

Has two entities — each a body, or one collider of one — not meet from the next step, or meet again: no touch between them, nor a push, nor a trigger's going in. How a thrown sword misses its thrower. Queries still find both. Kept until the game stops.

Parameters

  • a: One entity: a body, or a collider.
  • b: The other.
  • ignore: True for them not to meet, false for them to meet again.

CreateMesh

public MeshId CreateMesh(in MeshData data, MeshShape3D shape)

Makes a mesh of data, as World.CreateMesh does, and hands Physics 3D its shape, worked out ahead (MeshShape3D.Prepare), in one call: a Mesh Collider 3D of the mesh meets it from the first step it asks, the step making nothing of it. Any thread.

Parameters

  • data
  • shape

Exceptions

  • InvalidOperationException: The shape was handed over, or let go of, already.
  • AbyssException: The data cannot describe a mesh; the shape is still the caller's.

UpdateMesh

public void UpdateMesh(MeshId mesh, in MeshData data, MeshShape3D shape)

Replaces a mesh made by code with data, as World.UpdateMesh does, and hands Physics 3D its shape, worked out ahead (MeshShape3D.Prepare), in one call: a Mesh Collider 3D of the mesh meets the new shape from the next step, as the new data is drawn, the step making nothing of it. Any thread.

Parameters

  • mesh
  • data
  • shape

Exceptions

  • InvalidOperationException: The shape was handed over, or let go of, already.
  • AbyssException: The mesh is refused, as World.UpdateMesh says; the shape is still the caller's.

GetIgnoreCollision

public bool GetIgnoreCollision(ulong a, ulong b)

Whether two entities — bodies or colliders — are asked not to meet; see Physics3D.IgnoreCollision.

Parameters

  • a
  • b

AddForce

public void AddForce(ulong entity, Vector3 force)

Pushes a body with force, in newtons, through its center of mass, for the next step: what a jet or wind does.

Parameters

  • entity
  • force

AddForceAtPosition

public void AddForceAtPosition(ulong entity, Vector3 force, Vector3 position)

Pushes a body with force, in newtons, at position in world space, for the next step: off its center of mass, it turns it as well.

Parameters

  • entity
  • force
  • position

AddImpulse

public void AddImpulse(ulong entity, Vector3 impulse)

Gives a body impulse at once, in newton-seconds, through its center of mass: what a jump or a hit does.

Parameters

  • entity
  • impulse

AddImpulseAtPosition

public void AddImpulseAtPosition(ulong entity, Vector3 impulse, Vector3 position)

Gives a body impulse at once, in newton-seconds, at position in world space: a blow off its middle, which spins it.

Parameters

  • entity
  • impulse
  • position

AddTorque

public void AddTorque(ulong entity, Vector3 torque)

Turns a body with torque, in newton meters about each of the world's axes, for the next step.

Parameters

  • entity
  • torque

AddAngularImpulse

public void AddAngularImpulse(ulong entity, Vector3 impulse)

Gives a body a turning impulse at once, about each of the world's axes.

Parameters

  • entity
  • impulse

MovePosition

public void MovePosition(ulong entity, Vector3 position)

Moves a body to position over the next step, where it stops, pushing what is in its way as it goes: how a kinematic platform or a door is moved, where setting its Transform would jump it there through what is between. Asked each step, it goes on.

Parameters

  • entity
  • position

MoveRotation

public void MoveRotation(ulong entity, Quaternion rotation)

Turns a body to rotation over the next step, where it stops. With Physics3D.MovePosition in the same step, it is moved and turned at once.

Parameters

  • entity
  • rotation

Raycast

public RaycastHit3D? Raycast(Vector3 origin, Vector3 direction, float distance = Infinity, LayerMask? layers = null)

What a ray from origin along direction hits first, within distance meters, on layers: null where it hits nothing.

Parameters

  • origin: Where the ray starts, in world space.
  • direction: Which way it goes, of any length; none hits nothing.
  • distance: How far it goes, in meters; as far as there is, left out.
  • layers: The layers whose colliders it can hit; every layer, left out.

RaycastAll

public RaycastHit3D[] RaycastAll(Vector3 origin, Vector3 direction, float distance = Infinity, LayerMask? layers = null)

Every body a ray hits within distance meters on layers, the nearest first, each once where it is first hit.

Parameters

  • origin: Where the ray starts, in world space.
  • direction: Which way it goes, of any length; none hits nothing.
  • distance: How far it goes, in meters; as far as there is, left out.
  • layers: The layers whose colliders it can hit; every layer, left out.

SphereCast

public RaycastHit3D? SphereCast(Vector3 origin, float radius, Vector3 direction, float distance = Infinity, LayerMask? layers = null)

What a ball of radius swept from origin along direction meets first, within distance meters: the ball stops a hit's RaycastHit3D.Distance along, touching it there. Null where it meets nothing.

Parameters

  • origin: Where the ball's middle starts, in world space.
  • radius: Its radius, in meters.
  • direction: Which way it goes, of any length; none meets nothing.
  • distance: How far it goes, in meters; as far as there is, left out.
  • layers: The layers whose colliders it can meet; every layer, left out.

BoxCast

public RaycastHit3D? BoxCast(Vector3 origin, Vector3 size, Quaternion rotation, Vector3 direction, float distance = Infinity, LayerMask? layers = null)

What a box of size, turned by rotation, swept from origin along direction meets first: as Physics3D.SphereCast.

Parameters

  • origin: Where the box's middle starts, in world space.
  • size: How wide, high and deep it is, in meters.
  • rotation: How it is turned.
  • direction: Which way it goes, of any length; none meets nothing.
  • distance: How far it goes, in meters; as far as there is, left out.
  • layers: The layers whose colliders it can meet; every layer, left out.

CapsuleCast

public RaycastHit3D? CapsuleCast(Vector3 origin, float radius, float height, Quaternion rotation, Vector3 direction, float distance = Infinity, LayerMask? layers = null)

What a capsule of radius and height end to end, upright along its own Y as rotation turns it, swept from origin along direction meets first: as Physics3D.SphereCast.

Parameters

  • origin: Where the capsule's middle starts, in world space.
  • radius: Its radius, in meters.
  • height: How long it is end to end, its round ends among it, as a Capsule Collider 3D's.
  • rotation: How it is turned from upright.
  • direction: Which way it goes, of any length; none meets nothing.
  • distance: How far it goes, in meters; as far as there is, left out.
  • layers: The layers whose colliders it can meet; every layer, left out.

OverlapPoint

public ulong[] OverlapPoint(Vector3 point, LayerMask? layers = null)

The bodies whose colliders on layers are at point, each once.

Parameters

  • point: Where, in world space.
  • layers: The layers whose colliders are found; every layer, left out.

OverlapSphere

public ulong[] OverlapSphere(Vector3 center, float radius, LayerMask? layers = null)

The bodies whose colliders on layers are in or touch a ball, each once.

Parameters

  • center: The ball's middle, in world space.
  • radius: Its radius, in meters.
  • layers: The layers whose colliders are found; every layer, left out.

OverlapBox

public ulong[] OverlapBox(Vector3 center, Vector3 size, Quaternion? rotation = null, LayerMask? layers = null)

The bodies whose colliders on layers are in or touch a box, each once.

Parameters

  • center: The box's middle, in world space.
  • size: How wide, high and deep it is, in meters.
  • rotation: How it is turned; not at all, left out.
  • layers: The layers whose colliders are found; every layer, left out.

OverlapCapsule

public ulong[] OverlapCapsule(Vector3 center, float radius, float height, Quaternion? rotation = null, LayerMask? layers = null)

The bodies whose colliders on layers are in or touch a capsule, each once.

Parameters

  • center: The capsule's middle, in world space.
  • radius: Its radius, in meters.
  • height: How long it is end to end, its round ends among it.
  • rotation: How it is turned from upright; not at all, left out.
  • layers: The layers whose colliders are found; every layer, left out.