> For the complete documentation index, see [llms.txt](https://docs.kojascripts.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kojascripts.eu/jobs/trucker/features.md).

# 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 style="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.
{% endhint %}

### 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 style="success" %}
For Tebex rewards, `GrantPromoEffect` lets you apply a boost directly to a player without using a visible code.
{% endhint %}

### 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 style="info" %}
All bonus math is computed server-side at delivery time, including the night-shift check.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kojascripts.eu/jobs/trucker/features.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.