Events

React to player actions and server events

💡 Lua Tip: Use the onEvent function to handle all events in your scripts.

💡 C++ Tip: Override OnEvent in your module class to receive events.

Event Types

Player Events

Event	Description	Data
`PLAYER_JOIN`	Player connects to server	player (id, name)
`PLAYER_QUIT`	Player disconnects	player (id, name)
`PLAYER_DEATH`	Player dies	player, killer, cause

Chat Events

-- Handle chat messages
function onEvent(event)
    if event.type == "CHAT_MESSAGE" then
        local player = event.player
        local message = event.message
        
        -- Check for commands
        if message:sub(1, 1) == "!" then
            local cmd = message:sub(2)
            handleCommand(player, cmd)
        end
    end
end

function handleCommand(player, cmd)
    if cmd == "help" then
        MCX.sendMessage(player.id, "Available commands: !help, !spawn, !kit")
    elseif cmd == "spawn" then
        MCX.teleport(player.id, 0, 64, 0)
    end
end

// Handle chat messages
void MyModule::OnEvent(const Event& event, ActionList& actions) {
    if (event.type == EVENT_TYPE::CHAT_MESSAGE && event.chat.has_value()) {
        const auto& chat = event.chat.value();
        const auto& player = chat.player;
        const auto& message = chat.message;
        
        // Check for commands
        if (!message.empty() && message[0] == '!') {
            std::string cmd = message.substr(1);
            HandleCommand(player, cmd, actions);
        }
    }
}

void MyModule::HandleCommand(const Player& player, 
                              const std::string& cmd,
                              ActionList& actions) {
    if (cmd == "help") {
        SendMessageAction msg;
        msg.playerId = player.id;
        msg.text = "Available commands: !help, !spawn, !kit";
        actions.push_back(msg);
    }
    else if (cmd == "spawn") {
        TeleportAction tp;
        tp.playerId = player.id;
        tp.position = {0, 64, 0};
        actions.push_back(tp);
    }
}

World Events

Event	Description
`BLOCK_BREAK`	Player breaks a block
`BLOCK_PLACE`	Player places a block
`SCENE_CHANGE`	Scene is switched

Complete Example

Welcome new players and give them a starter kit:

-- Welcome script
local welcomeMessages = {
    "Welcome to the server, {name}!",
    "Hello {name}, enjoy your stay!",
    "{name} has joined the adventure!"
}

function onEvent(event)
    if event.type == "PLAYER_JOIN" then
        local player = event.player
        local msg = welcomeMessages[math.random(#welcomeMessages)]
        msg = msg:gsub("{name}", player.name)
        
        -- Broadcast welcome
        MCX.broadcast("§a" .. msg)
        
        -- Send private welcome
        MCX.sendMessage(player.id, "§6Welcome! Type !kit to get started.")
        
        -- Give starter items (if implemented)
        -- MCX.giveItem(player.id, "wooden_sword", 1)
    end
end

// Welcome module
class WelcomeModule : public mcx::IModule {
    std::vector welcomeMessages = {
        "Welcome to the server, {name}!",
        "Hello {name}, enjoy your stay!",
        "{name} has joined the adventure!"
    };
    
public:
    void OnEvent(const Event& event, ActionList& actions) override {
        if (event.type == EVENT_TYPE::PLAYER_JOIN && 
            event.playerJoin.has_value()) {
            
            const auto& player = event.playerJoin.value().player;
            
            // Random welcome message
            std::random_device rd;
            std::mt19937 gen(rd());
            std::uniform_int_distribution<> dis(0, welcomeMessages.size() - 1);
            
            std::string msg = welcomeMessages[dis(gen)];
            // Replace {name}
            size_t pos = msg.find("{name}");
            if (pos != std::string::npos) {
                msg.replace(pos, 6, player.name);
            }
            
            // Broadcast welcome
            BroadcastAction broadcast;
            broadcast.text = "§a" + msg;
            actions.push_back(broadcast);
            
            // Private welcome
            SendMessageAction privMsg;
            privMsg.playerId = player.id;
            privMsg.text = "§6Welcome! Type !kit to get started.";
            actions.push_back(privMsg);
        }
    }
};

Event Priority

Events are processed in order. You can cancel or modify actions:

-- Cancel certain events
function onEvent(event, actions)
    -- Prevent block breaking in spawn area
    if event.type == "BLOCK_BREAK" then
        local pos = event.position
        if pos.x > -50 and pos.x < 50 and pos.z > -50 and pos.z < 50 then
            -- Return empty actions to cancel
            return {}
        end
    end
    return actions
end

// Cancel certain events
void OnEvent(const Event& event, ActionList& actions) override {
    // Prevent block breaking in spawn area
    if (event.type == EVENT_TYPE::BLOCK_BREAK && 
        event.blockBreak.has_value()) {
        
        const auto& pos = event.blockBreak.value().position;
        if (pos.x > -50 && pos.x < 50 && pos.z > -50 && pos.z < 50) {
            // Clear actions to cancel
            actions.clear();
        }
    }
}