GivePlayerTaggedItem

Gives the player one item with the mode’s own id, name and text - a letter, a contract, a key to one door.

The game knows an item by its own number for one visit only; a tagged item carries the mode’s identity instead. id is the mode’s (unique among the player’s items: a database row’s key, "letter-17"), and name and text are what the game’s own item panel shows for it instead of the class’s name and description (leave them "" for the class’s own; text may hold line breaks). The item is one of its class in every other way. GetPlayerInventory lists it on its own with id, name and text, so a mode that saves the inventory saves it, and SetPlayerInventory gives it back at the next visit with the same tag; OnPlayerUseItem names its id when the player reads or uses it; FindPlayerItem finds it and SetPlayerItemTag renames it.

The tag goes wherever the item goes: dropped and picked up, put in a chest or a saddlebag and taken out again, left on a corpse, stolen by a pickpocket - GetContainerItems, GetHorseItems, GetCorpseItems and GetActorPocket list it as an entry of its own with its id, name and text, and SetContainerItems, SetHorseItems and SetActorPocket take such an entry too (a letter left in a chest for someone to find). The inventory lists it in a row of its own under the mode’s name. Reading it opens the game’s book with the mode’s text: plain text is one paragraph with its line breaks kept, and text with the game’s own document tags (<title>, <subtitle>, <paragraph>, <accent>, <br/>, <newpage/>) is shown as written. Traders do not buy it (the player is told “that one is not for sale”) unless it has a price of its own (SetPlayerItemPrice); a weight of its own is SetPlayerItemWeight’s, the look of another item SetPlayerItemModel’s. Lying on the ground it shows its name to every player who looks at it. Taking items of its class away (GivePlayerItem with a negative amount) takes the player’s plain ones first. A tagged item can open a door or a chest (SetDoorKey, SetContainerKey), and a shop can sell tagged items (SetShopTaggedItem).

Syntax

GivePlayerTaggedItem(pid, item, id, name, text [, health, quality])

Parameter	Type
pid	number	the player
item	string	the item class - any key of the item catalogue
id	string	the mode’s own id for this one item
name	string	the name the game’s item panel shows ("" = the class’s)
text	string	the description the item panel shows ("" = the class’s)
health	number	its condition, 0..100 (optional)
quality	number	its quality, 1..4 (left out = the class’s own) (optional)

Returns

boolean - false for an unknown class, an empty id, or an id the player holds already

Example

-- the baron's letter: its own text, and the mode knows when it is read
GivePlayerTaggedItem(pid, "andelStrazny_riddles", "baron-letter", "A letter from the baron",
  "To whoever holds this:\nthe mill road is closed until the feast.")
function OnPlayerUseItem(pid, class, health, buff, id)
  if id == "baron-letter" then SetPlayerData(pid, "read_baron", true) end
end

See also

SetPlayerItemTag · FindPlayerItem · GetPlayerInventory · SetPlayerInventory · OnPlayerUseItem · the Items and inventory group of the index