Class PhysicsWorld¶
Namespace: Apogee.Physics
Assembly: Apogee.Physics.dll
The physics simulation of one ECS
public sealed class PhysicsWorld : EngineObject, IDisposable
Inheritance¶
object ← EngineObject ← PhysicsWorld
Implements¶
Inherited Members¶
EngineObject.IsAdopted, EngineObject.Handle, EngineObject.IsDestroyed, EngineObject.Class, EngineObject.Adopt(), EngineObject.TryGet(SlotHandle, out EngineObject), EngineObject.Destroy(), object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.ReferenceEquals(object?, object?), object.ToString()
Remarks¶
A frame calls World.Progress, so that the transforms the physics wrote are the ones the frame's systems see and the transform system
composes. Everything runs on the thread that calls it (Jolt's workers run inside
Constructors¶
PhysicsWorld(World, PhysicsOptions?)¶
Makes the physics world of ecs. Dispose it before the ECS world.
public PhysicsWorld(World ecs, PhysicsOptions? options = null)
Parameters¶
ecs World
options PhysicsOptions?
Properties¶
BodyCount¶
How many bodies the world has.
public int BodyCount { get; }
Property Value¶
BodySlept¶
public Signal<Entity> BodySlept { get; }
Property Value¶
BodyWoke¶
A body with
public Signal<Entity> BodyWoke { get; }
Property Value¶
Class¶
What the registry knows about this object's class.
public override ClassInfo Class { get; }
Property Value¶
ContactBegan¶
Two bodies started touching, at least one of them with
public Signal<Entity, Entity, Double3, Vector3> ContactBegan { get; }
Property Value¶
Signal<Entity, Entity, Double3, Vector3>
ContactEnded¶
public Signal<Entity, Entity> ContactEnded { get; }
Property Value¶
DebugDraw¶
Draw the bodies, joints and characters over the world (wireframes, colored by what each body is): the host that renders the world calls physics.debug_draw = true; the dev overlay has a checkbox.
public bool DebugDraw { get; set; }
Property Value¶
DroppedEvents¶
Events that did not fit the queue and were lost (see
public long DroppedEvents { get; }
Property Value¶
Ecs¶
The ECS world this one simulates.
public World Ecs { get; }
Property Value¶
Gravity¶
public Vector3 Gravity { get; set; }
Property Value¶
Interpolate¶
Show bodies between their last two steps instead of at the last one: smooth at any frame rate, at the price of showing the past by up to a step.
public bool Interpolate { get; set; }
Property Value¶
Paused¶
While true
public bool Paused { get; set; }
Property Value¶
SensorEntered¶
A body came into a sensor: the sensor's entity, then the other.
public Signal<Entity, Entity> SensorEntered { get; }
Property Value¶
SensorExited¶
public Signal<Entity, Entity> SensorExited { get; }
Property Value¶
StepSeconds¶
Seconds per step (
public float StepSeconds { get; }
Property Value¶
Stepping¶
Emitted before each fixed step with its length. Vehicle controllers and anything else that must act once per step belongs here, not in a frame callback.
public Signal<float> Stepping { get; }
Property Value¶
Steps¶
The number of steps taken so far.
public long Steps { get; }
Property Value¶
Methods¶
AddBody(Entity, BodyDesc)¶
Gives entity a body made as desc describes, where its transform puts it now (its scale scales the shape). The entity gets a
public void AddBody(Entity entity, BodyDesc desc)
Parameters¶
entity Entity
desc BodyDesc
AddForce(Entity, Vector3)¶
A force in newtons through the center of mass, applied during the next step only (call it every step to push continuously).
public void AddForce(Entity entity, Vector3 force)
Parameters¶
entity Entity
force Vector3
AddImpulse(Entity, Vector3)¶
An instant change of momentum in newton seconds through the center of mass.
public void AddImpulse(Entity entity, Vector3 impulse)
Parameters¶
entity Entity
impulse Vector3
AddTorque(Entity, Vector3)¶
public void AddTorque(Entity entity, Vector3 torque)
Parameters¶
entity Entity
torque Vector3
CastSphere(Double3, Vector3, float, float, uint, Entity)¶
Sweeps a sphere along direction and returns the first body it touches: whether there was one, the entity, the point of contact, the normal and how far the sphere got.
public (bool Hit, Entity Entity, Double3 Point, Vector3 Normal, float Distance) CastSphere(Double3 origin, Vector3 direction, float radius, float maxDistance, uint mask = 16383, Entity ignore = default)
Parameters¶
origin Double3
direction Vector3
radius float
maxDistance float
mask uint
ignore Entity
Returns¶
(bool Hit, Entity Entity, Double3 Point, Vector3 Normal, float Distance)
Create(World)¶
Makes the physics of an ECS world from a script (a game's own is the global physics). Destroy it, or let the script drop it, before the ECS world goes.
public static PhysicsWorld Create(World ecs)
Parameters¶
ecs World
Returns¶
CreateCharacter(Entity, float, float, uint, uint)¶
Makes a walking character for entity: a capsule of this height (feet to top, at least twice the radius) and radius, standing with its feet at the entity's position.
layers and mask are the collision layers it is in and collides with.
public CharacterController CreateCharacter(Entity entity, float height, float radius, uint layers = 1, uint mask = 16383)
Parameters¶
entity Entity
height float
radius float
layers uint
mask uint
Returns¶
CreateHitch(Entity, HitchKind)¶
Makes a hitch of kind on hitchEntity, which must be under the entity of a dynamic body (the vehicle): its transform is the hitch's frame in the
vehicle's space. Move the entity to lift what a mount hitch carries.
public Hitch CreateHitch(Entity hitchEntity, HitchKind kind)
Parameters¶
hitchEntity Entity
kind HitchKind
Returns¶
CreateVehicle(Entity, VehicleDesc)¶
Makes a vehicle of desc on the dynamic body of entity. The vehicle's space is the entity's, +Z forward, +Y up, +X left. Set its inputs, drive_ratio and
clutch in its stepping signal (or the world's); destroying the vehicle, its body or its entity ends it.
public Vehicle CreateVehicle(Entity entity, VehicleDesc desc)
Parameters¶
entity Entity
desc VehicleDesc
Returns¶
Dispose()¶
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
public void Dispose()
DrawDebug(DebugDraw, PhysicsDebugOptions?, Double3)¶
Adds the picture of the world (options says what) to draw, in world positions. camera picks the level of detail of round shapes.
The drawing is of the state the last
public void DrawDebug(DebugDraw draw, PhysicsDebugOptions? options = null, Double3 camera = default)
Parameters¶
draw DebugDraw
options PhysicsDebugOptions?
camera Double3
GetAngularVelocity(Entity)¶
public Vector3 GetAngularVelocity(Entity entity)
Parameters¶
entity Entity
Returns¶
GetLinearVelocity(Entity)¶
public Vector3 GetLinearVelocity(Entity entity)
Parameters¶
entity Entity
Returns¶
GetMass(Entity)¶
The mass of the body of entity in kilograms (0 for a static or kinematic one).
public float GetMass(Entity entity)
Parameters¶
entity Entity
Returns¶
HasBody(Entity)¶
Whether entity has a body here.
public bool HasBody(Entity entity)
Parameters¶
entity Entity
Returns¶
IsAwake(Entity)¶
public bool IsAwake(Entity entity)
Parameters¶
entity Entity
Returns¶
OnDestroyed()¶
protected override void OnDestroyed()
OverlapBox(Double3, Quaternion, Vector3, uint, Entity)¶
The entities of the bodies that touch this box (centered on center, turned by rotation), each once.
public Entity[] OverlapBox(Double3 center, Quaternion rotation, Vector3 halfExtents, uint mask = 16383, Entity ignore = default)
Parameters¶
center Double3
rotation Quaternion
halfExtents Vector3
mask uint
ignore Entity
Returns¶
Entity[]
OverlapSphere(Double3, float, uint, Entity)¶
The entities of the bodies that touch this sphere (sensors excluded), each once.
public Entity[] OverlapSphere(Double3 center, float radius, uint mask = 16383, Entity ignore = default)
Parameters¶
center Double3
radius float
mask uint
ignore Entity
Returns¶
Entity[]
Pose(Entity)¶
The exact pose of the body in the world after the last step (the entity's own transform may show a blend between two steps, see
public (Double3 Position, Quaternion Rotation) Pose(Entity entity)
Parameters¶
entity Entity
Returns¶
(Double3 Position, Quaternion Rotation)
Raycast(Double3, Vector3, float, uint, Entity)¶
Casts a ray and returns the nearest hit: whether there was one, the entity, the hit point, the surface normal and the distance. mask picks the collision layers
that count; ignore is an entity (the shooter's own body) the ray passes through. Sensors are never hit.
public (bool Hit, Entity Entity, Double3 Point, Vector3 Normal, float Distance) Raycast(Double3 origin, Vector3 direction, float maxDistance, uint mask = 16383, Entity ignore = default)
Parameters¶
origin Double3
direction Vector3
maxDistance float
mask uint
ignore Entity
Returns¶
(bool Hit, Entity Entity, Double3 Point, Vector3 Normal, float Distance)
RemoveBody(Entity)¶
Takes the body off entity (the entity stays, where the body left it).
public void RemoveBody(Entity entity)
Parameters¶
entity Entity
SetAngularVelocity(Entity, Vector3)¶
public void SetAngularVelocity(Entity entity, Vector3 velocity)
Parameters¶
entity Entity
velocity Vector3
SetLinearVelocity(Entity, Vector3)¶
public void SetLinearVelocity(Entity entity, Vector3 velocity)
Parameters¶
entity Entity
velocity Vector3
Teleport(Entity, Double3, Quaternion)¶
Puts the body at this world pose at once, keeping its velocity, and its entity too (no blend). For a static body this is how it moves at all.
public void Teleport(Entity entity, Double3 position, Quaternion rotation)
Parameters¶
entity Entity
position Double3
rotation Quaternion
Update(float)¶
Advances the simulation by deltaSeconds of game time in fixed steps (at most World.Progress.
public void Update(float deltaSeconds)
Parameters¶
deltaSeconds float
Wake(Entity)¶
public void Wake(Entity entity)
Parameters¶
entity Entity