Phone cases

Choose one mode in config/config.phoneCases.lua:

Config.PhoneCases.Mode = 'settings' -- settings | dedicated | unified | hybrid

Edit the existing Mode field inside Config.PhoneCases; the line above illustrates the setting. Restart YSeries after changing modes or item names. settings remains the upgrade default.

• settings: existing enable, color and artwork controls; no case item required.
• dedicated: one item for each of the 16 palette colors, such as phone_case_black. Item names determine color; cases use the Plain design. Metadata is optional.
• unified: one phone_case item with color and design metadata. Requires Config.Item.Require = true, Config.Item.UniquePhones = true and an inventory adapter with metadata support.
• hybrid: one generic phone_case item without metadata. Equip it first, then select color and artwork in settings. Removing returns a generic case; the customization is not a transferable item property.

The item names are configurable under Config.PhoneCases.Items. Dedicated names must be distinct from one another and the unified item. The palette supports red, black, white, blue, green, purple, yellow, pink, orange, cyan, navy, gray, cream, brown, teal and lavender. Color IDs and palette indices are separate: keep the existing indices aligned with the streamed case props.

Install inventory items

Copy the entries you need from inventory-items/ox-items-phone-cases.txt or inventory-items/qb-items-phone-cases.txt into your inventory's item definitions. Copy the matching inventory-items/phone_case*.png icons into its image directory. These snippets and icons are included with YSeries; they do not modify your inventory automatically.

For dedicated mode, install the 16 color items. For unified or hybrid mode, install phone_case. Unified cases must be non-stacking (stack = false in Ox, unique = true in QB). Generic hybrid cases may stack. Keep Ox consume = 0 and the yseries.UsePhoneCaseItem server export: YSeries consumes and returns cases itself.

Add the installed items to your normal shops. Dedicated and hybrid shops do not need metadata. Unified shop entries must supply valid color and design IDs:

-- Example Ox shop inventory entry, inside a configured shop:
{ name = 'phone_case', price = 100, metadata = { color = 'blue', design = 'plain' } },

For scripts that give or sell custom cases, build metadata on the server after the design resource has registered:

local metadata, reason = exports.yseries:BuildPhoneCaseMetadata('blue', 'my_custom_case')
if not metadata then
    print('Cannot create phone case: ' .. tostring(reason))
    return
end

-- Ox
local added = exports.ox_inventory:AddItem(playerId, 'phone_case', 1, metadata)
-- QB-family alternative (use your configured inventory resource):
-- local added = exports['qb-inventory']:AddItem(playerId, 'phone_case', 1, false, metadata, 'shop-case')

Metadata contains canonical color and design IDs plus readable colorName, designLabel, label and description. For example, Blue / Artist Edition remains distinguishable from Blue / Plain. Ox creation hooks populate these labels for shop/AddItem entries. QB shop/give scripts should use the builder, since they have no shared Ox-style item creation hook. If your inventory uses custom tooltip templates, display colorName and designLabel from Ox metadata or QB info; the readable description also contains both names.

Unknown colors and unregistered designs cannot be newly equipped. Designs must fit the selected phone and satisfy existing ImeiLocks. No cases are available for the yTriFold. Item metadata cannot introduce new models, artwork URLs or privileges; design resources still register through the existing case API.

Custom designs

Create artwork with the Case Creator, install the updated props package, and start its design registration before giving custom cases to players. Use the registered design ID with BuildPhoneCaseMetadata; the readable design name comes from that registration.

Custom designs work through settings in settings mode and on an equipped generic case in hybrid mode. In unified mode, the design belongs to the metadata item. Dedicated color items use Plain and do not represent custom artwork.

Equip, swap and remove

Select the phone you want to customize, then use the case in inventory. YSeries reads the authoritative item slot and equips it on the selected, owned phone. Swapping returns the previously attached item. Settings show the installed design/color and a removal action; dedicated/unified modes do not allow free changes through settings.

An installed case is saved against the phone's IMEI and travels with that unique phone. Without unique phones, dedicated and hybrid modes attach to the character's existing phone profile; they cannot follow individual traded phone items.

Existing menu-configured appearances remain visible when changing modes. They have no physical item backing and removing them gives no item. An item-backed case retains its original return item across mode changes; changing free settings does not convert that return item into a more valuable design. Remove old cases before switching inventories or deleting their item definitions. Returning metadata cases through a count-only inventory is rejected.

Inventory adapters

server/custom/functions/phoneCaseInventory.lua is editable and included in the existing escrow-ignore paths. It supplies Ox, QB, LJ and PS adapters, plus standard ESX count-based support for dedicated/hybrid modes. QB variants must expose compatible AddItem, RemoveItem and CanAddItem exports; capacity checks fail closed when unavailable. These integrations have fixture coverage; a live server check is still needed for the exact inventory version you deploy.

Other inventories need a case adapter even if their unique-phone integration already works. Provide YseriesPhoneCaseInventory with SupportsMetadata, GetSlot(source, slot), Remove(source, snapshot), CanCarry(source, item) and Add(source, item); see the included implementations. A snapshot has name, slot, count, metadata; a returned item has name, metadata. Count-only ESX uses the trusted usable item's name as its slot token.

Re-read the exact slot and metadata before removal. Return false only when the operation definitely had no side effect; throw if the result is uncertain. Custom inventories also need a trusted usable handler calling YseriesUsePhoneCaseItem(source, slot). Do not expose that function through an event accepting client item metadata.

Interrupted operations

Inventory exports and SQL saves cannot share a transaction. YSeries records operation stages in the existing yphone_settings.metadata.phoneCaseOperation JSON field before inventory changes, compensates proven failures when possible, and blocks further mutations when the outcome is uncertain. No schema migration is needed. The operation record is not sent to the phone UI or nearby players.

For an interrupted operation, inspect it from the server console:

yseries_case_recover PHONE_IMEI

The record includes the owner, old/new appearance and return item, incoming slot, phase and operation ID. Check the player's actual inventory and the record before reconciling missing or duplicate loose items with your administrative inventory tools. Do not repeatedly give/refund items based solely on an uncertain phase.

After inventory is reconciled, explicitly retain the proven attachment state:

yseries_case_recover PHONE_IMEI keep-old OP_ID inventory-reconciled
yseries_case_recover PHONE_IMEI keep-new OP_ID inventory-reconciled

Run one resolution, matching the inspected operation ID. These console-only commands update attachment state and clear the journal; they do not move inventory items or automatically retry an uncertain side effect.