Getting Started with CSL

CSL is All Out's custom programming language built to make writing multiplayer games as easy as creating single player games.

CSL is All Out’s custom scripting language. It’s statically typed and feels most similar to Go/Odin — except gameplay state is automatically synced from the server to clients.

You don’t need to write RPCs, SyncVars, or custom replication. We handle these for you!

Your first script (main.csl)

When you create a new project, All Out generates a main.csl in your project’s scripts/ folder.

import "core:ao"

// ============================================================================
// Global lifecycle
// ============================================================================

ao_before_scene_load :: proc() {
    // Register item definitions, currencies, etc.
    // Runs before the scene is created.
}

ao_start :: proc() {
    // Called once when the scene starts.
}

ao_update :: proc(dt: float) {
    // Called every frame.
}

ao_late_update :: proc(dt: float) {
    // Called every frame after ao_update.
}

// ============================================================================
// Player lifecycle
// ============================================================================

Player :: class : Player_Base {
    ao_start :: method() {
    }

    ao_update :: method(dt: float) {
    }

    ao_late_update :: method(dt: float) {
    }

    ao_end :: method() {
    }
}

For example, log a message when each player joins:

Player :: class : Player_Base {
    ao_start :: method() {
        log_info("hello %", {this.get_username()});
    }
}

If you want a deeper explanation of when these functions run, see Game/Frame Lifecycle.

Imports

Your main.csl should import core:ao and any folders you create (like ui/, abilities/, etc).

import "core:ao"
import "ui"

Imports point at folders, not individual files. A folder import includes the .csl files in that folder. Imports inside that folder are resolved relative to it:

// main.csl
import "core:ao"
import "abilities"

// abilities/projectiles.csl
import "helpers"

In most projects, import in main.csl only. Don’t sprinkle imports across lots of files — you’ll eventually end up with confusing order/visibility issues.

Declarations (variables and constants)

Declarations bind a name to a value.

Variables

// General form
<name>: <type> = <expression>;

Either <type> or <expression> can be omitted:

// Explicit type
my_value: int = 42;

// Type inference
my_value := 42; // inferred to int

// Zero-init (same as my_value := 0;)
my_value: int;

Constants

Constants use :: and must be compile-time constants. They can be scalars, strings, types, procedure values, arrays, or compound literals:

MAX_PLAYERS :: 12;

Spawn_Desc :: struct {
    name: string;
    pos: v2;
}

DEFAULT_SPAWNS: []Spawn_Desc : {
    {"Blue", {-4, 0}},
    {"Red", {4, 0}},
};

This is invalid (because a is not compile-time constant):

a := 123;
b :: a; // compile error

Global variable initializers must also be compile-time constants. Use ao_before_scene_load or ao_start for runtime initialization.

Global variables

Globals use the same declaration syntax as locals. They can be left zero-initialized or initialized with compile-time constants, including structs, arrays, procedure values, and typeid values:

score_total: int;
spawn_names: []string = {"Blue", "Red"};
default_type: typeid = int;

start_round :: proc() {
}

on_match_start: proc() = start_round;

Globals are mutable and persist for the lifetime of the script instance. Avoid using them for per-player gameplay state.

Types

Primitive types

• Signed integers: s8, s16, s32, s64
• Unsigned integers: u8, u16, u32, u64
• Booleans: bool
• Floats: f32, f64
• Aliases:

  • int == s64
  • uint == u64
  • float == f32
• Vectors: v2, v3, v4
• string
• typeid
• any

Vector types

v2 has .x, .y; v3 adds .z; v4 adds .w — all float fields:

pos: v2 = {10, 20};        // x=10, y=20
color: v4 = {1, 0, 0, 1};  // red with alpha=1
offset := v3{1, 4, 9};     // type inference

Structs and classes

Structs are value types (copies on assignment). Classes are reference types (you allocate them with new).

Structs (value types)

Food_Definition :: struct {
    name: string;
    food_value: int;
}

food: Food_Definition;
food.name = "Apple";
food.food_value = 10;

Classes (reference types)

Foo :: class {
    value: int = 10;
    position: v2 = {12, 34};
}

foo := new(Foo);

Class fields can have default values. A derived class can override inherited defaults without redeclaring the field:

Enemy :: class {
    health: int = 100;
    speed: float = 3.0;
}

Boss :: class : Enemy {
    health = 500;
    speed = 1.5;
}

Inheritance

Structs/classes can inherit from other structs/classes:

Animal :: class {
    name: string;
    age: int;
}

Dog :: class : Animal {
    breed: string;
}

dog := new(Dog);
dog.name = "Buddy";
dog.age = 5;
dog.breed = "Labrador";

Procedures and methods

Procedures (proc)

add :: proc(a: int, b: int) -> int {
    return a + b;
}

result := add(2, 4); // 6

Procedures are normal values and can be assigned/stored like any other value:

op := proc(a: int, b: int) -> int { return a + b; };
op = proc(a: int, b: int) -> int { return a * b; };

Methods (method)

Use method() inside a struct/class. Methods have an implicit this reference parameter.

