#📦 INSTALLATION

resources/
└── [FIXITFY]/
    └── fx-accessories/

• Place the resource folder inside your server's resources directory
• Add ensure fx-accessories to your server.cfg below your framework

---

#⚙️ DEPENDENCIES

text/assetpacks       ← built into RedM, no extra install needed
vorp_core         ← only if using VORP
vorp_inventory    ← only if using VORP
rsg-core          ← only if using RSG

• /assetpacks must be ensured before fx-accessories in server.cfg
• Framework is optional — the script runs without one

---

#🗄️ SERVER.CFG

VORP

ensure vorp_core
ensure vorp_inventory
ensure fx-accessories

RSG

ensure rsg-core
ensure fx-accessories

No Framework

ensure /assetpacks
ensure fx-accessories

• After a successful start you will see [Accessories] Framework: VORP (or RSG / NONE) in the console

---

#🗃️ ITEM REGISTRATION

VORP — run Section 1 from fx_accessories.sql in your database

sqlINSERT INTO `items` (`item`, `label`, ...)
VALUES
    ('silverring', 'Silver Ring', ...),
    ('pearlnecklace', 'Pearl Necklace', ...),
    ...
ON DUPLICATE KEY UPDATE ...;

• Safe to re-run — uses ON DUPLICATE KEY UPDATE
• Includes all 43 default items

RSG — paste Section 2 from fx_accessories.sql into your shared items file

lua['silverring'] = { ['name'] = 'silverring', ['label'] = 'Silver Ring', ... },
['pearlnecklace'] = { ['name'] = 'pearlnecklace', ['label'] = 'Pearl Necklace', ... },

• Do NOT run the RSG section as SQL — it is Lua only
• The Accadmin panel can auto-generate these blocks for any new item you create

---

#🌐 LANGUAGE

lua-- config.lua
Config.Locale = "en"  -- "en" | "tr" | "de"

• Set your server language here
• To add a new language, copy an existing block in locales.lua and translate the strings

---

#🎮 COMMANDS

• Commands are configurable in Config.OpenMenuCommands inside config.lua

---

#⌨️ KEY BINDING

lua-- config.lua
Config.OpenMenuKey = {
    useKey = true,
    key    = 115,  -- Default: F4
}

Config.MenuOpenMode = "keybind"  -- "keybind" | "command" | "both"
Config.MenuToggle   = true       -- true: key toggles open/close | false: key only opens

• Full key list: https://cherrytree.at/misc/vk.htm

---

#🔧 ATTACHMENT SETTINGS

lua-- config_items.lua
Config.MaxAttachedLimit = 10

Config.CategoryLimits = {
    -- Head  = 1,
    -- Neck  = 2,
    -- Hand  = 2,
}

Config.RequireItem = false  -- true: item must be in inventory to equip
Config.BoneCheck   = true   -- true: two items cannot share the same bone

• RequireItem = true → server validates inventory every 6 seconds and removes items the player no longer owns
• BoneCheck = true → prevents visual conflicts from two props sharing the same bone

---

#🎬 ANIMATION SETTINGS

lua-- config.lua
Config.AnimationSetting = "auto"
-- "auto"      → HoldPose items freeze on last frame, others play once then stop
-- "forceStop" → always stop animation after AnimationDelay ms
-- "disable"   → no animation, prop attaches silently

Config.AnimationDelay = 2000  -- ms

---

#🏷️ ITEM DEFINITION

Items are defined in config_items.lua.

lua["itemkey"] = {
    Label       = "Display Name",
    Gender      = "all",         -- "all" | "male" | "female"
    Category    = "Hand",        -- Head | Neck | Hand | Torso | Arm | Belt | Leg
    Model       = `modelname`,
    Anim        = "hold_pose",   -- equip animation key (optional)
    AttachDelay = 0.0,           -- seconds before prop appears after animation starts (optional)
    AnimCut     = 1.2,           -- stop animation at this timestamp in seconds (optional)
    AnimBlacklist = {            -- hide prop while these animations play (optional)
        { "clipset_name", "anim_name" },
    },
    Attach = {
        Male   = { BoneID = 24818, BoneName = "skel_r_hand", PX = 0.0, PY = 0.0, PZ = 0.0, Pitch = 0.0, Roll = 0.0, Yaw = 0.0, fixedRot = true },
        Female = { BoneID = 24818, BoneName = "skel_r_hand", PX = 0.0, PY = 0.0, PZ = 0.0, Pitch = 0.0, Roll = 0.0, Yaw = 0.0, fixedRot = true },
    },
},

• itemkey must match the inventory item name exactly (case-sensitive)
• Bone IDs are listed in libs/Male-Bones.md and libs/Female-Bones.md
• Per-gender animation override: add Anim = "key" inside a Male or Female attach block
• The Accadmin panel generates this block for you — no manual editing required

---

#🖼️ ITEM ICONS

