Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mythicframework.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Character events fire at key moments in the character lifecycle, allowing other resources to react to character creation, selection, updates, and deletion.

​
Server Events

All character events fire on the server-side.

Lifecycle Events

Created, Selected, Deleted

State Changes

Job changes, money changes, updates

Persistent

Save and load events

Hookable

Add custom logic to character operations

​
Lifecycle Events

​
mythic-characters:server:CharacterCreated

Fired when a new character is successfully created. 
AddEventHandler('mythic-characters:server:CharacterCreated', function(source, character)
    -- Handler code
end)
Parameters:
​
source
number
Player server ID who created the character
​
character
table
Newly created character object with all fields
Examples: 
-- Give starter items
AddEventHandler('mythic-characters:server:CharacterCreated', function(source, character)
    -- Create inventory
    Inventory:Create(character.SID)

    -- Give starter items
    Inventory:AddItem(character.SID, 'phone', 1, {
        number = character.Phone
    })
    Inventory:AddItem(character.SID, 'water', 2)
    Inventory:AddItem(character.SID, 'sandwich', 2)
    Inventory:AddItem(character.SID, 'id_card', 1, {
        name = character.First .. ' ' .. character.Last,
        dob = character.DOB,
        gender = character.Gender
    })

    Logger:Info('Characters', 'New character created', {
        console = true,
        file = true
    }, {
        player = source,
        character = character.SID,
        name = character.First .. ' ' .. character.Last
    })
end)

-- Set default job
AddEventHandler('mythic-characters:server:CharacterCreated', function(source, character)
    Jobs:GiveJob(character.SID, 'unemployed')
end)

-- Send welcome notification
AddEventHandler('mythic-characters:server:CharacterCreated', function(source, character)
    TriggerClientEvent('mythic-notifications:client:Send', source, {
        message = 'Welcome to the city, ' .. character.First .. '!',
        type = 'success',
        duration = 5000
    })
end)

-- Create default bank account
AddEventHandler('mythic-characters:server:CharacterCreated', function(source, character)
    Database.Game:insertOne({
        collection = 'bank_accounts',
        document = {
            owner = character.SID,
            type = 'checking',
            balance = 5000,  -- Starting balance
            accountNumber = GenerateAccountNumber(),
            createdAt = os.time()
        }
    })
end)

​
mythic-characters:server:CharacterSelected

Fired when a player selects and loads a character. 
AddEventHandler('mythic-characters:server:CharacterSelected', function(source, character)
    -- Handler code
end)
Parameters:
​
source
number
Player server ID
​
character
table
Selected character object
Examples: 
-- Load character data for other systems
AddEventHandler('mythic-characters:server:CharacterSelected', function(source, character)
    -- Inventory is loaded automatically by the Inventory component on character select

    -- Load vehicles
    Database.Game:find({
        collection = 'vehicles',
        query = { owner = character.SID }
    }, function(success, vehicles)
        if success then
            TriggerClientEvent('mythic-vehicles:client:SetVehicles', source, vehicles)
        end
    end)

    -- Load properties
    Database.Game:find({
        collection = 'properties',
        query = { owner = character.SID }
    }, function(success, properties)
        if success then
            TriggerClientEvent('mythic-properties:client:SetProperties', source, properties)
        end
    end)

    -- Jobs are loaded automatically by the Jobs component on character select
end)

-- Log character selection
AddEventHandler('mythic-characters:server:CharacterSelected', function(source, character)
    Logger:Info('Characters', 'Character selected', {
        console = true,
        file = true
    }, {
        player = source,
        playerName = GetPlayerName(source),
        character = character.SID,
        characterName = character.First .. ' ' .. character.Last
    })

    -- Update last login
    Characters:UpdateCharacter(character.SID, {
        ['metadata.lastLogin'] = os.time()
    })
end)

