Customization

Discord Support

Guide for customizing nc-busjob through hook functions, editable files, and the route builder tool.

Integration Architecture

client/main.lua (encrypted) ──▶ client/client_utils.lua (editable)
server/main.lua (encrypted) ──▶ server/server_utils.lua (editable)

Server Utils (server_utils.lua)

Framework Detection: auto (qbx_core → qb-core → ox_core → es_extended)
Money: ServerUtils.AddMoneyToPlayer(), RemoveMoneyFromPlayer(), GetPlayerBalance()
Player Info: GetPlayerCitizenId(), GetPlayerDisplayName(), GetPlayerByCitizenId()
Logging: ServerUtils.Log() (default: debug print, uncomment for Discord/qb-log)
Event Hooks: OnRouteCompleted(), OnPaymentReceived()
Validation: CanStartRoute() — return false to block (e.g., require specific job)

Client Utils (client_utils.lua)

Framework: GetFramework(), GetCoreObject(), GetPlayerData(), GetVehiclePlate()
Target System: GetTargetSystem(), AddEntityTarget(), RemoveEntityTarget()
Framework Events: OnPlayerLoaded(), OnPlayerUnloaded(), OnJobUpdate()
Notifications: ShowNotification() (default: ox_lib, overridable)
Sounds: PlayCardBeep(), PlayCardFail(), PlayCashRegister(), PlayChangeReturn(), PlayRouteComplete()
Event Hooks: OnRouteStarted(), OnRouteCompleted(), OnPassengerBoarded(), OnPaymentCompleted(), OnStopReached(), OnChangeReturned()
Dispatch: ReportIncident() (uncomment for ps-dispatch)

Route Builder

The built-in route builder lets you create custom routes directly in-game using an interactive map.

How to Use

Open the Route Builder
```
/routebuilder
```
This opens a full-screen NUI with a GTA V satellite map.
Add Stops
- Click on the map to place bus stops
- Each stop is numbered automatically
- Drag stops to reposition them
Configure Route
- Set a route name
- Choose route color
- Configure stop details (name, zone, NPC counts)
Save the Route
- Click "Save" in the route builder
- The route is saved as a Lua file in the generated/ folder
- A timestamp is added to the filename (e.g., route_builder_20260228_143000.lua)
- A generated/latest_route.lua is also created for convenience
Apply the Route
- Open generated/latest_route.lua (or the timestamped file)
- Copy the Lua code
- Paste it into shared/config.lua inside Config.Routes
- Restart the resource

Example Output

The route builder generates ready-to-paste Lua code:

[6] = {
    id = 6,
    name = 'My Custom Route',
    description = 'Custom route',
    color = '#9333ea',
    requiredLevel = 1,
    basePay = 50,
    completionBonus = 100,
    estimatedTime = 15,
    stops = {
        { id = 1,  name = 'Stop A',  coords = vector4(123.45, -678.90, 30.00, 0.00),  waitTime = 10, minNPC = 1, maxNPC = 5, zone = 1 },
        { id = 2,  name = 'Stop B',  coords = vector4(234.56, -789.01, 31.00, 0.00),  waitTime = 10, minNPC = 1, maxNPC = 5, zone = 1 },
        -- ... more stops
    },
},

Route Stop Parameters

Parameter	Description	Example
`id`	Sequential stop number	`1`, `2`, `3`
`name`	Display name for the stop	`'Downtown Station'`
`coords`	Position + heading (vector4)	`vector4(x, y, z, heading)`
`waitTime`	Seconds bus waits at stop	`10`
`minNPC`	Minimum NPC passengers at stop	`1`
`maxNPC`	Maximum NPC passengers at stop	`5`
`zone`	Fare zone number (affects pricing)	`1`, `2`, `3`

Route Properties

Property	Description	Example
`id`	Unique route ID	`6`
`name`	Route display name	`'My Custom Route'`
`description`	Route description	`'A scenic downtown loop'`
`color`	HEX color for map display	`'#9333ea'`
`requiredLevel`	Minimum player level	`1`
`basePay`	Base earnings per stop	`50`
`completionBonus`	Bonus for completing the route	`100`
`estimatedTime`	Estimated minutes to complete	`15`

Bus Stops (bus.lua)

Physical bus stop marker locations are defined in shared/bus.lua, separate from route configurations. These are the 3D world markers where bus models stop:

BusStops.Routes = {
    [1] = {
        id = 1,
        name = 'Downtown Loop',
        color = '#4CAF50',
        stops = {
            { id = 1, name = 'Bus Stop #1', coords = vector4(x, y, z, heading), zone = 1 },
            -- ...
        },
    },
}

You can add new bus stop groups in bus.lua and reference them from route configurations.

Tips for Route Creation

Zone System: Use different zone numbers for fare calculation. More zones = higher fares.
NPC Counts: Downtown stops should have more NPCs (maxNPC = 5), rural stops fewer (maxNPC = 2).
Wait Time: Standard is 10 seconds. Busy stops can be 15.
Route Length: 8-15 stops is ideal. Too few feels short, too many gets tedious.
Route Color: Use distinct hex colors so routes are easily distinguishable on the map.

Adding Languages

Copy lang/en.lua → lang/xx.lua
Copy lang/en.json → lang/xx.json
Translate all strings
Set Config.Locale = 'xx' in shared/config.lua

Lua Locale (lang/xx.lua)

Used for server-side and client-side notifications, labels, and system messages.

JSON Locale (lang/xx.json)

Used for NUI (dashboard, HUD, payment screen) — loaded by the Vue 3 frontend.

Last updated: February 28, 2026