# House Robbery

***

### 1. What This Script Does

This resource adds an advanced house robbery loop to your RedM server:

* Players talk to a **robbery vendor NPC** to start a job
* Players choose a house **level (1–5)** gated by trust level
* Players pay money and/or give items (lockpick, etc.) based on config
* A random house location is selected per level and marked with **GPS + blip**
* Players lockpick the door using a configurable **minigame**
* Inside the house:
  * Sleeping NPC + guard dog spawn
  * A **noise system** tracks player actions (too loud → NPC wakes + police alert)
  * Players loot configured spots for items or money
* Exiting correctly (and looting everything) can increase the player’s trust
* Optional **bucket/routing bucket** system isolates robberies per player

All gameplay is driven by a single config table:

```lua
Codex = {
  -- all settings...
}
```

***

### 2. Requirements & Dependencies

#### Required

* RedM (`fx_version cerulean`, `game rdr3`)
* `codex_core` — money, items, jobs, callbacks, notifications integration
* `ox_lib` — context menus
* `codex_trustlevel` — trust/reputation gating (default profile: `breaker`)
* A notification system listening to `TriggerEventNotification` (default: `lab-lib:notification`)

#### Recommended / Optional

* `SS-PoliceJob` — advanced police alert system (used when `SSPolice = true`)
* `legends-keypress` — lockpick minigame (used by the default example in `CustomLockPick`)

✅ Ensure all dependencies start before `codex_house_robbery`.

***

### 3. Installation

1. Place the resource folder (e.g. `codex_house_robbery`) into your resources directory.
2. Ensure the UI files exist:
   * `html/index.html` — noise progress bar UI
   * `html/scripts.js` — NUI message handling
   * `html/style.css` — UI styling
3. Confirm `fxmanifest.lua` paths are correct.
4. Add to `server.cfg`:

```cfg
ensure ox_lib
ensure codex_core
ensure codex_trustlevel
ensure SS-PoliceJob    # if used
ensure codex_house_robbery
```

5. Configure `codex_config.lua` (see below).

> ⚠️ **Important**\
> The config header warns **not to restart this resource while players are online**, or the script may not work correctly until a full server restart.

***

### 4. Player Gameplay Flow

High-level experience based on config:

1. **Find the vendor NPC** (from `NpcsLocations`)
2. Press the interaction key (default: **G**) within `DistanceToInteractWithVendor`
3. Choose **Apartment Level 1–5**
   * Each level requires minimum trust (`LeveL1AccessTrust` ... `LeveL5AccessTrust`)
4. Script checks:
   * Player isn’t already on a robbery
   * Enough law jobs online (`LawManNeeded`, `LawJobs`)
   * Cooldown valid (`CooldownType`, `GlobalCoolDown`)
   * Money/item requirements (`CheckForMoney`, `CheckForItem`, etc.)
5. Player receives random house location (from `HousesForRob`) + GPS/blip
6. Player lockpicks door (default or custom minigame)
7. On success:
   * Optional bucket instance (`EnableBucketSystem`)
   * Teleport inside (`TeleportInsideCoords`)
   * Sleeping NPC + dog spawn
8. Noise system runs:
   * Too loud (≥ `AwakeNpcandPoliceAlertNoise`) → NPC wakes + police alert
9. Player loots configured spots (`LootLocations`)
10. Player exits properly via `GoOutSideCoords` → teleports out
11. If all loot completed → trust increase request (`AddTrustLevel`)

***

### 5. Global Configuration Overview

All settings live inside:

```lua
Codex = {
  -- all settings
}
```

#### 5.1 General & Debug

* `SeasonCheck` — delay (ms) while waiting for core (default `1000`)
* `DeveloperMode` — debug prints (`true` for testing, `false` for production)
* `VersionNextUpdate` — internal toggle for some features (leave default)
* `SSPolice` — use `SS-PoliceJob` alerts when `true`
* `ResetThePlayerBucketOnLoad` — resets players to bucket 0 after load

***

#### 5.2 Admin & Player Commands

