Getting Started

Project structure

What each file in a new BornEngine project does, which folders the CLI creates, and where build output goes.

A BornEngine project is a normal TypeScript package with a few extra files for the native build. This page describes what bornengine create writes, and what appears later as you build and run the game.

Files in a new project

FilePurpose
main.tsThe entry file. It contains your Game subclass and the new ...().run() call.
package.jsonThe package name, the engine dependency, and the perry setting that lets the native build use the engine’s native library.
perry.tomlBuild settings. entry names the entry file. The [bornengine] table holds native_profile, and optionally native_features.
.gitignoreKeeps generated folders out of version control: node_modules/, .perry-cache/, .perry-dev/, .bornengine/, target/, and dist/.
README.mdThe run and build commands for the project.
AGENTS.mdThe BornEngine guide for AI coding agents. create and new write it. init does not.

perry.toml for a 2D project looks like this:

toml
[project]
name = "my-game"
entry = "main.ts"

[bornengine]
native_profile = "2d"

The profile is 2d, 2.5d, or 3d. It is chosen when you create the project, and you can change it later in this file. The profile decides which engine modules the native build includes. The project commands reference lists the options that affect the profile.

Folders you add

The starter does not include an assets/ folder. Create one next to main.ts for images, sounds, fonts, and models:

plaintext
MyGame/
  assets/
    player.png
  main.ts
  perry.toml
  package.json

Paths in your code are relative to the project folder, such as assets/player.png. See Assets for the rules.

If you use an asset manifest, bornengine.assets.json, the CLI validates it and reports missing files. See the asset audit reference.

Folders the CLI creates

These folders appear when you build or run. You do not create them by hand.

FolderCreated byContents
node_modules/Your package managerInstalled packages, including the engine.
.bornengine/builds/<target>/<name>/<stamp>/bornengine build, bornengine run, and bornengine devThe executable for each build. Each build gets its own <stamp> folder.
.perry-dev/<name>/bornengine dev --watchExecutables for the watch mode.

The CLI records the files it writes into .bornengine/, so bornengine clean removes only what it created. See Build and run and Native build cache.

Changing the engine version

The engine version is the dependency in package.json. To change it, use the engine commands instead of editing the file by hand. bornengine engine update moves to the latest stable release, and bornengine upgrade upgrades the current project’s engine dependency. The engine versions reference lists the full set of commands.

Using a local engine checkout

To develop the engine and a game side by side, point a project at a local checkout with --engine-path. bornengine new and bornengine init accept the flag. The CLI then writes a link: dependency for pnpm or a file: dependency for npm and yarn, with a path relative to the project.

Next steps