Configuration

Everything lives in config.lua. Career ranks live in data/career.lua, texts in locales/. New settings are added to this file as each phase ships.

General

Database

Admin

Security

Career

With the default curve: level 5 at 1,988 XP, level 10 at 7,064, level 20 at 30,949, level 30 at 78,938, level 50 at 267,368.

Ranks (data/career.lua)

{ level = 10, key = 'rank_city' },                    -- name from locales
{ level = 10, key = 'rank_city', label = 'Metro' },   -- fixed name, ignores locales

Levels must be ascending and start at 1.

Job and shift

Depots

Config.Depots = {
    {
        id = 'downtown',
        label = 'depot_downtown',                        -- locale key or plain text
        blip = { enabled = true, sprite = 513, color = 5, scale = 0.8 },
        ped = { model = 's_m_m_gentransport', coords = vector4(...) },
        vehicleSpawns = { vector4(...), vector4(...) }, -- first free bay is used
        returnPoint = { coords = vector3(...), radius = 12.0 },
        servicePoint = { coords = vector3(...), radius = 10.0 }, -- optional, Phase 13
    },
}

The default coordinates are examples. Stand where you want the desk or a bay and run /buscoords (needs dev commands): the vector4 is copied to your clipboard. Invalid depots are skipped with a console message.

Vehicles

With VehicleKeys = 'custom', ns-bus fires the server events ns-bus:giveKeys and ns-bus:removeKeys with (src, netId, plate).

Bus condition, fuel, cleaning and upgrades

Every driver has their own bus of each model. Fuel, engine, body, cleanliness and interior (0 to 100) and the distance it has driven carry over to the next shift (table ns_bus_fleet). The server keeps the numbers; the game only shows them.

