Armor upgrades

Armor upgrades

Available from 0.1.9. Both client and server need the matching update. Server-side control of base armor plus three selected upgrade slots for players and scripted human NPCs. Armor catalog lists 26 bases; Armor upgrade catalog lists all 84 parts and exact family presets.

Base, ownership and selection are different

1. Give the player the base and the required parts through the normal inventory API.
2. Equip the base using setPlayerArmor.
3. Select the parts using setPlayerArmorUpgrades or setPlayerArmorPreset.

Merely owning a part does not select it. The upgrade setters do not grant items, raise attributes, bypass requirements, refill HP/mana or equip a different base. The native equipment selection is updated for the local player; appearance state also carries the selected parts to relevant remote clients.

Eight new functions (from 0.1.9)

• getArmorUpgrades and getArmorUpgradePresets: catalog queries.
• getPlayerArmorUpgrades, setPlayerArmorUpgrades, setPlayerArmorPreset: players.
• getNpcArmorUpgrades, setNpcArmorUpgrades, setNpcArmorPreset: scripted NPCs.

Each has a first-letter-capitalized alias, for example SetPlayerArmorPreset. All are server functions, not client functions or automatically exposed network events.

Equip a full Mercenary set

-- Trusted server-side loadout code; validate playerId and permissions first.
-- This example deliberately grants missing items. The setters themselves do not.
local function ensureOwned(playerId, key)
    return (getPlayerItemCount(playerId, key) or 0) > 0
        or givePlayerItem(playerId, key, 1)
end
local presets = getArmorUpgradePresets("mercenary")
local parts = presets and presets.heavy_2
assert(parts, "Mercenary preset unavailable")
assert(ensureOwned(playerId, "mercenary"), "Cannot grant base")
for _, slot in ipairs({"top", "mid", "bottom"}) do
    local key = parts[slot]
    if key ~= "" then assert(ensureOwned(playerId, key), "Cannot grant part") end
end
assert(setPlayerArmor(playerId, "mercenary"), "Base rejected: check requirements")
assert(setPlayerArmorPreset(playerId, "heavy_2"), "Parts rejected: check requirements")

The loadout sequence is not one atomic grant transaction: if a later step fails, previously granted items remain. Check returns and let your gamemode decide how to handle failure. It does not silently prepare STR/DEX.

Change one piece without clearing the others

-- Read-modify-write preserves the other slots.
local parts = getPlayerArmorUpgrades(playerId)
local presets = getArmorUpgradePresets("mercenary")
if parts and presets and presets.light_1 then
    parts.top = presets.light_1.top
    -- Player must still wear mercenary and own the selected part.
    assert(setPlayerArmorUpgrades(playerId, parts))
end

The part setter replaces ALL three slots. Passing only {top=...} clears mid and bottom. Omitted slots, "" or "none" clear a slot. {} clears every part but leaves the base equipped. Getters return all three keys with empty strings for empty slots.

Clear or remove

assert(setPlayerArmorUpgrades(playerId, {})) -- keep the base
-- Equivalent: setPlayerArmorPreset(playerId, "none")
-- Remove the base and its parts instead:
assert(setPlayerArmor(playerId, "none"))

NPC equipment

-- npcId is an existing human NPC created by this resource.
assert(setNpcArmor(npcId, "mercenary"))
assert(setNpcArmorPreset(npcId, "heavy_2"))
local parts = getNpcArmorUpgrades(npcId)
if parts then outputDebugString(parts.top) end

Only the resource owning the NPC can modify its parts. NPC selection does not require player-inventory ownership or player equipment requirements. It does not create an NPC, change identity, start combat or heal. Player and NPC IDs are not interchangeable.

Presets and validation

Preset names: light_1, light_2, medium_1, medium_2, heavy_1, heavy_2; none clears. Sparse families retain the best existing part up to that tier. Some presets are identical, and a low Novice preset can have empty upper/middle slots. Query the preset table instead of constructing class names. Every part must match the equipped base family and slot. Unknown keys, invalid types, foreign-family parts, missing player ownership and failed requirements are rejected. A different base clears the previous selection; selecting the same base retains compatible parts. Losing ownership of a selected piece clears that selection. Do not expose unrestricted equipment setters through client-triggered events; enforce your own permissions and gameplay rules.

Protection and item profiles

Effective protection is calculated from the base and each selected part once. setItemStats can configure either the base type or a piece type for all copies on the server; use getItemStatDefinitions to check support. Protection points are not percentages. Increased maximum HP/mana does not heal/refill; decreases clamp current values where necessary. Clearing parts removes their contributions, not the character's base attributes. Unsupported stagger/super-armor mechanics are not enabled by choosing heavier-looking parts.

Persistence and synchronization

Store the base key together with the three selected part keys. On restoration, restore/validate inventory and base first, then reapply parts and check the result. The bundled GothicRP integration saves the paired selection with appearance data; older saves without it remain compatible. Other gamemodes must implement their own persistence. Equipment setters do not automatically save arbitrary gamemode databases. The server sends canonical selections to relevant remote players and replays them when a player becomes relevant again or joins later. Characters in different dimensions remain subject to the existing visibility rules. Each remote character maintains its own selection and visual generation state. Identity, skin tint and tattoos are independent; clothing naturally hides covered regions.

Validation status

Local-player upgraded armor and a scripted NPC have been reported working in the current development test. Catalog/slot validation, local selection, customization and related automated checks pass. Code review confirms a separate remote-human receive/replay path carrying the same part selection. A two-human-client visual test (including late join) is still pending; the NPC result is not presented as proof of that test. Check the identity/outfit combinations your gamemode exposes. Royal Guard and Judge have separate qualification notes in Armor catalog. A true setter result means server acceptance, not proof that every remote mesh has finished rebuilding. No public binary release is announced by this documentation.