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.

-- @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.

-- @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.

-- @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.

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

5. Open Tattoo Shop (OpenTattooShop)

Opens a studio showcasing only tattoo zones.

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

6. Close Menu (CloseMenu)

Programmatically closes the active clothing menu.

-- @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.

-- @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.

exports['aty_clothing']:ResetPedAppearance()

9. Get Ped Skin Data (GetPedSkinData)

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

-- @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.

-- @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.

-- @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.

-- @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.

-- @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.

-- @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.

-- @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.

-- @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:

-- 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:

-- 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:

-- 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)