Achievements

🏆 Achievements Script Documentation

⚙️ Setup Instructions

1. SQL Import

Run the following SQL file to create the achievements table in your database:

achievements.sql

---

2. Config Setup

Edit your config.lua file to match your server's systems and desired behaviour:

Config = {
    System = {
        Debug = true,            -- Show debug zones for achievement areas
        Menu = "ox",             -- Menu type: "qb", "ox"
        Notify = "qb",           -- Notifications: "qb", "ox", "esx", "okok", "gta"
        ProgressBar = "ox",      -- Progress bars: "qb", "ox"
    },
    Crafting = {
        showItemBox = true,      -- Only works if your inventory supports item boxes
    },
    OpenUICommand = 'achievements',  -- Command to open achievements menu
    NotificationTimeout = 10,        -- Time (in seconds) the earned notification is shown
}

---

📂 Achievement Structure

Each achievement is defined in Config.Achievements using a unique code. Example:

['ACH001'] = {
    imgSrc = "first_kill.png",
    title = "First Kill",
    description = "Defeat your first zombie",
    group = 'zombiekills',
    valueNeeded = 1,
}

Fields:

Field	Description
imgSrc	Image name (used in UI popups)
title	Display title for the achievement
description	What the player needs to do
group	Optional group tag (used for AddGroupValue)
valueNeeded	How much progress is needed to complete the achievement

Achievements are displayed alphabetically in the UI by their title.

---

🧠 How It Works

🧾 Database Initialisation

When the player loads, their achievements are automatically initialised or updated via:

TriggerServerEvent('tss-achievements:CheckDB')

📊 Updating Progress

You can increase progress either for a specific achievement or for a group of achievements.

✅ Add Value (Single)

Client-Side Event Example:

TriggerServerEvent('tss-achievements:AddValue', "ACH001", 1)

Server-Side Export Example:

exports['tss-achievements']:AddValue(source, "ACH001", 1)

---

✅ Add Group Value

Used to increment all achievements that belong to a specific group.

Client-Side Event Example:

TriggerServerEvent('tss-achievements:AddGroupValue', "zombiekills", 1)

Server-Side Export Example:

exports['tss-achievements']:AddGroupValue(source, "zombiekills", 1)

---

🚫 Removing Progress (Optional)

If needed, you can also remove progress:

• RemoveValue(src, code, value)

• RemoveGroupValue(src, group, value)

These support both exports and events.

---

🖥️ UI Integration

🔘 Open Menu

Command:

/achievements

Or trigger the event manually:

TriggerEvent('tss-achievements:OpenAchievements')

📦 What Happens:

• Triggers tss-achievements:GetAchievements server callback

• Sends the list of achievements with progress to the UI

• UI is opened via NUI and player can view their stats

---

🌟 Achievement Earned Notification

When an achievement is completed:

TriggerClientEvent('tss-achievements:AchievementEarned', src, code)

Triggers a client-side NUI popup showing the achievement title, imgSrc, and an optional timer.

Example UI Data Sent:

{
    action = "achievement-earned",
    Image = "first_kill.png",
    Title = "First Kill",
    Timer = 10000
}

---

🧩 Available Exports

You can call these server-side exports from other scripts:

Export	Description
AddValue(src, code, value)	Add value to a single achievement
RemoveValue(src, code, value)	Remove value from a single achievement
AddGroupValue(src, group, value)	Add value to all achievements with matching group
RemoveGroupValue(src, group, value)	Remove value from all achievements in the group
GetAchievements(src)	Returns decoded achievements table for the player
HasAchievement(src, code)	Returns true/false if player has completed the achievement

---

🧪 Example Integration

-- Check if player has earned a specific achievement
local hasSlayed = exports['tss-achievements']:HasAchievement(source, "ACH002")
if hasSlayed then
    print("Player has killed 500 zombies!")
end

---