-- Check for pending notifications
AddEventHandler('mythic-characters:server:CharacterSelected', function(source, character)
    Database.Game:find({
        collection = 'notifications',
        query = { target = character.SID, read = false }
    }, function(success, notifications)
        if success and notifications and #notifications > 0 then
            TriggerClientEvent('mythic-phone:client:ReceiveNotifications', source, notifications)
        end
    end)
end)

​
mythic-characters:server:CharacterDeleted

Fired when a character is deleted. 
AddEventHandler('mythic-characters:server:CharacterDeleted', function(source, characterId)
    -- Handler code
end)
Parameters:
​
source
number
Player server ID who deleted the character
​
characterId
number
SID of the deleted character
Examples: 
-- Clean up character data
AddEventHandler('mythic-characters:server:CharacterDeleted', function(source, characterId)
    -- Delete inventory
    Inventory:Delete(characterId)

    -- Delete all vehicles
    Database.Game:delete({
        collection = 'vehicles',
        query = { owner = characterId }
    })

    -- Delete properties
    Database.Game:delete({
        collection = 'property_ownership',
        query = { owner = characterId }
    })

    -- Delete phone data
    Database.Game:delete({
        collection = 'phone_messages',
        query = {
            ['$or'] = {
                { sender = characterId },
                { receiver = characterId }
            }
        }
    })

    -- Delete bank accounts
    Database.Game:delete({
        collection = 'bank_accounts',
        query = { owner = characterId }
    })

    Logger:Info('Characters', 'Character data cleaned up', {
        console = true, file = true
    }, { character = characterId })
end)

-- Log deletion for audit
AddEventHandler('mythic-characters:server:CharacterDeleted', function(source, characterId)
    Database.Game:insertOne({
        collection = 'audit_log',
        document = {
            type = 'character_deleted',
            player = GetPlayerIdentifier(source, 0),
            character = characterId,
            timestamp = os.time()
        }
    })
end)

​
State Change Events

​
mythic-characters:server:JobChanged

Fired when a character’s job or job grade changes. 
AddEventHandler('mythic-characters:server:JobChanged', function(characterId, newJob, newGrade, oldJob, oldGrade)
    -- Handler code
end)
Parameters:
​
characterId
number
Character SID
​
newJob
string
New job identifier
​
newGrade
number
New job grade
​
oldJob
string
Previous job identifier
​
oldGrade
number
Previous job grade
Examples: 
-- Give job-specific items
AddEventHandler('mythic-characters:server:JobChanged', function(characterId, newJob, newGrade, oldJob, oldGrade)
    if newJob == 'police' then
        -- Give police equipment
        Inventory:AddItem(characterId, 'weapon_pistol', 1)
        Inventory:AddItem(characterId, 'radio', 1)
        Inventory:AddItem(characterId, 'handcuffs', 1)
    elseif newJob == 'ems' then
        -- Give EMS equipment
        Inventory:AddItem(characterId, 'medkit', 5)
        Inventory:AddItem(characterId, 'bandage', 10)
    end

    -- Remove old job items
    if oldJob == 'police' then
        Inventory.Items:Remove(characterId, 1, 'weapon_pistol', 999)
        Inventory.Items:Remove(characterId, 1, 'handcuffs', 999)
    end
end)

-- Update permissions
AddEventHandler('mythic-characters:server:JobChanged', function(characterId, newJob, newGrade, oldJob, oldGrade)
    local player = Fetch:SID(characterId)

    if player then
        local source = player:GetData('Source')
        -- Update Discord roles or permissions
        TriggerEvent('discord:updateRoles', source, newJob)
    end
end)

-- Notify player
AddEventHandler('mythic-characters:server:JobChanged', function(characterId, newJob, newGrade, oldJob, oldGrade)
    local player = Fetch:SID(characterId)

    if player then
        local source = player:GetData('Source')
        local jobLabel = newJob
        local gradeLabel = Jobs:GetGradeLabel(newJob, newGrade)

        TriggerClientEvent('mythic-notifications:client:Send', source, {
            message = 'Job changed to ' .. jobLabel .. ' - ' .. gradeLabel,
            type = 'info'
        })
    end
end)

