AP-Questionnaire V2: Documentation

Welcome to AP-Questionnaire V2! This system has been completely rebuilt from the ground up. Gone are the days of hardcoding exam questions into Lua files. V2 introduces a beautiful, fully interactive in-game tablet UI where admins and department managers can build, edit, and publish exams on the fly.

Dependencies & Installation

Before installing, ensure your server meets the following requirements:

Dependencies

• Framework: QBCore, ESX, Qbox, or a Custom framework.
• Database: oxmysql (or your framework's default async wrapper).
• Artifacts: Server artifact version 4752 or higher.

Installation Steps

Accessing the System

V2 is designed to be highly flexible. You can allow players to open the tablet via a chat command, or you can disable the command and use the client export to tie the tablet to an NPC, a desk (using qb-target/ox_target), or a radial menu.

Chat Command

By default, players and admins can open the tablet using:

• /exams (This can be changed or disabled in config.lua)

Client-Side Export

If you want to open the tablet via a third-party script (like an eye-target or phone app), use this client-side export:

-- CLIENT-SIDE EXPORT
-- Opens the main Citizen Portal (and Admin Panel if they have permissions)
exports['ap-questionnaire']:OpenTablet()

Creating Exams (The New In-Game Builder)

Creating exams is now done entirely in-game via the Admin Panel. Only Full System Admins can create new exams, but you can assign "Exam Managers" (e.g., Police Chiefs) to manage specific exams once created.

Developer Hooks: Custom Event Triggers

In the "Scoring" tab of the in-game builder, you can enable Custom Event Triggers. This allows you to define a specific Server Event name that the script will fire when a player interacts with the exam.

How to catch the event in your own scripts

If you define an event named my_custom_exam_event in the UI, you can listen for it in any server-side script like this:

-- SERVER-SIDE
RegisterNetEvent('my_custom_exam_event', function(source, action, examId, score)
    local src = source
    
    if action == "pass" then
        print("Player " .. src .. " just passed exam: " .. examId .. " with a score of " .. score)
        -- Give them a custom set of car keys, update a database, etc.
        
    elseif action == "fail" then
        print("Player " .. src .. " failed exam: " .. examId)
        
    elseif action == "cancel" then
        print("Player " .. src .. " closed the tablet during exam: " .. examId)
    end
end)

Legacy Dynamic Exams (Code-Based)

Note: With V2's in-game builder, this is rarely needed. However, if you are a developer who wants to force a player to take a one-off dynamic exam (generated via code that isn't saved to the DB), you can still use the legacy Client Export.

Client-Side Dynamic Exam Export

-- CLIENT-SIDE EXPORT
local result = exports['ap-questionnaire']:StartExam({
    title = "Dynamic Scenario Test",
    description = "A temporary exam generated by an external script.",
    logo = "https://img.icons8.com/fluency/256/test.png",
    minimum = 1,
    shuffleQuestions = true,
    amountOfQuestionsToShow = 1,
    Questions = {
        [1] = {
            question = "What color is the sky?",
            answers = { a = "Blue", b = "Green", c = "Red" },
            correctAnswer = "a"
        }
    }
})

-- Handle the result
if result then
    print("Player passed the dynamic exam!")
else
    print("Player failed the dynamic exam!")
end