> 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/player-model.md).

# Adding Player Logic

In All Out, the player is a first-class gameplay object. Your `Player :: class : Player_Base` is where you put **per-player state** (health, loadouts, cooldowns, UI toggles, progression, etc).

{% hint style="warning" %}
Assume multiple players are connected. Avoid global state that would break when there’s more than one player.
{% endhint %}

## Per-player state

Store gameplay state on the player or objects owned by the player.

```go
Player :: class : Player_Base {
    health: int;
    inventory_open: bool;
}
```

## Server + client: what runs where?

All Out automatically syncs gameplay state from the server to clients. Gameplay methods run on both the predicting client and the server, so do not guard them with `Game.is_server()`.

Two common checks:

* `is_local_or_server()`: all player UI and the input it produces
* `is_local()`: player-specific visual overrides only

```go
Player :: class : Player_Base {
    ao_late_update :: method(dt: float) {
        if is_local_or_server() {
            // Draw all player UI and handle its input here.
        }

        if is_local() {
            // Apply player-specific visibility here, but do not change fields.
        }
    }
}
```

{% hint style="info" %}
Draw all player UI from `Player.ao_late_update` under `is_local_or_server()`. Fields changed only inside `is_local()` are replaced during reconciliation.
{% endhint %}

## Runtime orientation

`player.device_orientation` selects that player's view using the `Device_Orientation` enum: `.LANDSCAPE` (the default) or `.PORTRAIT`. There is no editor game setting. Set it at startup or change it during gameplay:

```go
Player :: class : Player_Base {
    ao_start :: method() {
        device_orientation = .PORTRAIT;
    }
}

// Later, from gameplay or player UI:
// player.device_orientation = .LANDSCAPE;
```

Orientation is synchronized player state. Use the normal predicted path or `is_local_or_server()` for UI actions; a local-only assignment can be replaced by reconciliation. Each player's value is independent and survives state synchronization without an extra callback. The engine applies changes between frames, updates the viewport and safe area, and cancels gestures from the previous layout while preserving text focus. Gameplay continues while the device rotates. If rotation is unavailable, the requested orientation fits inside the available screen. Adapt your own HUD and camera framing to the resulting viewport.

## Player identity and profile data

`Player_Base` exposes identity fields you’ll use often:

* `p.get_username() -> string`
* `p.get_user_id() -> string`
* `p.avatar_color`
* `p.device_kind` (`.PHONE`, `.TABLET`, `.PC`)
* `p.is_game_owner()`, `p.is_game_editor()`, `p.is_owner_or_editor()` (the game's owner and their team), `p.is_vip()`, `p.is_moderator()`, `p.is_youtuber()`
* `p.is_chat_open()` and UI rect helpers such as `p.get_chat_rect()`

```go
Player :: class : Player_Base {
    ao_start :: method() {
        log_info("player joined: % (%)", {this.get_username(), this.get_user_id()});
    }
}
```

## Account trust (dev/nightly)

`Player_Base.get_trust_level()` returns a read-only `Account_Trust_Level`: `.BASIC` (0), `.ESTABLISHED` (1), or `.TRUSTED` (2).

```go
can_use_trading :: proc(player: Player_Base) -> bool {
    return player.get_trust_level() >= .ESTABLISHED;
}
```

The server fetches the tier before spawning the player and syncs it to clients, including late joiners. It stays fixed for the server session. Evidence refreshes on use at most every six hours, with current restrictions checked at join. Unauthenticated local previews start at `.BASIC`.

Use the same condition in predicted and authoritative gameplay; UI alone does not enforce the restriction. This is an account-investment signal, not identity proof or a guarantee of good behavior. Basic means limited evidence; no purchase is required for Trusted. Games receive no raw IPs, email, payment details or scoring inputs. Moderation and parental controls still apply independently. The API requires matching dev/nightly protocol/core builds; C# uses `Player.TrustLevel` and `AccountTrustLevel`.

## Temporary state reasons

Player states such as freezing, invisibility, name hiding, ghosting, movement-input blocking, and joystick blocking use named reasons. Reasons are counted: every call to an `add_*_reason` method requires one matching `remove_*_reason` call.

Use the corresponding `has_*_reason` method when you need set-like behavior or need to avoid adding the same reason repeatedly:

```go
if !player.has_freeze_reason("cutscene") {
    player.add_freeze_reason("cutscene");
}

if player.has_freeze_reason("cutscene") {
    player.remove_freeze_reason("cutscene");
}
```

The same pattern is available for `invisibility`, `name_invisibility`, `name_offset`, `ghost`, `disable_movement_input`, and `joystick_disable` reasons. Each family also has `has_any_*_reason()` when only the presence of any reason matters. Do not call an add method every frame: matching by name does not make it idempotent.

## Persistence: where to store player progress

* **Economy**: currencies (coins/gems/xp) with automatic persistence + creator portal editing\
  See [Economy](https://docs.allout.game/data-and-persistence/economy.md).
* **Save**: general key/value persistence (settings, quest state, unlock lists, etc)\
  See [Save System](https://docs.allout.game/data-and-persistence/save.md).
* **Inventory**: item stacks/instances in a player inventory (optionally auto-saved)\
  See [Inventory](https://docs.allout.game/core-engine-concepts/inventory.md).

## Common pattern: load saved values in `ao_start`

```go
Player :: class : Player_Base {
    xp: s64;
    selected_skin: string;

    ao_start :: method() {
        xp = Save.get_int(this, "xp", 0);
        selected_skin = Save.get_string(this, "selected_skin", "default");
    }
}
```

## Best practices

* **Keep per-player state on `Player`.** Avoid globals for anything player-specific.
* **Run gameplay in the shared predicted path.** Draw player UI under `is_local_or_server()` and reserve `is_local()` for player-specific visual overrides.
* **Prefer the built-in persistence APIs** instead of rolling your own (Economy/Save/Inventory).

## Player\_Base reference

See `api_references/core/ao/core.csl_engine` in the project folder for the complete `Player_Base` API.