ui/assets/inventoryitemimages/{itemKey}.png

• Filename must exactly match the item key
• If no image is found, dropicon.png is used as a fallback
• Recommended size: 128×128 px, PNG with transparency

---

#🛒 SHOP SYSTEM

Shops are defined in config_shops.lua inside Config.Stores.

luaConfig.Stores = {
    ["mystore"] = {

        info = {
            storename  = "Accessories Shop",
            promptitle = "Accessories Store",
            useTarget  = false,       -- false = native hold-prompt | true = ox_target
            distance   = 2.0,
            coords     = vector4(0.0, 0.0, 0.0, 180.0),

            blip = {
                enabled = true,
                sprite  = -417940443,
                color   = "BLIP_MODIFIER_MP_COLOR_0",
                name    = "Accessories Store",
                scale   = 0.6,
            },

            openTimeSetting = {
                allowed = false,  -- false = always open | true = enforce open/close hours
                open    = 8,
                close   = 21,
            },

            requiredJobs = false,  -- false = all players | { "sheriff", "doctor" } = job whitelist
        },

        ped = {
            enabled       = true,
            model         = "cs_mp_travellingsaleswoman",
            outfit        = 0,
            spawnDistance = 30.0,
            scenario      = "WORLD_HUMAN_SMOKE_NERVOUS_STRESSED",
        },

        preview = {
            enabled           = true,
            previewPropsCoord = vector4(0.0, 0.0, 0.0, 180.0),
            camCoords         = vector3(0.0, 0.0, 0.0),
            camFov            = 40.0,
            autoRotate        = false,
        },

        wagon = {
            enabled       = false,
            spawnDistance = 80.0,
            model         = "mp005_p_collectorwagon01",
            coords        = vector4(0.0, 0.0, 0.0, 0.0),
            wagonProps    = {
                { model = "mp005_p_collectorwagon01b",     attach = true, bone = 0, offset = vector3(0,0,0), rotation = vector3(0,0,0), collision = false },
                { model = "mp005_p_collectorwagon01_draw", attach = true, bone = 0, offset = vector3(0,0,0), rotation = vector3(0,0,0), collision = false },
            },
        },

        BuyItems = {
            { itemName = "pearlnecklace", itemLabel = "Pearl Necklace",   gender = "all",  category = "Neck", price = 15.0 },
            { itemName = "skullmaskred",  itemLabel = "Skull Mask (Red)", gender = "all",  category = "Head", moneytype = "gold", price = 5.0 },
        },
    },
}

BuyItems fields:

• itemName — must match the key in config_items.lua and the inventory
• itemLabel — display name shown in the shop UI
• gender — "all" · "male" · "female"
• category — "Head" · "Neck" · "Hand" · "Arm" · "Torso" · "Belt" · "Leg"
• price — cost in the chosen currency
• moneytype — "cash" (default) or "gold"

---

#🎃 SEASONAL EVENTS

Defined in config_shops.lua inside Config.SeasonalEvents.

luaConfig.SeasonalEvents = {
    enabled = true,

    christmas = {
        enabled          = true,
        label            = "Christmas Celebration",
        desc             = "Holiday accessories are here! Limited-time discount.",
        startDate        = { month = 12, day = 1  },
        endDate          = { month = 12, day = 31 },
        discount         = 15,             -- % discount applied to all BuyItems prices
        announceDuration = 8,              -- seconds the announcement toast stays visible
        sendAnnouncement = "christmas",    -- /christmas → broadcasts the event notice
        seasonStore      = { "blackwater", "valentine" },
        seasonItems      = {
            { itemName = "snowflakering", itemLabel = "Snowflake Ring",
              gender = "all", category = "Hand", moneytype = "gold", price = 20.0 },
        },
    },
}

• seasonStore — list of store keys that receive the discount
• seasonItems — exclusive items visible only while the event is active
• Multiple events can be active at the same time if their date ranges overlap
• sendAnnouncement defines the admin command suffix — e.g. /christmas broadcasts to all players

---

#🌙 NIGHT MARKET

Defined in config_shops.lua inside Config.NightMarket.

luaConfig.NightMarket = {
    enabled          = false,
    storename        = "Night Market",
    sendAnnouncement = "nightmarket",
    openHour         = 22,
    closeHour        = 7,

    coords = {
        { pos = vector4(-866.70, -734.94, 59.84, 180.52), spawnChance = 70 },
        { pos = vector4(2295.28, -1175.81, 42.85, 285.70), spawnChance = 50 },
    },

    BuyItems = {
        { itemName = "silverring",   itemLabel = "Silver Ring",   gender = "all",  category = "Hand",
          price = 3.0,   tier = "COMMON",    limitedStock = 15 },
        { itemName = "skullmask",    itemLabel = "Skull Mask",    gender = "male", category = "Head",
          moneytype = "gold", price = 50.0, tier = "LEGENDARY", limitedStock = 3 },
        { itemName = "skullmaskred", itemLabel = "Skull Mask (Red)", gender = "all", category = "Head",
          moneytype = "gold", price = 800.0, tier = "EXCLUSIVE", limitedStock = 1 },
    },
}

