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

# Admin Panel

> Manage every apartment, motel group, and tier in-game via /aptmanager.

The `/aptmanager` command opens a themed NUI panel for managing everything without restarting the resource.

## Permissions

`/aptmanager` is admin-only. A player can open it once you give them the `apartments.admin` permission (FiveM calls this an "ace"). Add the line(s) below to your `server.cfg`.

**Quickest setup** - most servers already have an `admin` group, so give that whole group access in one line:

```cfg theme={"dark"}
add_ace group.admin apartments.admin allow
```

Anyone in your `admin` group can now use the panel. Done.

**Granting it to one specific person** instead (no group needed) - use any one of their IDs:

```cfg theme={"dark"}
# FiveM license (most reliable)
add_ace identifier.license:abcdef0123456789abcdef0123456789abcdef01 apartments.admin allow

# Steam hex
add_ace identifier.steam:110000XXXXXXXXX apartments.admin allow

# Discord ID
add_ace identifier.discord:123456789012345678 apartments.admin allow
```

To find someone's IDs, type `getplayeridentifiers <their server id>` in the server console and copy the line that starts with `license:`.

Players without the permission get a "no permission" message and the panel stays shut.

<Note>
  For the technically curious: access is checked against the `apartments.admin` ace, **not** `command.aptmanager`. The `/aptmanager` command is registered unrestricted and gated server-side by that ace.
</Note>

## Tabs

<Tabs>
  <Tab title="Rooms">
    Lists every apartment, grouped by motel. Each row shows:

    * Apartment number
    * Label
    * Current occupant (if any)
    * Tier badge (T2 / T3)
    * Type badge (MLO / IPL)

    **Per-room actions:**

    * **Set Waypoint** - drops a waypoint to the apartment door
    * **Teleport to Door** - admin teleport to the exterior
    * **Teleport Inside** - admin enter the apartment
    * **Transfer Resident** - move the current occupant to a different free slot
    * **Change Motel Group** - reassign to a different motel
    * **Change Tier** - switch the room's tier
    * **Rename** - change the room's label
    * **Delete Room** - two-click confirm to remove

    **Add Room:** click `+ Add Room` to open the form. Use the `🎯 Pick` buttons to grab your character's current position for the Door, Exit, and (MLO only) Interior/Stash coordinates.
  </Tab>

  <Tab title="Groups">
    Manage motel groups (e.g., Pink Cage Motel, Lodge Motel).

    Each group has:

    * **ID** - internal identifier (kebab\_case)
    * **Display name** - shown to players
    * **Transfer cost** - charged when a player transfers between groups
    * **Clerk NPC** - model name + position (use `🎯 Pick`)
    * **Tier availability** - which tiers can be transferred into at this motel

    Adding a group spawns the clerk NPC immediately for all online players. No restart needed.
  </Tab>

  <Tab title="Tiers">
    Manage global tier definitions.

    Each tier:

    * **Tier number** - 1, 2, 3, …
    * **Label** - Standard, Deluxe, Premium, etc.
    * **Monthly cost** - rent charged every 30 in-game days

    <Warning>
      Tier 1 is always free regardless of `monthlyCost`. New characters are always assigned to a free Tier 1 room.
    </Warning>
  </Tab>
</Tabs>

## Adding a new apartment

<Steps>
  <Step title="Open the admin panel">
    Run `/aptmanager` in-game.
  </Step>

  <Step title="Click + Add Room">
    Bottom of the Rooms sidebar.
  </Step>

  <Step title="Fill in basic fields">
    * **Label** - e.g., "Room 42"
    * **Motel Group** - pick from your existing groups, or leave as "None"
    * **Tier** - 1 (free), 2, or 3
    * **Room Type** - IPL or MLO
  </Step>

  <Step title="Pick the door coordinates">
    Walk to where the player should interact with the door, then click `🎯 Pick`. For MLO doors, this also auto-detects the door prop hash.
  </Step>

  <Step title="Pick the exit coordinates">
    Walk to where the player should land when they leave. Click `🎯 Pick`.
  </Step>

  <Step title="(MLO only) Pick the interior spawn point">
    Walk to where the player should land when entering the MLO. Click `🎯 Pick`.
  </Step>

  <Step title="(Optional, MLO only) Pick the stash location">
    Walk to where you want the storage interaction zone. Click `🎯 Pick`.
  </Step>

  <Step title="Submit">
    Click `Add Room`. The new apartment is saved to `data/apartments.json` and door zones spawn immediately for all online players.
  </Step>
</Steps>

## Adding a new motel group

<Steps>
  <Step title="Switch to the Groups tab">
    Top of the admin panel.
  </Step>

  <Step title="Click + Add Group">
    Opens the group form.
  </Step>

  <Step title="Fill in fields">
    * **Group ID** - e.g., `pink_cage` (lowercase, underscores)
    * **Display Name** - e.g., "Pink Cage Motel"
    * **Transfer Cost** - what players pay to move into this motel
    * **NPC Model** - ped model name (e.g., `s_m_m_gentransport`)
    * **NPC Position** - use `🎯 Pick` to grab your current position + heading
    * **Tiers** - add the tier IDs that players can transfer into at this motel
  </Step>

  <Step title="Save Group">
    The clerk NPC spawns immediately. Players can now interact with them to transfer apartments.
  </Step>
</Steps>

## Live changes

All changes via the admin panel take effect **immediately**. No resource restart required:

* Adding a room → door zones spawn for all clients
* Adding a group → NPC spawns + clerk blip appears
* Changing a tier → billing recalculates for the next cycle
* Renaming → label updates everywhere

## Data persistence

The admin panel writes to JSON files in the resource:

* `data/apartments.json`
* `data/motel_groups.json`

These are auto-managed. Don't edit them by hand - use `/aptmanager`.

<Tip>
  You can copy these JSON files between servers to clone your apartment setup.
</Tip>

## Re-theming

Change the accent colour in `server.cfg`:

```cfg theme={"dark"}
setr awoken:primaryColor "#FF6B9D"   # pink
# or
setr awoken:primaryColor "#7FFF00"   # lime
# or
setr awoken:primaryColor "#A78BFA"   # purple
```

Restart the resource - entire admin panel + 3D markers re-theme.