​
mythic-characters:server:MoneyChanged

Fired when a character’s cash or bank balance changes. 
AddEventHandler('mythic-characters:server:MoneyChanged', function(characterId, account, amount, newBalance, reason)
    -- Handler code
end)
Parameters:
​
characterId
number
Character SID
​
account
string
Account type: 'cash' or 'bank'
​
amount
number
Change amount (positive = added, negative = removed)
​
newBalance
number
New balance after change
​
reason
string
Transaction reason
Examples: 
-- Update client HUD
AddEventHandler('mythic-characters:server:MoneyChanged', function(characterId, account, amount, newBalance, reason)
    local player = Fetch:SID(characterId)

    if player then
        local source = player:GetData('Source')
        TriggerClientEvent('mythic-hud:client:UpdateMoney', source, {
            account = account,
            balance = newBalance,
            change = amount
        })
    end
end)

-- Log large transactions
AddEventHandler('mythic-characters:server:MoneyChanged', function(characterId, account, amount, newBalance, reason)
    if math.abs(amount) >= 10000 then  -- Log transactions $10k+
        Logger:Info('Economy', 'Large transaction', {
            character = characterId,
            account = account,
            amount = amount,
            newBalance = newBalance,
            reason = reason
        }, { file = true })
    end
end)

-- Achievement tracking
AddEventHandler('mythic-characters:server:MoneyChanged', function(characterId, account, amount, newBalance, reason)
    if account == 'bank' and newBalance >= 1000000 then
        -- Unlock millionaire achievement
        Achievements:Unlock(characterId, 'millionaire')
    end
end)

-- Transaction log
AddEventHandler('mythic-characters:server:MoneyChanged', function(characterId, account, amount, newBalance, reason)
    Database.Game:insertOne({
        collection = 'transactions',
        document = {
            character = characterId,
            account = account,
            amount = amount,
            balance = newBalance,
            reason = reason,
            timestamp = os.time()
        }
    })
end)

​
Client Events

​
mythic-characters:client:Spawned

Fired on the client when the character spawns in the world. 
AddEventHandler('mythic-characters:client:Spawned', function(character, location)
    -- Handler code
end)
Parameters:
​
character
table
Character data
​
location
table
Spawn location {x, y, z, heading}
Examples: 
-- Client-side initialization
AddEventHandler('mythic-characters:client:Spawned', function(character, location)
    -- Initialize HUD
    SendNUIMessage({
        type = 'INIT_CHARACTER',
        character = {
            name = character.First .. ' ' .. character.Last,
            cash = character.Cash,
            jobs = character.Jobs
        }
    })

    -- Load player appearance
    TriggerEvent('mythic-appearance:client:LoadAppearance', character.metadata.appearance)

    -- Enable controls
    FreezeEntityPosition(PlayerPedId(), false)

    print('Spawned as', character.First, character.Last, 'at', location.x, location.y, location.z)
end)

-- Camera transition
AddEventHandler('mythic-characters:client:Spawned', function(character, location)
    -- Fade out character selection screen
    DoScreenFadeOut(500)
    Wait(500)

    -- Spawn player
    SetEntityCoords(PlayerPedId(), location.x, location.y, location.z)
    SetEntityHeading(PlayerPedId(), location.heading)

    -- Fade in game world
    Wait(1000)
    DoScreenFadeIn(1000)
end)

​
mythic-characters:client:CharacterUpdated

Fired on the client when character data is updated. 
AddEventHandler('mythic-characters:client:CharacterUpdated', function(character)
    -- Handler code
end)
Examples: 
-- Update HUD
AddEventHandler('mythic-characters:client:CharacterUpdated', function(character)
    SendNUIMessage({
        type = 'UPDATE_CHARACTER',
        character = character
    })
end)

​
Using Events for Custom Logic

​
Hook Into Character Creation

