altanis / kinetics

A blazingly fast physics engine for both servers and the web, written in TypeScript 🔥

_{Credits to SimplyTav for creating this logo.}

About

A blazingly fast, simple 2D physics engine for JavaScript and TypeScript, for both frontend and backend applications.

Features

• System/Entity Architecture Support
• Built-in Canvas2D Renderer
• Fast Narrowphase Collision Detection
• Fast Broadphase Collision Detection
• Fast Collision Resolution
• Collision Callbacks

Installation

To install this package on a server or a web framework, use the following command:

npm install kinetics.ts

For a vanilla HTML/CSS/JS project, use the following script tag:

<script src="https://cdn.jsdelivr.net/gh/Altanis/kinetics-ts/build/kinetics.min.js" defer></script>

and all of the engine's classes will be available under the Kinetics namespace (window.Kinetics.System, window.Kinetics.Entity, etc.).

Benchmarks

A 1920x1080 rectangular system of 1,000 entities was benchmarked, where each entity had a radius randomly selected between 3 and 13. Entity sleeping was disabled for each benchmark.

System Specifications:

• Apple M2 chip
• 8-core CPU with 4 performance cores and 4 efficiency cores
• 8-core GPU
• 16-core Neural Engine
• 100GB/s memory bandwidth

The benchmarks provide evidence of the engine's exceptional speed and performance in comparison to other alternatives.

kinetics's Issues

`CollisionResolver.detect()` requires specific order depending on entities

When calling detect(entity1, entity2), the collision is inaccurate depending on the order of parameters.

`detectLineLine` does not get invoked at starting time.

CollisionResolver.detectLineLine() does not get invoked at starttime if two lines are in eachothers' collision ranges.

Importing `Capsule` throws an error where its subclass (`Line`) is undefined.

I suspect an issue with circular referencing.

Line collision inaccuracies with fast entities

Line collisions (and possibly hitboxes) are inaccurate.

Implement circle collisions

The SAT detection algorithm does not account for circles/circular objects.

Make wall generation up to the client

The code enforces a rectangular boundary system with the private System.defineBoundaries method. Make defining walls up to the client.

Question about positioning entities.

Hey, I would first like to sincerely thank you for developing this library. It has been amazing tampering around with it regardless of my limited coding knowledge.

I have managed to create a very simple system which spawns a controllable square that can collide with a triangle. I am sure there may be other problems with my current approach but here comes my question:

How do I determine where to position the square or triangle? I have tried using the position property but have failed tremendously.

Here is my current code:

`const { System, Entity, Vector, Movement } = Kinetics;
const system = new System({
tickRate: 60,
friction: 0.1,
gravity: 0,
collisionInfo: { cellSize: 6 },
render: {
canvas: document.getElementById('gameCanvas'),
hooks: {
postRender: function () {
const movements = Array.from(keys).map(key => {
switch (key) {
case 'KeyW': return Movement.Up;
case 'KeyS': return Movement.Down;
case 'KeyA': return Movement.Left;
case 'KeyD': return Movement.Right;
}
})
square1.move(...movements);
}
}
}
});

function createEntity(vertices, mass, speed, system) {
const entity = new Entity({
form: { vertices },
mass: mass,
speed: speed,
}, system);

system.addEntity(entity);
return entity;
}

const squareVertices = [
new Vector(-20, -20),
new Vector(-20, 20),
new Vector(20, 20),
new Vector(20, -20)
];

const triangleVertices = [
new Vector(-20, -20),
new Vector(0, 20),
new Vector(20, -20)
];

const square1 = createEntity(squareVertices, 10, 1, system); // Mass, speed, etc...
const triangle1 = createEntity(triangleVertices, 10, 1, system); // Mass, speed, etc...

const keys = new Set();

document.addEventListener("keydown", (event) => keys.add(event.code));
document.addEventListener("keyup", (event) => keys.delete(event.code));`

Collision resolution issues

The "push" to fix the overlap doesnt work due to the chance that two entities overlap on two axes.

Regular polygon generation.

Include a flag in EntityInfo which says the number of sides. If defined as a first instance of Entity, utilize it to make a regular n-gon of a variable amount of sides (using the same method as wall generation).

Is there a 'Wall' class?

I like the structure of your physics engine and am adding features to it. Is there a way to make wall implementation easier here?

Entity with vertices colliding with wall deforms entity.

When an entity collides with the wall, the entity's size gets changed.

This is due to one vertex not moving (due to colliding with the wall), while the others do move, causing the side lengths to change.

Fix `System.addEntity`.

If two new Entity() classes are instantiated without being added through System.addEntity, they will have the same ID and issues will occur. Overhaul the current ID system for more efficiency.

New Features

Features which must be completed in order of necessity:

• Collision detection/resolution between different types of polygons.
  • Utilize the Separating Axis Theorem.
  • Utilize Minimum Translation Vectors.
  • Apply a valid push force when two entities overlap.
• Inbuilt canvas rendering system.
• Gravity.
• Compound entities which can merge two different entities (e.g. jewish star by merging two triangles).
• Collision detection/resolution of concave entities by partitioning the entity into convex parts.
• New types of objects.
  • "String constraint" which can hold an object and cause oscillation (like a pendulum)
  • Jointed objects.
• Documentation.
• Orbitrals.

Angular velocity when colliding not perfectly accurate

        entity1.angularVelocity += ((1 / entity1.inertia) * axis.cross(entity1.center.clone.subtract(entity2.center)) * impulse) / 1000;
        entity2.angularVelocity -= ((1 / entity2.inertia) * axis.cross(entity1.center.clone.subtract(entity2.center)) * impulse) / 1000;

Two issues:

• The inertia property of an Entity may not be accurate for generic entities.
• The division by 1000 is due to the angular velocity being too fast on its own. Requires a real accurate approach to fix.

Implement CCD

For fast moving entities, entities may phase through eachother.

Smoothen physics engine for browsers.

Use requestAnimationFrame rather than setInterval if config.useRAF is set to true and a browser environment is detected.

smallestAxis calculation in CollisionResolver

CollisionResolver.resolve() sometimes get passed a NaN or empty vector for the smallestAxis parameter.

Dynamic Getters Inaccurate in the Wall Class

The Wall class has getters in place for properties such as minX, width, etc.

They are not accurate.

Rename Wall to Line

Optimize/enhance physics calculations and collision detection/resolution.

• Merge CollisionResolver.detect and CollisionResolver.resolve functions (many overlapping calculations between the two).
• Optimize spatial hashing detection.
• Return Entity[] from spatial hashing in O(1) time rather than iterating over query array.
• Optimize out the Set functions, as they are extremely slow.
• Remove refreshBounds, and make bounds simply a getter (experiment effect on perf)
• [?] Detect parallel line segments to minimize the amount of axis projection calculations.

Are the physics calculations decoupled?

I know it might be inconvenient to keep asking questions here, but I have one last problem with my project I can't seem to fix. After reading through the documentation I can't tell if the physics engine is able to update the state of the entities without the need to render them.

I coded a separate canvas which renders the entities differently with WebGL (by using pixi.js). Both canvases are running at the same time, with the first rendering the default Kinetics shapes and the second the WebGL shapes overlapped on top of the first. The WebGL shapes follow the rotation and position of the Kinetics shapes, and the system works perfectly. The only concern I have is the optimization, which should be improved by only rendering the second canvas, hence my question. I can of course provide my code if requested.

After reading the documentation I attempted using system.renderer = null, but with no success. Would this be possible?

I am sure it would be possible for one to know this, but I am not the most experienced programmer right now lol,

Thank you for creating this.