Difference between revisions of "Items"

From SphereWiki
Jump to: navigation, search
(Created page with 'This page documents reference, properties, functions and triggers for items. ==References== References return pointers to other objects (e.g. the REGION reference allows you to ...')
 
(Visual change)
 
(57 intermediate revisions by 12 users not shown)
Line 1: Line 1:
−
This page documents reference, properties, functions and triggers for items.
+
{{Languages|Items}}
 +
 
 +
__FORCETOC__
 +
Generally speaking, there are two types of "things" in the game; characters and items. Compared to characters, items are very complex. Items have a number of different uses, for example a sword is an item that players can see and equip to increase the damage they can do in combat. Some items in the game can not be seen by the players, but they have as much impact on the player as their sword, for example, a memory item is equipped every time a player is under the effects of a spell. Some [[Special Items|special types of item]] also have additional properties that can be accessed via scripts. The following tables detail the various properties of items in SphereServer:
 +
 
  
 
==References==
 
==References==
Line 5: Line 9:
  
 
{| border="1" cellspacing="4" cellpadding="4"
 
{| border="1" cellspacing="4" cellpadding="4"
−
| '''Name''' || '''R/W''' || '''Description'''
+
| '''Name''' || '''Read/Write''' || '''Description'''
 +
|-
 +
| [[CONT]] || RW || Gets or sets the [[Characters|character]] or [[Special Items#Containers|container item]] that the object is inside.  When an item's CONT is changed, it bypasses the typical behavior (for example, you can force an item to be "in" a container and bypass @dropon triggers, or force an item to be equipped to a player and bypass @equiptest and @equip triggers -- but be careful, because in this second scenario it may end up in an invalid layer.)
 +
|-
 +
| [[LINK]] || RW || Gets or sets the [[Characters|character]] or [[Items|item]] that the item is linked to.  Note, you can make circular LINK's, but a single item cannot be linked to more than one other item.
 
|-
 
|-
−
| [[CONT]] || RW || Gets or sets the container that the object is in.
+
| [[Regions|REGION]] || R || Gets the [[Regions|region]] that the object is in.
 
|-
 
|-
−
| [[LINK]] || RW || Gets or sets the object that the item is linked to.
+
| [[ROOM]] || R || Gets the [[Rooms|room]] that the object is in.
 
|-
 
|-
−
| [[REGION]] || R || Gets the region that the object is in.
+
| [[P]] || RW || Gets or sets the [[Map Points|position]] that the object is at.
 
|-
 
|-
−
| [[P]] || RW || Gets or sets the position that the object is at.
+
| [[Sectors|SECTOR]] || R || Gets the [[Sectors|sector]] that the object is in.
 
|-
 
|-
−
| [[TOPOBJ]] || R || Gets the top-most object in the world that contains the item.
+
| [[TOPOBJ]] || R || Gets the top-most [[Characters|character]] or [[Items|item]] in the world that contains the item.
 +
|-
 +
| [[TYPEDEF (Reference)|TYPEDEF]] || R || Gets the [[ITEMDEF]] that defines the item.
 
|}
 
|}
  
−
 
+
==Properties and Functions==
−
==Properties and Functions with a Return Value==
+
Here is a list of all item properties and functions. If a function is marked as readable then it can return a value when used as <KEY>. Click on the name for more detailed information such as usage and examples. If an attempt is made to access a property that does not exist on the item, the property from the [[ITEMDEF]] will be accessed instead.
−
Here is a list of all item properties and functions that can return a value when used as &lt;KEY&gt;. Click on the name for more detailed information such as usage and examples.
 
  
 
{| border="1" cellspacing="4" cellpadding="4"
 
{| border="1" cellspacing="4" cellpadding="4"
−
| '''Name''' || '''R/W''' || '''Description'''
+
! Name !! '''Read/Write''' !! '''Description'''
 +
|-
 +
| [[ADDCIRCLE]] ''spell_circle'' || W || Adds all of the spells in the given Magery circle to the spellbook.
 +
|-
 +
| [[ADDSPELL]] ''spell_id'' || RW || Gets whether or not a spell exists in the spellbook, or adds a spell to the spellbook.
 +
|-
 +
| [[AMMOANIM]] || RW || Overrides TDATA4 for bow/crossbow type weapons.
 +
|-
 +
| [[AMMOANIMHUE]] || RW || Sets the color of the effect when firing bow/crossbow type weapons.
 +
|-
 +
| [[AMMOANIMRENDER]] || RW || Sets the render mode of the effect when firing bow/crossbow type weapons.
 +
|-
 +
| [[AMMOCONT]] || RW || Sets the container UID or ID where to search for ammos for bow/crossbow type weapons.
 +
|-
 +
| [[AMMOSOUNDHIT]] || RW || Overrides the hit sound on weapons.
 
|-
 
|-
−
| [[ADDSPELL]] ''spell_id'' || R || Gets whether or not a spell exists in the spellbook.
+
| [[AMMOSOUNDMISS]] || RW || Overrides the miss sound on weapons.
 
|-
 
|-
−
| [[AMOUNT]] || RW || Gets the amount of this items this item represent (e.g. a pile of gold).
+
| [[AMMOTYPE]] || RW || Overrides TDATA3 for bow/crossbow type weapons.
 +
|-
 +
| [[AMOUNT]] || RW || Gets the amount of items this icon represents (e.g. a pile of gold or any stacked item).
 
|-
 
|-
 
| [[ATTR]] || RW || Gets or sets the item's attribute flags.
 
| [[ATTR]] || RW || Gets or sets the item's attribute flags.
 +
|-
 +
| [[BOUNCE]] || W || Moves the item to SRC's backpack (triggering the ''you put the item in your pack'' message.
 +
|-
 +
| [[CAN]] || RW ||  Gets or Sets the can_flags (Setting can be only done in the Itemdef itself). Only readable in X branch.
 +
|-
 +
| [[CANMASK]] || RW ||  Stores the CAN flags to be dynamically switched on or off from the base CAN property.
 
|-
 
|-
 
| [[CANSEE]] || R || Returns 1 if SRC can see the item.
 
| [[CANSEE]] || R || Returns 1 if SRC can see the item.
 
|-
 
|-
−
| [[CANSEELOS]] || R || Returns 1 if SRC has line of sight to the item.
+
| [[CANSEELOS]] ''point_or_uid'' || R || Returns 1 if SRC has line of sight to the item or character (uid) or point (location).
 +
|-
 +
| [[CANSEELOSFLAG]] ''flags,point_or_uid'' || R || Returns 1 if SRC has line of sight to the item.  The ''flags'' are defined in the los_flags section of the sphere_defs.scp file and can be used to modify what tests take place.  The ''point_or_uid'' is an object or position that can be used to test line of sight to something other than SRC.  Note, the delimiter for FLAG values is ;
 
|-
 
|-
−
| [[CANSEELOSFLAG]] ''flags'' || R || Returns 1 if SRC has line of sight to the item, with flags to modify what tests take place.
+
| [[CLEARTAGS]] ''prefix'' || W || Removes all TAGs from the item that start with the given prefix.
 
|-
 
|-
 
| [[COLOR]] || RW || Gets or sets the object's hue.
 
| [[COLOR]] || RW || Gets or sets the object's hue.
 +
|-
 +
| [[CONSUME]] ''amount'' || W || Deducts an amount from the item, deleting it at 0.
 +
|-
 +
| [[CONTCONSUME]] ''resource_list'' || W || Deletes items from inside the container.
 
|-
 
|-
 
| [[CONTGRID]] || RW || If in a container, gets or sets the grid number that the item occupies (in KR's grid view)
 
| [[CONTGRID]] || RW || If in a container, gets or sets the grid number that the item occupies (in KR's grid view)
Line 43: Line 80:
 
| [[CONTP]] || RW || Gets or sets the position of the item within its container.
 
| [[CONTP]] || RW || Gets or sets the position of the item within its container.
 
|-
 
|-
−
| [[DEFMSG]]''.message text'' || RW || Gets or sets the text of a DEFMESSAGE from sphere_msgs.scp
+
| [[DAMAGE]] ''chance, type, source'' || W || If ''chance'' is greater than (Rand(maxhits*16)), inflicts  damage of ''type'' (the damage type flags are defined in the sphere_defs.scp file) upon the item.  You can optionally specify the ''source'' of the damage.
 +
|-
 +
| [[DCLICK]] || W || Double clicks the item, with SRC as the source of the event.
 +
|-
 +
| [[DECAY]] ''time'' || W || Sets the decay timer (in tenths of a second) for the item.
 +
|-
 +
| [[DESTROY]] || W || Deletes the object, not stopped by a return 1 in [[@Destroy]]
 +
|-
 +
| [[DIALOG (Function)|DIALOG]] ''dialog_id, page, parameters'' || W || Displays a dialog to SRC.
 
|-
 
|-
 
| [[DISPID]] || RW || Gets or sets the ID that the item will appear as to players.
 
| [[DISPID]] || RW || Gets or sets the ID that the item will appear as to players.
Line 49: Line 94:
 
| [[DISPIDDEC]] || RW || Same as [[DISPID]], except it returns the ID as a decimal number.
 
| [[DISPIDDEC]] || RW || Same as [[DISPID]], except it returns the ID as a decimal number.
 
|-
 
|-
−
| [[DISTANCE]] ''point_or_uid'' || R || Gets the distance between this object and either SRC, a map location or another object.
+
| [[DISTANCE]] ''point_or_uid'' || R || Gets the distance between this object and SRC.  If ''point_or_uid'' is used, SRC can be replaced with a map location or another object.
 
|-
 
|-
 
| [[DMGCOLD]] || RW || Gets or sets the amount of cold damage the weapon will give.
 
| [[DMGCOLD]] || RW || Gets or sets the amount of cold damage the weapon will give.
Line 59: Line 104:
 
| [[DMGPOISON]] || RW || Gets or sets the amount of poison damage the weapon will give.
 
| [[DMGPOISON]] || RW || Gets or sets the amount of poison damage the weapon will give.
 
|-
 
|-
−
| [[EVENTS]] ''event_defname'' || RW || Gets a list of events attached to the object, or adds or removes an event to or from the object.
+
| [[DROP]] || W || Drops the item to the ground.
 
|-
 
|-
−
| [[FRUIT]] || RW ||
+
| [[DUPE]] || W || Clones the item.
 +
|-
 +
| [[EDIT]] || W || Displays an editing dialog for the item to SRC.
 +
|-
 +
| [[EFFECT]] ''type, item_id, speed, loop, explode, colour, rendermode'' || W || Displays an effect to nearby clients.
 +
|-
 +
| [[EMOTE]] ''message'' || W || Displays a *You see* message to all nearby clients.
 +
|-
 +
| [[EQUIP]] || W || Equips the item to SRC.
 +
|-
 +
| [[EVENTS (Property)|EVENTS]] ''event_defname'' || RW || Gets a list of events attached to the object, or adds or removes an event to or from the object.
 +
|-
 +
| [[FIX]] || W || Re-aligns the item or character's Z level to ground level (if items are on the ground, the top item's ''Z+HEIGHT'' is used).
 +
|-
 +
| [[FLIP]] || W || Rotates the item clockwise.
 +
|-
 +
| [[FRUIT]] || RW || Gets or sets the fruit that will be produced by the crops.
 
|-
 
|-
 
| [[HEIGHT]] || R || Gets the height of the item.
 
| [[HEIGHT]] || R || Gets the height of the item.
Line 70: Line 131:
 
|-
 
|-
 
| [[ID]] || RW || Gets or sets the ID of the item.
 
| [[ID]] || RW || Gets or sets the ID of the item.
 +
|-
 +
| [[INFO]] || W || Displays an information dialog about the item to SRC.
 
|-
 
|-
 
| [[ISARMOR]] ''object_uid'' || R || Returns 1 if the object is armour.
 
| [[ISARMOR]] ''object_uid'' || R || Returns 1 if the object is armour.
Line 81: Line 144:
 
| [[ISITEM]] || R || Returns 1 if the object is an item.
 
| [[ISITEM]] || R || Returns 1 if the object is an item.
 
|-
 
|-
−
| [[ISNEARTYPE]] ''type, distance, flags'' || R || Returns 1 if a nearby item has the given TYPE.
+
| [[ISNEARTYPE]] ''type, distance, flags'' || R || Returns 1 if a nearby item has the given TYPE and is within ''distance''.
 
|-
 
|-
−
| [[ISNEARTYPETOP]] ''type, distance, flags'' || R || Returns a nearby world location of a nearby item which has the given TYPE.
+
| [[ISNEARTYPETOP]] ''type, distance, flags'' || R || Returns a nearby world location of a nearby item which has the given TYPE and is within ''distance''.
 
|-
 
|-
−
| [[ISPLAYER]] || R || Returns 1 if the object is a player.
+
| [[ISPLAYER]] || R || Returns 1 if the object is a player character.
 
|-
 
|-
 
| [[ISTEVENT]]''.event_defname'' || R || Returns 1 if the object has an event attached to its ITEMDEF.
 
| [[ISTEVENT]]''.event_defname'' || R || Returns 1 if the object has an event attached to its ITEMDEF.
 +
|-
 +
| [[ISTIMERF]]''.function'' || R || Returns the number of seconds left on the specified timerf if it exists.
 
|-
 
|-
 
| [[ISWEAPON]] ''object_uid'' || R || Returns 1 if the object is a weapon.
 
| [[ISWEAPON]] ''object_uid'' || R || Returns 1 if the object is a weapon.
 
|-
 
|-
−
| [[LAYER]] || RW || Gets or sets the layer that the item occupies when equipped.
+
| [[LAYER]] || RW || Gets or sets the layer that the item occupies when equipped (possible layers are defined in the sphere_defs.scp file).
 
|-
 
|-
 
| [[MAP]] || RW || Gets or sets the map that this object is located.
 
| [[MAP]] || RW || Gets or sets the map that this object is located.
Line 97: Line 162:
 
| [[MAXHITS]] || RW || Gets or sets the maximum number of hitpoints the item can have.
 
| [[MAXHITS]] || RW || Gets or sets the maximum number of hitpoints the item can have.
 
|-
 
|-
−
| [[MODAR]] || RW || Gets or sets a modifier for the item's armour rating.
+
| [[MENU (Function)|MENU]] ''menu_defname'' || W || Displays a menu to SRC.
 +
|-
 +
| [[MESSAGE]] ''message'' || W || Displays a message above this item to SRC.
 +
|-
 +
| [[MESSAGEUA]] ''colour, talkmode, font, lang_id, message'' || W || Displays a UNICODE message above this item to SRC.
 +
|-
 +
| [[MODAR]] || RW || Gets or sets a modifier for the item's armour rating if it is clothing, armor, or a shield. This gets or sets a modifier for the item's damage if it is a weapon type.
 
|-
 
|-
 
| [[MORE1]] || RW || Gets or sets the MORE1 value for the item.
 
| [[MORE1]] || RW || Gets or sets the MORE1 value for the item.
Line 121: Line 192:
 
| [[MOREP]] || RW || Gets or sets the MOREP value for the item.
 
| [[MOREP]] || RW || Gets or sets the MOREP value for the item.
 
|-
 
|-
−
| [[NAME]] || RW || Gets or sets the object's name.
+
| [[MOVE]] ''direction amount''<br /> [[MOVE]] ''x y'' || W || Moves the object relative to its current position.  Possible ''direction'' values are N,S,W, or E.  Note, you can combine directions (like:  MOVE SW 1) but nonsensical directions (like: MOVE WE 2) have the nonsense removed.
 
|-
 
|-
−
| [[SERIAL]] || R || Gets the item's unique ID in the world.
+
| [[MOVENEAR]] ''object_uid, distance'' || W || Moves the object to a random location near another object within a certain distance.
 
|-
 
|-
−
| [[SEXTANTP]] ''location'' || R || Converts the item's location or a specified location into sextant coordinates.
+
| [[MOVETO]] ''location'' || W || Moves the object to a specific location (note, the AREADEF or ROOMDEF must have a P defined).
 
|-
 
|-
−
| [[TAG]]''.name'' || RW || Gets or sets the value of a TAG.
+
| [[NAME]] || RW || Gets or sets the object's name.
−
|-
 
−
| [[TAGAT]]''.index'' || R || Gets a TAG at the given zero-based index.
 
−
|-
 
−
| [[TAGAT]]''.index''.KEY || R || Gets the name of the TAG at the given zero-based index.
 
−
|-
 
−
| [[TAGAT]]''.index''.VAL || R || Gets the value of the TAG at the given zero-based index.
 
 
|-
 
|-
−
| [[TAGCOUNT]] || R || Gets the number of TAGs stored on the item.
+
| [[NUDGEDOWN]] ''amount'' || W || Decreases the object's Z level.
 
|-
 
|-
−
| [[TIMER]] || RW || Gets or sets the length of time before the item's timer expires, in seconds.
+
| [[NUDGEUP]] ''amount'' || W || Increases the object's Z level.
 
|-
 
|-
−
| [[TIMERD]] || RW || Gets or sets the length of time before the item's timer expires, in tenths of a second.
+
| [[PROMPTCONSOLE]] ''function, prompt_message'' || W || Displays a prompt message to SRC and passes their response into a specified function.
 
|-
 
|-
−
| [[TRIGGER]] ''trig_name, trig_type'' || R || Fires a custom trigger and returns the RETURN value.
+
| [[PROMPTCONSOLEU]] ''function, prompt_message'' || W || Displays a prompt message to SRC and passes their response into a specified function, supporting UNICODE response.
 
|-
 
|-
−
| [[TYPE]] || RW || Gets or sets the item type.
+
| [[REMOVE]] || W || Deletes the object.
 
|-
 
|-
−
| [[UID]] || R || Gets the item's unique ID in the world.
+
| [[REMOVEFROMVIEW]] || W || Removes the object from nearby clients' screens.
 
|-
 
|-
−
| [[WEIGHT]] || R || Gets the weight of the item.
+
| [[RESCOUNT]] ''item_defname'' || R || Returns the total amount of a specific item inside a container.
 
|-
 
|-
−
| [[Z]] || R || Gets the Z position of the item.
+
| [[RESENDTOOLTIP]] || W || Forces Sphere to update the tooltips for nearby clients.
−
|}
 
−
 
 
−
 
 
−
==Properties and Function without a Return Value==
 
−
Here is a list of all item properties and functions that do not return a value. Click on the name for more detailed information such as usage and examples.
 
−
 
 
−
{| border="1" cellspacing="4" cellpadding="4"
 
−
| '''Name''' || '''Description'''
 
 
|-
 
|-
−
| [[ADDCIRCLE]] ''spell_circle'' || Adds all of the spells in the given circle to the spellbook.
+
| [[SAY]] ''message'' || W || Makes the object speak a message.
 
|-
 
|-
−
| [[ADDSPELL]] ''spell_id'' || Adds a spell to the spellbook.
+
| [[SAYU]] ''message'' || W || Makes the object speak a UTF-8 message
 
|-
 
|-
−
| [[BOUNCE]] || Moves the item to SRC's backpack.
+
| [[SAYUA]] ''colour, talkmode, font, lang_id, text'' || W || Makes the object speak a UNICODE message.
 
|-
 
|-
−
| [[CLEARTAGS]] ''prefix'' || Removes all TAGs from the item that start with the given prefix.
+
| [[SDIALOG]] ''dialog_id, page, parameters'' || W || Displays a dialog to SRC, providing that it is not already open.
 
|-
 
|-
−
| [[CONSUME]] ''amount'' || Deducts an amount from the item, deleting it at 0.
+
| [[SERIAL]] || R || Gets the item's unique ID in the world.
 
|-
 
|-
−
| [[CONTCONSUME]] ''resource_list'' || Deletes items from inside the container.
+
| [[SEXTANTP]] ''location'' || R || Converts the item's location or a specified location into sextant coordinates.
 
|-
 
|-
−
| [[DCLICK]] || Double clicks the item, with SRC as the source of the event.
+
| [[SOUND]] ''sound_id, repeat'' || W || Plays a sound from this object.
 
|-
 
|-
−
| [[DAMAGE]] ''amount, type, source'' || Inflicts damage upon the item.
+
| [[SPELLEFFECT]] ''spell_id, strength, source_character_uid, source_item_uid'' || W || Causes the item to be affected by a spell.
 
|-
 
|-
−
| [[DECAY]] ''time'' || Sets the decay timer for the item.
+
| [[TAG]]''.name'' || RW || Gets or sets the value of a TAG.
 
|-
 
|-
−
| [[DIALOG]] ''dialog_id, page, parameters'' || Displays a dialog to SRC.
+
| [[TAGAT]]''.index'' || R || Gets a TAG at the given zero-based index.
 
|-
 
|-
−
| [[DROP]] || Drops the item to the ground.
+
| [[TAGAT]]''.index''.KEY || R || Gets the name of the TAG at the given zero-based index.
 
|-
 
|-
−
| [[DUPE]] || Clones the item.
+
| [[TAGAT]]''.index''.VAL || R || Gets the value of the TAG at the given zero-based index.
 
|-
 
|-
−
| [[EDIT]] || Displays an editing dialog for the item to SRC.
+
| [[TAGCOUNT]] || R || Gets the number of TAGs stored on the item.
 
|-
 
|-
−
| [[EFFECT]] ''type, item_id, speed, loop, explode, colour, rendermode'' || Displays an effect to nearby clients.
+
| [[TAGLIST]] || W || Outputs a list of the object's TAGs.
 
|-
 
|-
−
| [[EMOTE]] ''message'' || Displays a *You see* message to all nearby clients.
+
| [[TARGET]]''FGMW'' ''function'' || W || Displays a targeting cursor to SRC. ''F'' makes the ''function'' available, and when added, the function name must be the 1st argument.  ''M'' allows you to place a ''multi'' item, in which case the multi number must be passed as an argument.  ''G'' forces the target to only be the ground.  ''W'' checks the criminal status of the player before (or after?) the target selection is made.
 
|-
 
|-
−
| [[EQUIP]] || Equips the item to SRC.
+
| [[TIMER]] || RW || Gets or sets the length of time before the item's timer expires, in seconds.
 
|-
 
|-
−
| [[FIX]] || Re-aligns the item's Z level to ground level.
+
| [[TIMERD]] || RW || Gets or sets the length of time before the item's timer expires, in tenths of a second.
 
|-
 
|-
−
| [[FLIP]] || Rotates the item.
+
| [[TIMERF]] ''time, function'' || W || Schedules a function to be executed on this object in ''time'' seconds.
 
|-
 
|-
−
| [[INFO]] || Displays an information dialog about the item to SRC.
+
| [[TIMERF]] ''CLEAR'' || W || Clears all scheduled functions from the object.
 
|-
 
|-
−
| [[MENU]] ''menu_defname'' || Displays a menu to SRC.
+
| [[TIMERF]] ''STOP, function'' || W || Stops the specified function from the item. (On X version wild character * is available for defining the function name or the argument)
 
|-
 
|-
−
| [[MESSAGE]] ''message'' || Displays a message above this item to SRC.
+
| [[TRIGGER]] ''trig_name, trigger_argtype, argument1, argument2, ...'' || R || Fires a custom trigger (trig_name), allowing you to define the behavior of the arguments (the types are defined under trigger_argtype in the sphere_defs.scp file).  The result of the trigger's RETURN value is returned.  For example:
 +
LOCAL.result=<TRIGGER @CustomTrigger,<DEF.tat_as_argn>,1,2,3>
 
|-
 
|-
−
| [[MESSAGEUA]] ''colour, talkmode, font, lang_id, message'' || Displays a UNICODE message above thsi item to SRC.
+
| [[TYPE]] || RW || Gets or sets the item type.  You can use built-in or custom [[TYPEDEF]]s as a value.
 
|-
 
|-
−
| [[MOVE]] ''direction, amount''<br /> [[MOVE]] ''x y'' || Moves the object relative to its current position.
+
| [[UID]] || R || Gets the item's unique ID in the world.
 
|-
 
|-
−
| [[MOVENEAR]] ''object_uid, distance'' || Moves the object to a random location near another object within a certain distance.
+
| [[UNEQUIP]] || W || Unequips the item and places it in SRC's backpack.
 
|-
 
|-
−
| [[MOVETO]] ''location'' || Moves the object to a specific location.
+
| [[UPDATE]] || W || Updates the state of the item to nearby clients.
 
|-
 
|-
−
| [[NUDGEDOWN]] ''amount'' || Decreases the object's Z level.
+
| [[UPDATEX]] || W || Updates the state of the item to nearby clients, removing it from their view first to ensure a full refresh.
 
|-
 
|-
−
| [[NUDGEUP]] ''amount'' || Increases the object's Z level.
+
| [[USESCUR]] || W || X branch only. Gets or sets the current uses of an item. Only partially supported.
 
|-
 
|-
−
| [[PROMPTCONSOLE]] ''function, prompt_message'' || Displays a prompt message to SRC and passes their response into a specified function.
+
| [[USESMAX]] || W || X branch only. Gets or sets the maximum uses of an item. Only partially supported.
 
|-
 
|-
−
| [[PROMPTCONSOLEU]] ''function, prompt_message'' || Displays a prompt message to SRC and passes their response into a specified function, supporting UNICODE response.
+
| [[USE]] ''check_los'' || W || Uses the item, as if SRC had double clicked it.
 
|-
 
|-
−
| [[REMOVE]] || Deletes the object.
+
| [[USEITEM]] || W || Double clicks the item, with SRC as the source of the event, without checking for line of sight.
 
|-
 
|-
−
| [[REMOVEFROMVIEW]] || Removes the object from nearby clients' screens.
+
| [[WEIGHT]] || R || Gets the weight of the item.
 
|-
 
|-
−
| [[RESENDTOOLTIP]] || Forces Sphere to update the tooltips for nearby clients.
+
| [[Z]] || R || Gets the Z position of the item.
−
|-
 
−
| [[SAY]] ''message'' || Makes the object speak a message.
 
−
|-
 
−
| [[SAYU]] ''message'' || Makes the object speak a UTF-8 message
 
−
|-
 
−
| [[SAYUA]] ''colour, talkmode, font, lang_id, text'' || MAkes the object speak a UNICODE message.
 
−
|-
 
−
| [[SDIALOG]] ''dialog_id, page, parameters'' || Displays a dialog to SRC, providing that it is not already open.
 
−
|-
 
−
| [[SOUND]] ''sound_id, repeat'' || Plays a sound from this object.
 
−
|-
 
−
| [[SPELLEFFECT]] ''spell_id, strength, source_character_uid, source_item_uid'' || Causes the item to be affected by a spell.
 
−
|-
 
−
| [[TAGLIST]] || Outputs a list of the object's TAGs.
 
−
|-
 
−
| [[TARGET]]''FGMW'' ''function'' || Displays a targeting cursor to SRC.
 
−
|-
 
−
| [[TIMERF]] ''time, function'' || Scheduled a function to be executed on this object in ''time'' seconds.
 
−
|-
 
−
| [[TIMERF]] CLEAR || Clears all scheduled functions from the object.
 
−
|-
 
−
| [[UNEQUIP]] || Unequips the item and places it in SRC's backpack.
 
−
|-
 
−
| [[UPDATE]] || Updates the state of the item to nearby clients.
 
−
|-
 
−
| [[UPDATEX]] || Updates the state of the item to nearby clients, removing it from their view first to ensure a full refresh.
 
−
|-
 
−
| [[USE]] ''check_los'' || Uses the item, as if SRC had double clicked it.
 
−
|-
 
−
| [[USEITEM]] || Double clicks the item, with SRC as the source of the event, without checking for line of sight.
 
 
|}
 
|}
−
 
  
 
==Triggers==
 
==Triggers==
Line 259: Line 286:
  
 
{| border="1" cellspacing="4" cellpadding="4"
 
{| border="1" cellspacing="4" cellpadding="4"
−
| '''Name''' || '''Description'''
+
| '''Name''' || '''Description''' || '''Sphere X Only?'''
 
|-
 
|-
−
| [[@AfterClick]] || Fires when the object has been single-clicked, after the hardcoded behaviour.
+
| [[@AfterClick]] || Fires when the object has been single-clicked, just before the overhead name is shown.
 
|-
 
|-
 
| [[@Buy]] || Fires when the item is being bought from a vendor.
 
| [[@Buy]] || Fires when the item is being bought from a vendor.
Line 272: Line 299:
 
|-
 
|-
 
| [[@ContextMenuSelect]] || Fires when a client selects a context menu option for the object.
 
| [[@ContextMenuSelect]] || Fires when a client selects a context menu option for the object.
 +
|-
 +
|[[@Carve]] || Fires when a corpse item is being carved. || X
 
|-
 
|-
 
| [[@Create]] || Fires when the object is initially created, before it is placed in the world.
 
| [[@Create]] || Fires when the object is initially created, before it is placed in the world.
Line 288: Line 317:
 
|-
 
|-
 
| [[@DropOn_Self]] || Fires when an item has been dropped on to this item.
 
| [[@DropOn_Self]] || Fires when an item has been dropped on to this item.
 +
|-
 +
| [[@DropOn_Trade]] || Fires when an item is being dropped on a Trade Window.
 +
|-
 +
| [[@Dye]] || Fires when an item is having its colored changed.
 
|-
 
|-
 
| [[@Equip]] || Fires when the item has been equipped.
 
| [[@Equip]] || Fires when the item has been equipped.
Line 293: Line 326:
 
| [[@EquipTest]] || Fires when the item is about to be equipped.
 
| [[@EquipTest]] || Fires when the item is about to be equipped.
 
|-
 
|-
−
| [[@Fire]] ||
+
| [[@HouseDesignBegin]] || A trigger for t_multi_custom, called when the player enters on design mode. || X
 +
|-
 +
| [[@HouseDesignCommitItem]] || Fires for each commited item in house design system. || X
 
|-
 
|-
 
| [[@PickUp_Ground]] || Fires when the item ihas been picked up from the ground.
 
| [[@PickUp_Ground]] || Fires when the item ihas been picked up from the ground.
Line 302: Line 337:
 
|-
 
|-
 
| [[@PickUp_Stack]] || Fires when the item is picked up from a stack.
 
| [[@PickUp_Stack]] || Fires when the item is picked up from a stack.
 +
|-
 +
| [[@Redeed]] || Fires when multi item is about to redeed (t_multi, t_ship, t_multi_custom, t_addon).
 
|-
 
|-
 
| [[@Sell]] || Fires when the item is sold to a vendor.
 
| [[@Sell]] || Fires when the item is sold to a vendor.
 +
|-
 +
| [[@Smelt]] || Fires when the item is being smelt. || X
 
|-
 
|-
 
| [[@SpellEffect]] || Fires when the object is hit by the effects of a spell.
 
| [[@SpellEffect]] || Fires when the object is hit by the effects of a spell.
Line 319: Line 358:
 
| [[@Timer]] || Fires when the item's timer expires.
 
| [[@Timer]] || Fires when the item's timer expires.
 
|-
 
|-
−
| [[@ToolTip]] ||
+
| [[@ToolTip]] || Fires when old-style tooltips are requested for the item.
 
|-
 
|-
 
| [[@UnEquip]] || Fires when the item is unequipped.
 
| [[@UnEquip]] || Fires when the item is unequipped.
 
|}
 
|}
 +
 +
[[Category: Reference Compendium]]
 +
[[Category: Objects]]

Latest revision as of 23:37, 2 December 2023

Help
Available languages
Missing languages


Generally speaking, there are two types of "things" in the game; characters and items. Compared to characters, items are very complex. Items have a number of different uses, for example a sword is an item that players can see and equip to increase the damage they can do in combat. Some items in the game can not be seen by the players, but they have as much impact on the player as their sword, for example, a memory item is equipped every time a player is under the effects of a spell. Some special types of item also have additional properties that can be accessed via scripts. The following tables detail the various properties of items in SphereServer:


References

References return pointers to other objects (e.g. the REGION reference allows you to access the REGION that an object is in). These can either be accessed by using <REFNAME> to return the UID (1 for object types that don't have UIDs) of the object or 0 if it doesn't exist, or by using <REFNAME.KEY> where KEY is a valid property/function/reference for the REFNAME object. Click on the name for more detailed information such as usage and examples.

Name Read/Write Description
CONT RW Gets or sets the character or container item that the object is inside. When an item's CONT is changed, it bypasses the typical behavior (for example, you can force an item to be "in" a container and bypass @dropon triggers, or force an item to be equipped to a player and bypass @equiptest and @equip triggers -- but be careful, because in this second scenario it may end up in an invalid layer.)
LINK RW Gets or sets the character or item that the item is linked to. Note, you can make circular LINK's, but a single item cannot be linked to more than one other item.
REGION R Gets the region that the object is in.
ROOM R Gets the room that the object is in.
P RW Gets or sets the position that the object is at.
SECTOR R Gets the sector that the object is in.
TOPOBJ R Gets the top-most character or item in the world that contains the item.
TYPEDEF R Gets the ITEMDEF that defines the item.

Properties and Functions

Here is a list of all item properties and functions. If a function is marked as readable then it can return a value when used as <KEY>. Click on the name for more detailed information such as usage and examples. If an attempt is made to access a property that does not exist on the item, the property from the ITEMDEF will be accessed instead.

Name Read/Write Description
ADDCIRCLE spell_circle W Adds all of the spells in the given Magery circle to the spellbook.
ADDSPELL spell_id RW Gets whether or not a spell exists in the spellbook, or adds a spell to the spellbook.
AMMOANIM RW Overrides TDATA4 for bow/crossbow type weapons.
AMMOANIMHUE RW Sets the color of the effect when firing bow/crossbow type weapons.
AMMOANIMRENDER RW Sets the render mode of the effect when firing bow/crossbow type weapons.
AMMOCONT RW Sets the container UID or ID where to search for ammos for bow/crossbow type weapons.
AMMOSOUNDHIT RW Overrides the hit sound on weapons.
AMMOSOUNDMISS RW Overrides the miss sound on weapons.
AMMOTYPE RW Overrides TDATA3 for bow/crossbow type weapons.
AMOUNT RW Gets the amount of items this icon represents (e.g. a pile of gold or any stacked item).
ATTR RW Gets or sets the item's attribute flags.
BOUNCE W Moves the item to SRC's backpack (triggering the you put the item in your pack message.
CAN RW Gets or Sets the can_flags (Setting can be only done in the Itemdef itself). Only readable in X branch.
CANMASK RW Stores the CAN flags to be dynamically switched on or off from the base CAN property.
CANSEE R Returns 1 if SRC can see the item.
CANSEELOS point_or_uid R Returns 1 if SRC has line of sight to the item or character (uid) or point (location).
CANSEELOSFLAG flags,point_or_uid R Returns 1 if SRC has line of sight to the item. The flags are defined in the los_flags section of the sphere_defs.scp file and can be used to modify what tests take place. The point_or_uid is an object or position that can be used to test line of sight to something other than SRC. Note, the delimiter for FLAG values is ;
CLEARTAGS prefix W Removes all TAGs from the item that start with the given prefix.
COLOR RW Gets or sets the object's hue.
CONSUME amount W Deducts an amount from the item, deleting it at 0.
CONTCONSUME resource_list W Deletes items from inside the container.
CONTGRID RW If in a container, gets or sets the grid number that the item occupies (in KR's grid view)
CONTP RW Gets or sets the position of the item within its container.
DAMAGE chance, type, source W If chance is greater than (Rand(maxhits*16)), inflicts damage of type (the damage type flags are defined in the sphere_defs.scp file) upon the item. You can optionally specify the source of the damage.
DCLICK W Double clicks the item, with SRC as the source of the event.
DECAY time W Sets the decay timer (in tenths of a second) for the item.
DESTROY W Deletes the object, not stopped by a return 1 in @Destroy
DIALOG dialog_id, page, parameters W Displays a dialog to SRC.
DISPID RW Gets or sets the ID that the item will appear as to players.
DISPIDDEC RW Same as DISPID, except it returns the ID as a decimal number.
DISTANCE point_or_uid R Gets the distance between this object and SRC. If point_or_uid is used, SRC can be replaced with a map location or another object.
DMGCOLD RW Gets or sets the amount of cold damage the weapon will give.
DMGENERGY RW Gets or sets the amount of energy damage the weapon will give.
DMGFIRE RW Gets or sets the amount of fire damage the weapon will give.
DMGPOISON RW Gets or sets the amount of poison damage the weapon will give.
DROP W Drops the item to the ground.
DUPE W Clones the item.
EDIT W Displays an editing dialog for the item to SRC.
EFFECT type, item_id, speed, loop, explode, colour, rendermode W Displays an effect to nearby clients.
EMOTE message W Displays a *You see* message to all nearby clients.
EQUIP W Equips the item to SRC.
EVENTS event_defname RW Gets a list of events attached to the object, or adds or removes an event to or from the object.
FIX W Re-aligns the item or character's Z level to ground level (if items are on the ground, the top item's Z+HEIGHT is used).
FLIP W Rotates the item clockwise.
FRUIT RW Gets or sets the fruit that will be produced by the crops.
HEIGHT R Gets the height of the item.
HITS RW Gets or sets the number of hitpoints the item has.
HITPOINTS RW Gets or sets the number of hitpoints the item has.
ID RW Gets or sets the ID of the item.
INFO W Displays an information dialog about the item to SRC.
ISARMOR object_uid R Returns 1 if the object is armour.
ISCHAR R Returns 1 if the object is a character.
ISCONT R Returns 1 if the object is a container.
ISEVENT.event_defname R Returns 1 if the object has an event attached to it.
ISITEM R Returns 1 if the object is an item.
ISNEARTYPE type, distance, flags R Returns 1 if a nearby item has the given TYPE and is within distance.
ISNEARTYPETOP type, distance, flags R Returns a nearby world location of a nearby item which has the given TYPE and is within distance.
ISPLAYER R Returns 1 if the object is a player character.
ISTEVENT.event_defname R Returns 1 if the object has an event attached to its ITEMDEF.
ISTIMERF.function R Returns the number of seconds left on the specified timerf if it exists.
ISWEAPON object_uid R Returns 1 if the object is a weapon.
LAYER RW Gets or sets the layer that the item occupies when equipped (possible layers are defined in the sphere_defs.scp file).
MAP RW Gets or sets the map that this object is located.
MAXHITS RW Gets or sets the maximum number of hitpoints the item can have.
MENU menu_defname W Displays a menu to SRC.
MESSAGE message W Displays a message above this item to SRC.
MESSAGEUA colour, talkmode, font, lang_id, message W Displays a UNICODE message above this item to SRC.
MODAR RW Gets or sets a modifier for the item's armour rating if it is clothing, armor, or a shield. This gets or sets a modifier for the item's damage if it is a weapon type.
MORE1 RW Gets or sets the MORE1 value for the item.
MORE1H RW Gets or sets the upper 4 bytes of the item's MORE1 value.
MORE1L RW Gets or sets the lower 4 bytes of the item's MORE1 value.
MORE2 RW Gets or sets the MORE2 value for the item.
MORE2H RW Gets or sets the upper 4 bytes of the item's MORE2 value.
MORE2L RW Gets or sets the lower 4 bytes of the item's MORE2 value.
MOREM RW Gets or sets the MOREM value for the item.
MOREX RW Gets or sets the MOREX value for the item.
MOREY RW Gets or sets the MOREY value for the item.
MOREZ RW Gets or sets the MOREZ value for the item.
MOREP RW Gets or sets the MOREP value for the item.
MOVE direction amount
MOVE x y 		W Moves the object relative to its current position. Possible direction values are N,S,W, or E. Note, you can combine directions (like: MOVE SW 1) but nonsensical directions (like: MOVE WE 2) have the nonsense removed.
MOVENEAR object_uid, distance W Moves the object to a random location near another object within a certain distance.
MOVETO location W Moves the object to a specific location (note, the AREADEF or ROOMDEF must have a P defined).
NAME RW Gets or sets the object's name.
NUDGEDOWN amount W Decreases the object's Z level.
NUDGEUP amount W Increases the object's Z level.
PROMPTCONSOLE function, prompt_message W Displays a prompt message to SRC and passes their response into a specified function.
PROMPTCONSOLEU function, prompt_message W Displays a prompt message to SRC and passes their response into a specified function, supporting UNICODE response.
REMOVE W Deletes the object.
REMOVEFROMVIEW W Removes the object from nearby clients' screens.
RESCOUNT item_defname R Returns the total amount of a specific item inside a container.
RESENDTOOLTIP W Forces Sphere to update the tooltips for nearby clients.
SAY message W Makes the object speak a message.
SAYU message W Makes the object speak a UTF-8 message
SAYUA colour, talkmode, font, lang_id, text W Makes the object speak a UNICODE message.
SDIALOG dialog_id, page, parameters W Displays a dialog to SRC, providing that it is not already open.
SERIAL R Gets the item's unique ID in the world.
SEXTANTP location R Converts the item's location or a specified location into sextant coordinates.
SOUND sound_id, repeat W Plays a sound from this object.
SPELLEFFECT spell_id, strength, source_character_uid, source_item_uid W Causes the item to be affected by a spell.
TAG.name RW Gets or sets the value of a TAG.
TAGAT.index R Gets a TAG at the given zero-based index.
TAGAT.index.KEY R Gets the name of the TAG at the given zero-based index.
TAGAT.index.VAL R Gets the value of the TAG at the given zero-based index.
TAGCOUNT R Gets the number of TAGs stored on the item.
TAGLIST W Outputs a list of the object's TAGs.
TARGETFGMW function W Displays a targeting cursor to SRC. F makes the function available, and when added, the function name must be the 1st argument. M allows you to place a multi item, in which case the multi number must be passed as an argument. G forces the target to only be the ground. W checks the criminal status of the player before (or after?) the target selection is made.
TIMER RW Gets or sets the length of time before the item's timer expires, in seconds.
TIMERD RW Gets or sets the length of time before the item's timer expires, in tenths of a second.
TIMERF time, function W Schedules a function to be executed on this object in time seconds.
TIMERF CLEAR W Clears all scheduled functions from the object.
TIMERF STOP, function W Stops the specified function from the item. (On X version wild character * is available for defining the function name or the argument)
TRIGGER trig_name, trigger_argtype, argument1, argument2, ... R Fires a custom trigger (trig_name), allowing you to define the behavior of the arguments (the types are defined under trigger_argtype in the sphere_defs.scp file). The result of the trigger's RETURN value is returned. For example: 
LOCAL.result=<TRIGGER @CustomTrigger,<DEF.tat_as_argn>,1,2,3>
TYPE RW Gets or sets the item type. You can use built-in or custom TYPEDEFs as a value.
UID R Gets the item's unique ID in the world.
UNEQUIP W Unequips the item and places it in SRC's backpack.
UPDATE W Updates the state of the item to nearby clients.
UPDATEX W Updates the state of the item to nearby clients, removing it from their view first to ensure a full refresh.
USESCUR W X branch only. Gets or sets the current uses of an item. Only partially supported.
USESMAX W X branch only. Gets or sets the maximum uses of an item. Only partially supported.
USE check_los W Uses the item, as if SRC had double clicked it.
USEITEM W Double clicks the item, with SRC as the source of the event, without checking for line of sight.
WEIGHT R Gets the weight of the item.
Z R Gets the Z position of the item.

Triggers

Here is a list of all item triggers. Click on the trigger name for more detailed information such as arguments and examples.

Name Description Sphere X Only?
@AfterClick Fires when the object has been single-clicked, just before the overhead name is shown.
@Buy Fires when the item is being bought from a vendor.
@Click Fires when the object has been single-clicked.
@ClientTooltip Fires when tooltips are about to be sent to a client.
@ContextMenuRequest Fires when a client requests the context menu options for the object.
@ContextMenuSelect Fires when a client selects a context menu option for the object.
@Carve Fires when a corpse item is being carved. X
@Create Fires when the object is initially created, before it is placed in the world.
@Damage Fires when the item receives damage.
@DClick Fires when the object is double-clicked.
@Destroy Fires when the object is being deleted.
@DropOn_Char Fires when the item has been dropped on to a character.
@DropOn_Ground Fires when the item has been dropped on to the ground.
@DropOn_Item Fires when the item is dropped on to another item.
@DropOn_Self Fires when an item has been dropped on to this item.
@DropOn_Trade Fires when an item is being dropped on a Trade Window.
@Dye Fires when an item is having its colored changed.
@Equip Fires when the item has been equipped.
@EquipTest Fires when the item is about to be equipped.
@HouseDesignBegin A trigger for t_multi_custom, called when the player enters on design mode. X
@HouseDesignCommitItem Fires for each commited item in house design system. X
@PickUp_Ground Fires when the item ihas been picked up from the ground.
@PickUp_Pack Fires when the item is picked up from inside a container.
@PickUp_Self Fires when an item has been picked up from inside the item.
@PickUp_Stack Fires when the item is picked up from a stack.
@Redeed Fires when multi item is about to redeed (t_multi, t_ship, t_multi_custom, t_addon).
@Sell Fires when the item is sold to a vendor.
@Smelt Fires when the item is being smelt. X
@SpellEffect Fires when the object is hit by the effects of a spell.
@Step Fires when a character steps on the item.
@TargOn_Cancel Fires when a target is cancelled from the item.
@TargOn_Char Fires when a character is targeted from the item.
@TargOn_Ground Fires when the ground is targeted from the item.
@TargOn_Item Fires when an item is targeted from this item.
@Timer Fires when the item's timer expires.
@ToolTip Fires when old-style tooltips are requested for the item.
@UnEquip Fires when the item is unequipped.
Retrieved from "https://wiki.spherecommunity.net/index.php?title=Items&oldid=8102"