* `AdminCommandForSetBucket` — admin bucket set command (default `set_bucket`)
* `UserCommandBacket` — prints player bucket id (default `mybucket`)
* `UserCommandTrust` — prints trust to console (default `mytrust`)
* `AdminSteamIDs` — list of Steam IDs allowed to use admin bucket commands

***

#### 5.3 Keybinds

Keys map to RedM control hashes:

```lua
Codex.Keys["G"] = 0x760A9C6F
```

Internally:

* `G` — vendor interaction, robbery menu, lockpick/loot
* `E` — exit house

> ⚠️ Only change the hex codes if you’re sure of the correct mapping.

***

#### 5.4 Interaction Distances

* `DistanceToInteractWithVendor` — vendor prompt radius (default `2.0`)
* `InteractWithHouse` — door/loot interaction distance (default `2.0`)

***

#### 5.5 Vendor NPC Setup (`NpcsLocations`)

```lua
NpcsLocations = {
  {
    name = "Mateo Romualdo",
    npcmodel = "u_m_m_bht_outlawmauled",
    coords = { x = 2917.28, y = 1380.4, z = 56.22, h = 251.65 },
  },
}
```

Add more vendors by adding entries.

***

#### 5.6 Notification Event

`TriggerEventNotification` is the client event used for notifications.

Default:

```lua
TriggerEvent("lab-lib:notification", "Your message", 6000)
```

Make sure your notification script listens to the configured event name.

***

#### 5.7 Economy & Items

| Setting                  | Meaning                               |
| ------------------------ | ------------------------------------- |
| `CheckForMoney`          | Player must pay when starting robbery |
| `MoneyNeeded`            | Amount charged                        |
| `MoneyAccount`           | Account index (per `codex_core`)      |
| `CheckForItem`           | Player must give an item to start     |
| `ItemName`               | Item ID required                      |
| `ItemQuantity`           | Quantity required                     |
| `ItemTolockpick`         | Item required for lockpick step       |
| `ItemQuantityTolockpick` | Quantity consumed on lockpick         |

💡 Item names must exist in your inventory and be recognized by `codex_core`.

***

#### 5.8 GPS & Models

* `HashKeyGpsColor` — GPS route color (e.g. `COLOR_RED`)
* `PedHomeHash` — sleeping NPC model
* `Weaponhash` — weapon given when NPC wakes
* `DogHomeHash` — dog model

Ensure all models and weapon hashes are valid for RedM.

***

### 6. Trust System & Level Access

#### 6.1 Trust Profile

* `TrustSystem` — trust category name used by `codex_trustlevel` (default `breaker`)
* `LeveL1AccessTrust` ... `LeveL5AccessTrust` — minimum trust per level
* `AddTrustLevel` — trust rewarded after fully looting and exiting correctly

Example trust gates:

* Level1: `0`
* Level2: `10`
* Level3: `20`
* Level4: `40`
* Level5: `80`

#### 6.2 Player Trust Command

Default: `/mytrust` prints trust level to F8 console.

***

### 7. Police & Noise System

#### 7.1 Noise Settings

Noise increases from actions:

* Running/sprinting/climbing/jumping → `GainHighestNoise`
* Walking → `GainWalkingNoise`
* Shooting → `GainShootingNoise`

Threshold:

* `AwakeNpcandPoliceAlertNoise` — wakes NPC and alerts police

Progress bar text values:

* `NoiseTextSilentPerfect`
* `NoiseTextNormal`
* `NoiseTextTread`
* `NoiseTextRisky`
* `NoiseTextSoLoud`

***

#### 7.2 Anti-Abuse Radius

* `AntiAbuseRadius` — max distance players can travel during robbery

If exceeded (without proper exit), they are snapped back inside to prevent glitch escapes.

***

#### 7.3 Law Jobs & Required Count

* `LawJobs` — jobs considered law enforcement (e.g. `police`)
* `LawManNeeded` — minimum law job players online to allow robberies

***

#### 7.4 Police Alert Modes

**SS-Police Integration (`SSPolice = true`)**

* Uses SS-PoliceJob exports to count on-duty police
* Sends alerts and blips to them

**Default Law Job Notification (`SSPolice = false`)**