Dog :: class {
    name: string;

    bark :: method() {
        log_info("% says bark!", {name});
    }
}

dog := new(Dog);
dog.name = "Buddy";
dog.bark();

Field access vs method calls

Use . for both fields and methods:

hp := player.health;        // field access
player.respawn();          // method call
entity.set_local_scale({2, 2});

Any procedure can be called as a “method” if its first parameter matches the receiver type. Real methods and procedure-valued fields on the type win before CSL falls back to a matching free procedure.

Arrays

CSL has a few “array-like” types you’ll use constantly:

• Fixed arrays: [4]int
• Slices / managed arrays: []T (often used as “read-only view” into an array)
• Dynamic arrays: [..]T (resizable list)
• Unmanaged arrays: [^]T (used in built-in API signatures like format_string, log_info, etc — pass values as {a, b, c})

Dynamic arrays expose .data, .count, and .capacity, and use method-call syntax for operations:

numbers: [..]int;
numbers.append(10);
numbers.append(20);

log_info("count: %", {numbers.count});
log_info("first: %", {numbers[0]});

For a full guide (including removal patterns), see Arrays and Collections.

Control flow

If / else

if hp <= 0 {
    die();
} else if hp < 25 {
    Notifier.notify(player, "Low health!");
} else {
    // all good
}

Switch

Use default: for the default clause. Cases support multiple values (comma-separated) and ranges. No C-style fallthrough.

Item_Tier :: enum {
    COMMON;
    UNCOMMON;
    RARE;
    EPIC;
    LEGENDARY;
}

get_tier_color :: proc(tier: Item_Tier) -> v4 {
    switch tier {
        case .COMMON:              return {0.7, 0.7, 0.7, 1.0};
        case .UNCOMMON:            return {0.3, 0.8, 0.3, 1.0};
        case .RARE, .EPIC:         return {0.3, 0.5, 1.0, 1.0};
        case .LEGENDARY:           return {1.0, 0.8, 0.2, 1.0};
        default:                   return {1, 1, 1, 1};
    }
}

// Range cases
get_difficulty :: proc(level: int) -> string {
    switch level {
        case 1..5:          return "Easy";
        case 6..<11:        return "Medium";
        case 11..20, 25:    return "Hard";
        default:            return "Unknown";
    }
}

.. includes both endpoints. ..< excludes the upper endpoint.

While / for

while condition {
    // ...
}

// Inclusive range: 0..9 includes 9
for i: 0..9 {
    log_info("i=%", {i});
}

// Half-open range: 0..<count excludes count
for i: 0..<items.count {
    log_info("item %", {items[i]});
}

// Reverse iteration
for i: 0..<items.count #reverse {
    log_info("reverse item %", {items[i]});
}

// Iterate array/slice elements
for item: my_items {
    // ...
}

// With index variable
for item, i: my_items {
    log_info("item % at index %", {item, i});
}

// Iterate custom iterators (common for entities/components)
for enemy: component_iterator(Enemy) {
    enemy.update_ai();
}

Custom iterator-based for loops require a next :: method() -> bool and a current field.

Casting

Use expr.(T) or cast(T)expr to cast:

a := 123.4;
b := a.(int);   // 123
c := cast(float)b; // 123.0

When the target type is already known, you can let CSL infer it:

i: int = a.();
j: int = cast a;

Passing by reference: ref (preferred)

When you need to modify a parameter, prefer ref over raw pointers.

update_position :: proc(pos: ref v2, velocity: v2, dt: float) {
    pos.x += velocity.x * dt;
    pos.y += velocity.y * dt;
}

my_pos := v2{0, 0};
update_position(ref my_pos, {10, 5}, 0.16);

Callbacks: function pointers + userdata (no closures)

CSL does not have closures. Inline proc(...) { ... } cannot capture surrounding variables.

To carry context, pair callbacks with a userdata: Object field:

Player :: class : Player_Base {
    on_death_userdata: Object;
    on_death: proc(player: Player, userdata: Object);

    die :: method() {
        if on_death != null {
            on_death(this, on_death_userdata);
        }
    }
}

Death_Tracker :: class : Component {
    count: int;

    ao_start :: method() {
        player := entity.get_component(Player);
        player.on_death_userdata = this;
        player.on_death = proc(player: Player, userdata: Object) {
            tracker := userdata.(Death_Tracker);
            tracker.count += 1;
        };
    }
}

Type info (types as values)

typeid values can be passed to polymorphic procs:

default_of :: proc($T: typeid) -> T {
    t: T;
    return t;
}

a := default_of(int);      // 0
b := default_of(string);   // ""
c := default_of([4]int);   // {0, 0, 0, 0}

Best practices (CSL in All Out)

• Avoid global gameplay state. Multiple players connect — store per-player state on Player instead.
• Separate cosmetic vs gameplay logic. Use is_local() for local-only UI/particles, and is_local_or_server() for gameplay inputs that must run on server + local client.
• Mobile-first defaults. Don’t rely on keyboard/mouse input unless your game is explicitly PC-focused.
• If you’re unsure about syntax or APIs, check the api_reference/ folder generated in your project (it contains the latest core.csl surface).