> For the complete documentation index, see [llms.txt](https://docs.allout.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.allout.game/scripting/game-frame-lifecycle.md).

# Game/Frame Lifecycle

All Out games run on a simple lifecycle: some callbacks happen once at startup, and some happen every frame.

You’ll implement these callbacks either:

* **Globally** (top-level `ao_*` procs in `main.csl`), or
* **On components** (methods like `ao_update` inside `Player` or your own `Component` subclasses)

{% hint style="info" %}
If you’re looking for the “template” `main.csl`, see [Getting Started with CSL](/scripting/syntax.md).
{% endhint %}

## Global lifecycle (scene-wide)

These are top-level procs in `main.csl`:

### `ao_before_scene_load`

Runs before the scene is created. This is where you typically register “global definitions”:

* Item definitions (inventory system)
* Currencies (economy system)
* Global config values/constants

### `ao_start`

Runs once when the scene starts.

Common uses:

* Spawn runtime entities/prefabs
* Initialize global systems
* Read game-wide save data

### `ao_update(dt)`

Runs every frame.

Common uses:

* Game timers, wave managers
* Spawning logic that depends on time
* Server-authoritative game rules

### `ao_late_update(dt)`

Runs every frame after `ao_update`.

Common uses:

* UI that depends on final positions/state for the frame
* “Cleanup” work after updates

## Component lifecycle (per-entity)

Components (including `Player`) can implement:

* `ao_start()`
* `ao_update(dt)`
* `ao_late_update(dt)`
* `ao_end()`
* `ao_on_state_sync()` (called when network state is synchronized)

Example:

```go
Orbiter :: class : Component {
    ao_start :: method() {
        // init
    }

    ao_update :: method(dt: float) {
        // per-frame behavior
    }

    ao_end :: method() {
        // cleanup (when destroyed)
    }
}
```

## Where to put code: a rule of thumb

* **Per-player state/logic**: put it on `Player` (see [Adding Player Logic](/scripting/player-model.md))
* **Reusable entity behaviors**: put them on custom components (see [Entities and Components](/scripting/entities-and-components.md))
* **Global coordination / rules**: put it in the global lifecycle (`ao_*` procs)

## Server vs local

All Out syncs gameplay state from server to clients automatically, but you still want to keep *cosmetic-only* work local.

Use:

* `this.is_local_or_server()` for gameplay UI + input handling (runs on server + local client)
* `this.is_local()` for cosmetic UI/effects (runs only on the local client)

These are methods on `Player_Base`. Call them on a player reference, or as `is_local_or_server()` / `is_local()` inside a `Player` method (implicit `this`).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.allout.game/scripting/game-frame-lifecycle.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.