Seasonal event system (advanced)

Watch

The goal

You are finishing a small event resource named qu_event. It has three moving parts:

• A config table, Config, that holds when the event runs (a start and end date, or a simple on/off flag) and what the reward is. This lives on the server and is the single source of truth for whether the event is live.
• A client script that asks to claim the reward when the player runs /claim.
• A server script that receives that request and is supposed to decide whether to grant the reward.

Right now the server grants the reward to anyone who asks, every time they ask. By the end you want this exact behaviour:

• A player who claims while the event is live and has not claimed before gets the reward once.
• A second claim by the same player is rejected. One reward per person.
• A claim sent outside the event window is rejected, even if the player's game insists the event is on.

What you start with

Below is the resource as it ships. The claim flows end to end, but every decision that protects it is left as a -- TODO:. Read the comments. Nothing is hidden; the gaps are written right into the code so you can see exactly what is missing.

The manifest. Note there is no lua54 line: Lua 5.4 is the only runtime now, so that old setting is gone.

-- fxmanifest.lua
fx_version 'cerulean'
game 'gta5'
 
shared_script 'config.lua'
client_script 'client.lua'
server_script 'server.lua'

The config. Set the event window and the reward here. You can gate the event two ways: a hard on/off flag, or a real date window. Both are shown so you can pick one.

-- config.lua
Config = {}
 
-- Simple switch. Flip to false to turn the event off instantly.
Config.EventActive = true
 
-- Date window (used when you check by dates instead of the flag).
-- These are os.time values for the first and last moment the event is live.
-- os.time(table) turns a date into a number you can compare.
Config.EventStart = os.time({ year = 2026, month = 2, day = 1,  hour = 0,  min = 0,  sec = 0 })
Config.EventEnd   = os.time({ year = 2026, month = 2, day = 14, hour = 23, min = 59, sec = 59 })
 
-- What a player gets for claiming. A name here; granting it is your job.
Config.Reward = { item = 'event_token', amount = 1 }

The client. It only asks. It has no power to decide anything, and that is the point.

-- client.lua
-- A real event UI would call this from a button. For the exercise we
-- expose it as a command so you can test by typing /claim.
RegisterCommand('claim', function()
    -- The client cannot be trusted to know if the event is live or if the
    -- player already claimed. It just asks the server and waits.
    TriggerServerEvent('qu_event:claimReward')
end, false)

The server. This is the part you will finish. Right now it hands out the reward to everyone, every time.

-- server.lua
 
-- Placeholder reward function.
-- A real server would call its framework (ESX, QBCore, Qbox) or oxmysql here.
-- For the exercise this is a stand-in so you can focus on the decisions.
local function GiveReward(src)
    print(('[qu_event] gave %s x%d to player %d'):format(Config.Reward.item, Config.Reward.amount, src))
end
 
-- Remembers who already claimed, keyed by a stable player identifier.
-- NOTE: this lives in memory, so a server restart wipes it. A real event
-- persists claims in oxmysql so they survive a restart. That is out of
-- scope here and is your Track B next step.
local claimed = {}
 
RegisterNetEvent('qu_event:claimReward', function()
    local src = source -- the real player id, set by the server, not the client
 
    -- TODO: check the event is currently active. Do NOT trust the client to
    --       tell you this. Decide it here from Config and the server clock.
 
    -- TODO: build a stable identifier for this player, then check the claimed
    --       table. If they already claimed, reject and stop.
 
    -- TODO: grant the reward and record the claim so a second /claim is refused.
 
    -- Right now it just gives the reward to anyone, always. That is the bug.
    GiveReward(src)
    print(('[qu_event] %d claimed the reward'):format(src))
end)

Your job

Finish server.lua so a claim only succeeds when the server agrees. The client already does its whole job: it asks. Everything below happens server-side.

Checklist

