A Body is an Object representing a Physical Body in a World.

Bodies have position, velocity, mass, an optional collider shape, and many other properties that are used in a World simulation.

Static variables

@:value(AUTO)staticdefault_mass:MassType = AUTO

staticread onlydefaults:BodyOptions

Default Body Options

@:value(0.0001)staticfinalread onlyminimum_mass:Float = 0.0001

Constructor

new(?options:Null<BodyOptions>)

Creates a new Body.

Parameters:

options

Optional values to configure the new Body

Variables

@:value(new Vector2(0, 0))acceleration:Vector2 = new Vector2(0, 0)

A measure of how fast a Body will change it's velocity.

Can be thought of the sum of all external forces on an object during a step.

active:Bool

Flag to set if the Body is active and will participate in a World's Physics calculations or Collision querys.

collided:Bool

Flag to check if the Body collided with something during the step. Used for debug drawing.

read onlydata:Dynamic

Dynamic Object to store any user data on the Body. Useful for Callbacks.

dirty:Bool

Flag to check if the Body has changed its position, rotation, or shape colliders. Used for Collision optimization.

read onlydisposed:Bool

@:value(new Vector2(0, 0))drag:Vector2 = new Vector2(0, 0)

A measure of how fast a Body will move its velocity's x and y components towards 0, when there is no acceleration.

Note: this is calculated separately from a Body's drag_length, so be careful when applying both.

drag_length:Float

A measure of how fast a Body will move its velocity towards 0 along the velocity's length, when there is no acceleration.

Note: this is calculated separately from a Body's drag, so be careful when applying both.

elasticity:Float

Deprecated: "Elasticity Value has been moved into the Material object. Use `body.material.elasticity instead."

Value to determine how much of a Body's velocity should be retained during collisions (or how much should the Body "bounce", in other words).

gravity_scale:Float

Deprecated: "Gravity Value has been moved into the Material object. Use `body.material.gravity_scale instead."

Percentage value that represents how much a World's gravity affects the Body.

read onlyid:Int

Unique id of the Body.

read onlyinverse_mass:Float

Cached value of 1 divided by the Body's mass. Used in Internal calculations.

kinematic:Bool

Flag to set how a Body is affected by Collisions.

If set to true, the Body will still Collide and move through the world, but it will not be moved by external collision forces. This is useful for things like moving platforms.

@:allow(echo.Physics.step_body)read onlylast_rotation:Float

@:allow(echo.Physics.step_body)read onlylast_x:Float

@:allow(echo.Physics.step_body)read onlylast_y:Float

@:value(new BitMask())layer_mask:BitMask = new BitMask()

Collision layers that this Body will collide with. Combine with layers to filter collisions between layers.

Note: a maximum of 32 layers are supported.

@:value(new BitMask())layers:BitMask = new BitMask()

Collision layers that this Body belongs to. Combine with layer_mask to filter collisions between layers.

Note: a maximum of 32 layers are supported.

mass:Float

The Body's mass. Affects how the Body reacts to Collisions and Acceleration Forces. The higher a Body's mass, the more resistant it is to those forces.

If a Body's mass is set to 0, it becomes static - unmovable by forces and collisions.

@:value(Material.global)material:Material = Material.global

max_rotational_velocity:Float

The maximum rotational velocity range that a Body can have.

If set to 0, the Body has no restrictions on how fast it can rotate.

@:value(new Vector2(0, 0))max_velocity:Vector2 = new Vector2(0, 0)

The maximum values a Body's velocity's x and y components can be. If set to 0, the Body has no restrictions on how fast it can move.

Note: this is calculated separately from a Body's max_velocity_length, so be careful when applying both.

max_velocity_length:Float

The maximum velocity that a Body can have along the velocity's length. If set to 0, the Body has no restrictions on how fast it can move.

Note: this is calculated separately from a Body's max_velocity, so be careful when applying both.

on_move:Null<(Float, Float) ‑> Void>

If set, this method is called whenever the Body's X or Y changes.

on_rotate:Null<Float ‑> Void>

If set, this method is called whenever the Body's rotation changes.

rotation:Float

Body's current rotational angle as Degrees.

rotational_drag:Float

A measure of how fast a Body will move its rotational_velocity towards 0.

rotational_velocity:Float

The units/second that a Body will rotate.

scale_x:Float

Body's scale on the X axis.

scale_y:Float

Body's scale on the Y axis.

shape:Null<Shape>

