How to integrate Echo with Heaps engine?

Add the ECHO_USE_HEAPS compiler flag in your khafile.js or hxml, and use the echo-heaps extension for rendering integration. The README provides specific setup steps for Kha and other frameworks.

Does Echo support concave polygons for collision?

No, Echo currently only handles convex polygons. Concave polygon support is planned for a later release, so you'll need to decompose concave shapes into convex ones manually for now.

Echo vs HaxeFlixel physics for 2D games – which should I use?

Echo is engine-agnostic and offers features like undo/redo and broader framework support, while HaxeFlixel's physics is tightly integrated but limited to Flixel. Choose Echo for cross-engine projects or if you need advanced state management.

How to add custom data like an entity reference to Echo bodies?

Use the build macro --macro echo.Macros.add_data("fieldName", "typePath") in your hxml, then assign values directly (e.g., body.entity = new Entity()). This is detailed in the Integration section of the README.

What's the performance impact of Echo's quadtree in large scenes?

The quadtree significantly optimizes collision checks by reducing broadphase queries in dense environments, but it adds memory overhead and setup complexity. Performance scales well, but tune world bounds for best results.

Can Echo be used for server-side physics without a game engine?

Yes, Echo works in headless environments since it only requires an update loop and doesn't depend on rendering. Ensure your math library integrations are compatible, and use the standard Haxe setup without engine-specific flags.

How to implement collision callbacks with separation in Echo?

Create listeners in the world with enter, stay, and exit callbacks, and set the 'separate' option to true for automatic body separation on collision. The basic example in the README shows this configuration.

echo — 2D Physics Library for Haxe

What is echo?

Echo is a 2D physics library written in Haxe that provides robust collision detection and physics simulation with a straightforward API. It is designed for easy integration into various Haxe-based engines and frameworks like Heaps, OpenFL, and Kha, requiring only an update loop to function. The library solves the problem of adding performant and flexible physics to Haxe projects without being tightly coupled to a specific engine.

Target Audience

Haxe developers building 2D games or simulations who need a physics engine that works across multiple Haxe frameworks like Heaps, OpenFL, Kha, HaxeFlixel, and HaxePunk. It is also suitable for developers who prioritize a simple API and easy integration into existing codebases.

Value Proposition

Developers choose Echo for its engine-agnostic design, allowing seamless use with various Haxe math libraries and game engines via compiler flags. Its straightforward API, built-in features like physics state history with undo/redo, and extensible debug drawing provide a balance of performance, flexibility, and ease of use compared to more rigid alternatives.

Simple Physics Library written in Haxe

Use Cases

Best For

Adding 2D physics to Haxe games using engines like Heaps, OpenFL, or Kha without engine-specific dependencies
Implementing collision detection with accurate SAT-powered algorithms for shapes like rectangles, circles, and convex polygons
Creating physics simulations that require undo/redo functionality for state management
Optimizing performance in dense 2D scenes using a quadtree for broadphase collision querying
Developing custom integrations where physics bodies need to sync with external objects via on_move and on_rotate callbacks
Building projects that benefit from extendable debug drawing for visualizing physics bodies and collisions

Not Ideal For

Projects requiring 3D physics simulation or advanced 3D collisions
Teams needing immediate support for concave polygons or physics constraints (both are on the 'Later' roadmap)
Developers working outside the Haxe ecosystem or with game engines not supported via compiler flags
Applications where minimizing file size is critical and the performance trade-off from reducing inlined functions is unacceptable

Pros & Cons

Pros

Engine-Agnostic Flexibility

Integrates seamlessly with multiple Haxe frameworks like Heaps, OpenFL, and Kha via compiler flags, avoiding tight coupling and allowing reuse across projects.

Accurate Collision Detection

Uses Separating Axis Theorem (SAT) for reliable collision detection between rectangles, circles, and convex polygons, ensuring precise physics interactions.

Built-in State History

Features physics state management with undo/redo functionality, a rare inclusion that simplifies debugging and state reverts in simulations.

Performance Optimization

Implements a quadtree for broadphase collision querying, optimizing performance in dense scenes by reducing unnecessary checks.

Easy Code Integration

Provides on_move and on_rotate callbacks and a build macro for adding custom fields to bodies, streamlining synchronization with game entities without boilerplate.

Cons

Limited Shape Support

Only supports convex polygons currently, with concave polygons deferred to the roadmap, restricting collision scenarios for complex shapes.

Haxe-Exclusive Dependency

Tied exclusively to the Haxe ecosystem, making it unsuitable for projects using other languages or engines without Haxe bindings, reducing cross-platform appeal.

Configuration Overhead

Requires specific compiler flags and setup for different math libraries (e.g., hxmath, vector-math), which can be cumbersome and error-prone for newcomers.

Performance-Size Trade-off

The compiler flag to reduce inlined functions sacrifices performance for smaller file size, forcing a compromise that may not suit all use cases.

Frequently Asked Questions

What is echo?

Target Audience

Value Proposition

Use Cases

Best For

Adding 2D physics to Haxe games using engines like Heaps, OpenFL, or Kha without engine-specific dependencies
Implementing collision detection with accurate SAT-powered algorithms for shapes like rectangles, circles, and convex polygons
Creating physics simulations that require undo/redo functionality for state management
Optimizing performance in dense 2D scenes using a quadtree for broadphase collision querying
Developing custom integrations where physics bodies need to sync with external objects via on_move and on_rotate callbacks
Building projects that benefit from extendable debug drawing for visualizing physics bodies and collisions

Not Ideal For

Projects requiring 3D physics simulation or advanced 3D collisions
Teams needing immediate support for concave polygons or physics constraints (both are on the 'Later' roadmap)
Developers working outside the Haxe ecosystem or with game engines not supported via compiler flags
Applications where minimizing file size is critical and the performance trade-off from reducing inlined functions is unacceptable

Pros & Cons

Pros

Engine-Agnostic Flexibility

Integrates seamlessly with multiple Haxe frameworks like Heaps, OpenFL, and Kha via compiler flags, avoiding tight coupling and allowing reuse across projects.

Accurate Collision Detection

Uses Separating Axis Theorem (SAT) for reliable collision detection between rectangles, circles, and convex polygons, ensuring precise physics interactions.

Built-in State History

Features physics state management with undo/redo functionality, a rare inclusion that simplifies debugging and state reverts in simulations.

Performance Optimization

Implements a quadtree for broadphase collision querying, optimizing performance in dense scenes by reducing unnecessary checks.

Easy Code Integration

Provides on_move and on_rotate callbacks and a build macro for adding custom fields to bodies, streamlining synchronization with game entities without boilerplate.

Cons

Limited Shape Support

Only supports convex polygons currently, with concave polygons deferred to the roadmap, restricting collision scenarios for complex shapes.

Haxe-Exclusive Dependency

Tied exclusively to the Haxe ecosystem, making it unsuitable for projects using other languages or engines without Haxe bindings, reducing cross-platform appeal.

Configuration Overhead

Requires specific compiler flags and setup for different math libraries (e.g., hxmath, vector-math), which can be cumbersome and error-prone for newcomers.

Performance-Size Trade-off

The compiler flag to reduce inlined functions sacrifices performance for smaller file size, forcing a compromise that may not suit all use cases.

Frequently Asked Questions

echo

What is echo?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

echo

What is echo?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?