Item

TheiItem class represents a single item within the game. All items are individual and are not dependant on other item's or an item definition. Items can be cloned and have their values set from another item however if a definition like system is required.
Return to Index
static new ( string game_id = "" )
static new ( string game_id = "" , string def_name )
__gc ( )
__eq ( am.item rhs ) -> ( boolean )
static from_def ( string def_name ) -> ( Item )
clone ( ) -> ( am.item )
graphic ( ) -> ( am.sprite )
graphic ( am.sprite graphic , boolean calc_size = false ) -> ( am.item )
graphic ( string asset_name , boolean calc_size = false ) -> ( am.item )
ground_graphic ( ) -> ( am.sprite )
ground_graphic ( am.sprite graphic ) -> ( am.item )
ground_graphic ( string asset_name ) -> ( am.item )
item_type ( ) -> ( string )
item_type ( string item_type ) -> ( am.item )
inventory_size ( ) -> ( integer , integer )
inventory_size ( integer width , integer height ) -> ( am.item )
item_location ( ) -> ( )
item_location ( string location ) -> ( am.item )
quest_item_id ( ) -> ( integer )
quest_item_id ( integer quest_id ) -> ( am.item )
is_quest_item ( ) -> ( boolean )
item_name ( ) -> ( string )
item_name ( string name ) -> ( am.item )
description ( ) -> ( string )
description ( string description ) -> ( am.item )
prefix ( ) -> ( string )
prefix ( string prefix ) -> ( am.item )
postfix ( ) -> ( string )
postfix ( string postfix ) -> ( am.item )
item_fullname ( ) -> ( string )
item_fullname ( string main_name , string prefix = "" , string postfix = "" ) -> ( am.item )
set_item_from ( am.item other ) -> ( am.item )
stat_modifiers ( ) -> ( am.stats_modifiers )
stat_modifiers_self ( ) -> ( am.stats_modifiers )
width ( ) -> ( number )
height ( ) -> ( number )
name ( ) -> ( string )
item_value ( ) -> ( integer )
item_value ( integer value ) -> ( am.item )
location ( ) -> ( number , number )
location ( number x , number y ) -> ( am.item )
grid_location ( ) -> ( integer , integer )
grid_location ( integer x , integer y ) -> ( am.item )
game_id ( number x , number y ) -> ( am.item )
game_id ( integer x , integer y ) -> ( am.item )
game_id ( string id ) -> ( boolean )
game_id ( am.game_object talkee ) -> ( boolean )
game_id ( ) -> ( boolean )
game_id ( boolean fixed ) -> ( am.item )
game_id ( ) -> ( am.map )
game_id ( am.map map ) -> ( am.item )
game_id ( ) -> ( am.map )
game_id ( am.map map ) -> ( am.item )
game_id ( am.tile_type tile_type ) -> ( am.item )
game_id ( string tile_type_name ) -> ( am.item )
game_id ( am.tile_type tile_type ) -> ( am.item )
game_id ( ) -> ( am.item )
game_id ( am.tile_type tile_type ) -> ( boolean )
game_id ( ) -> ( table )
game_id ( ) -> ( am.dialogue_component )
game_id ( am.dialogue_component comp , boolean set_attached = true ) -> ( )
game_id ( ) -> ( string )
game_id ( string game_id ) -> ( boolean )
interact_with ( ) -> ( function )
interact_with ( function func ) -> ( am.item )
interact_dialogue ( am.game_object interacter , bool by_movement ) -> ( am.code )
on ( string event_type , function listener , table content = nil ) -> ( boolean )
off ( string event_type , function listener , table context = nil ) -> ( boolean )
has_event_listener ( string event_type ) -> ( boolean )
static find ( string game_id ) -> ( am.item )
attrs ( boolean create_table = false ) -> ( am.data_table )
attrs ( am.data_table attr_table ) -> ( am.item )
add_body_type ( string part_type ) -> ( am.item )
remove_body_type ( string part_type ) -> ( am.item )
has_body_type ( string part_type ) -> ( boolean )
get_body_types ( ) -> ( table )
static new ( string game_id = "" )
Creates or wraps an item instance, it will have the name "Item" and will take up 1x1 inventory slots. For example, the first time an item is created (as in the case of a new game) there should not be any existing item with the same game_id. In which case a new item will be created. If the item was not pre-existing then it will need all the specific values set onto it. However if it was pre-existing then you are unlikely to want to set it's current values back to what they were when the item was first created. However event listeners are not maintained between saves, so they will have to be added to an existing (loaded) item as well as a new one.
Parameters:
string game_id = "" : The game id to create the item with or the game id of an existing item.
Returns:
am.item : The newly created item or returns an existing item with the same game_id.
boolean : True if the item was newly created or false if it already existed.
static new ( string game_id = "" , string def_name )
Behaves the same as the base constructor however the new item will be created from the given item definition if it has to be created.
Parameters:
string game_id = "" : The game id to create the item with or the game id of an existing item.
string def_name : The item definition name to look up when creating the item if it one did not exist.
Returns:
am.item : The newly created item or returns an existing item with the same game_id.
boolean : True if the item was newly created or false if it already existed.
__gc ( )
Releases the reference counter on this item.
__eq ( am.item rhs ) -> ( boolean )
Returns true if the given item is the same as this item.
Parameters:
am.item rhs : The other item to compare with.
Returns:
boolean : True if they are the same item.
static from_def ( string def_name ) -> ( Item )
Creates a new item from the item definition. Item definitions are automatically loaded if one with the given name is not registered.

