Project
Back to the reference

Project

The project file: the game window, the main scene and the input map.

3 symbols

gameOptionsFromProjectfunctionnacatamalon

gameOptionsFromProject(settings: TProjectSettings) => TGameOptions

Turns a project's settings into what createGame takes.

The one place that translation happens, so that the day there is an editor with a play button and an exported build, both start the game down the same path and cannot drift apart.

mainScene is not part of it: which scene starts is createGame's second call, not an option.

For editors and other tools. A game written only in code does not need it: it passes its options straight to createGame. This exists so a tool can save those options as a file and a game made with that tool can read them back.

Parameters

settingsTProjectSettings

The project's settings, from parseProject.

Example

declare const scenes: Record<string, TSceneFn>;

const settings = parseProject(await (await fetch('/project.json')).json());
createGame('#app', gameOptionsFromProject(settings))(scenes, settings.mainScene || undefined);
View source · project/game_options_from_project.ts:31

parseProjectfunctionnacatamalon

parseProject(value: unknown) => TProjectSettings

Reads a project.json, whatever state it is in.

Total and never throws: a field that is missing, of the wrong shape or plain nonsense falls back to the default, and the game still runs. A project file is written by tools and edited by hand, so treating it as a promise would mean a typo takes the whole game down.

What it does say out loud is a file that is not a project of this engine at all, or one written by a newer version: those are warned about once, because carrying on quietly there would look like the settings simply being ignored.

For editors and other tools. A game written only in code does not need it: it passes its options straight to createGame. This exists so a tool can save those options as a file and a game made with that tool can read them back.

Parameters

valueunknown

Whatever JSON.parse gave back.

View source · project/parse_project.ts:40

TProjectSettingstypenacatamalon

A game's own settings: everything that is true of the game, not of one scene.

It lives on disk as project.json at the root of a project. The fields mirror what createGame takes wherever they can, so starting a game from a project is a translation and not a second set of decisions that can drift.

This is the format of that file: the editor writes it (its ProjectSettings is this type), and a game, the editor's play window and an exported build all read it through parseProject.

For editors and other tools. A game written only in code does not need it: it passes its options straight to createGame. This exists so a tool can save those options as a file and a game made with that tool can read them back.

Properties

format'nacatamalon-project'
version1
namestring

What the game is called.

widthnumber

The game window in pixels: how much it draws, not how big it looks. Kept small by default because this is a retro engine: a 320 by 224 picture blown up beats a huge canvas drawing pixel art at its own size.

heightnumber
backgroundTColor

What the frame is cleared to.

smoothboolean

Default filtering: false is crisp pixel art, true blends. A sprite can still choose.

msaa1 | 4

Anti-aliasing: 1 is off, which is the aliased look of the era.

rendererTRendererType

Which backend draws: 'AUTO', or one named on purpose.

scalingTCanvasScaling

How the canvas is fitted into the page.

keepTCanvasKeep

What is kept when it is fitted.

pixelRationumber | 'device'

How many real pixels each game pixel is drawn with: 1 (the default, and the one for pixel art), a number, or 'device' to follow the screen. Sharper edges for 3D and HD games, at the square of the cost. See TGameOptions.pixelRatio.

pauseOnBlurboolean

Whether the game pauses itself when the page loses focus.

seedoptionalnumber

The seed of the game's random numbers, or absent for a different run every time.

mainScenestring

Which scene the game starts on, by name. Empty means nobody has decided yet: better than quietly starting whichever sorts first, which is impossible to debug later.

actionsTActionMap

The input map: the named actions and what each one listens to. In the same file as everything else about the game.

actionsPersist'none' | 'localStorage' | 'indexedDb'

Whether the player's own controls survive a reload, and where they are kept. 'none' by default: writing to somebody's browser storage unasked is not something a game should start doing because the engine gained a feature.

postTPostChain

The full-screen effect chain: the effects applied to the finished frame, in order (a dither, a palette reduction, a CRT). "This game looks like a Mega Drive" is a fact about the project, not about whichever room is open, so it lives here and reaches the game as TGameOptions.post.

View source · project/types/t_project_settings.ts:25