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 Physics3DRemarks
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
ab
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
datashape
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
meshdatashape
Exceptions
InvalidOperationException: The shape was handed over, or let go of, already.AbyssException: The mesh is refused, asWorld.UpdateMeshsays; 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
ab
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
entityforce
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
entityforceposition
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
entityimpulse
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
entityimpulseposition
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
entitytorque
AddAngularImpulse
public void AddAngularImpulse(ulong entity, Vector3 impulse)Gives a body a turning impulse at once, about each of the world's axes.
Parameters
entityimpulse
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
entityposition
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
entityrotation
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.
