Adventure Game Studio

Properties: Difference between revisions

Page Discussion

Properties (view source)

Revision as of 23:44, 6 October 2008

15,161 bytes added ,  6 October 2008
no edit summary
VisualWikitext
*>SSH
mNo edit summary
 
*>Monkey 05 06
No edit summary
Line 1: Line 1:
{{Thread|27385|Properties}} by [[monkey_05_06]]. Create/edit/delete custom properties for all kinds of items, at run-time.
The {{thread|27385|Properties}} module by [[monkey_05_06]] provides methods for the user to create, edit, and delete custom properties via the script at run-time.
 
[http://monkey.05.06.googlepages.com/Properties_312.rar Download]
 
==Dependencies==
Adventure Game Studio Editor v3.1.0 or higher.
 
==Setup==
This module is ready-to-use right out of the "box" however there are some settings you may wish to customize to better fit your needs. For these, see below under {{link||Enumerated Values}} and {{link||Macros (#define-s)}}.
 
==Enumerated Values==
===Properties_Settings===
=====eProperties_IntDefault=====
Defines the default value to use for integers if the property is not defined or if no default value is given for the property.
 
<span id = "eProperties_StringDefault_1">
=====eProperties_StringDefault=====
</span>
This value is for autocomplete purposes '''only'''. To ''set'' this value, see the macro by the same name below.
 
''See Also'': {{link||eProperties_StringDefault_2|eProperties_StringDefault (macro)}}
 
=====eProperties_ObeyPropertyType=====
This setting controls whether the module will obey the type of properties (number or text) when getting and setting the value. It should only be set to TRUE or FALSE.
 
=====eProperties_MaxProperties=====
This defines the maximum number of properties you can define. Attempting to define more than this won't crash your game, but it won't work either until you delete some properties. You can lower this value if you need to save memory.
 
'''NOTE:''' If MaxProperties * MaxRooms is greater than 1000000 (one million) it WILL crash your game. The defaults for both are 1000.
 
''See Also'': {{link||eProperties_MaxRooms}}
 
=====eProperties_MaxRooms=====
This sets the maximum number of rooms the module will support. You can raise or lower this to fit your specific needs, but it '''cannot''' exceed 1000 since that is the highest number of rooms AGS supports. This setting should be set to one higher than the highest numbered room you have (so if you have 1 room named "room1.crm" this setting should be set to '''2''').
 
'''NOTE:''' If MaxProperties * MaxRooms is greater than 1000000 (one million) it WILL crash your game. The defaults for both are 1000.
 
''See Also'': {{link||eProperties_MaxProperties}}
 
==Macros (#define-s)==
<span id = "eProperties_StringDefault_2">
=====eProperties_StringDefault=====
</span>
This is used to set the default value for Strings if the property does not exist or no default value has been set for the property. This must be a string of text or be null.
 
''See Also'': {{link||eProperties_StringDefault_1|eProperties_StringDefault (enum)}}
 
=====PROPERTIES_VERSION=====
This defines the current version of the module. As of v3.1 you can use this macro as a float within your scripts.
 
=====PROPERTIES_VERSION_312=====
This defines that at least v3.12 of the module has been imported.
 
=====PROPERTIES_DEFAULTINTERACTION=====
If this macro is defined (you can comment it to exclude it) then an extra set of functions are included for default interactions. The property "DefaultInteraction" will be defined and wrapper functions will be created to simplify working with these functions.
 
==Functions and Properties==
===Property management functions===
=====Properties.Create=====
''static int Properties::Create(String property, optional int defaultValue={{link||eProperties_IntDefault}})''
 
Creates a new number property named PROPERTY if a similarly named property does not already exist. If the property was created you can also set the default value to DEFAULTVALUE. This function returns -1 if the property was not created.
 
''See Also'': {{link||Properties.CreateText}}, {{link||Properties.Delete}}
 
=====Properties.CreateText=====
''static int Properties::CreateText(String property, optional String defaultValue={{link||eProperties_StringDefault_2|eProperties_StringDefault}})''
 
Creates a new text property named PROPERTY if a similarly named property does not already exist. If the property was created you can also set the default value to DEFAULTVALUE. This function returns -1 if the property was not created.
 
''See Also'': {{link||Properties.Create}}, {{link||Properties.Delete}}
 
=====Properties.Delete=====
''static void Properties::Delete(String property)''
 
Deletes PROPERTY if it exists. This can be either a number or a text property.
 
''See Also'': {{link||Properties.Create}}, {{link||Properties.CreateText}}
 
=====Properties.Exists=====
''static bool Properties::Exists(String property)''
 
Returns whether PROPERTY exists.
 
''See Also'': {{link||Properties.IsTextProperty}}
 
=====Properties.GetDefaultValue=====
''static int Properties::GetDefaultValue(String property)''
 
Returns the default value of PROPERTY. If the property does not exist this returns {{link||eProperties_IntDefault}}. Note that this property obeys {{link||eProperties_ObeyPropertyType}}, which if true means this function will only return the value of number property default values.
 
=====Properties.GetDefaultTextValue=====
''static String Properties::GetDefaultTextValue(String property)''
 
Returns the default value of PROPERTY. If the property does not exist this returns {{link||eProperties_StringDefault_2|eProperties_StringDefault}}. Note that this property obeys {{link||eProperties_ObeyPropertyType}}, which if true means this function will only return the value of text property default values.
 
=====Properties.GetCount=====
''static int Properties::GetCount()''
 
Returns the number of currently created properties.
 
=====Properties.IsTextProperty=====
''static bool Properties::IsTextProperty(String property)''
 
Returns whether PROPERTY is a text property (TRUE) or a number property (FALSE). If the property does not exist this returns FALSE.
 
=====Properties.SetDefaultValue=====
''static void Properties::SetDefaultValue(String property, int value)''
 
Sets the default value of PROPERTY to VALUE. This obeys {{link||eProperties_ObeyPropertyType}} so it will only work on number properties and only if the property actually exists.
 
=====Properties.SetDefaultTextValue=====
''static void Properties::SetDefaultTextValue(String property, String value)''
 
Sets the default value of PROPERTY to VALUE. This obeys {{link||eProperties_ObeyPropertyType}} so it will only work on text properties and only if the property actually exists.
 
=====Properties.SetPropertyType=====
''static void Properties::SetPropertyType(String property, bool isText)''
 
Sets whether PROPERTY is a text property (TRUE) or a number property (FALSE). You should not normally need this function.
 
===Item properties===
<span id = "Character.GetCustomProperty"><span id = "Hotspot.GetCustomProperty"><span id = "InventoryItem.GetCustomProperty"><span id = "Object.GetCustomProperty"><span id = "RoomGetCustomProperty">
=====GetCustomProperty=====
</span></span></span></span></span>
''int Character.GetCustomProperty(String property)''
 
''int Hotspot.GetCustomProperty(String property, optional int roomID)''
 
''int InventoryItem.GetCustomProperty(String property)''
 
''int Object.GetCustomProperty(String property, optional int roomID)''
 
''int RoomGetCustomProperty(String property, optional int roomID)''
 
These five functions are used to retrieve the value of the number property for the respective Character, Hotspot, InventoryItem, Object, or Room that they correspond to. The Hotspot, Object, and Room functions all have optional ROOMID properties which can be used to specify a room other than the current one.
 
'''NOTE''': The Hotspot and Object functions operate on the item's ID. So even if you're using a specific instance in a specific room, if you pass a different room number for ROOMID it will access the hotspot/object with the same ID in that room.
 
'''NOTE''': The Room function is not an extender method of the Room struct. You DO NOT use a dot to use this function.
 
''See Also'': {{link||GetCustomTextProperty}}, {{link||SetCustomProperty}}
 
<span id = "Character.GetCustomTextProperty"><span id = "Hotspot.GetCustomTextProperty"><span id = "InventoryItem.GetCustomTextProperty"><span id = "Object.GetCustomTextProperty"><span id = "RoomGetCustomTextProperty">
=====GetCustomTextProperty=====
</span></span></span></span></span>
''String Character.GetCustomTextProperty(String property)''
 
''String Hotspot.GetCustomTextProperty(String property, optional int roomID)''
 
''String InventoryItem.GetCustomTextProperty(String property)''
 
''String Object.GetCustomTextProperty(String property, optional int roomID)''
 
''String RoomGetCustomTextProperty(String property, optional int roomID)''
 
These five functions are used to retrieve the value of the text property for the respective Character, Hotspot, InventoryItem, Object, or Room that they correspond to. The Hotspot, Object, and Room functions all have optional ROOMID properties which can be used to specify a room other than the current one.
 
'''NOTE''': Hotspot and Object functions operate on the item's ID, not a specific instance.
 
'''NOTE''': The Room function DOES NOT use a dot to operate.
 
''See Also'': {{link||GetCustomProperty}}, {{link||SetCustomTextProperty}}
 
<span id = "Character.SetCustomProperty"><span id = "Hotspot.SetCustomProperty"><span id = "InventoryItem.SetCustomProperty"><span id = "Object.SetCustomProperty"><span id = "RoomSetCustomProperty">
=====SetCustomProperty=====
</span></span></span></span></span>
''void Character.SetCustomProperty(String property, int value)''
 
''void Hotspot.SetCustomProperty(String property, int value, optional int roomID)''
 
''void InventoryItem.SetCustomProperty(String property, int value)''
 
''void Object.SetCustomProperty(String property, int value, optional int roomID)''
 
''void RoomSetCustomProperty(String property, int value, optional int roomID)''
 
These five functions are used to set the value of the number property for the respective Character, Hotspot, InventoryItem, Object, or Room that they correspond to. The Hotspot, Object, and Room functions all have optional ROOMID properties which can be used to specify a room other than the current one.
 
'''NOTE''': Hotspot and Object functions operate on the item's ID, not a specific instance.
 
'''NOTE''': The Room function DOES NOT use a dot to operate.
 
''See Also'': {{link||GetCustomProperty}}, {{link||SetCustomTextProperty}}
 
<span id = "Character.SetCustomTextProperty"><span id = "Hotspot.SetCustomTextProperty"><span id = "InventoryItem.SetCustomTextProperty"><span id = "Object.GetSustomTextProperty"><span id = "RoomSetCustomTextProperty">
=====SetCustomTextProperty=====
</span></span></span></span></span>
''void Character.SetCustomTextProperty(String property, String value)''
 
''void Hotspot.SetCustomTextProperty(String property, String value, optional int roomID)''
 
''void InventoryItem.SetCustomTextProperty(String property, String value)''
 
''void Object.SetCustomTextProperty(String property, String value, optional int roomID)''
 
''void RoomSetCustomTextProperty(String property, String value, optional int roomID)''
 
These five functions are used to set the value of the text property for the respective Character, Hotspot, InventoryItem, Object, or Room that they correspond to. The Hotspot, Object, and Room functions all have optional ROOMID properties which can be used to specify a room other than the current one.
 
'''NOTE''': Hotspot and Object functions operate on the item's ID, not a specific instance.
 
'''NOTE''': The Room function DOES NOT use a dot to operate.
 
===Default interaction functions===
The following functions are only implemented if the {{link||PROPERTIES_DEFAULTINTERACTION}} macro is defined. See {{link||Macros (#define-s)}} for more information.
 
<span id = "Character.GetDefaultInteraction"><span id = "Hotspot.GetDefaultInteraction"><span id = "InventoryItem.GetDefaultInteraction"><span id = "Object.GetDefaultInteraction">
=====GetDefaultInteraction=====
</span></span></span></span>
''CursorMode Character.GetDefaultInteraction()''
 
''CursorMode Hotspot.GetDefaultInteraction()''
 
''CursorMode InventoryItem.GetDefaultInteraction()''
 
''CursorMode Object.GetDefaultInteraction()''
 
These four functions all return the value of the property DefaultInteraction for the specified item.
 
'''NOTE''': There is no Room function specified here. You cannot directly interact with a Room so it wouldn't make sense for there to be a default.
 
''See Also'': {{link||SetDefaultInteraction}}, {{link||GetDefaultInteractionAtScreenXY}}
 
<span id = "Character.SetDefaultInteraction"><span id = "Hotspot.SetDefaultInteraction"><span id = "InventoryItem.SetDefaultInteraction"><span id = "Object.SetDefaultInteraction">
=====SetDefaultInteraction=====
</span></span></span></span>
''void Character.SetDefaultInteraction(CursorMode)''
 
''void Hotspot.SetDefaultInteraction(CursorMode)''
 
''void InventoryItem.SetDefaultInteraction(CursorMode)''
 
''void Object.SetDefaultInteraction(CursorMode)''
 
These four functions all set the value of the property DefaultInteraction for the specified item.
 
'''NOTE''': There is no Room function specified here. You cannot directly interact with a Room so it wouldn't make sense for there to be a default.
 
''See Also'': {{link||GetDefaultInteraction}}, {{link||GetDefaultInteractionAtScreenXY}}
 
=====GetDefaultInteractionAtScreenXY=====
''CursorMode GetDefaultInteractionAtScreenXY(int x, int y)''
 
Returns the value of the property DefaultInteraction for whatever is shown on the screen at the specified (X, Y) co-ordinates. This can be a Character, Hotspot, InventoryItem, or an Object.
 
==Licensing==
 
This AGS Script Module is hereby released to public domain with restriction as follows: the module may be modified and released in any fashion such that modifications do not nullify this license, and any subsequent versions of this module must be released using the same license, and may not be relicensed. This module is released without any warranty of any kind implicit or otherwise, and by using this module you agree to waive liability of the author of any subsequent consequence of using this module. The original author reserves the right at any time to void and revoke this license in favor of another license only provided the subsequently chosen license submits this module to public domain in some fashion. Furthermore, lol. That is all.
 
==Changelog==
===Version 3.12===
  Version:    3.12
  Author:      monkey_05_06
  Date:        06 October 2008
  Description: Improved handling of room functions:
    Fixed crash if you didn't specify a room and the
    player was in a room unsupported by the module.
    Also implemented DefaultInteraction functions.
    Updated documentation to correct required AGS
    version which is 3.1.0+ and not 3.0.2+.
 
===Version 3.11===
  Version:    3.11
  Author:      monkey_05_06
  Date:        05 October 2008
  Description: Fixes crash using InventoryItem
    functions due to InventoryItems being indexed
    from one instead of zero like most other items.
 
===Version 3.1===
  Version:    3.1
  Author:      monkey_05_06
  Date:        30 September 2008
  Description: Fixes crash due to limit on number of
    properties. Implements static limits to increase
    functionality and speed. Provided method to
    enforce/ignore property type.


{{Module|Misc}}
{{Module|Misc}}
Anonymous user
Retrieved from ‘https://www.adventuregamestudio.co.uk/wiki/Special:MobileDiff/7121’