• spawnChance — 0–100, probability this location is chosen each night cycle
• tier — "COMMON" · "RARE" · "LEGENDARY" · "EXCLUSIVE" — shown as a coloured badge
• limitedStock — max units available at the current location, resets when the NPC moves
• sendAnnouncement defines the admin command — e.g. /nightmarket broadcasts the arrival notice

---

#🛠️ ACCADMIN — CALIBRATION PANEL

The in-game calibration panel lets you create and position new accessories in real-time — no file editing, no server restarts.

Opening the panel:

/giveadminpanel [serverid]     ← opens for a target player (admin command)
fxaccmenu [serverid]           ← server console / RCON

Permanent access without being an admin:

lua-- config.lua
Config.AccadminAdminOnly = false
Config.AllowedAccAdmin   = "acceditor"  -- ACE permission name

• Grant the ACE permission acceditor to a player for permanent self-access from the radial menu

---

Step 1 — Setup

Set item key, label, model, gender, category, and equip animation.

Click Import to pre-fill all fields from an existing config_items.lua entry.

Step 2 — Bone

Browse bones by body region or search by name. The active region dot highlights as you navigate.

Step 3 — Calibrate

Move and rotate the prop on the character in real-time.

↑ ↓ ← →     Move forward / back / left / right
Q / Z        Move up / down
C / V        Cycle rotation axis (Pitch → Roll → Yaw)
B            Toggle active axis
W A S D      Camera movement
Space/Shift  Camera up / down

• Use the scrub bar and frame-step buttons to find the exact frame the prop should appear
• Add Delay sets AttachDelay so the prop appears at the right moment mid-animation

Step 4 — Output

A ready-to-paste config_items.lua entry is generated automatically.

• Copy — copies the config entry to clipboard
• Save — saves the item to reload_items.json as a draft
• Item Registration — opens Step 5 to generate the framework registration block

Step 5 — Item Registration

• VORP SQL — ready-to-run INSERT statement
• RSG Lua — paste-ready entry for your shared items file

---

#💡 NOTIFICATION SYSTEM

By default the resource uses fx-hud if running, the framework notification system, or chat as a fallback.

To use your own notification system, add this to frameworks.lua on the client side:

luaFX.SetNotifyHandler(function(text)
    TriggerEvent("my-hud:showNotify", text)
end)

-- Optional
FX.NotifyPrefs.time = 4000
FX.NotifyPrefs.type = "success"  -- "info" | "success" | "error"

---

#⚙️ DEVELOPER API

All exports are server-side only. Full reference: EXPORTS.md

lua-- Check if a specific item is currently equipped on a player
exports['fx-accessories']:isAttached(serverId, itemName)  -- returns: boolean

-- Get all currently equipped items for a player
exports['fx-accessories']:getAttachments(serverId)  -- returns: table { [itemName] = true }

-- Equip an item on a player from an external resource
exports['fx-accessories']:attachItem(serverId, itemName)  -- returns: boolean

-- Remove a specific item from a player
exports['fx-accessories']:removeItem(serverId, itemName)  -- returns: boolean

Example — remove all accessories from a player:

lualocal items = exports['fx-accessories']:getAttachments(source)
for itemName in pairs(items) do
    exports['fx-accessories']:removeItem(source, itemName)
end

• itemName must match a key in Config.Items (case-sensitive)
• All normal checks apply on attachItem (gender, limits, RequireItem)

---

#⚠️ TROUBLESHOOTING

• Items do not attach → item key exists in config_items.lua, gender matches, model hash is valid
• Item icons missing → PNG exists in ui/assets/inventoryitemimages/ named exactly {itemKey}.png
• Prop invisible after attach → model hash is correct and included in /assetpacks
• Prop drifts during animation → bone is IK-driven — switch to a stable bone (see libs/Male-Bones.md)
• Item removed automatically → RequireItem = true and player no longer has the item in inventory
• Framework detected as NONE → framework resource is not ensured before fx-accessories in server.cfg
• Calibration panel not opening → check Config.AccadminAdminOnly and ACE permission setup
• No notifications → check if fx-hud is running or set a custom notify handler in frameworks.lua

---

#📁 FILES OVERVIEW

---

#🏁 SUMMARY

FX-ACCESSORIES provides:

• Full prop attachment system with radial menu and prop browser
• In-world accessory shops with 3D preview, cart, and cash/gold pricing
• Seasonal events with automatic discounts and exclusive items
• Night market with rarity tiers, limited stock, and randomised locations
• Full in-game calibration studio — no file editing required
• 109 pre-configured animations and 43 sample items out of the box
• Server-side export API for external script integration
• Framework support: VORP / RSG / Custom

---

© Fixitfy Development