This guide builds a small platformer level. You describe the level as rows of text, turn the # cells into a Tilemap, and create a physics body for each solid area. A player runs and jumps with CharacterBody2D, and a ball falls and bounces in a PhysicsWorld2D.
The sections add one piece at a time. The last section has the complete main.ts.
What you will build
- A 20 by 12 tile level that is drawn from a sprite atlas.
- Static physics bodies that match the solid tiles.
- A player you move with
A/Dor the arrow keys and jump withSpace. - A ball that bounces on the tiles. The game counts the bounces.
Words you will see
- Tilemap: a component that draws a grid of tiles from a sprite sheet. Each cell holds a tile ID. ID
0means an empty cell. - Physics world: a
PhysicsWorld2D. It owns the bodies and moves them in fixed time steps. - Body: a
PhysicsBody2D, a component with a shape. A static body never moves. A dynamic body is moved by gravity and collisions. A kinematic body is moved by your code. - Character body: a
CharacterBody2D. You give it a velocity and it slides along solid surfaces. It also tells you when it stands on the floor.
Setup
Create a 2D project and an assets folder:
bornengine new TilePhysics
cd TilePhysics
mkdir assetsThe level needs one image, assets/tiles.png, with three cells that are 32 by 32 pixels in a single row. The picture is 96 by 32 pixels:
| Cell | Used for |
|---|---|
| 0 | The ground tile |
| 1 | The player |
| 2 | The ball |
Any three small pictures work. For a quick test, the first three cells of examples/sprite-animation/assets/atlas.png in the BornEngine repository work as placeholders.
Game loop
A scene updates its objects, and the physics world moves its bodies. The world does not step by itself, so the scene steps it. Create the world once, hand it to the scene with own(), and step it after the scene has updated its objects:
import { Game, PhysicsWorld2D, Scene, Vector2D } from '@bornengine/engine';
class Level extends Scene {
private readonly physics: PhysicsWorld2D;
constructor() {
super({ name: 'level' });
const physics = this.own(
new PhysicsWorld2D(Game.current, {
gravity: new Vector2D(0, 900),
fixedTimeStep: 1 / 60,
maxSubSteps: 5,
}),
);
if (physics === null || !physics.isReady) {
throw new Error(physics === null ? 'The scene could not own the physics world.' : (physics.error ?? 'The physics world is not ready.'));
}
this.physics = physics;
}
override update(deltaTime: number): void {
super.update(deltaTime);
this.physics.step(deltaTime);
}
}How this works:
gravityis in world units per second squared. The y axis points down on screen, so a positive y pulls bodies down. The default is(0, 980).step(deltaTime)adds the frame time to an accumulator and runs whole fixed steps offixedTimeStepseconds. The simulation advances in equal steps whatever the frame rate. The call returns the number of steps it ran.maxSubStepslimits the steps for one call. If a frame is longer thanfixedTimeStep * maxSubSteps, the extra time is dropped and added todroppedTime. A long pause cannot make the world run hundreds of steps.own()ties the world to the scene. When another scene replaces this one, the scene disposes the world and all of its bodies.own()returnsnullif the scene is already unloading or if another scene owns the object.- A world that cannot be created has
isReadyset tofalseand describes the reason inerror.
Tile collisions
A Tilemap draws tiles. It does not create bodies. You choose which tiles collide, and you create the bodies yourself. That keeps the map and the physics separate, so a decoration tile never blocks the player.
Each tile definition decides its own collision:
import { SpriteSheet, Tilemap } from '@bornengine/engine';
function createMap(sheet: SpriteSheet): Tilemap | null {
const block = sheet.gridFrame(0, 0);
const slab = sheet.gridFrame(1, 0);
const grass = sheet.gridFrame(2, 0);
if (block === null || slab === null || grass === null) return null;
const tilemap = new Tilemap(sheet, {
columns: 4,
rows: 2,
tileWidth: 32,
tileHeight: 32,
tiles: [
{ id: 1, frame: block, solid: true },
{ id: 2, frame: slab, collision: { x: 0, y: 16, width: 32, height: 16 } },
{ id: 3, frame: grass },
],
data: [0, 3, 3, 0, 1, 2, 2, 1],
});
return tilemap.error === null ? tilemap : null;
}solid: truemakes the whole cell solid.collisionis one rectangle, measured from the top-left corner of the cell. Theslabtile above is solid only in its lower half.- A tile with neither is decoration. Tile ID
0is always empty, so definitions use IDs from1. datalists the cells row by row. It must hold exactlycolumns * rowsnumbers, and every number must be0or a defined ID. Otherwise the map reports a message inerrorand does not draw.
After you create the map, ask it for its solid shapes. getSolidRegions() merges neighboring full-cell solids into larger rectangles, so a floor of twenty tiles becomes one body instead of twenty. Tiles with a custom collision rectangle stay separate. Use getSolidTiles() instead when you need the column, row, and tile ID of each solid cell.
import { GameObject, PhysicsWorld2D, Scene, Tilemap } from '@bornengine/engine';
function addTileColliders(scene: Scene, physics: PhysicsWorld2D, mapObject: GameObject, tilemap: Tilemap): void {
const origin = mapObject.transform.worldPosition;
for (const region of tilemap.getSolidRegions()) {
const collider = new GameObject({
name: 'Solid region',
position: {
x: origin.x + region.x + region.width / 2,
y: origin.y + region.y + region.height / 2,
z: 0,
},
});
collider.addComponent(
physics.createBody({
type: 'static',
shape: { type: 'box', width: region.width, height: region.height },
restitution: 0.7,
}),
);
scene.addNode(collider);
}
}Three details matter here:
- The rectangles are in the map’s own coordinates, measured from its top-left corner. A body is positioned at its center, so the code adds half the width and height and the map object’s world position.
- The rectangles are not scaled or rotated with the map object. Keep a map that has colliders at scale 1 and with no rotation.
- The bodies are not linked to the map. If you change a cell with
setTile(), rebuild the bodies for that area.
Complete example
Replace main.ts with this file. It combines the world, the map, the colliders, a player, and a ball:
import {
CharacterBody2D,
Colors,
FILTER_NEAREST,
Game,
GameObject,
Key,
PhysicsWorld2D,
Scene,
SpriteRenderer,
SpriteSheet,
Tilemap,
Vector2D,
} from '@bornengine/engine';
import type { InputActionMap, PhysicsBody2D, SpriteFrame } from '@bornengine/engine';
const TILE = 32;
const GRAVITY = 900;
const RUN_SPEED = 160;
const JUMP_SPEED = 380;
const BOUNCE = 0.7;
const LEVEL = [
'....................',
'....................',
'....................',
'....................',
'........####........',
'....................',
'....................',
'..####..........##..',
'....................',
'....................',
'....................',
'####################',
];
interface LevelFrames {
ground: SpriteFrame;
player: SpriteFrame;
ball: SpriteFrame;
}
class Player extends GameObject {
private readonly controls: InputActionMap;
private readonly body: CharacterBody2D;
constructor(controls: InputActionMap, physics: PhysicsWorld2D, frame: SpriteFrame) {
super({ name: 'Player', position: { x: 80, y: 300, z: 0 } });
this.controls = controls;
this.body = new CharacterBody2D(physics, { width: 24, height: 28 });
if (this.body.error !== null) throw new Error(this.body.error);
this.addComponent(new SpriteRenderer(frame, { size: new Vector2D(28, 28) }));
this.addComponent(this.body);
}
override update(deltaTime: number): void {
const velocity = this.body.velocity;
velocity.x = this.controls.readAxis('move-x') * RUN_SPEED;
velocity.y += GRAVITY * deltaTime;
if (this.controls.wasPressed('jump') && this.body.isOnFloor) velocity.y = -JUMP_SPEED;
this.body.moveAndSlide(velocity, deltaTime);
}
}
class Level extends Scene {
bounces = 0;
private readonly physics: PhysicsWorld2D;
private readonly ball: PhysicsBody2D;
constructor(controls: InputActionMap, frames: LevelFrames) {
super({ name: 'level' });
const physics = this.own(new PhysicsWorld2D(Game.current, { gravity: new Vector2D(0, GRAVITY) }));
if (physics === null || !physics.isReady) {
throw new Error(physics === null ? 'The scene could not own the physics world.' : (physics.error ?? 'The physics world is not ready.'));
}
this.physics = physics;
const data: number[] = [];
for (const row of LEVEL) {
for (const cell of row) data.push(cell === '#' ? 1 : 0);
}
const tilemap = new Tilemap(frames.ground.sheet, {
columns: LEVEL[0].length,
rows: LEVEL.length,
tileWidth: TILE,
tileHeight: TILE,
tiles: [{ id: 1, frame: frames.ground, solid: true }],
data,
});
if (tilemap.error !== null) throw new Error(tilemap.error);
const mapObject = new GameObject({ name: 'Tilemap' });
mapObject.addComponent(tilemap);
this.addNode(mapObject);
this.addTileColliders(tilemap, mapObject);
this.addNode(new Player(controls, physics, frames.player));
this.ball = this.addBall(frames.ball);
}
override update(deltaTime: number): void {
super.update(deltaTime);
this.physics.step(deltaTime);
for (const contact of this.physics.popContacts()) {
const touchesBall = contact.bodyA === this.ball || contact.bodyB === this.ball;
if (touchesBall && contact.phase === 'enter') this.bounces += 1;
}
}
private addTileColliders(tilemap: Tilemap, mapObject: GameObject): void {
const origin = mapObject.transform.worldPosition;
for (const region of tilemap.getSolidRegions()) {
const collider = new GameObject({
name: 'Solid region',
position: {
x: origin.x + region.x + region.width / 2,
y: origin.y + region.y + region.height / 2,
z: 0,
},
});
collider.addComponent(
this.physics.createBody({
type: 'static',
shape: { type: 'box', width: region.width, height: region.height },
restitution: BOUNCE,
}),
);
this.addNode(collider);
}
}
private addBall(frame: SpriteFrame): PhysicsBody2D {
const ball = new GameObject({ name: 'Ball', position: { x: 480, y: 40, z: 0 } });
ball.addComponent(new SpriteRenderer(frame, { size: new Vector2D(24, 24) }));
const body = this.physics.createBody({
type: 'dynamic',
shape: { type: 'circle', radius: 12 },
restitution: BOUNCE,
});
ball.addComponent(body);
this.addNode(ball);
return body;
}
}
class PlatformerGame extends Game {
private level: Level | null = null;
constructor() {
super({ window: { title: 'Tilemap and physics', width: 640, height: 384 }, targetFps: 60 });
}
protected override onStart(): void {
const texture = this.assets.loadTexture('assets/tiles.png');
if (texture === null || !texture.isLoaded) throw new Error(texture?.error ?? 'Could not load assets/tiles.png');
texture.setFilter(FILTER_NEAREST);
const sheet = new SpriteSheet(texture, { frameWidth: TILE, frameHeight: TILE });
const ground = sheet.gridFrame(0, 0);
const player = sheet.gridFrame(1, 0);
const ball = sheet.gridFrame(2, 0);
if (ground === null || player === null || ball === null) {
throw new Error(sheet.error ?? 'assets/tiles.png needs three cells of 32 by 32 pixels.');
}
const controls = this.input.createActionMap();
controls.bindAxis('move-x', {
negative: [{ kind: 'key', key: Key.LEFT }, { kind: 'key', key: Key.A }],
positive: [{ kind: 'key', key: Key.RIGHT }, { kind: 'key', key: Key.D }],
});
controls.bindAction('jump', [{ kind: 'key', key: Key.SPACE }, { kind: 'key', key: Key.UP }]);
const level = new Level(controls, { ground, player, ball });
if (!this.scenes.changeTo(level)) throw new Error('Could not activate the level.');
this.level = level;
}
protected override loop(deltaTime: number): void {
this.scenes.update(deltaTime);
}
protected override render(): void {
this.renderer.clear({ r: 20, g: 26, b: 37, a: 255 });
super.render();
const bounces = this.level === null ? 0 : this.level.bounces;
this.renderer.drawText('A/D move Space jump Ball bounces: ' + bounces, { x: 12, y: 12 }, 18, Colors.WHITE);
}
}
const game = new PlatformerGame();
game.run().then(() => {
if (game.error !== null) console.error(game.error);
});Run it with bornengine run main.ts. The ball drops onto the floor and bounces until it settles. Move the player with A/D or the arrow keys, and jump with Space.
What each part does:
LEVELis the whole map as text. The loop turns each#into tile ID1and every other character into0. TheTilemapdraws the tiles, andaddTileColliderscreates four static bodies for the 30 solid cells.Player.update()builds the velocity for this frame. It sets the horizontal speed from themove-xaxis, adds gravity, and starts a jump only whenisOnFlooris true.moveAndSlide()moves the object and slides it along the tiles. Afterwards,this.body.velocityreturns the velocity that is left after the slide, so landing on the floor cancels the fall speed. The next frame starts from that value.- The
CharacterBody2Dis a component, so it moves its own game object. TheSpriteRendereron the same object draws at that position. - The ball is a dynamic body. The world moves it and writes its position back into the game object’s transform after each fixed step, so its sprite follows the body.
Level.update()steps the world after the objects have updated, then reads the contact queue. A contact record has aphaseofenter,stay, orexit, and the two bodies that touch.- Both the ball and the ground have
restitution: 0.7. When two bodies touch, the solver uses the smaller of their two values. A ground body with the default0would stop the ball from bouncing. - Components with the same
renderOrderdraw in the order their objects were added to the scene. The tilemap object is added first, so the player and the ball draw over it.
The contact queue
The world records a pair for every contact on every fixed step and keeps the records until you call popContacts(). Call it once per frame, as the example does, even if you only use the per-body callbacks onCollisionEnter, onCollisionStay, onCollisionExit, and their onTrigger... versions. Do not call clearContacts() every frame. It also forgets which bodies are touching, so the next step reports them all as new enter contacts.
Limits to know
- Bodies have a position and a velocity, but no rotation. A box or circle stays upright.
- A body is a
box, acircle, asegment, or aconvexpolygon. Segments and convex shapes must be static. They are useful for slopes and one-way platforms. CharacterBody2Dalways uses a box shape and is a kinematic body: your code decides how far it moves.- All bodies belong to one world and one
Game. A body cannot move to another world.
Next steps
- Physics 2D API lists all shapes, body options, queries such as
raycast, one-way surfaces, and continuous collision detection. - Tilemaps API documents
Tilemapin full, including tile flips and changing cells at runtime. - Sprites API explains sprite sheets and frames.
- World2D API loads a map that you author in BornEngineTools, with tile layers, objects, and physics bodies.
- Build a 2D game adds animation, particles, and a camera to a 2D scene.