The event list

This page lists every event the game sends today, with its payload struct and fields. Come back to it whenever you write a new handler.

How to read the tables:

• Side says where the event happens. Server events run where the world is simulated: in singleplayer, or on a server that has your mod. Client events run in the player’s game window. Contexts and sides explains the difference.
• Cancel marks events you can stop with cl_event_cancel(&e->header).
• Fields in bold can be changed (/* mut */ in clight.h).
• Every payload also starts with header, which you only need for cancelling.

Startup and shutdown

These run once, in this order, while the game starts or a world opens. Their payload is cl_ev_lifecycle, and you won’t need its fields.

mod_main runs before all of them, so subscribing there catches every one. In singleplayer, each world you open runs SERVER_STARTING to SERVER_STOPPED again.

A few more come while the game runs:

Ticks

The game runs 20 ticks per second. These events run every tick, so keep their handlers short. Payload: cl_ev_tick.

PRE runs before the game’s own work for that tick, POST after it. When in doubt, use POST. The level ticks run for each world (overworld, Nether, End) separately, with level set.

Players

hand is CL_HAND_MAIN or CL_HAND_OFF. face is the side of the block that was clicked, CL_DIRECTION_DOWN to CL_DIRECTION_EAST. stack is a borrowed copy of the stack in the hand: read it, don’t release it.

Blocks

state is the block state as a number. Compare it with cl_block_state_is(e->state, CL_STR("minecraft:stone")).

tool is a borrowed copy of the stack in the player’s main hand (read it, don’t release it), and xp is the experience the block will drop. Set xp to 0 to drop none, or raise it for a bonus. Both are filled in for vanilla blocks; your own mod blocks drop no experience unless you set xp.

Entities

entity is the hurt or dying entity; cl_entity_is_player(e->entity) tells you whether it is a player. attacker is whoever caused it, or a null handle. source is the damage type as an interned id; get its name with cl_ident_name:

char src[64];
size_t len = 0;
cl_ident_name(e->source, src, sizeof src, &len);   // "minecraft:fall", "minecraft:player_attack", ...

Cancelling entity.death skips the death. Give the entity some health back with cl_living_set_health(e->entity, 4.0f) in the same handler, or it has none left.

Commands

Register your commands in here. Commands shows how.

Client

Client events also fire on servers that don’t have your mod. That is what makes client-only mods possible.

Most of these events can be filtered to one block, item, entity type or screen id; Changing and cancelling shows how.

Try it

Write one handler that greets a player when they join, and another that logs when a player died and what killed them (the damage source).

#include <clight_easy.h>

static void on_player_join(void* payload, void* user) {
    (void)user;
    cl_entity player = CL_EVENT(cl_ev_player, payload)->player;
    char name[64];
    cl_easy_player_name(player, name, sizeof name);
    cl_easy_send_messagef(player, "Hi %s, have fun!", name);
}

static void on_death(void* payload, void* user) {
    (void)user;
    cl_ev_entity_death* e = CL_EVENT(cl_ev_entity_death, payload);
    if (!cl_entity_is_player(e->entity)) return;   // only players

    char name[64], src[64];
    size_t len = 0;
    cl_easy_player_name(e->entity, name, sizeof name);
    if (cl_ident_name(e->source, src, sizeof src, &len) != CL_OK) snprintf(src, sizeof src, "something");
    CL_LOG("%s died (%s)", name, src);
}

static cl_result mod_main(void) {
    cl_result r = CL_ON(CL_EV_PLAYER_JOIN, on_player_join);
    if (r == CL_OK) r = CL_ON(CL_EV_ENTITY_DEATH, on_death);
    return r;
}

CLIGHT_MOD_ENTRY(mod_main)

Recap: startup events register and set up, tick events run 20 times a second, and player, block, entity and client events report what happens; the table tells you the payload struct to use with CL_EVENT.