Example (a test map Lua file):

 item = am.item.from_def("wooden:sword")
 if (item ~= nil)
     item:name("Fred's Sword")
 end

In "data/defs/wooden.lua":

 game = am.engine.game()
 
 item = am.item.new()
 item:item_type("sword")
     :graphic(am.sprite.new("item/sword"))
     :groundGraphic(am.sprite.new("item/swordGround"))
 
 -- Here the npc is registered with the name "sword" and "wooden:" will 
 -- automatically be prepended because of the filename.
 game:item_def("sword", item)
Parameters:
string def_name : The name of the item definition.
Returns:
Item : A copy of the item from the given definition, or nil if no definition was found.
clone ( ) -> ( am.item )
Creates a copy of this item, will create a new instance of the sprites used for the graphics.
Returns:
am.item : The newly cloned item.
graphic ( ) -> ( am.sprite )
Returns the graphic used to display the item. This graphic is used to display the item on the inventory screen and will also be used as the ground graphic if one is not set.
Returns:
am.sprite : The graphic for the item, can be nil.
graphic ( am.sprite graphic , boolean calc_size = false ) -> ( am.item )
Sets the graphic for the item, can be set to nil.
Parameters:
am.sprite graphic : The new graphic for the item.
boolean calc_size = false : Calculates the inventory size of the item based off the graphic size. This is based off the the size of the item compared to the size of each inventory slot size.
Returns:
am.item : This
graphic ( string asset_name , boolean calc_size = false ) -> ( am.item )
Sets the graphic by asset name for the item, can be set to nil.
Parameters:
string asset_name : The asset name for the new graphic for the item.
boolean calc_size = false : Calculates the inventory size of the item based off the graphic size. This is based off the the size of the item compared to the size of each inventory slot size.
Returns:
am.item : This
ground_graphic ( ) -> ( am.sprite )
Returns the graphic used to display the item on the ground. This graphic is used to display the item when it is on the ground and will also be used as the inventory graphic if one is not set.
Returns:
am.sprite : The ground graphic for the item, can be nil.
ground_graphic ( am.sprite graphic ) -> ( am.item )
Sets the ground graphic for the item, can be set to nil.
Parameters:
am.sprite graphic : The new ground graphic for the item.
Returns:
am.item : This
ground_graphic ( string asset_name ) -> ( am.item )
Sets the ground graphic by asset name for the item, can be set to nil.
Parameters:
string asset_name : The asset name for the new ground graphic for the item.
Returns:
am.item : This
item_type ( ) -> ( string )
Returns the item type. The item type defines what special properties the item has, such as if it is coin or a potion.
Returns:
string : The item type.
item_type ( string item_type ) -> ( am.item )
Sets the item type, can be one of the following values:
  • helm
  • body
  • sword
  • axe
  • bow
  • ring
  • amulet
  • leggins
  • boots
  • shield
  • potion
  • gold
  • unknown
