> For the complete documentation index, see [llms.txt](https://atiysus-organization.gitbook.io/aty-scripts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atiysus-organization.gitbook.io/aty-scripts/clothing/integrations.md).

# Integrations

## aty\_clothing - Integration & API Documentation

This document provides a comprehensive guide for integrating the `aty_clothing` script with external systems (such as admin menus, housing/motel systems, lockers, multicharacter screens, and apartment scripts). It also details the recent user experience (UX) enhancements implemented in the script.

***

### 🌟 Visual & User Experience (UX) Enhancements

To deliver a premium, AAA-game-quality experience, the following UX enhancements have been implemented:

1. **Cinematic Screen Fading:**
   * When the customization menu opens (`OpenClothingMenu`) or closes (`CloseClothingMenu`), the screen smoothly fades to black (`DoScreenFadeOut(400)`) and fades back in (`DoScreenFadeIn(600)`) once entity teleportation, model loading, and camera snapping are complete.
   * This prevents jarring frame snaps and can be toggled via `Config.UseScreenFade = true` in `config.lua`.
2. **Smooth Camera Lerp Autofocus:**
   * Switching categories (e.g., from hair to shoes) smoothly interpolates the camera height (`offsetZ`), distance (`offsetY`), and Field of View (`fov`) using a **Quadratic Ease-In-Out** curve over 400ms.
   * **User Override:** If the player manually rotates the camera (via A/D, arrow keys, or mouse dragging) or zooms, the active autofocus Lerp is immediately cancelled, returning full manual control to the player.
3. **Premium Web UI Micro-Interactions:**
   * Category selection items now feature a sleek `transition: all 0.25s cubic-bezier(0.4, 0, 0.2, 1)` easing.
   * Hovering over a category item translates it slightly rightwards (`translateX(4px)`).
   * Pressing a category gives an active "squish" scale transition (`scale(0.97)`) for responsive feedback.
   * Triggering a menu closure prompts a gorgeous 300ms Vue fade-out transition via the `fadeOutMenu` NUI action before camera and focus structures are dismantled.

***

### 🛠️ Client API (Client-Side Exports)

All client exports are declared in `client/api.lua` and can be invoked from any external resource.

#### 1. Open Custom Menu (`OpenCustomMenu`)

Opens the menu with a customized title and specifically restricted categories.

```lua
-- @param menuType string: "creator", "clothing", "barber", "tattoo", "market"
-- @param allowedCategories table: List of allowed categories (e.g., {"dna", "hairs", "clothes"})
-- @param title string: The title displayed in the UI header
-- @param shopId string/number: Optional unique shop identifier
exports['aty_clothing']:OpenCustomMenu(menuType, allowedCategories, title, shopId)

-- Example: Opening a custom barber shop offering only hair, face, and DNA customizations
exports['aty_clothing']:OpenCustomMenu("barber", {"hairs", "face", "dna"}, "Downtown Barber", "barber_downtown")
```

#### 2. Open Wardrobe Menu (`OpenWardrobeMenu`)

Directly opens the wardrobe category allowing players to change into saved outfits. Perfect for house and locker room scripts.

```lua
-- @param customTitle string (Optional): Wardrobe menu header title
exports['aty_clothing']:OpenWardrobeMenu(customTitle)

-- Example:
exports['aty_clothing']:OpenWardrobeMenu("My Wardrobe")
```

#### 3. Open Clothing Shop (`OpenClothingShop`)

Opens a standard clothing store limited to clothes and accessories categories.

```lua
-- @param customTitle string (Optional): Shop header title
-- @param shopId string/number (Optional): Unique shop identifier
exports['aty_clothing']:OpenClothingShop(customTitle, shopId)
```

#### 4. Open Barber Shop (`OpenBarberShop`)

Opens a barber shop containing hair, face, and DNA categories.

```lua
exports['aty_clothing']:OpenBarberShop(customTitle, shopId)
```

#### 5. Open Tattoo Shop (`OpenTattooShop`)

Opens a studio showcasing only tattoo zones.

```lua
exports['aty_clothing']:OpenTattooShop(customTitle, shopId)
```

#### 6. Close Menu (`CloseMenu`)

Programmatically closes the active clothing menu.

```lua
-- @param restoreSkin boolean: If true, discards changes and restores pre-open appearance
exports['aty_clothing']:CloseMenu(restoreSkin)
```

#### 7. Query Menu Open State (`IsMenuOpen`)

Checks if the customization menu is currently active.

```lua
-- @return boolean
local isOpen = exports['aty_clothing']:IsMenuOpen()
```

#### 8. Reset Ped Appearance (`ResetPedAppearance`)

Resets the character ped appearance to the original pre-opened state, discarding all unsaved changes.

```lua
exports['aty_clothing']:ResetPedAppearance()
```

#### 9. Get Ped Skin Data (`GetPedSkinData`)

Retrieves the active player ped skin, clothing, and tattoo configuration as a table object.

```lua
-- @return table skinData
local currentSkin = exports['aty_clothing']:GetPedSkinData()
```

#### 10. Apply Skin Data (`ApplySkinData`)

Applies a specific skin, clothing, and tattoo dataset to the active ped instantaneously.

```lua
-- @param skinData table: The skin representation table
exports['aty_clothing']:ApplySkinData(skinData)
```

***

### 🖥️ Server API (Server-Side Exports)

Server exports are declared in `server/api.lua` and can be invoked from any server-side script.

#### 1. Open Clothing Menu (`OpenClothingMenu`)

Triggers the clothing menu for a specific player from the server.

```lua
-- @param source number: Player server ID
-- @param menuType string: "creator", "clothing", "barber", "tattoo", "market"
-- @param shopData table (Optional): Custom parameters e.g., { title = "Shop", allowedCategories = {...} }
exports['aty_clothing']:OpenClothingMenu(source, menuType, shopData)
```

#### 2. Close Clothing Menu (`CloseClothingMenu`)

Forces the clothing menu to close for a specific player.

```lua
-- @param source number: Player server ID
-- @param restoreSkin boolean: Whether to revert player back to their original saved skin
exports['aty_clothing']:CloseClothingMenu(source, restoreSkin)
```

#### 3. Load Player Skin (`LoadPlayerSkin`)

Retrieves the player's saved skin and tattoos from the database and loads them onto their active ped.

```lua
-- @param source number: Player server ID
exports['aty_clothing']:LoadPlayerSkin(source)
```

#### 4. Get Player Skin (`GetPlayerSkin`)

Asynchronously retrieves the player's active skin data from the database.

```lua
-- @param source number: Player server ID
-- @param cb function: Callback returning (skinData, model)
exports['aty_clothing']:GetPlayerSkin(source, function(skinData, model)
    if skinData then
        print("Model: " .. tostring(model))
        print("Skin JSON: " .. json.encode(skinData))
    end
end)
```

#### 5. Save Player Skin (`SavePlayerSkin`)

Directly overwrites the player's database skin record with the provided skin dataset.

```lua
-- @param source number: Player server ID
-- @param skinData table: The skin configuration table to save
-- @return boolean
local success = exports['aty_clothing']:SavePlayerSkin(source, skinData)
```

#### 6. Get Player Outfits (`GetPlayerOutfits`)

Asynchronously retrieves a list of all saved outfits for the player.

```lua
-- @param source number: Player server ID
-- @param cb function: Callback returning the outfits table array
exports['aty_clothing']:GetPlayerOutfits(source, function(outfits)
    for _, outfit in ipairs(outfits) do
        print("Outfit Name: " .. outfit.outfitname)
    end
end)
```

***

### 💡 Practical Integration Examples

#### 1. Character Creator Integration (Multicharacter)

To launch the creator menu immediately when a player spawns with a newly created character:

```lua
-- Client-side
RegisterNetEvent('my_multicharacter:client:createCharacter', function(gender)
    -- Determine and request model
    local model = gender == 1 and "mp_f_freemode_01" or "mp_m_freemode_01"

    -- Open the character creator menu via aty_clothing
    exports['aty_clothing']:OpenCustomMenu(
        "creator",
        {"pedSelector", "dna", "hairs", "face", "clothes", "accessories"},
        "Character Customization"
    )
end)
```

#### 2. House or Motel Wardrobe Integration

To open the player's personal outfit drawer when interacting with a closet:

```lua
-- Client-side
local isNearWardrobe = false

-- Put this inside your interaction check / key press loop:
if isNearWardrobe and IsControlJustPressed(0, 38) then -- E key
    exports['aty_clothing']:OpenWardrobeMenu("House Wardrobe")
end
```

#### 3. Administrator Edit Command Integration

To let administrators customize another player's clothing programmatically:

```lua
-- Server-side
RegisterCommand('skin_edit', function(source, args)
    local targetId = tonumber(args[1])
    if targetId then
        -- Open full clothing customizer for the target player
        exports['aty_clothing']:OpenClothingMenu(targetId, "creator", {
            title = "Admin Customizer",
            shopId = "admin_edit"
        })
    end
end, true)
```