acdream/docs/research/2026-07-12-retail-weapon-switch-pseudocode.md

Retail inventory weapon-switch pseudocode

Scope

Inventory double-click of a weapon while another primary weapon is equipped, in both peace and combat modes. The UI request sequence is shared; combat-mode animation remains server-authoritative.

Retail oracle

• ItemHolder::DetermineUseResult @ 0x00588460 classifies an owned combat-use item as WieldRight.
• CPlayerSystem::UsingItem @ 0x00562F70 dispatches that result to AutoWield(item, SLOT_SIDE_RIGHT, 0, 1, 0, 1).
• CPlayerSystem::AutoWield @ 0x00560A60 treats 0x03500000 (MeleeWeapon | MissileWeapon | Held | TwoHanded) as one weapon-ready group. If occupied, it records the requested item, sends the blocking weapon to the player container, and does not wield the requested item yet.
• CPlayerSystem::RecvNotice_ServerSaysMoveItem @ 0x00563260 retries AutoWield only after the server confirms the blocking item moved.
• ACCWeenieObject::UIAttemptWield @ 0x0058D590 sends GetAndWieldItem(item, equipMask).
• ClientCombatSystem::OnQualityChanged @ 0x0056C1B0 reads player PropertyInt 40 (CombatMode) and applies it through SetCombatMode.

Addresses are from docs/research/named-retail/symbols.json; pseudo-C is in docs/research/named-retail/acclient_2013_pseudo_c.txt.

Cross-reference

• ACE Player_Inventory.cs says the client normally sends the conflicting item's dequip before GetAndWieldItem. TryShuffleStance changes a player who is already in combat to Missile, Magic, or Melee after the new item is equipped; it leaves a player in peace mode in peace.
• ACE Creature_Combat.cs::SwitchCombatStyles performs the visible old-stance -> peace -> new-stance motion chain and sends PrivateUpdatePropertyInt(CombatMode, ...).
• holtburger independently confirms the action/event shapes: GetAndWieldItem { item_guid, equip_mask }, WieldObject, and PropertyInt 40 as CombatMode.

Faithful pseudocode

on inventory item double-click(item):
    decision = DetermineUseResult(item)
    if decision is WieldRight or WieldLeft or AutoSort:
        auto_wield(item)

auto_wield(item):
    if another auto-wield transaction is waiting for the server:
        consume the request without sending another inventory action

    if item has no valid equip location or is already equipped:
        return false

    if item.validLocations intersects WEAPON_READY_MASK:
        desiredMask = item.validLocations & WEAPON_READY_MASK
        blocker = player's equipped item intersecting WEAPON_READY_MASK

        if blocker exists:
            pending = (requestedItem = item.id, blockingItem = blocker.id)
            send PutItemInContainer(blocker.id, player.id, placement = 0)
            return true

        if BlocksUseOfShield(item) and a shield is equipped:
            begin the same confirmed blocker transaction for the shield

        if item.ammoType is not AMMO_NONE
           and equipped ammo has a different ammoType:
            begin the same confirmed blocker transaction for the ammo

        send_wield(item, desiredMask)
        return true

    use the existing retail slot/auto-wear selection rules
    send_wield(item, selectedMask)

on server-confirmed item move(blocker):
    if blocker matches pending.blockingItem
       and blocker is now loose in the player's main pack:
        requested = pending.requestedItem
        clear pending before re-entry
        auto_wield(requested)

on server inventory-request failure(item, error):
    if item matches pending.blockingItem or pending.requestedItem:
        clear pending

send_wield(item, mask):
    pending = (requestedItem = item.id, blockingItem = none)
    update the retained inventory/paperdoll projection optimistically
    send GetAndWieldItem(item.id, mask)

on server-confirmed WieldObject(item):
    reconcile the item's optimistic rollback snapshot separately
    if item matches pending.requestedItem
       and pending.blockingItem is none:
        clear pending

on PrivateUpdatePropertyInt(property = CombatMode, value):
    if value is exactly NonCombat, Melee, Missile, or Magic:
        CombatState.SetCombatMode(value)

Animation ownership

The client must not synthesize a local bow-to-sword animation. In peace mode, ACE leaves CombatMode as NonCombat. In combat mode, ACE selects the new weapon's stance and sends the authoritative motion stream plus PropertyInt 40. The inventory controller only sequences the two wire requests and waits for the old weapon's confirmed move; the existing motion and equipped-child render paths consume the server events.

The request is not complete when GetAndWieldItem is merely sent. Retail UIAttemptWield records prevRequest = IR_WIELD and leaves the item waiting until ServerSaysMoveItem reconciles it. acdream therefore keeps AutoWield busy through the final authoritative WieldObject; allowing another switch during the optimistic interval makes ACE reject otherwise valid items. Retail ACCWeenieObject::ServerSaysMoveItem @ 0x0058DBB0 clears the matching request directly; that UI completion is intentionally independent of the object's separate optimistic rollback counter.

Known remaining retail surface

This port covers the primary weapon-ready group plus retail's secondary incompatible-shield and mismatched-ammo blockers. CreateObject now retains the exact AmmoType needed for those decisions. Full AutoWieldIsLegal, Aetheria, and dual-wield/off-hand rules remain tracked by divergence row AP-108.