The event list

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

How to read the tables:

• The event column is the type you put into clight::on<clight::ev::...>. In C, the same event is a CL_EV_ constant: ev::BlockBreak is CL_EV_BLOCK_BREAK.
• The payload is the struct your lambda takes by reference: [](cl_ev_block_break& e).
• 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 clight::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 and results.

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. The ones with a clight::Mod function can be used either way: override the function, or subscribe to the event.

on_construct runs before all of them, so subscribing there catches every one. In singleplayer, each world you open runs ServerStarting to ServerStopped 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 with clight::stack::is(e.stack, "minecraft:stick") and the other clight::stack functions, and don’t put it into a clight::ItemStack, which would release it.

Blocks

state is the block state as a number. Compare it with clight::registry::block_state_is(e.state, "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; clight::Entity(e.entity).is_player() tells you whether it is a player. attacker is whoever caused it, or an empty handle. source is the damage type as an interned id; get its name with clight::core::ident_name:

std::string src = clight::core::ident_name(e.source).value_or("unknown");   // "minecraft:fall", "minecraft:player_attack", ...

Cancelling entity.death skips the death. Give the entity some health back with clight::Entity(e.entity).set_health(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 events 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.hpp>

class DeathLogMod final : public clight::Mod {
public:
    void on_construct() override {
        clight::on<clight::ev::PlayerJoin>([](cl_ev_player& e) {
            clight::Entity player = e.player;
            player.send_message("Hi " + player.name() + ", have fun!");
        }).detach();

        clight::on<clight::ev::EntityDeath>([](cl_ev_entity_death& e) {
            clight::Entity dead = e.entity;
            if (!dead.is_player()) return;   // only players

            std::string src = clight::core::ident_name(e.source).value_or("something");
            clight::log::info("{} died ({})", dead.name(), src);
        }).detach();
    }
};

CLIGHT_MOD(DeathLogMod)

Recap: startup events (or the clight::Mod functions) 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 clight::ev type and the payload struct your lambda takes.