#Key concepts

Six ideas explain how every game in this engine is put together. Each links to the page with the details.

#Projects

A project is a folder. It holds a project file (.cairnproject), scenes and assets. The project file has the game's name, which scene opens first, the input actions and the physics settings.

Every file the editor writes is plain text, so a project works well with Git.

More: Project settings.

#Scenes

A scene is a level, a menu, or any other screenful of game. It is a file (.cairnscene) that lists entities.

One scene runs at a time. A script switches to another with Scene.Load, and can add a second on top with Scene.LoadAdditive.

More: Scenes and entities.

#Entities and components

An entity is one thing in a scene: a wall, a light, the player, a button on screen. By itself it is only a name, a place and a parent.

What an entity does comes from its components. There are no kinds of entity, only different sets of components:

This is the main idea to hold on to. To make something behave differently, add, remove or change a component.

Entities form a tree. A child's position is measured from its parent, so it moves with it.

More: Scenes and entities, and the pages under Engine features for each component.

#Assets

An asset is a file the game uses: a model, a texture, a material, a sound, a script, a prefab, a scene.

Every asset has an ID, kept in a small .meta file beside it. Scenes refer to assets by ID, never by path. That is why you can rename and move files in the Assets panel without breaking anything, and why .meta files belong in version control.

More: Assets.

#Scripts

A script is a Lua or TypeScript file that gives an entity behaviour of your own. The engine calls its functions: OnStart when the game starts, OnUpdate every frame, OnTriggerEnter when something walks into it.

A script lists fields, and the inspector shows them, so the same script can be on many entities with different values.

More: Scripting overview, and Learn Lua if the language is new to you.

#Prefabs

A prefab is an entity, with its children, saved as a file so it can be placed many times: a coin, an enemy, a tree. Change the prefab and every copy follows, apart from what a copy changed for itself.

More: Prefabs.

#How a frame runs

Knowing the order helps when two scripts depend on each other.

1. Input is read.
2. Screen UI works out what was clicked.
3. Zero or more fixed steps run, 60 per second of game time. Each is every script's OnFixedUpdate, then physics.
4. Every script's OnUpdate runs, in hierarchy order.
5. Animation and particles advance.
6. The frame is drawn.

Read input and move things in OnUpdate. Push physics bodies in OnFixedUpdate.

#Editing and playing

The editor has two states. While editing, every change is an undo step and is saved with the scene. While playing, the game runs on the same scene, and stopping puts everything back as it was.

The game in the editor and an exported game run the same engine code, so what you see in play mode is what a player gets.

More: Play mode and Exporting a game.