Parameters:
string item_type : The item type to set on this item.
Returns:
am.item : This
inventory_size ( ) -> ( integer , integer )
Returns the inventory size of this item as a pair of integers in inventory size units.
Returns:
integer : The width in inventory units.
integer : The height in inventory units.
inventory_size ( integer width , integer height ) -> ( am.item )
Sets size of the inventory size in inventory units.
Parameters:
integer width : The width in inventory units.
integer height : The height in inventory units.
Returns:
am.item : This
item_location ( ) -> ( )
Returns the item location, as being in either in an inventory, in the player's hand or on the ground. @return String The item location as either "ground", "inventory" or "hand"
item_location ( string location ) -> ( am.item )
Sets the item location as being either on the ground, in an inventory or in the player's hand.
Parameters:
string location : The location as either "ground", "inventory" or "hand"
Returns:
am.item : This
quest_item_id ( ) -> ( integer )
Returns the quest ID for this item. The quest ID is a unique identifier for this item, this allows this item to be kept track of. Any value above 0 is considered to be a valid id.
Returns:
integer : The quest ID of this time.
quest_item_id ( integer quest_id ) -> ( am.item )
Sets the quest ID, any value higher than 0 is considered a valid ID.
Parameters:
integer quest_id : The new quest ID.
Returns:
am.item : This
is_quest_item ( ) -> ( boolean )
Returns true if this item has a valid quest ID.
Returns:
boolean : True if this item is a quest item.
item_name ( ) -> ( string )
Returns the main item name.
Returns:
string : The main item name.
item_name ( string name ) -> ( am.item )
Sets the main item name, this goes between the prefix and the postfix.
Parameters:
string name : The main item name.
Returns:
am.item : This
description ( ) -> ( string )
Returns the description of the item. A nil return indicates that there was an error.
Returns:
string : The description of the item.
description ( string description ) -> ( am.item )
Sets the description of the item.
Parameters:
string description : The description to set the item.
Returns:
am.item : This.
prefix ( ) -> ( string )
Returns the item prefix, this goes before the item name, can be an empty string.
Returns:
string : The item prefix.
prefix ( string prefix ) -> ( am.item )
Sets the item prefix, nil is considered to be an empty string.
Parameters:
string prefix : The item prefix.
Returns:
am.item : This
postfix ( ) -> ( string )
Returns the item postfix, this goes after the item name, can be an empty string.
Returns:
string : The item postfix.
postfix ( string postfix ) -> ( am.item )
Sets the item postfix, nil is considered to be an empty string.
Parameters:
string postfix : The item postfix.
Returns:
am.item : This
item_fullname ( ) -> ( string )
Returns the whole item name as one string.
Returns:
string : The whole item name.
item_fullname ( string main_name , string prefix = "" , string postfix = "" ) -> ( am.item )
Sets the whole item name, the main name, prefix and postfix.
Parameters:
string main_name : The main item name.
string prefix = "" : The item prefix.
string postfix = "" : The item potsfix.
Returns:
am.item : This
set_item_from ( am.item other ) -> ( am.item )
Sets all the values from the given item onto this item.
Parameters:
am.item other : The other item to set the values from.
Returns:
am.item : This
stat_modifiers ( ) -> ( am.stats_modifiers )
Returns the stats modifiers object for this item.
Returns:
am.stats_modifiers : The stats modifiers object.
stat_modifiers_self ( ) -> ( am.stats_modifiers )
Returns the self stats modifiers object for this item.
Returns:
am.stats_modifiers : The self stats modifiers object.
width ( ) -> ( number )
Returns the item width for the main graphic.
Returns:
number : The width of the item graphic.
height ( ) -> ( number )
Returns the item height for the main graphic.
Returns:
number : The height of the item graphic.
name ( ) -> ( string )
An alias for returning the full item name.
Returns:
string : The full item name.
item_value ( ) -> ( integer )
Returns the items coin value.
Returns:
integer : The items coin value.
item_value ( integer value ) -> ( am.item )
Sets the items coin value.
Parameters:
integer value : The new coin value.
Returns:
am.item : This
location ( ) -> ( number , number )
Returns the items current map location.
Returns:
number : The items x map value
number : The items y map value
location ( number x , number y ) -> ( am.item )
Sets the items map location.
Parameters:
number x : The x map value
number y : The y map value
Returns:
am.item : This
grid_location ( ) -> ( integer , integer )
Returns the items currnet map grid location.
Returns:
integer : x The x grid value
integer : y The y grid value
grid_location ( integer x , integer y ) -> ( am.item )
Sets the items current map grid location.
Parameters:
integer x : The x grid value
integer y : The y grid value
Returns:
am.item : This
game_id ( number x , number y ) -> ( am.item )
Moves a item by {x, y} amount. If the new location isn't valid, the item isn't moved.
Parameters:
number x : The x amount to move by
number y : The y amount to move by
Returns:
am.item : This
game_id ( integer x , integer y ) -> ( am.item )
Moves a item by {x, y} grid amounts. If the new location isn't valid, the item isn't moved.
Parameters:
integer x : The x grid amount to by move by
integer y : The y grid amount to by move by
Returns:
am.item : This
game_id ( string id ) -> ( boolean )
Initiates a conversation between this item and the game object id passed in. Returns true if the conversation was initiated. False can mean that the game object id was invalid or that either this item or the game object did not have a dialog component attached.
Parameters:
string id : The game object id.
Returns:
boolean : True if the conversation was initiated.
game_id ( am.game_object talkee ) -> ( boolean )
Initiates a conversation between this item and the game object passed in. Returns true if the conversation was initiated. False can mean that the game object was nil or that either this item or the game object did not have a dialog component attached.
Parameters:
am.game_object talkee : The game object to start a converstation with.
Returns:
boolean : True if the conversation was initiated.
game_id ( ) -> ( boolean )
Returns true if this item is fixed to the game grid or false if the item is able to move freely about the map.
Returns:
boolean : True if the item is fixed to the grid.
game_id ( boolean fixed ) -> ( am.item )
Sets if the item is fixed to the grid or not. If a item is fixed to the grid, they cannot move to positions other than the center of each grid space.
Parameters:
boolean fixed : Sets the fixed to grid value.
Returns:
am.item : This
game_id ( ) -> ( am.map )
Returns the current map that this item is on, can be nil.
Returns:
am.map : The map the item is on.
game_id ( am.map map ) -> ( am.item )
Sets the map that the item is on, can be nil.
Parameters:
am.map map : The map to put the item on.
Returns:
am.item : This
game_id ( ) -> ( am.map )
Returns the original map that this item was on, can be nil.
Returns:
am.map : The map the item was originally on.
game_id ( am.map map ) -> ( am.item )
Sets the map that the item was originally on, can be nil. This is usually set automatically the first time a item is added to a map. This is primarily used for reloading the item and knowing where to find likely find any event handlers and additional information relating to the item that is not stored directly on the item.
Parameters:
am.map map : The map the item was originally was on.
Returns:
am.item : This
game_id ( am.tile_type tile_type ) -> ( am.item )
Adds a tile type to the list of tile types that this item can move freely on. TileTypes can be added multiple times.
Parameters:
am.tile_type tile_type : The type to add to the list.
Returns:
am.item : This
game_id ( string tile_type_name ) -> ( am.item )
Adds a tile type to the list of tile types that this item can move freely on. Tile types can be added multiple times.
Parameters:
string tile_type_name : The name of the type to add to the list.
Returns:
am.item : This
game_id ( am.tile_type tile_type ) -> ( am.item )
Removes a tile type from the list of passible tiles.
Parameters:
am.tile_type tile_type : The tile type to remove.
Returns:
am.item : This
game_id ( ) -> ( am.item )
Removes all tile types from this items passible list.
Returns:
am.item : This
game_id ( am.tile_type tile_type ) -> ( boolean )
Returns true if the given tile type is found on this items passible list.
Parameters:
am.tile_type tile_type : The tile type to search for
Returns:
boolean : True if the tile type is found
game_id ( ) -> ( table )
Returns a table of all the passible tile types for this item.
Returns:
table : Table of all the tile types.
game_id ( ) -> ( am.dialogue_component )
Returns the dialogue component attached to this item, can be nil.
Returns:
am.dialogue_component : The attached dialogue component
game_id ( am.dialogue_component comp , boolean set_attached = true ) -> ( )
Sets a dialogue component onto this item, can be nil.
Parameters:
am.dialogue_component comp : The dialogue component to attach to this item, can be nil.
boolean set_attached = true : When true it also sets that this item is the game object attached to the dialogue component.
game_id ( ) -> ( string )
Returns the game id for this item.
Returns:
string : The items game id.
game_id ( string game_id ) -> ( boolean )
Sets the items game id, this is used to refer to this item from the game engine. Should be unique.
Parameters:
string game_id : The items unique game id.
Returns:
boolean : True if the game id change was successful or if game id was the same as the given game_id. False indicates that either there is no current game engine or there is another game object with the same game id.
interact_with ( ) -> ( function )
Returns the interacting with function, returns nil if no Lua function was set.
Returns:
function : The interact with function.
interact_with ( function func ) -> ( am.item )
Sets the interact with function. This can be used to override the default interaction behaviour. If this function does not specify that it the game object was interacted with, then the default behaviour is executed.
Parameters:
function func : The new interact with functionality.
Returns:
am.item : This
interact_dialogue ( am.game_object interacter , bool by_movement ) -> ( am.code )
Executes dialogue interactions with the object. This can be used during an interact with function callback to start dialogue. This will work with any game object, unless it does not have a dialogue component.
Parameters:
am.game_object interacter : The game object that initiated the interaction.
bool by_movement : Flag that indicates if the interaction started because of movement or because of other reasons, such as mouse input.
Returns:
am.code : Standard interaction results:
did_interact Interaction occured, perform no further actions.
did_not_interact Interaction did not occur, can perform further actions.
do_not_interact Interaction did not occur, but do not perform any further actions.
on ( string event_type , function listener , table content = nil ) -> ( boolean )
Adds an event listener for an event fired on this item. eg: 
 item:on("talkTo", function(event)
     am_log("Character talked to")
 end)