* Tracks online law players
* On threshold:
  * Sends notification
  * Adds map blip for robbery location

***

### 8. Bucket System (Instance Handling)

* `EnableBucketSystem`
  * `true` → player moved into a random bucket per robbery
  * `false` → bucket logic disabled
* `ResetThePlayerBucketOnLoad = true` resets players to bucket 0 on load

#### Admin Bucket Command

`/set_bucket [playerId] [bucketId]`

Only allowed for `AdminSteamIDs`.

#### Player Bucket Command

`/mybucket` prints current bucket ID.

***

### 9. Mini-Game / Lockpick System

#### 9.1 Config Hook

* `MiniGameTotalTime` — time window
* `MiniGameKeyNeededSuccess` — required successes

You may set fixed values or use `math.random`.

***

#### 9.2 Custom Lockpick Integration

* `CustomlockpickSystem`
  * `true` → run `CustomLockPick(cb)`
  * `false` → use default internal minigame logic

Your custom function must always call:

```lua
cb(true)  -- success
-- or
cb(false) -- fail
```

***

### 10. Houses Configuration (`HousesForRob`)

This table defines all robbable houses and interiors.

#### Common House Fields

| Field                   | Description                               |
| ----------------------- | ----------------------------------------- |
| `ApartmentLevel1..5`    | Outside entrance coords for a given level |
| `TeleportInsideCoords`  | Spawn point inside the house              |
| `GoOutSideCoords`       | Exit interaction point inside             |
| `TeleportOutSideCoords` | Teleport location outside on exit         |
| `NpcSleepingLocation`   | Sleeping NPC spawn (vector4)              |
| `DogSleepingLocation`   | Dog spawn (vector4)                       |
| `LootLocations`         | Loot points & rewards                     |

#### LootLocations Entry

Each loot spot may include:

* `Pos` (vector3)
* `Reward` (item name or `dollars`)
* `Amount` (number or `math.random(min,max)`)
* Optional prop:
  * `ModelName`
  * `ModelPos`

If `VersionNextUpdate = true`, loot props can be spawned and removed on loot.

***

#### Adding New Houses

1. Duplicate an existing entry in `HousesForRob`
2. Update:
   * `ApartmentLevelX` door location
   * `TeleportInsideCoords`
   * exit coords
   * NPC + dog spawn
   * loot points & rewards
3. Ensure all `Reward` items exist in your inventory system
4. Test with `DeveloperMode = true`

***

### 11. Cooldown System

* `GlobalCoolDown` — cooldown duration (ms)
* `CooldownType`
  * `global` → shared cooldown for all players
  * `player` → per-player cooldown

If cooldown is active:

* Player cannot start
* Menu displays remaining time

***

### 12. Admin / Debug Tips

* Set `DeveloperMode = true` while testing
* Use:
  * `/mytrust` to view trust
  * `/mybucket` to verify instance bucket
  * `/set_bucket [id] 0` to reset stuck players

> ⚠️ Set `DeveloperMode = false` on production servers.

***

### 13. Troubleshooting

#### Players can’t see notifications

* Verify `TriggerEventNotification` matches your notifications resource
* Confirm argument format: `(message, duration)`

#### Players can’t talk to the vendor

* Check `NpcsLocations` coords and model
* Increase `DistanceToInteractWithVendor`
* Verify resource start order and console errors

#### Robberies won’t start (not enough law jobs)

* Lower `LawManNeeded`
* Ensure job names in `LawJobs` match `codex_core`

#### Lockpick minigame never starts / always fails

* If custom: ensure `CustomLockPick` always calls `cb(true/false)`
* If default example: ensure `legends-keypress` is running

#### Players stuck in houses / invisible

* Check `EnableBucketSystem` and `ResetThePlayerBucketOnLoad`
* Admins can use `/set_bucket id 0` to reset bucket

***

### ✅ Summary

Codex Advanced House Robbery is a fully configurable robbery system with:

* Trust-gated tiers
* Payments/items requirements
* Noise + police alert mechanics
* Loot tables per house
* Optional instancing via buckets

Everything is controlled through `codex_config.lua`.