function Entity(; kwargs...)

Create an Entity representing a body in the simulation.


  • name::Symbol: The name for the entity. Necessary, and must be distinct from all other entities in the World.
  • shape::AbstractShape{2} = nothing: The shape of the entity, specified as a 2D primitive from PrimitiveCollisions.jl. Can also be nothing, which removes the entity from the simulation.
  • position::SVector{2,Float64} = @SVector[0.0, 0.0]: The initial position of the entity.
  • velocity::SVector{2,Float64} = @SVector[0.0, 0.0]: The initial velocity of the entity.
  • rotation::Float64 = 0.0: The initial rotation of the entity. Specified in radians in an anticlockwise direction from the positive x-axis.
  • angular_velocity::Float64 = 0.0: The initial angular velocity of the entity. Specified in radians per second, in the same direction as rotation.
  • mass::Float64 = 1.0: The mass of the entity. Can be Inf to make the body immovable.
  • inertia::Float64 = 1.0: The moment of inertia ("rotational mass") of the entity. Can be Inf to make the body impossible to rotate.
  • linear_drag::Float64 = 0.1: The linear drag coefficient. Linear drag force is calculated as the product of this coefficient and the negative of the velocity of the entity.
  • angular_drag::Float64 = 0.1: The angular drag coefficient. Angular drag torque is calculated as the product of this coefficient and the negative of the angular velocity of the entity.
  • bounce::Float64 = 1.0: The coefficient of restitution used during collision resolution is taken as the minimum of the bounce values of the two involved bodies. Typically in the range [0.0, 1.0]. 1.0 is a perfectly elastic collision, 0.0 is a perfectly inelastic collision.

Symbolic variables

In the ODESystem returned by get_system the variables/parameters for an entity are referred to by sightly different names, prefixed by the name of the entity followed by an underscore (_). Following are the names ($name_ is the prefix):

  • $name_pos(t)[1:2]: Position
  • $name_vel(t)[1:2]: velocity
  • $name_acc(t)[1:2]: Acceleration
  • $name_θ(t): Rotation
  • $name_ω(t): Angular velocity
  • $name_α(t): Angular acceleration
  • $name_m: Mass
  • $name_I: Moment of inertia
  • $name_μ: Linear drag coefficient
  • $name_η: Angular drag coefficient
function Entity(template::Entity; kwargs...)

Create an copy of an existing entity template, with some values modified. Keyword arguments are the same as in the keyword constructor, and name must be specified regardless.

function Simulation(world::World, gravity = [0.0, -9.81])

Return a Simulation for the given world, which can be stepped using DifferentialEquations.step! to advance the simulation. Creates the system using get_system, and adds a callback for collision detection. The solver used is AutoTsit5(Rosenbrock23()). The underlying integrator is available as sim.integrator, and intermediate states are not saved during simulation.

function Base.delete!(w::World, sym::Symbol)

Remove the Entity with the name sym from the given World.

function Base.haskey(w::World, sym::Symbol)

Check whether the World contains an entity with name sym.

function get_self_equations(ent::Entity{S}, sts, prs, gravity)

Given an entity, its symbolic states and parameters, and the force of gravity, returns the equations of motion for the entity.

function get_symbols(ent::Entity)

Get the symbolic variables and parameters for the given entity, in a NamedTuple.

function get_system(w::World, gravity = [0.0, -9.81])

Return the ODESystem for the given [World]. Uses the provided value for the acceleration due to gravity, exposed in the ODESystem as g.

function DifferentialEquations.step!(sim::Simulation, args...)

Steps the given [Simulation]. args... are forwarded to DifferentialEquations.step!. See the relevant DiffEq docs for further information.