echo

A 2D Physics library written in Haxe.

Echo focuses on maintaining a simple API that is easy to integrate into any engine/framework (Heaps, OpenFL, Kha, etc). All Echo needs is an update loop and its ready to go!

Try the Samples 🎮!

Check out the API 📖!

Features

• Semi-implicit euler integration physics
• SAT-powered collision detection
• Quadtree for broadphase collision querying
• Collision listeners to provide collision callbacks
• Physics State History Management with Built-in Undo/Redo functionality
• Extendable debug drawing

Getting Started

Echo requires Haxe 4.2+ to run.

Install the library from haxelib:

haxelib install echo

Alternatively the dev version of the library can be installed from github:

haxelib git echo https://github.com/AustinEast/echo.git

Then for standard Haxe applications, include the library in your project's .hxml:

-lib echo

For OpenFL users, add the library into your Project.xml:

<haxelib name="echo" />

For Kha users (who don't use haxelib), clone echo to thee Libraries folder in your project root, and then add the following to your khafile.js:

project.addLibrary('echo');

Usage

Concepts

Echo

The Echo Class holds helpful utility methods to help streamline the creation and management of Physics Simulations.

World

A World is an Object representing the state of a Physics simulation and it configurations.

Bodies

A Body is an Object representing a Physical Body in a World. A Body has a position, velocity, mass, optional collider shapes, and many other properties that are used in a World simulation.

Shapes

A Body's collider is represented by different Shapes. Without a Shape to define it's form, a Body can be thought of a just a point in the World that cant collide with anything.

Available Shapes:

• Rectangle
• Circle
• Polygon (Convex Only)

When a Shape is added to a Body, it's transform (x, y, rotation) becomes relative to its parent Body. In this case, a Shape's local transform can still be accessed through shape.local_x, shape.local_y, and shape.local_rotation.

It's important to note that all Shapes (including Rectangles) have their origins centered.

Lines

Use Lines to perform Linecasts against other Lines, Bodies, and Shapes. Check out the Echo class for various methods to preform Linecasts.

Listeners

Listeners keep track of collisions between Bodies - enacting callbacks and physics responses depending on their configurations. Once you add a Listener to a World, it will automatically update itself as the World is stepped forward.

Integration

Codebase Integration

Echo has a couple of ways to help integrate itself into codebases through the Body class.

First, the Body class has two public fields named on_move and on_rotate. If these are set on a body, they'll be called any time the body moves or rotates. This is useful for things such as syncing the Body's transform with external objects:

var body = new echo.Body();
body.on_move = (x,y) -> entity.position.set(x,y);
body.on_rotate = (rotation) -> entity.rotation = rotation;

Second, a build macro is available to add custom fields to the Body class, such as a reference to an Entity class:

in build.hxml:

--macro echo.Macros.add_data("entity", "some.package.Entity")

in Main.hx

var body = new echo.Body();
body.entity = new some.package.Entity();

Other Math Library Integration

Echo comes with basic implementations of common math structures (Vector2, Vector3, Matrix3), but also allows these structures to be extended and used seamlessly with other popular Haxe math libraries.

Support is currently available for the following libraries (activated by adding the listed compiler flag to your project's build parameters):

Library	Compiler Flag
hxmath	ECHO_USE_HXMATH
vector-math	ECHO_USE_VECTORMATH
zerolib	ECHO_USE_ZEROLIB
heaps	ECHO_USE_HEAPS

(pull requests for other libraries happily accepted!)

If you compile your project with a standard .hxml:

# hxmath support
-lib hxmath
-D ECHO_USE_HXMATH

For OpenFL users, add one of the following into your Project.xml:

<!-- hxmath support -->
<haxelib name="hxmath" />
<haxedef name="ECHO_USE_HXMATH" />

For Kha users, add one of the following into your khafile.js:

// hxmath support
project.addLibrary('hxmath');
project.addDefine('ECHO_USE_HXMATH');

Examples

Basic

import echo.Echo;

class Main {
  static function main() {
    // Create a World to hold all the Physics Bodies
    // Worlds, Bodies, and Listeners are all created with optional configuration objects.
    // This makes it easy to construct object configurations, reuse them, and even easily load them from JSON!
    var world = Echo.start({
      width: 64, // Affects the bounds for collision checks.
      height: 64, // Affects the bounds for collision checks.
      gravity_y: 20, // Force of Gravity on the Y axis. Also available for the X axis.
      iterations: 2 // Sets the number of Physics iterations that will occur each time the World steps.
    });

    // Create a Body with a Circle Collider and add it to the World
    var a = world.make({
      material: {elasticity: 0.2},
      shape: {
        type: CIRCLE,
        radius: 16,
      }
    });

    // Create a Body with a Rectangle collider and add it to the World
    // This Body will be static (ie have a Mass of `0`), rendering it as unmovable
    // This is useful for things like platforms or walls.
    var b = world.make({
      mass: STATIC, // Setting this to Static/`0` makes the body unmovable by forces and collisions
      y: 48, // Set the object's Y position below the Circle, so that gravity makes them collide
      material: {elasticity: 0.2},
      shape: {
        type: RECT,
        width: 10,
        height: 10
      }
    });

    // Create a listener and attach it to the World.
    // This listener will react to collisions between Body "a" and Body "b", based on the configuration options passed in
    world.listen(a, b, {
      separate: true, // Setting this to true will cause the Bodies to separate on Collision. This defaults to true
      enter: (a, b, c) -> trace("Collision Entered"), // This callback is called on the first frame that a collision starts
      stay: (a, b, c) -> trace("Collision Stayed"), // This callback is called on frames when the two Bodies are continuing to collide
      exit: (a, b) -> trace("Collision Exited"), // This callback is called when a collision between the two Bodies ends
    });

    // Set up a Timer to act as an update loop (at 60fps)
    new haxe.Timer(16).run = () -> {
      // Step the World's Physics Simulation forward (at 60fps)
      world.step(16 / 1000);
      // Log the World State in the Console
      echo.util.Debug.log(world);
    }
  }
}

Samples

Check out the source code for the Echo Samples here: https://github.com/AustinEast/echo/tree/master/sample/state

Engine/Framework Specific

• HaxeFlixel: https://github.com/AustinEast/echo-flixel
• Heaps: https://github.com/AustinEast/echo-heaps
• Peyote View: https://github.com/maitag/peote-views-samples/tree/master/echo
• HaxePunk: https://github.com/XANOZOID/EchoHaxePunk

Roadmap

Sooner

• Endless length Line support
• Update Readme with info on the various utilities (Tilemap, Bezier, etc)

Later

• Allow Concave Polygons (through Convex Decomposition)
• Sleeping Body optimations
• Constraints
• Compiler Flag to turn off a majority of inlined functions (worse performance, but MUCH smaller filesize)