API

TypeScript API

Overview of the BornEngine TypeScript API, with the ownership rules, import paths, and a link to every module.

The BornEngine API is a set of TypeScript classes. Every program starts with one Game. The Game opens the window and gives you services as properties: game.renderer draws, game.input reads devices, game.audio plays sound, game.scenes runs scenes, and game.assets loads files. This page shows how the pieces fit together and links to the reference page of every module.

typescript
import { Colors, Game, Key } from '@bornengine/engine';

class Hello extends Game {
  constructor() {
    super({ window: { title: 'Hello', width: 640, height: 360 } });
  }

  protected override loop(_deltaTime: number): void {
    if (this.input.isKeyPressed(Key.ESCAPE)) this.stop();
  }

  protected override render(): void {
    this.renderer.clear(Colors.DARKBLUE);
    this.renderer.drawText('Hello, BornEngine', { x: 24, y: 24 }, 32, Colors.WHITE);
  }
}

new Hello().run();

The class overrides two hooks. loop(deltaTime) runs every frame and reads this.input. render() runs after it and draws with this.renderer. Core explains the full frame lifecycle.

How the API is organized

  • One Game per process. The Game owns the window and every service. A second Game created while the first is active fails with the error Only one BornEngine Game may be active at a time.
  • Resources have an owner. You create textures, fonts, sounds, music, and models through game.assets or scene.assets, not with new. game.assets keeps them until the game shuts down. scene.assets releases them when the scene unloads. See Assets.
  • Some systems take the Game directly. A Scene is created with new Scene(options). Context-bound systems such as PhysicsWorld and ColyseusClient also receive the Game in their constructors.
  • Value types stand alone. Vector2D, Vec3, Matrix4, Quat, and Colors only store numbers. They need no Game and have nothing to release. See Math.
  • Internal members are not public API. Names that start with an underscore, such as _create, are internal and can change without notice.

Import from the root or a subpath

Most games import everything from the package root. Import from a subpath when you want the module boundary to be visible in a library or in a feature package:

typescript
import { Colors, Game } from '@bornengine/engine/core';
import { Collision } from '@bornengine/engine/shapes';
import type { Rect } from '@bornengine/engine/shapes';

const BUTTON: Rect = { x: 40, y: 40, width: 120, height: 40 };

class Menu extends Game {
  protected override render(): void {
    this.renderer.clear(Colors.BLACK);
    const hovered = Collision.checkPointRectangle(this.input.getMousePosition(), BUTTON);
    this.renderer.drawRectangle(BUTTON, hovered ? Colors.GOLD : Colors.GRAY);
  }
}

The root package re-exports the classes you use most from the modules below, so import { Game } from '@bornengine/engine' and import { Game } from '@bornengine/engine/core' give you the same class. Some names exist only on a subpath, such as everything in @bornengine/engine/annotations and the extra helpers in @bornengine/engine/world2d/editor.

Module map

Runtime and rendering

ModuleImport pathWhat you find there
Core@bornengine/engine/coreGame, Window, Renderer, Colors, Key, MouseButton, and shared types such as Camera2D and Rect.
Game objects@bornengine/engine/gameGameObject, GameComponent, Scene, SceneManager, Transform, and adapter components.
Annotations@bornengine/engine/annotationsThe Asset and GameComponent field decorators. This GameComponent is a decorator function, not the component base class from game.
2D camera@bornengine/engine/camera2dCameraRig2D, Viewport2D, and ParallaxLayer2D.
Input@bornengine/engine/inputInputSystem and InputActionMap.
Shapes@bornengine/engine/shapesShape drawing on the renderer and 2D collision helpers.
Textures@bornengine/engine/texturesTexture, RenderTexture, and ImageData.
Assets@bornengine/engine/assetsAssetManager, SceneAssetManager, and AssetGroup.
Text@bornengine/engine/textFont, plus text drawing and measuring on the renderer.
Math@bornengine/engine/mathVector2D, Vec3, Vec4, Quat, Matrix4, Mathf, and Collision.

2D content and gameplay

ModuleImport pathWhat you find there
Sprites and animation@bornengine/engine/spritesSpriteSheet, SpriteRenderer, SpriteAnimation, SpriteAnimator, ParticleEmitter2D, and animation templates.
Physics 2D@bornengine/engine/physics2dPhysicsWorld2D, PhysicsBody2D, and CharacterBody2D.
Tilemaps@bornengine/engine/tilemapTilemap and its tile and collision data.
World2D@bornengine/engine/world2dVersioned 2D world documents: validation, serialization, a component registry, and World2DLoader. @bornengine/engine/world2d/editor exposes the pure editing APIs.
2D pathfinding@bornengine/engine/pathfinding2dAStarGrid2D and its grid types.
Procedural generation@bornengine/engine/proceduralSeededRandom and Noise2D.
Audio@bornengine/engine/audioAudioSystem, Sound, Music, SoundManager, AudioListener2D, and AudioEmitter2D.
Database and migrations@bornengine/engine/storageGameDatabase, typed SQLite schemas, queries, transactions, and migrations.
Mobile@bornengine/engine/mobileTouchControls, VirtualJoystick, and VirtualButton.

User interface and debugging

ModuleImport pathWhat you find there
UI@bornengine/engine/uiUi, the immediate-mode interface.
GUI controls@bornengine/engine/guiGUIManager, the retained controls such as GuiButton, and profiles and events.
Debug UI@bornengine/engine/debug-uiDebugUi and the optional inspector.

3D and networking

ModuleImport pathWhat you find there
Models@bornengine/engine/modelsModel, Mesh, Material, and the 3D Animation.
Scene@bornengine/engine/sceneSceneGraph and SceneNode, the retained 3D scene.
Physics@bornengine/engine/physicsPhysicsWorld, colliders, rigid bodies, joints, and vehicles.
World@bornengine/engine/worldWorldData, WorldInstance, and PrefabLibrary.
VFX@bornengine/engine/vfxThe 3D ParticleSystem, DecalSystem, and SceneVfx.
Colyseus@bornengine/engine/colyseusColyseusClient and Room for multiplayer.

Lifetime and failures

The engine reports most failures as values instead of exceptions:

  • Check game.isReady and game.error after you construct a Game. Core explains how a runtime error reaches game.error.
  • Resources that load from files, such as textures, fonts, and sounds, have isLoaded and error. Factories return null when they cannot create a resource at all, for example for an empty path.
  • Call dispose() on a resource when it leaves gameplay early. Calling game.dispose() or stopping the game releases whatever the game still owns.

Next steps

  • API shape explains the class-first design behind these modules.
  • Your first player builds a game with a scene, an object, and a camera.
  • 2D game puts several modules together in one level.