-- Add custom welcome package
AddEventHandler('mythic-characters:server:CharacterCreated', function(source, character)
    -- Custom welcome logic
    local welcomePackage = {
        { item = 'phone', count = 1 },
        { item = 'water', count = 5 },
        { item = 'sandwich', count = 5 },
        { item = 'starter_pack', count = 1 }
    }

    for _, item in ipairs(welcomePackage) do
        Inventory:AddItem(character.SID, item.item, item.count)
    end

    -- Starting cash is set automatically via character defaults
end)

​
Track Playtime

local playtime = {}

-- Start tracking on character select
AddEventHandler('mythic-characters:server:CharacterSelected', function(source, character)
    playtime[character.SID] = os.time()
end)

-- Save playtime on disconnect
AddEventHandler('playerDropped', function(reason)
    local player = Fetch:Source(source)

    if player then
        local char = player:GetData('Character')

        if char and playtime[char:GetData('SID')] then
            local stateId = char:GetData('SID')
            local sessionTime = os.time() - playtime[stateId]
            local metadata = char:GetData('MetaData') or {}
            local totalPlaytime = (metadata.playtime or 0) + sessionTime

            -- Update database directly as player is disconnecting
            Database.Game:updateOne({
                collection = 'characters',
                query = {SID = stateId},
                update = {
                    ['$set'] = {['MetaData.playtime'] = totalPlaytime}
                }
            })

            playtime[stateId] = nil
        end
    end
end)

​
Custom Job Logic

-- Custom logic when becoming police
AddEventHandler('mythic-characters:server:JobChanged', function(characterId, newJob, newGrade, oldJob, oldGrade)
    if newJob == 'police' then
        -- Grant police access
        local player = Fetch:SID(characterId)

        if player then
            local source = player:GetData('Source')
            -- Give police permissions
            ExecuteCommand('add_principal identifier.' .. GetPlayerIdentifier(source, 0) .. ' group.police')

            -- Notify
            TriggerClientEvent('mythic-notifications:client:Send', source, {
                message = 'You are now a police officer',
                type = 'success'
            })
        end
    elseif oldJob == 'police' then
        -- Remove police access when leaving
        local player = Fetch:SID(characterId)

        if player then
            local source = player:GetData('Source')
            ExecuteCommand('remove_principal identifier.' .. GetPlayerIdentifier(source, 0) .. ' group.police')
        end
    end
end)

​
Best Practices

❌ Bad:
AddEventHandler('mythic-characters:server:CharacterCreated', function(source, character)
    -- Long synchronous operation
    for i = 1, 1000000 do
        -- Heavy work
    end
})
✅ Good:
AddEventHandler('mythic-characters:server:CharacterCreated', function(source, character)
    -- Use thread for heavy work
    CreateThread(function()
        -- Heavy work
    end)
})

AddEventHandler('mythic-characters:server:JobChanged', function(characterId, ...)
    -- Validate character exists (check if online)
    local player = Fetch:SID(characterId)

    if not player then
        Logger:Warn('Characters', 'JobChanged for offline character', {
            console = true,
            file = true
        }, {
            characterId = characterId
        })
        return
    end

    -- Process event
end)

local sessionData = {}

AddEventHandler('mythic-characters:server:CharacterSelected', function(source, character)
    sessionData[character.SID] = {
        loginTime = os.time(),
        source = source
    }
end)

AddEventHandler('playerDropped', function()
    local player = Fetch:Source(source)

    if player then
        local char = player:GetData('Character')

        if char then
            sessionData[char:GetData('SID')] = nil  -- Clean up
        end
    end
end)

​
Next Steps

Characters - Exports

Character management methods

Characters - Data Structure

Character data schema

Event System

Understanding the event system

Inventory Events

Inventory-related events
Event Timing: Character events fire in a specific order. Use this to your advantage - for example, CharacterCreated fires before CharacterSelected, so you can set up initial data in the creation handler.