acdream/docs/research/2026-07-13-retail-give-item-pseudocode.md

Retail item giving — pseudocode and implementation plan (2026-07-13)

Scope

Port the retail inventory-drag path needed to hand a starter-dungeon exit token to its NPC. The same path also covers direct gifts to players when the retail DragItemOnPlayerOpensSecureTrade character option is disabled.

This is not targeted item use. Retail has no TARGET_MODE_GIVE: the player drags the physical item icon out of an item list and releases it over the 3-D target.

Retail sources

• ItemHolder::AttemptPlaceIn3D @ 0x00588600
• ACCWeenieObject::UIAttemptGive @ 0x0058D620
• CM_Inventory::Event_GiveObjectRequest @ 0x006ABB00
• ItemHolder::GetObjectSplitSize @ 0x00586F00
• PlayerModule::DragItemOnPlayerOpensSecureTrade @ 0x005D31B0
• SmartBox drag release call site at 0x004E5C32
• InventoryRequest::IR_GIVE = 0x9 in named-retail/acclient.h

The earlier complete placement translation remains in docs/research/2026-07-10-retail-toolbar-interaction-pseudocode.md §8. This note pins the live integration seam that was still missing.

Cross-reference

ACE's GameActionGiveObjectRequest.Handle reads (targetGuid, objectGuid, int32 amount) and calls Player.HandleActionGiveObjectRequest. The server validates ownership/amount/trade state, walks the player into range, then routes to GiveObjectToNPC or GiveObjectToPlayer. Accepted full-stack NPC gifts send InventoryRemoveObject; accepted partial gifts send an authoritative stack-size update. Rejected gifts send InventoryServerSaveFailed. Therefore the client must not remove or resize the source optimistically.

The inventory wire catalog independently cross-checked ACE and holtburger in docs/research/2026-06-16-inventory-deep-dive.md §4: action 0x00CD, payload u32 target, u32 item, i32 amount. The existing acdream builder already matches that layout byte-for-byte.

Retail pseudocode

SmartBox left-button release while dragging an inventory item:
    target = object under the release point, or 0 when none
    success = AttemptPlaceIn3D(draggedItem, target, allowGroundFallback=true)
    if not success:
        clear the item's waiting state

AttemptPlaceIn3D(itemId, targetId, allowGroundFallback):
    if player cannot make an inventory request: return false
    item = lookup(itemId)
    if item missing: return false

    if targetId == playerId:
        return PlaceInBackpack(itemId)
    if item is not owned by player:
        show "You must first pick up ..."
        return false
    if item.tradeState != 0:
        show traded-item error
        return false

    if targetId == 0:
        goto DROP_ON_GROUND when fallback is allowed
        return false

    if AttemptMerge(itemId, targetId): return true
    target = lookup(targetId)
    if target missing:
        goto DROP_ON_GROUND when fallback is allowed
        return false

    if target has BF_VENDOR:
        sell only a full stack; otherwise reject
        return false

    if DragItemOnPlayerOpensSecureTrade and target.IsPlayer:
        AttemptToTradeItem(targetId, itemId)
        return false

    if target.InqType() == ItemType.Creature:
        item.UIAttemptGive(targetId, GetObjectSplitSize(item))
        return true

    if target.IsContainer:
        require unlocked + currently open, then place in it

    if fallback is allowed: goto DROP_ON_GROUND
    show "Cannot give ..."
    return false

DROP_ON_GROUND:
    require player on ground
    if selected amount < full stack:
        send StackableSplitTo3D(itemId, amount)
    else:
        send DropItem(itemId)
    return true

UIAttemptGive(targetId, amount):
    if player cannot make an inventory request: return
    Event_GiveObjectRequest(targetId, this.id, amount)
    prevRequestObjectID = this.id
    prevRequest = IR_GIVE
    prevRequestTime = now

Event_GiveObjectRequest(targetId, itemId, amount):
    send GameAction 0x00CD(targetId, itemId, amount)

GetObjectSplitSize uses the global selected quantity only when the dragged object is the selected object; any other stack uses its full current size.

The retail default character-options mask 0x50C4A54A includes DragItemOnPlayerOpensSecureTrade (0x04000000). Consequently a normal drag onto another player opens secure trade by default; a direct player gift uses 0x00CD only when that option is off. AllowGive (0x40) is the recipient-side option and ACE validates it server-side.

Implementation plan

1. Keep ItemInteractionPolicy.DecidePlacement as the single pure policy.
2. Pass the exact drag-release coordinates through the existing world picker and call the controller with its target GUID (or zero).
3. Execute GiveToTarget through a new WorldSession.SendGiveObject wrapper; leave the object table unchanged until ACE's response arrives.
4. Feed PlayerDescription.Options1 into the controller so the player branch uses the real retail secure-trade preference rather than a constant.
5. Add policy/controller/session/wiring tests for NPCs, stack quantities, non-optimistic state, the player option, and exact packet bytes.
6. Build, run the full test suite, commit, then visually gate the starter token turn-in and teleport.