• Check the event is active on the server. Do not trust any client claim that it is. Decide it from Config: either read Config.EventActive, or compare os.time() against Config.EventStart and Config.EventEnd. If the event is not live, reject and stop.
• Build a stable identifier for the player. A raw player id like 1 is reused when players reconnect, so it is a poor key for "who already claimed". Use something stable for this session and key the claimed table by it.
• Check this player has not already claimed. If their identifier is already in claimed, reject and stop. One reward per person.
• Grant the reward and record the claim. Call GiveReward(src), then mark the identifier as claimed so the next /claim is refused.
• Reject politely on every failed check. A rejected claim should print a clear server-side line and give nothing, not error out.

The shape to aim for is the same as every server-authoritative feature: the client asks, the server checks, the server decides and records. The client never learns whether the event is live or whether it already claimed; it only finds out by asking.

Hints

Reveal the solution

-- config.lua
Config = {}
 
Config.EventActive = true
 
Config.EventStart = os.time({ year = 2026, month = 2, day = 1,  hour = 0,  min = 0,  sec = 0 })
Config.EventEnd   = os.time({ year = 2026, month = 2, day = 14, hour = 23, min = 59, sec = 59 })
 
Config.Reward = { item = 'event_token', amount = 1 }

-- client.lua
RegisterCommand('claim', function()
    TriggerServerEvent('qu_event:claimReward')
end, false)

-- server.lua (finished)
local function GiveReward(src)
    print(('[qu_event] gave %s x%d to player %d'):format(Config.Reward.item, Config.Reward.amount, src))
end
 
-- Who already claimed, keyed by a stable identifier. In memory only, so a
-- restart wipes it. A real event stores this in oxmysql (Track B).
local claimed = {}
 
-- Decide on the SERVER whether the event is live. Two strategies; use one.
local function isEventActive()
    -- Strategy A: a hard switch you can flip in config.
    if not Config.EventActive then
        return false
    end
 
    -- Strategy B: a real date window, judged by the server clock.
    local now = os.time()
    if now < Config.EventStart or now > Config.EventEnd then
        return false
    end
 
    return true
end
 
RegisterNetEvent('qu_event:claimReward', function()
    local src = source -- real player id, set by the server
 
    -- 1. Is the event live? Decided here, never trusting the client.
    if not isEventActive() then
        print(('[qu_event] %d claimed but the event is not active, rejected'):format(src))
        return
    end
 
    -- 2. A stable key for "who claimed". The raw src is reused on reconnect,
    --    so we key on the player's license, which stays the same.
    local identifier = GetPlayerIdentifierByType(src, 'license')
    if not identifier then
        print(('[qu_event] %d has no license identifier, rejected'):format(src))
        return
    end
 
    -- 3. Already claimed? One reward per person.
    if claimed[identifier] then
        print(('[qu_event] %d already claimed, rejected'):format(src))
        return
    end
 
    -- 4. Everything checked out. Grant the reward, then record the claim
    --    so the next /claim from this player is refused.
    GiveReward(src)
    claimed[identifier] = os.time()
    print(('[qu_event] %d claimed the reward (%s)'):format(src, os.date('%Y-%m-%d %H:%M', claimed[identifier])))
end)

What you practiced

• Decided on the server whether an event is live, instead of trusting the client to say so.
• Checked an event window with os.time and os.date against a server-owned start and end.
• Keyed a claim record by a stable player identifier so a reconnect does not earn a second reward.
• Refused a second claim by checking a server-side claimed table before granting anything.
• Granted the reward and recorded the claim only after every check passed, using return-early guards.
• Internalised the rule: both 'is it live' and 'did they claim' are server decisions, never client ones.

Nicely done. You just built the exact decision layer that separates an event a server runs once a year from one that gets farmed in an afternoon. The one thing left for production is memory that survives a restart: right now a reboot wipes the claimed table and everyone can claim again. Persisting each claim as an oxmysql row is a Track B job, and it slots straight into the spot where you set claimed[identifier]. You are ready for Track B. Go open it and turn this in-memory event into a database-backed one.

REFERENCES

Lua os.time / os.date ↗FiveM docs: events ↗