The core module holds Game, the root object of every BornEngine program. It also holds the Window, the Renderer, and shared values such as Colors, Key, and MouseButton. A Game opens the window, creates one instance of each engine service, and runs the frame loop. You normally subclass it.
Import these from @bornengine/engine, or from @bornengine/engine/core. A Game gives you its services as properties:
| Property | What it is | Reference |
|---|---|---|
game.window | The window: title, size, fullscreen. | The window section below |
game.renderer | Drawing, camera passes, and profiling. | Shapes, Textures, Text |
game.input | Keyboard, mouse, gamepad, touch, and action maps. | Input |
game.audio | Sounds and music. | Audio |
game.scenes | The scene manager. | Game objects |
game.assets | The shared asset cache. | Assets |
game.mobile, game.ui, game.gui, game.debugUi, game.sceneGraph | Optional systems. | Mobile, UI, GUI controls, Debug UI, Scene |
Only one Game can be active in a process. Creating a second one gives you a game whose error is Only one BornEngine Game may be active at a time.
Frame lifecycle
Subclass Game and override the hooks you need. The engine calls them in this order:
onStart()runs once, after the window and renderer exist and before the first frame.loop(deltaTime)runs every frame.deltaTimeis the time since the previous frame in seconds. It is measured, not fixed, so multiply speeds by it.render()runs every frame afterloop. The defaultrender()draws the current scene.onStop()runs once when the game ends, before the engine releases its resources.
import { Colors, Game, Key } from '@bornengine/engine';
const SPEED = 240;
class MovingSquare extends Game {
private x = 40;
constructor() {
super({ window: { title: 'Frame lifecycle', width: 800, height: 450 }, targetFps: 60 });
}
protected override onStart(): void {
console.log('The window and renderer are ready.');
}
protected override loop(deltaTime: number): void {
if (this.input.isKeyDown(Key.RIGHT)) this.x += SPEED * deltaTime;
if (this.input.isKeyDown(Key.LEFT)) this.x -= SPEED * deltaTime;
if (this.input.isKeyPressed(Key.ESCAPE)) this.stop();
}
protected override render(): void {
this.renderer.clear(Colors.DARKBLUE);
this.renderer.drawRectangle({ x: this.x, y: 200, width: 48, height: 48 }, Colors.ORANGE);
}
protected override onStop(): void {
if (this.error !== null) console.error(`The game stopped with an error: ${this.error}`);
}
}
const game = new MovingSquare();
if (!game.isReady) console.error(game.error);
game.run().then(() => console.log('The game has shut down.'));Inside each frame, the engine does this:
- The renderer starts the frame.
- Input updates, including every action map.
- Engine services update: the retained GUI (the control tree in
game.gui), audio, and on-screen touch controls. loop(deltaTime)runs.render()runs.- The retained GUI draws, then the debug inspector if you enabled it.
The renderer does not clear the screen, so call this.renderer.clear(color) first in render(). Scenes are not updated for you either. When you use scenes, call this.scenes.update(deltaTime) from loop, and call super.render() from your render() where the scene should draw.
Options
new Game(options) accepts these options. All of them are optional.
window:title(default'BornEngine'),width(default 800),height(default 600),fullscreen, andmode.modeis'windowed'by default.'embedded'is for hosts that provide their own surface. A width or height that is not above zero makes theGamefail with anerror.targetFps: the frame rate to aim for, 60 by default. On native platforms the engine sleeps at the end of a frame to keep to it. On the Web, the browser schedules frames and this option has no effect. A value that is not a positive finite number makes theGamefail.renderMode:'2d'selects the lightweight 2D renderer.'3d'and'2.5d'select the full scene renderer, which is also the default. This is a run-time choice. It is separate from thenative_profilebuild setting that the CLI uses.textureFilter:'linear'or'nearest'. It sets the sampling filter for textures thatgame.assetsand scene assets load, including@Assetfields and sprite templates. The default is'nearest'in'2d'render mode, which keeps pixel art sharp, and'linear'otherwise. Set'linear'to smooth textures in a 2D game. Textures you create from image data or render targets are not changed.debug:trueor an object that turns on the built-in inspector. It needs thedebug-uinative feature, a build option described in Project configuration. See Debug UI.
A Game also has the getters isReady, isRunning, isDisposed, error, and stats. Check isReady and error right after you construct it.
Game.current is a static getter that returns the active Game. It throws when no Game is running. Use it where a class does not receive the game, such as a scene or a component that runs after the constructor.
const game = Game.current;
console.log(game.window.width);The window
game.window describes the window or host surface. It has width, height, title, mode, and isOpen.
setTitle(title),setIcon(path),toggleFullscreen(), andresize(width, height, pixelRatio = 1)returntruewhen they act. They returnfalsewhen the window is not open, andresizealso returnsfalsefor a size that is not above zero.close()closes the window. In a standalone game this ends the run, likestop().widthandheighthold the size from your options or from the lastresize()call. The engine does not update them when a player drags the edge of a desktop window. Readgame.input.getScreenWidth()andgetScreenHeight()for the current size.
Start, stop, and the run Promise
run() starts the frame loop and returns a Promise<void>, the standard TypeScript object for work that finishes later. The Promise resolves after onStop() has run and the Game has released its resources. It never rejects.
- On native platforms, which means everything except the Web,
run()blocks until the game has finished, so the Promise is already resolved when you get it. Code after a plaingame.run()call runs after the game has ended. - On the Web, the browser schedules frames.
run()returns at once, and the Promise resolves later, when the game finishes. - Use
.then(...)on the Promise, oronStop(), for code that must run on every platform after shutdown. stop()asks for an orderly shutdown. The current frame finishes, thenonStop()runs, then theGameis disposed, and then the Promise resolves. Closing the window does the same.dispose()releases everything at once when the game is not running. If you call it while the game runs, it requests a stop, and the engine disposes theGamewhen the current frame ends.- A
Gameruns once. Callingrun()a second time returns the same Promise and starts nothing.
Runtime errors
The engine does not throw errors out of run() and does not print them. A failure is recorded as text in game.error, which is null when nothing went wrong. The text is the message of the error that was thrown, or String(value) when the thrown value is not an Error. The Game keeps only the first error.
An error is recorded when:
- The constructor cannot start the
Game: an invalid window size, an invalidtargetFps, or a second activeGame.isReadyisfalse, andrun()resolves at once. - Your
onStart,loop, orrenderthrows. The frame loop stops,onStop()still runs, the engine disposes theGame, and therun()Promise resolves. onStop()or the cleanup throws, and no earlier error exists.
import { Game } from '@bornengine/engine';
class BrokenGame extends Game {
protected override onStart(): void {
throw new Error('Level data is missing.');
}
}
const broken = new BrokenGame();
broken.run().then(() => {
console.log(broken.error);
});This prints Level data is missing., because the Promise resolves and the message is in broken.error. error stays readable after the Game is disposed.
Embedded hosts
runFrame(deltaTime, callbacks) is for embedded hosts. An embedded host is an application that owns the native window or view and its own frame scheduler, and runs BornEngine inside it. Create the Game with window.mode set to 'embedded', attach the host’s surface, and call runFrame once per host frame. Standalone games never call it. It returns false unless the Game is embedded.
import { Colors, Game } from '@bornengine/engine';
import type { EmbeddedFrameCallbacks } from '@bornengine/engine';
declare const surfaceHandle: number;
const game = new Game({ window: { mode: 'embedded', width: 640, height: 360 } });
const callbacks: EmbeddedFrameCallbacks = {
update(deltaTime: number): void {
game.scenes.update(deltaTime);
},
render(): void {
game.renderer.clear(Colors.DARKGRAY);
game.scenes.render(game.renderer);
},
onStop(): void {
console.log('The embedded game stopped.');
},
};
if (!game.window.attachNativeSurface(surfaceHandle, 640, 360)) {
console.error(game.error ?? 'The native surface could not be attached.');
}
export function onHostFrame(deltaSeconds: number): boolean {
if (game.runFrame(deltaSeconds, callbacks)) return true;
game.dispose();
return false;
}The host owns the loop, so the rules differ from a standalone game:
surfaceHandleis a number that identifies the host’s native view. The host supplies it, andattachNativeSurface(handle, width, height)returnsfalseif the attach fails.deltaSecondsis the time since the host’s previous frame, in seconds.runFrameruns one frame with the same internal order asrun(): input, services, then your callbacks. Theupdateandrendercallbacks replace theloopandrenderhooks. TheonStart,loop,render, andonStophooks of a subclass are not used, andrun()does not start a loop for an embeddedGame.runFramereturnstruewhile the game keeps running. It returnsfalsewhen theGameis not ready, is not embedded, was asked to stop, its window closed, or a callback threw.- When a callback throws, the error goes to
game.error, theonStopcallback runs, andrunFramereturnsfalse. TheGamecloses its window but still holds its resources, so calldispose()as the example does.
Input
Read devices through game.input, or create a named action map with game.input.createActionMap(). The engine reads input once per frame, before loop runs, so every call during a frame sees the same state.
import { Colors, Game, Key, MouseButton } from '@bornengine/engine';
import type { InputActionMap } from '@bornengine/engine';
class InputDemo extends Game {
private readonly controls: InputActionMap;
private x = 100;
private jumps = 0;
constructor() {
super({ window: { title: 'Input', width: 640, height: 360 } });
this.controls = this.input.createActionMap();
this.controls.bindAction('jump', [
{ kind: 'key', key: Key.SPACE },
{ kind: 'mouse', button: MouseButton.LEFT },
]);
}
protected override loop(deltaTime: number): void {
if (this.input.isKeyDown(Key.RIGHT)) this.x += 200 * deltaTime;
if (this.input.isKeyDown(Key.LEFT)) this.x -= 200 * deltaTime;
if (this.controls.wasPressed('jump')) this.jumps += 1;
}
protected override render(): void {
this.renderer.clear(Colors.BLACK);
this.renderer.drawText(`Jumps: ${this.jumps}`, { x: 16, y: 16 }, 24, Colors.WHITE);
this.renderer.drawRectangle({ x: this.x, y: 200, width: 32, height: 32 }, Colors.ORANGE);
}
}
new InputDemo().run();Use the Key and MouseButton constants instead of raw numbers. Input covers bindings, axes, rebinding, and device differences.
Cameras and coordinates
By default, drawing coordinates are window pixels with the origin at the top-left corner and y growing downward. A camera pass changes that to world coordinates.
renderer.begin2D(camera, viewport?)starts a 2D pass with aCamera2D:{ offset, target, rotation, zoom }.renderer.end2D()ends it.renderer.begin3D(camera)starts a 3D pass with aCamera3D:{ position, target, up, fovy, projection }, wherefovyis in degrees andprojectionis'perspective'or'orthographic'.renderer.end3D()ends it.- Each
beginreturnsfalsewhen it cannot start: theGameis not ready, or another pass or a render texture is already active.begin2Dalso returnsfalsefor a camera with a value that is not finite or a zoom that is not above zero. Passes do not nest. Match every successfulbeginwith itsend. - A scene starts and ends its own 2D pass when it has a camera or viewport, so you do not call
begin2Dfor scene content.
import { Colors, Game } from '@bornengine/engine';
import type { Camera2D } from '@bornengine/engine';
class CameraDemo extends Game {
private readonly camera: Camera2D = {
offset: { x: 400, y: 225 },
target: { x: 0, y: 0 },
rotation: 0,
zoom: 1,
};
constructor() {
super({ window: { title: 'Camera pass', width: 800, height: 450 } });
}
protected override render(): void {
this.renderer.clear(Colors.BLACK);
if (!this.renderer.begin2D(this.camera)) return;
this.renderer.drawCircle({ x: 0, y: 0 }, 32, Colors.GOLD);
const mouse = this.input.screenToWorld(this.input.getMousePosition(), this.camera);
if (mouse !== null) this.renderer.drawCircle(mouse, 8, Colors.RED);
this.renderer.end2D();
}
}
new CameraDemo().run();camera.target is the world point the camera looks at, and camera.offset is where that point appears on screen. Here the offset is the middle of the 800 by 450 window, so the circle at the world origin draws in the middle.
game.input.screenToWorld(position, camera?) turns a screen position into a world position, and worldToScreen(position, camera?) does the opposite. Without a camera argument they use the current scene’s camera and viewport. They return null when no conversion is possible. The 2D camera and viewport page explains scaling modes, letterbox bars, and the camera rig.
Files and profiling
Several platform helpers live on game.input, because they talk to the host system:
fileExists(path),readFile(path), andwriteFile(path, data)read and write small text files.readFilereturns an empty string when the file cannot be read, so callfileExistsfirst when an empty file is possible.writeFilereturnsfalsewhen it fails.setClipboardText(text)andgetClipboardText()use the system clipboard.openFileDialog(filter, title)andsaveFileDialog(defaultName, title)open native file pickers and return the chosen path, or an empty string if the player cancels. The CLI turns on the nativedialogsfeature when your source calls them.
Where files go depends on the platform:
- On Linux, Windows, and macOS, a relative path is relative to the folder the game runs from.
bornengine runstarts the game in your project folder. - On Android and iOS, the engine resolves relative paths for you.
- On the Web,
writeFilestores text in the browser’s local storage, andreadFileandfileExistscheck that storage first and then the files served with the game. The clipboard and file dialogs are not implemented there.
For structured save data, use the typed database in Database and migrations instead of text files.
The renderer has a built-in profiler. It is off by default and costs nothing while off.
import { Colors, Game, Key } from '@bornengine/engine';
class ProfiledGame extends Game {
private profiling = false;
protected override onStart(): void {
const path = 'save.json';
if (this.input.fileExists(path)) {
console.log(`The save file has ${this.input.readFile(path).length} characters.`);
}
if (!this.input.writeFile(path, JSON.stringify({ level: 3 }))) {
console.error('Could not write save.json.');
}
}
protected override loop(_deltaTime: number): void {
if (!this.input.isKeyPressed(Key.F3)) return;
this.profiling = !this.profiling;
this.renderer.setProfilerEnabled(this.profiling);
}
protected override render(): void {
this.renderer.clear(Colors.BLACK);
if (!this.profiling) return;
const cpuMs = this.renderer.getProfilerCpuTimeUs() / 1000;
const gpuMs = this.renderer.getProfilerGpuTimeUs() / 1000;
this.renderer.drawText(`CPU ${cpuMs.toFixed(2)} ms GPU ${gpuMs.toFixed(2)} ms`, { x: 12, y: 12 }, 20, Colors.LIME);
let y = 40;
for (const row of this.renderer.getProfilerOverlay().slice(0, 8)) {
this.renderer.drawText(`${row.label}: ${(row.cpuUs / 1000).toFixed(2)} ms`, { x: 12, y }, 16, Colors.WHITE);
y += 20;
}
}
}
new ProfiledGame().run();The profiler methods on game.renderer are:
setProfilerEnabled(enabled)turns it on or off.getProfilerCpuTimeUs()andgetProfilerGpuTimeUs()return the average frame time over the last 120 frames, in microseconds. The GPU value is0when the graphics device cannot time passes.getProfilerOverlay()returns one row per phase,{ label, cpuUs, gpuUs }, sorted by CPU time. A row’sgpuUsis-1when GPU timing is not available.getProfilerFrameHistory()returns the last frames’ totals as{ cpuUs, gpuUs }, oldest first.printProfilerSummary()prints a timing table to the console.
Two read-only snapshots help when you do not need the profiler. game.stats reports frameTimeMs, updateTimeMs, renderTimeMs, and the object and component counts of the current scene. game.renderer.stats reports fps, frameIntervalMs, drawSubmissions2D, spritesDrawn, and spritesCulled. renderer.screenshot(path) asks the renderer to save a screenshot to path.
Renderer methods return false, 0, or an empty value instead of throwing when the Game is not ready.
Next steps
- Game objects explains scenes, objects, and components that run inside this lifecycle.
- Input covers action maps and device behavior.
- 2D camera and viewport builds on the camera passes described above.
- Game loop explains the same frame order as a concept.
- Desktop and Web / WASM list platform differences.