# Apartments

### 🏠 Overview

When `Config.ApartmentStart = true`, new characters will see an apartment selection screen before spawning. This integrates with apartment/housing systems.

***

### ⚙️ Enable Apartments

In `config/config.lua`:

```lua
Config.ApartmentStart = true  -- Enable apartment selection for new characters
```

***

### 📁 Configuration File

Apartments are configured in:

```
config/apartments.lua
```

***

### 🏗️ Apartment Structure

```lua
local Apartments = {}

Apartments.List = {
    ['qb-core'] = {
        {
            id = 'apartment_1',
            label = 'South Rockford Drive',
            img = 'integrity-way',
            icon = 'fa-solid fa-building',
            coords = vec4(-667.02, -1105.01, 14.63, 242.32),
        },
        -- More apartments...
    },
    ['es_extended'] = {
        -- ESX apartments...
    },
    ['qbx_core'] = {
        -- QBox apartments...
    },
}

-- Function called when player selects an apartment
Apartments.SpawnCreateCharacter = function(apartmentType)
    -- Integration with your apartment/housing script
end

return Apartments
```

***

### ⚙️ Apartment Properties

| Property | Type   | Description                          |
| -------- | ------ | ------------------------------------ |
| id       | string | Unique identifier for the apartment  |
| label    | string | Display name                         |
| img      | string | Image filename (in web/build/imgs/)  |
| icon     | string | FontAwesome icon class               |
| coords   | vec4   | Spawn coordinates (x, y, z, heading) |

***

### 🎮 Framework-Specific Configuration

#### QBCore

```lua
['qb-core'] = {
    {
        id = 'apartment_alta',
        label = 'Alta Street Apartments',
        img = 'alta-apartments',
        icon = 'fa-solid fa-building',
        coords = vec4(-271.23, -957.79, 31.22, 205.56),
    },
    {
        id = 'apartment_integrity',
        label = 'Integrity Way',
        img = 'integrity-way',
        icon = 'fa-solid fa-city',
        coords = vec4(-47.87, -585.88, 37.95, 70.27),
    },
}
```

#### ESX

```lua
['es_extended'] = {
    {
        id = 'motel_1',
        label = 'Cheap Motel',
        img = 'motels',
        icon = 'fa-solid fa-house',
        coords = vec4(327.56, -205.08, 53.08, 163.5),
    },
}
```

***

### 🔧 Spawn Function

The `SpawnCreateCharacter` function is called when a player selects their apartment:

```lua
Apartments.SpawnCreateCharacter = function(apartmentType)
    local playerId = PlayerId()
    local ped = PlayerPedId()
    
    -- Integration with qb-apartments
    if GetResourceState('qb-apartments') == 'started' then
        TriggerServerEvent('apartments:server:CreateApartment', apartmentType)
        return
    end
    
    -- Integration with custom housing
    if GetResourceState('my-housing') == 'started' then
        exports['my-housing']:assignApartment(apartmentType)
        return
    end
    
    -- Default: Just spawn at apartment coords
    TriggerServerEvent('0r-multicharacterv3:server:changeRoutingBucket', true)
end
```

***

### 🖼️ Adding Apartment Images

1. Take a screenshot of the apartment exterior
2. Save as PNG in `web/build/imgs/`
3. Reference the filename (without extension) in config

```lua
{
    id = 'my_apartment',
    label = 'My Custom Apartments',
    img = 'my-apartment-image',  -- web/build/imgs/my-apartment-image.png
    icon = 'fa-solid fa-building',
    coords = vec4(100.0, 200.0, 30.0, 90.0),
}
```

***

### 📋 Complete Example

```lua
-- config/apartments.lua

local Apartments = {}

Apartments.List = {
    ['qb-core'] = {
        {
            id = 'apartment_alta',
            label = 'Alta Street',
            img = 'alta-street',
            icon = 'fa-solid fa-building',
            coords = vec4(-271.23, -957.79, 31.22, 205.56),
        },
        {
            id = 'apartment_integrity',
            label = 'Integrity Way',
            img = 'integrity-way',
            icon = 'fa-solid fa-city',
            coords = vec4(-47.87, -585.88, 37.95, 70.27),
        },
        {
            id = 'apartment_tinsel',
            label = 'Tinsel Towers',
            img = 'tinsel-towers',
            icon = 'fa-solid fa-hotel',
            coords = vec4(-619.29, 36.84, 43.59, 178.92),
        },
    },
    ['qbx_core'] = {
        -- Same as qb-core or customize
    },
    ['es_extended'] = {
        {
            id = 'motel_route68',
            label = 'Route 68 Motel',
            img = 'motels',
            icon = 'fa-solid fa-house',
            coords = vec4(327.56, -205.08, 53.08, 163.5),
        },
    },
}

Apartments.SpawnCreateCharacter = function(apartmentType)
    -- qb-apartments integration
    if GetResourceState('qb-apartments') == 'started' then
        TriggerServerEvent('apartments:server:CreateApartment', apartmentType)
    end
    
    -- qs-housing integration
    if GetResourceState('qs-housing') == 'started' then
        TriggerEvent('qs-housing:client:assignApartment', apartmentType)
    end
    
    TriggerServerEvent('0r-multicharacterv3:server:changeRoutingBucket', true)
end

return Apartments
```

***

### ❓ Troubleshooting

#### Apartment Selection Not Showing

1. Ensure `Config.ApartmentStart = true`
2. Check that apartments are configured for your framework

#### Apartment Not Assigned

1. Check integration with your housing script
2. Verify `SpawnCreateCharacter` function
3. Check server console for errors


---

# Agent Instructions: 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.0resmon.org/0resmon/0r-resources/0r-multicharacter-v3/configuration/apartments.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.