Service bay. Drive the bus into Config.Depots[].servicePoint (or the return point when a depot has none) and press G (or use the buttons in the dashboard's Vehicle tab): refuel, clean or repair. The server checks that the bus stays in the bay until the time is up; a route cannot start during a service.

Upgrades (data/upgrades.lua) are fitted at the depot desk and belong to that driver's bus of that model. Each level has a price, a career level and optionally a distance the bus must have driven. Active in this version: comfort (passenger mood), economy engine tune (fuel use), easy-clean interior (dirt), heavy-duty seats (interior wear). Brakes, engine, suspension, doors and safety are defined but not offered yet; new effects can be read with Condition.Effect(rec, name).

Stops

Stops are created in game with /busadmin and stored in the database. config.lua only holds the rules:

Creating a stop

1. Park a bus where it should stop (or stand there) and run /busadmin.
2. Create stop, set a code (legion_01) and a display name.
3. Select Bus stopping position: your vehicle's position and heading are stored.
4. Walk to the sidewalk and capture the waiting area, NPC spawn points, boarding and exit points and the ticket inspection area.
5. Save stop.

Routes

Routes are built in game with /busadmin and stored in the database.

Building a route

1. /busadmin → Create route, set a code (ls-101) and a name.
2. Stops → Add stop in driving order. Open a stop to move it, skip it on express routes, set a waiting time or remove it.
3. Set type, difficulty, direction, required level, minimum bus tier and payout multiplier.
4. The route is drawn on your map while you edit. Save route.
5. For the way back, open the saved route and pick Create return route.

Driving routes

Pay = (Base + PerStop x served + PerPassenger x delivered - MissedPenalty x missed) x route multiplier x difficulty x (1 + OnTimeBonus x on-time ratio), never below 0. delivered counts passengers taken to their stop.

XP = (Base + PerStop x served + PerPassenger x delivered + PerKm x km + PerRequest x requests served) x difficulty x (1 + OnTimeBonus x on-time ratio) + ticket XP + CleanBonus + PerfectBonus + conversation XP. XP never goes down; mistakes cost pay and reputation.

NPC passengers

Passenger models and idle animations live in data/passengers.lua.

At a stop, people get off first, then the queue boards into free seats. The doors close when everyone is done and the stop's waiting time has passed. Anyone who does not fit stays at the stop and you get a "no available seats" notice. A stuck NPC never costs you anything: the server settles it when its time runs out.

Capacity is the smaller of the model's capacity and the real number of passenger seats of the bus. To use only some seats, give the model a seats list; to choose which doors open at stops, give it a doors list.

Better stops: capture the waiting area, NPC spawn points, the boarding point (where the queue forms, next to the front door) and the exit point in /busadmin. Without them, passengers stand on the nearest pavement and queue beside the bus.

Stop requests

The HUD shows what waits at the coming stop: STOP REQUEST with the number of riders (bell icon), the number of people waiting, or "Nobody waiting, no request" when you may drive past. F6 lists the passengers on board, where each gets off and who pressed the button. A rider whose stop you drive past sits down unhappy and gets off at the next stop that is served.

Passengers: personality, conversations, events

Personalities and their effects are in data/passengers.lua, conversations in data/dialogues.lua (texts are locale keys), events in server/events/ (one file each).

When a passenger talks to you, their line shows in the HUD and as a subtitle; press F6 to answer. A sick passenger is an emergency: the route waits until you decide (stop the bus, call EMS or drive on to the next stop). Stopping only works when the bus is standing still. On foot near a passenger you can Talk to them or Ask destination with the target eye.

The route report shows the average satisfaction of the passengers you took to their stop.

Police inspections and fines

During an inspection the route waits and goes on where it was afterwards. Fare dodgers found are taken off the bus. The driver is fined only for dodgers they let on: nothing for one who slipped past unnoticed, half when you ignored "Ticket required", in full when you checked and let them in anyway. The amount is always calculated by the server; a police player only decides to issue or waive it.

Assignments and achievements

Drivers open the career menu at the depot desk, in the route menu (F6 while on shift) or with /busprofile. It shows level, rank and XP, reputation, the daily and weekly assignments with their progress and time left, achievements and statistics.

Assignments (data/assignments.lua)

Each period a driver gets a pick from this pool, weighted, by level, and only assignments for a route type that exists on the server. The pick is saved and does not change during the period.

{ id = 'd_city_routes', period = 'daily', key = 'asg_city_routes', event = 'route_completed',
    filter = { routeType = 'CITY' }, target = 3, reward = { money = 450, xp = 200 } },
{ id = 'w_distance', period = 'weekly', key = 'asg_distance', event = 'route_completed',
    amount = 'distance', unit = 'km', target = 500000, reward = { money = 3000, xp = 1200 } },

• event: route_completed (completed, paid routes only) or inspection
• amount: 1 (default), a number, or a field of the event: passengers, ticketsChecked, caught, requestsServed, served, distance (meters) ...
• filter: every field must match: a value (clean = true), a list (routeType = { 'CITY', 'NIGHT' }) or a range (onTimePct = { min = 90 })
• route fields: routeType, difficulty, served, missed, total, onTimePct, passengers, ticketsChecked, caught, evaded, requestsServed, requestsMissed, satisfaction, distance, clean, perfect, inspection; inspection fields: passed, kind, violations
• minLevel, maxLevel, weight are optional
• reward: money, xp, reputation, unlock (an id other resources can check with exports['ns-bus']:HasUnlock)

Never reuse an id for a different task. key is a locale key that gets the target as %d, or use label = 'My text %d'.

Achievements (data/achievements.lua)

{ id = 'routes_100', key = 'ach_routes_100', icon = 'route', stat = 'completed_routes', target = 100,
    reward = { xp = 1500, money = 5000 } },
{ id = 'perfect_route', key = 'ach_perfect_route', counter = 'perfect_routes', target = 1 },
{ id = 'master_driver', key = 'ach_master_driver', level = 40, hidden = true },
{ id = 'zero_fare_evasion', key = 'ach_zero_fare_evasion', event = 'route_completed',
    filter = { evaded = 0, ticketsChecked = { min = 10 } } },

One condition each: a career statistic (stat), a counter (perfect_routes, clean_routes, stops_served, requests_served, inspections_passed), a level, or a single matching event. The description is the locale key key .. '_desc'. Achievements are checked when a driver loads, so new ones also unlock for drivers who already reached them. Never rename a released id.

Interface (NUI) and statistics

The texts of every panel come from locales/; change them there. "Today" starts at midnight server time. The admin dashboard needs the same permission as before (ns-bus.admin or framework admin); the server checks it on every action.

Stops in the admin dashboard: stand where a point belongs (or park the bus on the stopping position) and press Capture here. Hide panel closes it but keeps your draft: walk to the next point and type /busadmin again. Routes: drag stops in the list to reorder them, click a grey stop on the map to add it, click a numbered stop to change its settings.

Tickets and fare dodgers

While passengers get on, one of them stands at the door at a time. A validator beep means they have a ticket. "Ticket required" means they do not, and they say so. Silence means someone is walking past without paying, and only a spot check catches them. Doing nothing lets the passenger in. Checking shows a ticket card (name, ticket, destination, valid or not).

XP, reputation and statistics for tickets are settled only when the route is completed, never for a cancelled route. Letting someone in without checking after a warning, or letting them in after seeing an invalid ticket, costs reputation; so does refusing a valid passenger. A dodger who slipped past unnoticed costs nothing yet, but police inspections (Phase 10) may find them.

Ticket machine (real players)

Players can ride a bus that is on a route like any passenger. On board they open the ticket machine with K and buy a ticket; the driver opens the same machine, sees the players on board and offers them a ticket. Prices, validity, money and the commission are decided on the server; a ticket is printed in the character's name and stored in ns_bus_tickets, so it survives a relog.

A rider holds one covering ticket at a time: buying again while a ticket is valid on this bus is refused. The driver cannot buy (drivers ride for free) and can only offer tickets to players on their own bus who have none. The machine works on real routes only, not on admin test drives.

Police inspections (routine and police players) check every player rider. One without a valid ticket pays PassengerFine themselves (an unpaid fine is written to the audit log); the driver is never blamed or fined for them. Tickets sold on a route show on the route report.

Integrations

Custom dispatch

With Provider = 'custom', ns-bus fires the client event ns-bus:dispatch with a ready alert (service, code, title, message, coords, blip). Listen to it from your own script, or edit Adapters.custom in bridge/dispatch.lua (that file is not escrowed).

Dispatch export signatures are based on each resource's public documentation. They change between versions, so test alerts with the version you run.

Notifications