> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heartbreakhotel.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Drop hb_citizensjourney into resources, import the SQL schema, ensure dependencies, configure season + quests, restart.

## Requirements

* `ox_lib`
* `oxmysql`
* `qbx_core` **or** `qb-core`
* `ox_inventory`

<Note>
  All dependencies must be started **before** `hb_citizensjourney` in `server.cfg`.
</Note>

<Note>
  The resource should be started before any script that contains exports for quests.
</Note>

## Steps

**1.** Drop `hb_citizensjourney` into your `resources/` folder (subfolder doesn't matter).

**2.** Import the database schema:

```sql theme={null}
sql/cj_tables.sql
```

**3.** Add to `server.cfg` after all dependencies:

```
ensure ox_lib
ensure oxmysql
ensure qbx_core
ensure ox_inventory
ensure hb_citizensjourney
```

**4.** Configure your season, quests, and tier rewards in `configs/`.

**5.** Start or restart the resource.

## Database Tables

| Table                | Purpose                                                                      |
| -------------------- | ---------------------------------------------------------------------------- |
| `cj_players`         | Per-player, per-season state: tier, XP, premium, streak, passive XP counters |
| `cj_claimed_rewards` | Which tier rewards have been claimed (free / premium lane)                   |
| `cj_quest_progress`  | Quest progress and claimed state, period-aware                               |

`period_key` format: `YYYY-MM-DD` (daily) · `YYYYWnn` (weekly) · `season_N` (seasonal)

<Note>
  It is highly encouraged to add your own quests instead of depending on the predefined ones.
</Note>