> For the complete documentation index, see [llms.txt](https://striga.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://striga.gitbook.io/docs/striga-tokyo-hud/installation-and-configuration.md).

# Installation & Configuration

Install Striga Tokyo HUD in a few minutes.

{% stepper %}
{% step %}

### Add the resources

Put the `striga-tokyo-hud` and `striga-core` folders in your `resources` folder (any subfolder is fine, for example `[striga]`).

Do not rename or move the files inside. Everything you may change is in `editable/`. The UI comes prebuilt, there is nothing to build.
{% endstep %}

{% step %}

### Remove your old HUD

Stop and remove **qb-hud**, **qbx\_hud** or **esx\_hud**. They use the same stress events, so both together double every stress gain.
{% endstep %}

{% step %}

### Start it in server.cfg

Start `striga-core` **first**, after ox\_lib, oxmysql and your framework. Then start the HUD:

```
ensure oxmysql
ensure ox_lib
ensure qb-core        # or qbx_core / es_extended
ensure striga-core
ensure pma-voice
ensure striga-tokyo-hud
```

{% hint style="warning" %}
Tokyo HUD needs **striga-core 0.1.0 or newer**.

* No striga-core: the HUD does not start.
* striga-core too old: striga-core stops the HUD and prints a red error in the server console. Update striga-core.
  {% endhint %}
  {% endstep %}

{% step %}

### Restart the server

Restart the server. The database tables are made by themselves, there is no SQL to import.

On a good start, striga-core prints a line like `striga-core ... ready (framework: qbcore, ...)` in the server console. No line? Fix that first, the HUD can do nothing without it.
{% endstep %}
{% endstepper %}

***

## striga-core settings

Framework, inventory, fuel and notifications are set in `striga-core/config.json`, so every Striga script uses the same setup. The parts the HUD uses:

| Key              | What it does for the HUD                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `framework`      | `"auto"` checks qbx\_core, then qb-core, then es\_extended, else standalone. Force `"qbcore"`, `"qbox"`, `"esx"` or `"standalone"` if it guesses wrong |
| `inventory`      | `"auto"` by default. Used for weapon names in the info panel                                                                                           |
| `notify`         | Where stress notifications show                                                                                                                        |
| `fuel.resources` | Fuel scripts to look for, in order. The first one running wins. A script with a `GetFuel(vehicle)` export usually only needs its name here             |
| `fuel.adapter`   | Leave on `"auto"` unless you registered your own fuel adapter                                                                                          |

Seatbelt, harness and pma-voice are found by striga-core too. After a change in `config.json`, restart striga-core, then the HUD.

***

## Updates

striga-core checks GitHub for new versions of your Striga scripts when the server starts. If one is out of date, you see a red `UPDATE` line in the server console with the download link.

To turn this off, set `"versionCheck": false` in `striga-core/config.json`. More on [Updates & Versions](/docs/updates-and-versions.md).

***

## Settings hub

The `/hud` menu is the settings place for the whole suite: every Striga script with player settings shows a block there, and the theme color goes to every script. Nothing to set up.

Full guide: [Settings Menu (/hud)](/docs/striga-tokyo-hud/settings-menu.md).

***

## Editable files

The resource uses FiveM Asset Escrow. Everything you may change is in `editable/`, and that folder ships open:

```
editable/
  config.lua                  all HUD settings
  locales/<code>.json         every text, one file per language
```

After a change, restart the resource. No rebuild needed.

### Languages

Each locale file has three parts:

* `_meta`: `name`, `dir` (`ltr` or `rtl`) and `intl` (a tag like `en-US`, for numbers and plurals).
* `game`: texts the game shows (key names, chat suggestion, stress notifications).
* `ui`: everything in the HUD and the menu.

Keep placeholders like `{n}` and `{time}`. Entries with keys like `one` and `other` are plural forms; `other` is always needed.

**Add a language:** copy `en.json` to for example `sv.json`, translate it, set `Config.Locale = 'sv'` and restart. For a new server-wide language see [Languages](/docs/languages.md). Missing keys fall back to English. Keep the file valid JSON.

***

## Config

File: `editable/config.lua`

### General

| Option                  | Default            | What it does                                                                                                                                                   |
| ----------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.Locale`         | `'auto'`           | `'auto'` follows the striga-core server language. A code (e.g. `'tr'`) pins this script to `editable/locales/<code>.json`. See [Languages](/docs/languages.md) |
| `Config.Command`        | `'hud'`            | Command that opens the menu                                                                                                                                    |
| `Config.MenuKey`        | `'F9'`             | Default key for the menu. `false` = command only                                                                                                               |
| `Config.UpdateInterval` | `200`              | ms between status updates. Players can make it faster or slower in the menu                                                                                    |
| `Config.HideWhenPaused` | `true`             | Hide the HUD in the pause menu                                                                                                                                 |
| `Config.MenuBlur`       | `true`             | Blur the game behind the `/hud` menu (never in the editor)                                                                                                     |
| `Config.ServerName`     | `'Striga Scripts'` | Shown in the info panel                                                                                                                                        |
| `Config.Currency`       | `'$'`              | Currency symbol for cash and bank                                                                                                                              |

### Info panel (`Config.Info`)

| Option           | Default | What it does                                             |
| ---------------- | ------- | -------------------------------------------------------- |
| `Enabled`        | `true`  | `false` = no info panel                                  |
| `Interval`       | `30000` | Backup refresh in ms. Name, money and job update at once |
| `WeaponInterval` | `200`   | ms between weapon / ammo checks, only while armed        |

### Compass (`Config.Compass`)

| Option                | Default | What it does                                                                      |
| --------------------- | ------- | --------------------------------------------------------------------------------- |
| `Enabled`             | `true`  | Top center compass on or off                                                      |
| `Interval`            | `100`   | ms between heading checks (sends only on a 1 degree change)                       |
| `StreetInterval`      | `1000`  | ms between street / zone checks                                                   |
| `StreetOnlyInVehicle` | `true`  | Default for players. Each player can pick always / on foot / in vehicle in `/hud` |

### Storage (`Config.Storage`)

Layouts are always cached on the player's PC, so the HUD shows at once on join.

| Option          | Default | What it does                                                                                            |
| --------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `Server`        | `true`  | Also save layouts per FiveM license in the database, so they follow the player to any PC. Needs oxmysql |
| `Share`         | `true`  | Share codes like `strg-7K2QX9`. Needs oxmysql                                                           |
| `ShareCooldown` | `300`   | Seconds before a player can make a new code                                                             |

### GTA texts (`Config.HideGtaHud`)

`VehicleName`, `VehicleClass`, `AreaName`, `StreetName`: `true` hides that GTA text in the bottom right. `StreetName` is hidden by default, the HUD has its own.

### Vehicle HUD (`Config.Vehicle`)

Shown only for the driver.

| Option              | Default  | What it does                                                                                                |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `Enabled`           | `true`   | Whole vehicle HUD, seatbelt and indicators included                                                         |
| `SpeedUnit`         | `'kmh'`  | `'kmh'` or `'mph'`. Boats and aircraft always use knots and feet                                            |
| `Interval`          | `250`    | ms between updates while driving                                                                            |
| `IdleInterval`      | `500`    | ms between checks on foot                                                                                   |
| `Seatbelt.Own`      | `'auto'` | `'auto'` = built in seatbelt only without qb-smallresources and qbx\_seatbelt. `true` always, `false` never |
| `Seatbelt.Key`      | `'B'`    | Key of the built in seatbelt                                                                                |
| `Seatbelt.Warning`  | -        | Chime when unbuckled: `Enabled` (`true`), `MinSpeed` (`20`), `Volume` (`0.20`), `Interval` (`1200`)         |
| `Indicators`        | -        | `Enabled`, keys `Left` (`'LEFT'`), `Right` (`'RIGHT'`), `Hazards` (`'UP'`). `false` = key not bound         |
| `ElectricModels`    | -        | Models that show a charge icon instead of fuel                                                              |
| `SpeedLimits`       | -        | Street name to speed limit, shows a sign                                                                    |
| `DefaultSpeedLimit` | -        | Limit for streets not in the list. `nil` = no sign                                                          |

```lua
ElectricModels = {
    [`neon`] = true,
},
SpeedLimits = {
    ['Great Ocean Hwy'] = 120,
    ['Alta St'] = 50,
},
DefaultSpeedLimit = 80,
```

{% hint style="info" %}
If `SpeedLimits` is empty, no sign shows anywhere. Street names must match what GTA calls them.
{% endhint %}

### Weapon labels (`Config.WeaponLabels`)

Fallback names for the info panel when the framework or inventory does not know a weapon:

```lua
[`weapon_pistol`] = 'Pistol',
```

### Voice (`Config.Voice`)

| Option      | Default  | What it does                                                       |
| ----------- | -------- | ------------------------------------------------------------------ |
| `Enabled`   | `'auto'` | On when striga-core finds pma-voice. `true` or `false` to force    |
| `ModeCount` | `3`      | Number of pma-voice range modes (default whisper / normal / shout) |

### Minimap (`Config.Minimap`)

| Option            | What it does                                                                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Enabled`         | `false` = vanilla minimap, not touched                                                                                                           |
| `HideHealthArmor` | Hide GTA's health / armor bars under the map                                                                                                     |
| `DisableBigmap`   | Block the big radar (keep it on, it breaks the custom position)                                                                                  |
| `Default`         | Player defaults: `position` (`'top-left'`, `'bottom-left'`, `'bottom-right'`), `shape` (`'rounded'`, `'circle'`), `waypointColor`, `vehicleOnly` |
| `Frame`           | Border and shadow: `Enabled`, `Color` (`'theme'` or a hex color), `Width` (`2`), `Radius` (`12`), `Vignette` (`0.5`), `Offset`, `Circle`         |
| `Offsets`         | Fine tuning of the map per corner, in screen fractions                                                                                           |

### Stress (`Config.Stress`)

Off by default.

| Option              | Default | What it does                                                                                                                                 |
| ------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `Enabled`           | `false` | `true` turns stress on                                                                                                                       |
| `Notify`            | -       | Notify the player when stress goes up or down                                                                                                |
| `MaxChangePerEvent` | `25`    | Most one GainStress / RelieveStress call can change                                                                                          |
| `WhitelistedJobs`   | -       | Jobs or job types that never gain stress (`leo`, `ambulance`)                                                                                |
| `Shooting`          | -       | `Enabled`, `Chance` (`0.1`), `Min` / `Max`, `WhitelistedWeapons`                                                                             |
| `Speeding`          | -       | `Enabled`, `Interval` (`10000`), `UseMPH`, `SpeedUnbuckled` (`50`), `SpeedBuckled` (`100`), `Min` / `Max`, `IgnoredClasses`, `IgnoredModels` |
| `Effects`           | -       | `Enabled`, `MinimumStress` (`50`), `Blur`, `Shake`, `RagdollAtMax` (off)                                                                     |

Stress is saved in the framework's player metadata. On standalone it resets on reconnect.

### Texts (`Config.Text`)

Empty by default. Override one game text by key: `menu`, `menuHelp`, `seatbelt`, `signalLeft`, `signalRight`, `hazards`, `stressGain`, `stressRemoved`.

```lua
Config.Text = {
    stressGain = 'Your custom text',
}
```

***

## Database

Both tables are made by themselves when oxmysql runs.

* `striga_hud_layouts`: one row per FiveM license.
* `striga_hud_shares`: share codes. Each player keeps at most 20 codes, older ones are deleted.

***

## Troubleshooting

Something does not work? See [Troubleshooting & FAQ](/docs/striga-tokyo-hud/troubleshooting-and-faq.md).

{% content-ref url="/pages/Xkw616bftBHrHeyFx7fT" %}
[Settings Menu (/hud)](/docs/striga-tokyo-hud/settings-menu.md)
{% endcontent-ref %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://striga.gitbook.io/docs/striga-tokyo-hud/installation-and-configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.