Scripting API

Scripting API

Physics2D

Class in Abyss.Physics2D, from Abyss.Physics2D.

Physics 2D, as a game's code reaches it: context.Services.Get<Physics2D>(). 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 Box2D steps; a body's velocities are its Rigidbody2D'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 Physics2D

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 Rigidbody2D by the next step, it does nothing.

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.

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. Physics2DSettings.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 Physics2DSettings.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. A swept shape stops within half a centimeter of touching what it meets: a box just short of it, a round shape just into it, as Box2D sweeps them.

Properties

CollisionsEntered

public IReadOnlyList<Collision2D> CollisionsEntered { get; }

The bodies whose colliders began touching, each pair once however many colliders of theirs did, with the colliders that touched first, where and along which normal. A body is an entity with a Rigidbody 2D, of its own colliders and those under it on no body nearer, or ground: a collider with no Rigidbody 2D at or above it. A trigger touches nothing; two bodies that are both ground — no Rigidbody 2D, or a static one — never do.

CollisionsExited

public IReadOnlyList<Collision2D> 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<Trigger2D> 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 in ground is nothing, and a body's trigger never finds that body.

TriggersExited

public IReadOnlyList<Trigger2D> TriggersExited { get; }

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

JointsBroken

public IReadOnlyList<JointBroken2D> 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 step ended: seen as what touched is.

CollisionsStaying

public IReadOnlyList<Collision2D> CollisionsStaying { get; }

The pairs of bodies whose colliders touch as the last step left them — those that began in it among them — 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<Trigger2D> 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

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, and a character's move passes through. How a character drops down through a one-way platform, and a sword thrown 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.

GetIgnoreCollision

public bool GetIgnoreCollision(ulong a, ulong b)

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

Parameters

  • a
  • b

AddForce

public void AddForce(ulong entity, Vector2 force)

Pushes a body with force, in newtons, for the next step: what a jet or wind does.

Parameters

  • entity
  • force

AddImpulse

public void AddImpulse(ulong entity, Vector2 impulse)

Gives a body impulse at once, in newton-seconds: what a jump or a hit does.

Parameters

  • entity
  • impulse

AddTorque

public void AddTorque(ulong entity, float torque)

Turns a body with torque for the next step, anticlockwise.

Parameters

  • entity
  • torque

AddAngularImpulse

public void AddAngularImpulse(ulong entity, float impulse)

Gives a body a turning impulse at once, anticlockwise.

Parameters

  • entity
  • impulse

MovePosition

public void MovePosition(ulong entity, Vector2 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 character 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, float degrees)

Turns a body to degrees, anticlockwise, over the next step, where it stops: by 45 degrees at most, as far as Box2D turns a body in a step. With Physics2D.MovePosition in the same step, it is moved and turned at once.

Parameters

  • entity
  • degrees

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: what a game asks of two it knows, between the enter and the exit.

Parameters

  • a
  • b

Raycast

public RaycastHit2D? Raycast(Vector2 origin, Vector2 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 RaycastHit2D[] RaycastAll(Vector2 origin, Vector2 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.

CircleCast

public RaycastHit2D? CircleCast(Vector2 origin, float radius, Vector2 direction, float distance = Infinity, LayerMask? layers = null)

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

Parameters

  • origin: Where the circle'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 RaycastHit2D? BoxCast(Vector2 origin, Vector2 size, float angle, Vector2 direction, float distance = Infinity, LayerMask? layers = null)

What a box of size, turned angle degrees anticlockwise, swept from origin along direction meets first: as Physics2D.CircleCast.

Parameters

  • origin: Where the box's middle starts, in world space.
  • size: How wide and high it is, in meters.
  • angle: How far it is turned, in degrees anticlockwise.
  • 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 RaycastHit2D? CapsuleCast(Vector2 origin, Vector2 size, CapsuleDirection2D capsuleDirection, float angle, Vector2 direction, float distance = Infinity, LayerMask? layers = null)

What a capsule of size, its length along capsuleDirection and turned angle degrees anticlockwise, swept from origin along direction meets first: as Physics2D.CircleCast.

Parameters

  • origin: Where the capsule's middle starts, in world space.
  • size: How wide and high it is, in meters, its rounded ends among it, as a Capsule Collider 2D's.
  • capsuleDirection: Which way it is long, as a Capsule Collider 2D's.
  • angle: How far it is turned, in degrees anticlockwise.
  • 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(Vector2 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.

OverlapCircle

public ulong[] OverlapCircle(Vector2 center, float radius, LayerMask? layers = null)

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

Parameters

  • center: The circle'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(Vector2 center, Vector2 size, float angle = 0, 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 and high it is, in meters.
  • angle: How far it is turned, in degrees anticlockwise.
  • layers: The layers whose colliders are found; every layer, left out.

OverlapCapsule

public ulong[] OverlapCapsule(Vector2 center, Vector2 size, CapsuleDirection2D capsuleDirection, float angle = 0, 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.
  • size: How wide and high it is, in meters, its rounded ends among it, as a Capsule Collider 2D's.
  • capsuleDirection: Which way it is long, as a Capsule Collider 2D's.
  • angle: How far it is turned, in degrees anticlockwise.
  • layers: The layers whose colliders are found; every layer, left out.