# QBCore Code Generator: Lua Resources, Jobs & NUI Templates

Choose a resource type, configure its name and download editable Lua files with a matching `fxmanifest.lua`. Start with a [first scripting resource](/docs/guides/scripting) if you need the client/server model explained. These are scaffolds to adapt and test, not finished production scripts.

## Overview

The Resource Generator creates QBCore scaffolds with matched manifests, callbacks, configuration, and downloadable source files. Generated Lua is syntax-checked in CI, but each scaffold still requires server-specific configuration and in-game acceptance testing before production use.

## Template Capabilities

### Job Resource Template
- **QBCore Event Hooks**: Client events for `OnPlayerLoaded` and `OnJobUpdate` with helper bootstrap function.
- **Config & Locale Scaffolds**: Feature toggles persisted to `config.lua` plus starter locale entries in `locales/en.lua`.
- **Persistent Job Setup**: `setup/jobs.lua` contains a valid `QBShared.Jobs` entry to merge into `qb-core/shared/jobs.lua`; the generator does not invent a generic jobs SQL table.
- **Shared Metadata**: `shared.lua` includes the normalized job key, display label, grade placeholders, and feature comments.
- **Optional Extras**: Add event documentation and a small Lua configuration test from the generator panel.

### Shop System Template
- **Declared NUI Bundle**: HTML/CSS/JS assets are listed in `fxmanifest.lua`, with matching purchase and close callbacks.
- **Safe Purchase Boundary**: The generated server callback rejects malformed input and deliberately returns a disabled result until you implement authoritative item, price, money, capacity, and duplicate-request checks.
- **Configured Inventory**: Default shop items live in `config.lua` for expansion.
- **Optional Docs/Tests**: Generate event documentation and a configuration test without creating unused database tables.

### Housing Script Template
- **Callback Skeletons**: Server callback for fetching houses and client event for entering a property.
- **Configuration File**: `config.lua` seeded with debug flag and empty housing table.
- **Shared Flags**: `shared.lua` exposes multicharacter support state for downstream logic.
- **Optional Docs/Tests**: Create event documentation and a configuration test without implying database persistence that the scaffold does not implement.

### Heist Framework Template
- **Stage Hooks**: Client and server events are ready for custom stage logic; rewards must be resolved from server-owned state rather than client input.
- **Configurable Stages**: `config.lua` populated with sample stage timings to extend.
- **Feature Awareness**: Shared config tracks phone/management requirements for conditional behaviour.

### Phone App Template
- **qb-phone Integration**: Registers the open event plus matching NUI `data` and `close` callbacks.
- **UI Bundle**: Uses FiveM's runtime `GetParentResourceName()` bridge instead of hard-coding the resource URL.
- **Config Toggles**: `config.lua` exposes whether the feature requires the phone system.

### Utility Script Template
- **Shared Helpers**: Demonstrates exporting notify/log helpers across client and server.
- **Command Example**: Client script registers a sample command bound to the utilities module.
- **Server Logging Stub**: Placeholder server event that illustrates structured logging.

## Generator Options

All templates share optional documentation and Lua configuration-test toggles. Database migrations are intentionally not generated unless a template actually implements matching persistence logic.

## Validation Boundary

Every generated `.lua` file, including `fxmanifest.lua`, is parsed with Lua 5.4 in repository CI. Contract tests also check manifest file lists, concrete test filenames, NUI callback pairs, and server-authoritative heist reward handling.

This does **not** prove FiveM runtime compatibility for your server. Test generated resources on a staging server with the exact QBCore and dependent-resource revisions you deploy.

## Best Practices Included

### Code Structure
```lua
-- Example client.lua structure
local QBCore = exports['qb-core']:GetCoreObject()
local PlayerData = {}

-- Events
RegisterNetEvent('QBCore:Client:OnPlayerLoaded', function()
    PlayerData = QBCore.Functions.GetPlayerData()
end)

RegisterNetEvent('QBCore:Client:OnJobUpdate', function(JobInfo)
    PlayerData.job = JobInfo
end)

-- Functions
local function DoSomething()
    -- Your code here
end

-- Exports
exports('DoSomething', DoSomething)

-- Commands
RegisterCommand('example', function()
    DoSomething()
end, false)
