Expression 2 Events

Expression 2 has events that allow you to manage what parts of your code run when certain things happen, like a player typing in chat and when a player leaves the server.
They're analogous to gmod's hook system if you are familiar Garry's Mod Lua.

❔ Why?

If you're here because of your code giving you warnings about certain runOn* functions being deprecated, this is for you.

The clk (trigger) system is the old way of handling "events" with runOn* and *clk() functions. It's being replaced due to being one of the most confusing and suboptimal things about the language.

Events are closer to what real world programming languages do, are more efficient, and simpler to understand.

🔣 Syntax

The syntax is pretty simple. They are similar to functions in how you declare them, but missing the return value type, and using event instead of function. Note, however, that events are not functions. They are a compile time construct. You can't redeclare them or stop them, at least for now. Check a variable inside the event if you do not want code inside of it to run anymore.

event chat(Ply:entity, Said:string, Team:number) {
    print(Ply, " just said ", Said)
}

Owner = owner()
event keyPressed(Ply:entity, Key:string, Down:number, Bind:string) {
    if (Ply == Owner & !Down) {
        print("Owner released key " + Key)
    }
}

Additionally, if you just begin to type event and the name of the event, the editor will autocomplete the whole declaration for you!

📚 How do they work?

All events you write in the code are registered at compile time once. So you should nest them inside any if statement.
Once they are registered, every time the event fires, only the code inside of the event will run. You can think of them as functions you give to lua.

⏲️ Timers

If you've come here looking for a replacement for interval(n), and timer(sn), unfortunately, there is no replacement as of yet.
The plan is to add functions similar to Javascript's setTimeout and setInterval functions that take functions as parameters and call them.
E2 currently does not have functions as objects, so this will be done at a later point, likely soon after #2555 is finished.

📖 List of Events

Declaration	Replacing
event tick()	runOnTick, tickClk
event chat(Player:entity, Message:string, Team:number)	runOnChat, chatClk
event keyPressed(Player:entity, Key:string, Down:number, Bind:string)	runOnKeys, keyClk
event input(InputName:string)	inputClk, inputClkName, Partially ~Input
event chipUsed(Player:entity)	runOnUse, useClk
event removed(Resetting:number)	runOnLast, last
event playerSpawn(Player:entity)	runOnSpawn spawnClk
event playerDeath(Victim:entity, Inflictor:entity, Attacker:entity)	runOnDeath, deathClk
event playerConnected(Player:entity)	runOnPlayerConnect, playerConnectClk
event playerDisconnected(Player:entity)	runOnPlayerDisconnect, playerDisconnectClk
event httpErrored(Error:string, Url:string)	runOnHTTP, httpClk
event httpLoaded(Body:string, Size:number, Url:string)	runOnHTTP, httpClk
event fileErrored(File:string, Error:number)	runOnFile, fileClk
event fileLoaded(File:string, Data:string)	runOnFile, fileClk
event playerLeftVehicle(Player:entity, Vehicle:entity)	Nothing
event playerEnteredVehicle(Player:entity, Vehicle:entity)	Nothing
event playerUse(Player:entity, Entity:entity)	Nothing
event entityDamage(Victim:entity, Damage:damage)	Nothing

Examples

📦 Using a prop

event playerUse(Player:entity, Entity:entity) {
    print(Player, "just used the prop", Entity)
}

💬 Chat Commands

This chip shows basic use of the chat event for chat commands.

@persist Owner:entity
Owner = owner()

event chat(Player:entity, Message:string, _:number) {
    if (Player == Owner & Message:sub(1, 1) == "!") {
        local Rest = Message:sub(2)
        local Arguments = Rest:explode(" ")
        
        switch (Arguments[1, string]) {
            case "ping",
                print("pong!")
                break
            default,
                print("Unknown command: " + Arguments[1, string])
        }
    }
}

💣 Detecting Explosions

This chip detects any explosion damage to the chip and keeps track of it, and destroys itself if it takes too much damage.

@persist Health:number
Health = 1000

event entityDamage(Victim:entity, Damage:damage) {
    if (Victim == entity()) { # Check if damaged prop was the chip
        if (Damage:isType(_DMG_BLAST)) { # Only check for blast damage
            Health -= Damage:getAmount() # Subtract health by damage amount
            if (Health <= 0) {
                selfDestruct() # Destroy chip, out of health
            }
        }
    }
}