gridlike : A physics engine tailor-made for making 2D platformers
It is often difficult to handle the movement of your 2D platformer character using generic physics libraries. gridlike is built from the ground up with the intention of being used to build platformers, making the process of creating the logic for a character controller extremely straight forward (literally a dozen or so lines, barely more if you want to get fancy, see below).
It also comes with features that allow you to create modifiable grids like those of terraria or King arthur's gold.
Checkout some of the neat stuff you can do with it here: https://gibss.github.io/test/gridlike/
Install
npm install --save grid-like
Simple usage
Falling square:
var gridlike = // world: the top level instance of the library, create entities and manage layers through itvar world = gridlike // world contains a few function that allow you to create different entities with shapes attached to themvar entity = world var ground = world forvar i = 0; i < 100; i++ entityvy = -10 world console
A (very) simple character controller:
// character creationvar character = world // character logic (to run in your main loop)if characterhasDownContact // character is on the ground // jumping ifjump entityvy = 8 // there are two types of "parenting": // - static: the entity becomes a part of its parent // entity and has no independant movement // - follow: the entity moves within the // referential of the followed parent entity. Perfect for moving platform, ships.. // we use follow here so that the character can stay still on moving platforms character // walking ifmoveLeft charactervx = -speed else ifcharactermoveRight charactervx = speed else charactervx = 0 else // character is in mid-air character // mid-air movement ifmoveLeft entityvx = Math else ifmoveRight entityvx = Math // gravitycharactervy -= 10 * delta
Key features
World creation
gridlike allows you to create the game world you want. The world is made up of entities which themselves contain a list of bodies. You can move entities around with their speed vector (.vx and .vy).
Creating a world
var world = gridlike
Creating entities
// plain entityvar entity = world // entity with a rect attached to itvar entity = world // entity with a line attached to itvar entity = world
Creating bodies
var body = entity
Levels
A very important point to understand is the concept of levels: unlike most physics engine, there is a hierarchy of entities defined by their levels. If entity A is of a greater or equal level to an entity B, A will not be able to affect the trajectory of B. However if B will affect the trajectory of A if their levels are different.
This allows you to define different categories of entities: A ground that is immobile (level 0), ships (level 1) that can only be affected by the ground and a character (level 2) that is moved by both.
Alevel // = 1 Blevel // = 0
Simulation step
world
Grids!
Grids are special bodies that are made up of blocks and lines arranged in a grid.
// initvar entity = world var grid = entitybody // adding blocksgrid grid grid // returns 1
There are quite a few ways of changing the grid and you can also add oneway lines on it aswell. Checkout the declaration file (.d.ts) for more information.
Layering
Layers defined in the world allow you to filter collisions between any two bodies.
Setting layer rules
world // to always collide (the default), layers are created if inexistantworldworld // to collide if the .layerGroup of the two bodies is equalworld // to collide if the .layerGroup of the two bodies is different
Setting layer and layer group on bodies
bodylayer = "layer1"bodylayerGroup = 2 // or var body = entity
Sensors
Sensors do not collide with other bodies, they just overlap and call the attached listener's callback.
Defining a listener
var listener = { console } { console } var entitylistener = listener
Defining a body as a sensor
var body = entity
And more!
Check out the .d.ts definition file at the root of this repository for more information.
Test + Testbed
Tests are included with the library alongside a testbed: a simple web page that has a few very simple use scenarios.
You can also find the testbed at https://gibss.github.io/test/gridlike/.
Setup
git clone https://github.com/GibsS/gridlike.gitcd gridlikenpm install
Run the tests:
npm test
Run the testbed:
npm run build-testbedfirefox dist/testbed/index.html # Or whatever browser you choose (but not safari, oh god (jk, safari works as well (somehow)))
Upcoming features
I am currently working on adding the following features:
- Slopes
- Enabling rotation on some entities
- Co-existence of physics currently define in this library and "traditional" physics (Box2D, physics.js...)
- Movement locked to "rails": definition of node maps and fixed trajectories along those nodes
- Networking: more specifically the possibility to sync different worlds through the transmission of serialized messages
- Connexity detection on grids: evaluate dynamically whether a grid's blocks are all part of a single mass or not.
- Slopes in grids
- Serialization (maybe)
State of the library
The library is still at a very early stage of development:
- Though the core features are implemented and usable to make a simple platformer, some of the more elaborate features remain to be implemented (The future of this library is bright though, trust me ;))
- Test coverage is minimal
- The only documentation is the index.d.ts
- Quite a few bugs remain
- ..
These issues will be adressed as soon as possible and the missing features will be added. In the meantime, the library is perfectly fine to reproduce the physics of games such as super meat boy (without slopes), terraria (with ships if you so wish), super crate box, Super Mario Bros. (the first one ^^)..
Contact
If you have any questions, issues or bugs to report, don't hesitate to contact me at emerick.gibson@hotmail.fr or add an issue on this git repo.