Interface IItemAutomation
- Namespace
- AcDream.Plugin.Abstractions
- Assembly
- AcDream.Plugin.Abstractions.dll
Reads and acts on the items the player owns: using them, moving them between packs, splitting and merging stacks, dropping, giving, salvaging, and selling. Every command here only asks the server; the result lands later, through the completion properties or the object events.
public interface IItemAutomationRemarks
These commands are not safe to call from another thread. Issue them from the same thread the host raises its tick on, as they touch the same inventory and movement state the client itself does.
Properties
ActiveOwnedPetCount
How many living creatures the player currently owns as pets; zero when none, or when the session is not in the world.
int ActiveOwnedPetCount { get; }Property Value
ActiveVendorObjectId
The vendor whose shop is open, or zero when none is. This is what Sell(uint, uint) sells to.
uint ActiveVendorObjectId { get; }Property Value
IsAvailable
True when this surface can be used: the session is in the world and the host wired up item commands.
bool IsAvailable { get; }Property Value
IsBusy
True while a use or an inventory request offered right now would come back Busy. Two things put it there: a request of your own already in flight, and the short pacing the client keeps between one use and the next. Both mean "not yet" rather than "no", so a command refused this way has not failed and should not count against whatever attempt limit or back-off you pair with a failure -- wait for this to read false and ask again. It never reads false while a command would be refused as busy; it may read true a moment longer than a move or a merge strictly needs, because those do not take the use pacing.
bool IsBusy { get; }Property Value
LastCompletion
The server's answer to the last item use. Default until something completes.
PluginItemUseCompletion LastCompletion { get; }Property Value
LastInventoryCompletion
The server's answer to the last inventory request -- a move, split, merge, drop, or give. Default until something completes.
PluginInventoryCompletion LastInventoryCompletion { get; }Property Value
Methods
Apply(uint, uint)
Uses one owned item on another object -- a lockpick on a chest, a tinkering tool on a weapon. The first object must be one the player owns; the second only has to be one the client knows about.
PluginItemCommandResult Apply(uint objectId, uint targetObjectId)Parameters
Returns
CaptureOwnedItems()
Lists everything the player owns, including what is inside their packs and what they have equipped, ordered by name. Returns an empty list when the session is not in the world.
IReadOnlyList<PluginInventoryItem> CaptureOwnedItems()Returns
Drop(uint, uint)
Drop all or an exact partial stack on the ground.
PluginItemCommandResult Drop(uint objectId, uint amount = 0)Parameters
Returns
ForgetStaleItem(uint)
Lets go of an item the client still lists in the player's packs but the server no longer has. The item leaves the client exactly as it would if the server had deleted it: out of its pack, out of every inventory list and window, and ObjectChanged reports it released. Nothing is sent to the server, and the server is not asked whether the item exists; if it does after all, it comes back the next time the server describes the inventory, at the latest on the next login.
PluginItemCommandResult ForgetStaleItem(uint objectId)Parameters
objectIduint
Returns
Remarks
Only an item the server has just refused to appraise is let go of: LastAppraisalUnsuccessful must be true for it -- so the server has said nothing else about the item since -- and that refusal must have arrived within the last 30 seconds of game time. The server also refuses an item made to resist appraisal and a repeat request sent within about five seconds of an unsuccessful one, so a careful caller asks again after that pause and drops only an item refused twice, straight after the second refusal.
Reports Completed when the item is gone from the client. Reports InvalidItem for an unknown id, the character itself, anything the player does not carry, and an item the client has no server record of to let go of. Reports Refused with a notice for an item that is worn or wielded, a pack that still holds anything, an item the server has not refused to appraise, and one whose refusal is more than 30 seconds old. Reports Busy while an appraisal of this very item is still awaited -- its answer, not the earlier one, is what counts -- and whenever IsBusy reads true, since an item request in flight may be about this item too. IsBusy does not cover an appraisal in flight, so a caller that has just asked about the item waits for the answer before letting go of it.
Give(uint, uint, uint)
Give all or an exact partial stack to a world target.
PluginItemCommandResult Give(uint objectId, uint targetObjectId, uint amount = 0)Parameters
Returns
Merge(uint, uint, uint)
Asks the server to pour one owned stack into another owned stack of
the same thing. Pass an amount of zero to move the
whole source stack; an amount larger than it is refused with a notice.
PluginItemCommandResult Merge(uint sourceObjectId, uint targetObjectId, uint amount = 0)Parameters
Returns
MoveToContainer(uint, uint, uint, int)
Asks the server to move an owned item into one of the player's
containers, or into the player themselves for the main pack. Pass an
amount of zero to move the whole stack, or a
smaller number to split that many off into the container instead;
placement is the slot to drop it into. An amount
larger than the stack is refused with a notice.
PluginItemCommandResult MoveToContainer(uint objectId, uint containerObjectId, uint amount = 0, int placement = 0)Parameters
Returns
MoveToContainer(uint, uint, uint, int, bool)
The same move, able to join a stack the way dropping a stack onto a
pack does. With joinStack true the client first
looks for a stack of the same thing in the container -- its own items
first, then those in each pack inside it -- that has room for
everything being moved; the first one found is joined instead, with
no slot needed, and the request is a merge. A stack that could take
only part of it is passed over. When no stack qualifies, or with
joinStack false, this is exactly
MoveToContainer(uint, uint, uint, int).
PluginItemCommandResult MoveToContainer(uint objectId, uint containerObjectId, uint amount, int placement, bool joinStack)Parameters
objectIduintThe owned item to move.
containerObjectIduintThe container to move it into, or the player for the main pack.
amountuintZero for the whole stack, or how many to split off and move.
placementintThe slot to put it in when it takes one.
joinStackboolWhether to join a stack already in the container.
Returns
Remarks
A host that cannot join stacks passes a move with
joinStack false on to the plain move, and answers
one with joinStack true
Unavailable without moving
anything.
Salvage(uint, IReadOnlyList<uint>)
Asks the server to break a set of owned items down with an owned salvaging tool. Reports InvalidTarget when the tool is not one the player owns or is not a salvaging tool, and InvalidItem for an empty list or any item the player does not own.
PluginItemCommandResult Salvage(uint toolObjectId, IReadOnlyList<uint> itemObjectIds)Parameters
toolObjectIduintitemObjectIdsIReadOnlyList<uint>
Returns
Sell(uint, uint)
Asks the open vendor to buy an owned item, all of it or an exact partial stack. Reports InvalidTarget when no vendor is open, and Refused with a notice when this particular vendor will not take the item -- wrong kind of goods, worth too little or too much, or an item that cannot be sold.
PluginItemCommandResult Sell(uint objectId, uint amount = 0)Parameters
Returns
TryCaptureProperties(uint, out PluginItemProperties)
Reads the property tables the client holds for one owned item, including its weapon and armor profiles once it has been appraised. Returns false for anything the player does not own -- use the object surface for that.
bool TryCaptureProperties(uint objectId, out PluginItemProperties properties)Parameters
objectIduintpropertiesPluginItemProperties
Returns
Use(uint)
Uses an object. An owned item is used where it lies. Anything else -- a vendor, a corpse, a chest, a character to talk to -- is approached first if it is out of reach, exactly as double-clicking it does; in that case Started means the walk began, not that the use has happened. An owned item that needs a target of its own is refused with a notice saying to call Apply(uint, uint) instead.
PluginItemCommandResult Use(uint objectId)Parameters
objectIduint