# 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