The Body's first Shape object in the shapes array. If it isn't null, this Shape object act as the Body's Collider, allowing it to be checked for Collisions.

read onlyshapes:Array<Shape>

The Body's array of Shape objects. If the array isn't empty, these Shape objects act as the Body's Collider, allowing it to be checked for Collisions.

NOTE: If adding shapes directly to this Array, make sure to parent the Shape to the Body (ie shape.set_parent(body.frame);).

@:value(0)torque:Float = 0

A measure of how fast a Body will change it's rotational velocity.

Can be thought of the sum of all external rotation forces on an object during a step.

@:value(new Transform())transform:Transform = new Transform()

Structure to help perform matrix calculations for the Body's position, rotation, and scale.

@:value(new Vector2(0, 0))velocity:Vector2 = new Vector2(0, 0)

The units/second that a Body moves.

@:allow(echo.World)read onlyworld:World

The World that this body is attached to. It can only be a part of one World at a time.

x:Float

The Body's position on the X axis.

y:Float

The Body's position on the Y axis.

Methods

@:value({ position : -1 })inlineadd_shape(shape:Shape, position:Int = -1):Shape

Adds a Shape to the Body.

If mass has not been manually set, It's recommended to call calculate_mass() after adding/removing a Body's shapes.

Parameters:

shape
position

The position in the Body's shapes array the Shape will be added to. If set to -1, the Shape is pushed to the end.

Returns:

The added Shape.

bounds(?aabb:AABB):AABB

If a Body has shapes, it will return an AABB representing the bounds of the Body's shapes relative to its position. If the Body does not have any shapes, this will return `null'.

Parameters:

aabb

Optional AABB to set the values to. If the Body does not have any shapes, the AABB will not be set.

Returns:

Null

inlinecalculate_mass():Void

Calculates the Body's mass based on the volume of it's shapes and the density defined in it's Material.

This should be called whenever a Body's overall shape is changed, such as in cases of changing the Body's scale - or if an individual shape on the Body has been added, removed, moved, rotated, or scaled.

inlineclear_shapes():Void

Clears all Shapes from the Body, releasing them to their respective pools.

If mass has not been manually set, It's recommended to call calculate_mass() after adding/removing a Body's shapes.

@:value({ position : -1 })inlinecreate_shape(options:ShapeOptions, position:Int = -1):Shape

Adds a new Shape to the Body based on the ShapeOptions passed in.

If mass has not been manually set, It's recommended to call calculate_mass() after adding/removing a Body's shapes.

Parameters:

options
position

The position in the Body's shapes array the Shape will be added to. If set to -1, the Shape is pushed to the end.

Returns:

The newly created Shape.

dispose():Void

Disposes the Body. DO NOT use the Body after disposing it, as it could lead to null reference errors.

get_position(?vec2:Vector2):Vector2

Gets the Body's position as a new Vector2 (or sets the Vector2, if passed in).

inlineis_dynamic():Bool

Checks if the Body is Dynamic (if it's mass is greater than 0).

Returns:

body.mass > 0

inlineis_static():Bool

Checks if the Body is Static (if it's mass is equal to 0).

Returns:

body.mass == 0

load_options(?options:Null<BodyOptions>):Void

Sets a Body's values from a BodyOptions object.

Parameters:

null

options

inlinemoved():Bool

Returns true if the Body has moved since the last Physics.step().

@:value({ force_type : ACCELERATION, forward : false, y : 0, x : 0 })push(x:Float = 0, y:Float = 0, forward:Bool = false, force_type:ForceType = ACCELERATION):Void

Adds forces to a Body.

Options are available to apply the forces relative to the Body's forward, or to configure whether the forces are applied to the Body's acceleration, velocity, or position.

Parameters:

x
y
forward

Set as true to apply the forces relative to the Body's forward (based on the Body's rotation).

force_type

Determines whether the forces are applied to the Body's acceleration, velocity, or position.

inlineremove():Body

If the Body is attached to a World, it is removed.

Returns:

The detached Body.

inlineremove_shape(shape:Shape):Shape

Removes a Shape from the Body.

If mass has not been manually set, It's recommended to call calculate_mass() after adding/removing a Body's shapes.

Parameters:

shape

The Shape to remove.

Returns:

Shape The removed Shape.

@:value({ y : 0, x : 0 })set_position(x:Float = 0, y:Float = 0):Void

inlineupdate_static_bounds():Void

If the Body is Static, update it's Quadtree Bounds.