Parameters:
string event_type : The event type or name to trigger on
function listener : The function to call when the event is fired.
table content = nil : An option context for the listener to be called with.
Returns:
boolean : True if the event was added successfully.
off ( string event_type , function listener , table context = nil ) -> ( boolean )
Removes an event listener from this item. eg: 
 function talkToOnce(event)
     am_log("Character talked to once")
     item:off("talkTo", talkToOnce)
 end
 item:on("talkTo", talkToOnce)
Parameters:
string event_type : The event type the listener was listening for.
function listener : The listener function to remove.
table context = nil : The context which the listener was going to be called with, this is only optional if the listener was added with no context.
Returns:
boolean : True if the event listener was successfully removed.
has_event_listener ( string event_type ) -> ( boolean )
Returns true when there is an event listener for the given event_type.
Parameters:
string event_type : The event type to look up.
Returns:
boolean : True if there is any event listener that will be trigged by this event type.
static find ( string game_id ) -> ( am.item )
Looks up an item in the current game engine with the given game id.
Parameters:
string game_id : The game id to look up.
Returns:
am.item : The found item or nil.
attrs ( boolean create_table = false ) -> ( am.data_table )
Returns the items attribute data table. By default if no attribute data table is present nil is returned unless true is passed as the first argument, then a data table is created if one is not present.
Parameters:
boolean create_table = false : Create a data table if one didn't exist.
Returns:
am.data_table : The data table on this character.
attrs ( am.data_table attr_table ) -> ( am.item )
Sets the data table on this item, can be set to nil.
Parameters:
am.data_table attr_table : The data table to set on the item.
Returns:
am.item : This
add_body_type ( string part_type ) -> ( am.item )
Adds a new body type which this item can be equipped to. If the new body type is already on the item it will be ignored.
Parameters:
string part_type : The name of the body part.
Returns:
am.item : This
remove_body_type ( string part_type ) -> ( am.item )
Remove a new body type from this item that it can be equipped to. If the body type is not on the item, this function will be ignored.
Parameters:
string part_type : The name of the body part.
Returns:
am.item : This
has_body_type ( string part_type ) -> ( boolean )
Checks if a new body type is on this item.
Parameters:
string part_type : The name of the body part.
Returns:
boolean : True if the body part type was found on this item.
get_body_types ( ) -> ( table )
Returns the set of all the body part types that this item can be equipped on to.
Returns:
table : A set of all the body part types.