Tutorial: first messages

Prefer hi.actors / Actors.* for find, send, and (when needed) name-keyed component fields. Delivery is deferred until after entity updates in the same Play tick. Zig and Kawa both use the World event dispatcher; recipients run Zig handlers first, then Kawa handlers.

Deep reference: Actor communication. Sample: src/games/example/scenes/messaging.json and the message_* entities.

Concepts in one minute

Stable scene "id" strings are the usual address.

Zig → Zig / Kawa

Sender (sample pad — fires once on trigger enter). Prefer self-as-sender helpers so you don’t pass id as .from:

const hi = @import("hikari_game");

// ActorContext lifecycle (best):
// e.sendEventTo("msg_door_zig", "open", .{});
// e.sendEventTo("msg_door_kawa", "open", .{});
// e.emitEvent("ping", .{});

// ActorRef lifecycle (update(self, id, ctx)):
const a = hi.actors;
a.sendEventToFrom(id, "msg_door_zig", "open", .{});
a.sendEventToFrom(id, "msg_door_kawa", "open", .{});
a.emitEventFrom(id, "ping", .{});

Zig receiver (on a defineComponent data type):

pub fn onMessage(_: *@This(), _: hi.ActorContext, msg: *const hi.Message) void {
    if (hi.actors.messageNameEql(msg.name, "open")) {
        // open door …
    }
}

Optional: branch on a live handle:

if (hi.actors.tryFind("msg_door_zig")) |door| {
    a.sendEventFrom(id, door, "open", .{});
}
// Fire-and-forget does not need isAlive — dead targets no-op.

Kawa → doors / listeners

Kawa receiver (assets/scenes/messaging/scripts/message_door.kawa):

fn on_message(name, from, a0, a1, a2, a3) {
    if (name == "open") {
        // Actor.set_position(...)
    }
}

Send from script (preferred namespace):

Actors.send("msg_door_zig", "open");
Actors.emit("ping");

let door = Actors.find("msg_door_kawa");
if (Actors.is_alive(door)) {
    Actors.send(door, "open");
}

World.send / World.find still work; use Actors.* for new scripts.

Script-primary door archetype: message_kawa_door_entity.zig (default script asset://./scenes/messaging/scripts/message_door).

Optional: read a field on another actor

When you need data rather than an event. Prefer component-bound helpers so the component name is not repeated as a string (numbers / bools / enums here; string and asset field helpers are also available — see Actor communication):

// Health = hi.defineComponent(.{ .name = "health", .data = struct { hp: f32 = 100 } });
if (hi.actors.tryFind("enemy_00")) |enemy| {
    if (enemy.component(Health).has()) {
        const hp = enemy.component(Health).get(.hp) orelse 0;
        _ = enemy.component(Health).set(.hp, hp - 10);
    }
}

if (Actors.has(enemy, "health")) {
    let hp = Actors.get_number(enemy, "health", "hp");
    Actors.set_number(enemy, "health", "hp", hp - 10);
}

Same-actor Zig siblings with known types: prefer ActorContext.get(Health) in lifecycle callbacks (see Actor communication — ActorContext).

Try the messaging scene

1. Play physics_playground.json (or any scene with the sample session HUD).
2. Choose Browse scenes → Tutorials → Messaging, or open scenes/messaging.json directly.
3. Both doors start closed (low). The falling weight cube lands on the pad — Zig (blue) and Kawa (pink) doors lift; listeners receive ping. You can also walk onto the pad yourself after Reload.
4. Reload / re-Play should restore both doors closed until the pad fires again.

Gotchas

• Messages flush after updates — do not expect synchronous side effects in the same update. Game modules enqueue via hi.actors.send / sendToSceneId / emit only (no HostApi sendNow for games).
• Kawa’s standalone Events.* bus is disabled in Hikari, including its events_* aliases. Use Actors.* for gameplay messages.
• ActorRef is weak — despawn/unload invalidates handles; check isAlive. Refs never keep an actor loaded.
• Additive layers require unique entity ids across all loaded layers.
• Cross-actor “call a function by name” is not an API — send a message (or set a field).

Next

• Actor communication — full API, fan-out, field access
• Play, Edit, and scenes
• First entity — add your own door / pad pair
• Game-facing refs — ActorRef rules