# Features

Koja Trucker includes a full set of progression, social, and admin-driven systems. This page groups the core features in one place.

### What's included

* [Leaderboard](#leaderboard)
* [Convoys](#convoys)
* [Companies](#companies)
* [Localization](#localization)
* [Promo codes](#promo-codes)
* [Orders](#orders)
* [Rentals](#rentals)
* [Quests](#quests)
* [Skills](#skills)

### Leaderboard

The leaderboard ranks **companies** by earnings across three time ranges.

#### Ranges

* **This week**
* **This month**
* **All time**

#### What's shown

* A **podium** for the top 3 with badges, earnings, and member counts.
* A full **standings** table with rank, company, earnings, km, members, and rank delta.
* The player's **own company** is highlighted with a `YOU` tag.

Weekly company stats are reset by the admin **Weekly reset** action. That also clears members' weekly delivery counts.

### Convoys

A **convoy** lets multiple drivers haul the **same contract together** and all get paid on delivery.

#### How it works

1. A driver creates a convoy from the tablet top bar and invites up to **3** others.
2. When the leader accepts an order, it is replicated to every convoy member.
3. All members must use a matching vehicle class before loading begins.
4. Everyone drives to pickup, loads, and delivers.
5. Each driver is paid for their own run.

#### Riding along

A player can ride as a **passenger** in the leader's truck. Passengers are paid automatically when the driver completes the delivery.

#### Cancellation

If the leader or a member leaves mid-run, convoy mates are notified and the run is handled gracefully. Followers can still finish their own delivery, depending on timing.

### Companies

Players can found a **company**, recruit drivers, and build a shared brand that competes on the leaderboard.

#### Roles

| Role        | Can do                                                     |
| ----------- | ---------------------------------------------------------- |
| **Owner**   | Everything: settings, bank, disband, promote/demote, kick. |
| **Manager** | Invite, accept/reject join requests, kick drivers.         |
| **Driver**  | Haul under the company and contribute to its stats.        |

#### Tabs

* **Overview** — totals, live activity feed, level progression, server rank.
* **Members** — roster with online status, weekly deliveries, and contribution.
* **Invitations** — invite by ID or name and review join requests.
* **Statistics** — weekly/monthly earnings, category breakdown, highlights.
* **Bank** — deposit, withdraw, and transaction history.
* **Settings** — name, tag, description, avatar, recruitment mode, min level, cut.

#### The company cut and bank

The owner can set a **company cut** from `0–50%` on every employee delivery. The cut lands in the **firm bank**. Drivers see it as a line item on the end screen.

#### Recruitment modes

| Mode            | Meaning                                               |
| --------------- | ----------------------------------------------------- |
| **Open**        | Anyone meeting the level requirement joins instantly. |
| **Invite only** | Players must request to join or be invited.           |
| **Closed**      | No new members and hidden from the company browser.   |

#### Founding requirement

By default a player must be **level 5** to found a company with `Config.Company.MinLevelToCreate`.

### Localization

Koja Trucker ships fully translated into **9 languages** and every user-facing string is translatable.

| Code | Language |
| ---- | -------- |
| `en` | English  |
| `pl` | Polski   |
| `de` | Deutsch  |
| `es` | Español  |
| `fr` | Français |
| `hi` | हिन्दी   |
| `ja` | 日本語      |
| `ru` | Русский  |
| `zh` | 中文       |

#### How it works

* Translation files live in `locales/<code>.json` and share the same key structure.
* The default language is `general.locale` in the config.
* The tablet UI, Lua notifications, blips, and help text read from the same files.

#### Adding or editing a language

1. Copy `locales/en.json` to `locales/<code>.json`.
2. Translate the values and keep the keys identical.
3. Set `general.locale` to your code.

:::hint{type="info"}
Native GTA text renders Latin and Cyrillic reliably, but not CJK or Devanagari. For `hi`, `ja`, and `zh`, those specific strings stay in English by design. Tablet and notification text is still fully translated.
:::

### Promo codes

Promo codes grant a **temporary reward boost**. They work well for events and **Tebex** rewards.

#### Redeeming

Players redeem codes from the **dashboard** on the tablet. There is no chat command.

#### Code fields

| Field        | Meaning                                                     |
| ------------ | ----------------------------------------------------------- |
| `code`       | What the player types. Case-insensitive.                    |
| `kind`       | `money`, `xp`, or `sp` — what gets multiplied.              |
| `multiplier` | For example, `2.0` doubles the reward.                      |
| `duration`   | How long the boost lasts, in seconds.                       |
| `max_uses`   | Total redeems before the code expires. `0` means unlimited. |
| `expires_at` | Unix timestamp hard expiry. `0` means never.                |
| `note`       | Internal note such as Tebex SKU or event name. Not shown.   |

A player can redeem a given code **once**.

#### Managing codes

Create and manage codes from **Admin → Promos**, or programmatically:

* `CreatePromoCode`
* `DeletePromoCode`
* `GrantPromoEffect`

:::hint{type="success"}
For Tebex rewards, `GrantPromoEffect` lets you apply a boost directly to a player without using a visible code.
:::

### Orders

Orders are the core contracts players haul. Each order targets a **vehicle class** and belongs to a **category** that changes the rules and reward.

#### Vehicle classes

| Class | Type           | Loading style                                     |
| ----- | -------------- | ------------------------------------------------- |
| 1     | **Van**        | Small box — drive to the marker and load          |
| 2     | **Truck**      | Depot loading — carry crates into the back        |
| 3     | **Semi-truck** | Forklift loads pallets onto a trailer you hook up |

#### Categories

| Category      | Behaviour                                                              |
| ------------- | ---------------------------------------------------------------------- |
| **Default**   | Standard delivery.                                                     |
| **Urgent**    | Has a deadline. Late delivery cuts payout by 50%.                      |
| **Dangerous** | Cargo explodes if you exceed a damage threshold.                       |
| **Fragile**   | Each hit reduces payout. Too many hits destroys the cargo.             |
| **Illegal**   | Police may stop and arrest you mid-delivery. Higher risk, higher pay.  |
| **Business**  | Exclusive company contract. One driver at a time. Respawns on a timer. |

#### Business orders

Business orders are premium, single-driver contracts shown on their own tablet screen. While one driver has it, it shows as `taken` to everyone else and restocks after `business_respawn_interval` seconds.

The reward can be fixed or rolled between `business_reward_min` and `business_reward_max`.

#### Creating orders

Open **Admin → Orders → New order**. You set:

* Identity — label, id, description, category, crate image.
* Requirements and reward — vehicle class, required level, payout, XP.
* Cargo — weight, predicted time, props.
* Pickup and drop-off — captured in-game with a live coordinate picker.

A live tablet preview updates as you type.

#### Anti-cheat

Server-side, a delivery is only paid out if the player is **actually at the drop-off zone**. Suspicious completions are reported to the anti-cheat Discord channel.

### Rentals

Players who do not own a suitable rig can **rent one** from the tablet. An NPC driver delivers it to the nearest road and leaves it for them.

#### Flow

1. Open **Rentals**, filter by class, and rent a vehicle.
2. An NPC spawns and drives the rig to you.
3. The rental stays valid for a set number of **deliveries**.

#### Configuration

Rentable vehicles are defined in `data/vehicles.json` and edited via **Admin → Vehicles**. A vehicle becomes rentable once it has a **rental price** and a **deliveries** count.

The class and capacity are also defined there. They control which orders a player can accept.

#### Notes

* The rental price is charged from the player's **bank account**.
* A player may only hold **one active rental** at a time.
* Starting an order requires a valid rental or owned vehicle of that class.

### Quests

**Daily** and **weekly** quests give players extra goals and rewards. Each player gets a random selection from a configurable pool.

#### How it works

* Every player receives **N daily** and **N weekly** quests.
* **Daily** quests reset at midnight server time.
* **Weekly** quests reset every Monday.
* Progress updates live as the player delivers.
* Completed quests are claimed from the **Quests** tab.

Players who already have quests for the current period keep them until the next reset. Editing the pool only affects new assignments.

#### Quest types

| Type         | Counts                            |
| ------------ | --------------------------------- |
| `deliveries` | Any completed delivery            |
| `distance`   | Kilometres driven                 |
| `earn`       | Money earned from deliveries      |
| `night`      | Deliveries completed at night     |
| `flawless`   | Deliveries with no fragile damage |
| `category`   | Deliveries of a chosen category   |
| `class`      | Deliveries with a chosen class    |

Rewards can combine **money**, **XP**, and **skill points**.

#### Editing quests

Open **Admin → Quests**. You can set how many of each type are shown, then add, edit, or remove quests in the daily and weekly pools. Everything is saved to `data/quests.json`.

### Skills

Drivers earn **skill points** on level-up and spend them on perks across **three skill trees**.

#### Trees

| Tree      | Focus                |
| --------- | -------------------- |
| **Van**   | Light delivery perks |
| **Truck** | Medium hauler perks  |
| **Semi**  | Heavy hauler perks   |

#### Example perks

Perks are configured in `data/skills.json` and edited from **Admin → Skills**.

* **Loading speed** — faster load and unload.
* **Night jobs** — bonus payout for deliveries between `22:00–05:00`.
* **More per KM** — extra payout scaling with route distance.
* **Cheaper company cut** — lowers the firm cut.
* **Lucky streak** — chance for a `+25%` payout.
* **Veteran XP** — extra XP per run.
* **No time penalty** — removes the urgent late penalty.
* **Trailer durability** — tougher cargo.

Each perk can have multiple levels with rising costs and prerequisites.

:::hint{type="info"}
All bonus math is computed server-side at delivery time, including the night-shift check.
:::

## Related pages

- [Installation](/jobs/trucker/installation) — Make sure these are installed and started before Koja Trucker.
- [Commands](/jobs/trucker/commands) — Every admin command lives under one root: /truckeradmin.
- [Configuration](/jobs/trucker/configuration) — Almost everything is editable live from the in-game admin panel (no restart), and persisted to data/config.json. You can also edit that file directly.
- [Trucker](/jobs/trucker) — back to the section overview