# Locations & Backgrounds

### 📍 Configuration File

Background locations are configured in:

```
config/locations.lua
```

***

### 🎬 Location Structure

```lua
local Locations = {}

Locations.List = {
    {
        id = 1,
        label = 'Location Name',           -- Display name
        img = 'location-1',                 -- Image filename
        coords = vec4(x, y, z, heading),    -- Camera/player position
    },
    -- More locations...
}

return Locations
```

***

### ⚙️ Location Properties

| Property | Type   | Description                        |
| -------- | ------ | ---------------------------------- |
| id       | number | Unique identifier (sequential)     |
| label    | string | Name shown in the UI               |
| img      | string | Image filename (without extension) |
| coords   | vec4   | Position (x, y, z) and heading (w) |

***

### 🖼️ Adding Custom Backgrounds

#### Step 1: Choose a Location In-Game

1. Go to your desired location
2. Find a good camera angle
3. Get coordinates: `/coords` or use a coords script

#### Step 2: Take a Screenshot

1. Position your camera
2. Take a high-quality screenshot
3. Crop to 16:9 aspect ratio (recommended: 1920x1080 or 800x450)

#### Step 3: Add the Image

Save your image to:

```
web/build/imgs/my-location.png
```

And also to (for development):

```
web/public/imgs/my-location.png
```

#### Step 4: Add to Config

```lua
Locations.List = {
    -- Existing locations...
    {
        id = 11,  -- Next available ID
        label = 'My Custom Location',
        img = 'my-location',
        coords = vec4(123.45, -456.78, 30.0, 180.0),
    },
}
```

***

### 📋 Default Locations

The script comes with these pre-configured locations:

```lua
Locations.List = {
    {
        id = 1,
        label = 'Location 1',
        img = 'location-1',
        coords = vec4(-75.96, -818.95, 326.18, 0.0),
    },
    {
        id = 2,
        label = 'Location 2',
        img = 'location-2',
        coords = vec4(-1033.18, -2728.22, 20.18, 237.57),
    },
    -- ... up to 10 locations
}
```

***

### 🎥 Camera Behavior

When a player selects a background:

1. Player ped is teleported to the coordinates
2. Camera is positioned 1 unit in front of the player
3. Player faces the camera (180° offset from heading)
4. Shallow depth of field is applied for visual effect

#### Camera Settings

The camera configuration is in `config/camera.lua`:

```lua
local CameraConfig = {}

CameraConfig.List = {
    'default',
    'cinema',
    'CAMERA_secuirity_FUZZ',
    'hud_def_blur',
    -- More filters...
}

return CameraConfig
```

***

### 🌤️ Weather Configuration

Weather settings during character selection are in `config/weather.lua`:

```lua
local WeatherConfig = {}

WeatherConfig.List = {
    'EXTRASUNNY',
    'CLEAR',
    'CLOUDS',
    'OVERCAST',
    'RAIN',
    'THUNDER',
    'CLEARING',
    'NEUTRAL',
    'SNOW',
    'BLIZZARD',
    'SNOWLIGHT',
    'XMAS',
    'HALLOWEEN',
}

return WeatherConfig
```

***

### ✨ Effects Configuration

Particle effects are in `config/effects.lua`:

```lua
local EffectsConfig = {}

EffectsConfig.List = {
    {
        pName = 'scr_rcbarry2',
        pNameChild = 'scr_clown_appears',
    },
    {
        pName = 'scr_rcbarry1',
        pNameChild = 'scr_alien_teleport',
    },
    -- More effects...
}

return EffectsConfig
```

***

### 🎭 Animation Configuration

Character animations/scenarios are in `config/animation.lua`:

```lua
local AnimationConfig = {}

AnimationConfig.List = {
    'WORLD_HUMAN_AA_COFFEE',
    'WORLD_HUMAN_AA_SMOKE',
    'WORLD_HUMAN_BINOCULARS',
    'WORLD_HUMAN_CHEERING',
    'WORLD_HUMAN_DRINKING',
    -- More scenarios...
}

return AnimationConfig
```

***

### 🖼️ Image Guidelines

#### Recommended Specifications

| Property     | Value                            |
| ------------ | -------------------------------- |
| Format       | PNG or JPG                       |
| Aspect Ratio | 16:9                             |
| Resolution   | 800x450 (min) to 1920x1080 (max) |
| File Size    | Under 500KB                      |

#### Tips for Good Screenshots

1. **Use good lighting** - Dawn/dusk for dramatic effect
2. **Clear weather** - Avoid rain/fog unless intentional
3. **Hide UI** - Remove all HUD elements
4. **Steady camera** - No motion blur
5. **Interesting angles** - Show the location's best features

***

### 📋 Complete Example

```lua
-- config/locations.lua

local Locations = {}

Locations.List = {
    {
        id = 1,
        label = 'Vinewood Sign',
        img = 'vinewood',
        coords = vec4(726.77, 1198.28, 326.26, 270.0),
    },
    {
        id = 2,
        label = 'Del Perro Pier',
        img = 'pier',
        coords = vec4(-1850.15, -1231.51, 13.02, 315.0),
    },
    {
        id = 3,
        label = 'Downtown',
        img = 'downtown',
        coords = vec4(195.17, -933.77, 29.7, 144.5),
    },
    {
        id = 4,
        label = 'Airport',
        img = 'airport',
        coords = vec4(-1037.74, -2737.75, 20.17, 327.06),
    },
    {
        id = 5,
        label = 'Beach',
        img = 'beach',
        coords = vec4(-1183.35, -1509.75, 4.65, 125.0),
    },
}

return Locations
```

***

### ❓ Troubleshooting

#### Image Not Showing

1. Check filename matches exactly (case-sensitive)
2. Ensure image is in `web/build/imgs/`
3. Rebuild if using development mode

#### Wrong Camera Position

1. Adjust z-coordinate (height)
2. Change heading for different angle
3. Test in-game before finalizing