Events (Developing)

How to emit and subscribe to events in your module.

Internal Events (Lua to Lua)

Use the IEventBus contract for communication within the server:

local bus = container:make('IEventBus')

-- Subscribe (in start())
bus:on('player:spawned', function(event)
    print(('Player %d spawned at %s'):format(event.playerId, tostring(event.coords)))
end)

-- Emit
bus:emit('my-module:fishCaught', {
    playerId = source,
    fish     = 'fish_bass',
    weight   = 1.2,
})

Net Events (Server ↔ Client)

Server → Client

-- Server
TriggerClientEvent('my-module:showResult', source, {
    success = true,
    fish = 'fish_bass',
})

-- Client
AddEventHandler('my-module:showResult', function(data)
    if data.success then
        -- show notification
    end
end)

Client → Server

-- Client (trigger the server)
TriggerServerEvent('my-module:castLine', {
    spotId = currentSpotId,
})

-- Server (handle the client event — ALWAYS validate!)
RegisterNetEvent('my-module:castLine', function(data)
    local source = source
    -- validate data before trusting it
    if type(data.spotId) ~= 'number' then return end
    -- ...
end)

Event Naming Convention

module:action           -- my-module:fishCaught
module:entity:action    -- my-module:spot:activated
shiva:system:action     -- reserved for shiva-core

Documenting Your Events

Each event emitted by your module should be documented in docs/events.md:

## my-module:fishCaught

Fired when a player successfully catches a fish.

**Payload:**
| Field | Type | Description |
|-------|------|-------------|
| `playerId` | `number` | Server ID of the player |
| `fish` | `string` | Item name of the fish caught |
| `weight` | `number` | Weight of the fish in kg |

See Also

• Concepts: Events →
• API: EventBus →