crystal.physics

Overview

This module contains components to facilitate positioning and moving entities, as well as detecting collisions or overlaps between them. These components are based on LOVE’s physics module which itself relies on Box2D. Box2D is designed to support games with realistic physics and complex interactions. This module hides a lot of said functionality and expose an API which gives more programmatic control.

One important difference between LOVE physics and this module is that Crystal bodies never rotate. Their rotation field is useful to keep track of which direction a character is facing, but has no effect on the actual physics simulation (ie. colliders and sensors components do not rotate).

Many functions in this module rely on categories. Categories are used to describe what type of object a Collider or Sensor represents. Some example categories could be characters, level obstacles, invisible triggers or destructible objects. The list of valid categories must be defined once during game startup via crystal.physics.define_categories.

Examples

This example defines an entity with a position in the world, the ability to move and a circular collision box.

local Hero = Class("Hero", crystal.Entity);
Hero.init = function(self)
  self:add_component(crystal.Body);
  self:add_component(crystal.Movement);
  self:add_component(crystal.Collider, love.physics.newCircleShape(10));
end

local ecs = crystal.ECS:new();
ecs:add_system(crystal.PhysicsSystem);

local hero = ecs:spawn(Hero);

Functions

Name	Description
define_categories	Sets the list of categories that can describe colliders and sensors.

Classes

Name	Description
crystal.Body	A Component representing an entity’s position in space and other physics parameters.
crystal.Collider	Component allowing an entity to collide with others.
crystal.Movement	Component allowing an entity to move of its own volition.
crystal.PhysicsSystem	System powering the components in the crystal.physics module.
crystal.Sensor	Component allowing an entity to detect collision with others without blocking them.