Properties

From Adventure Game Studio | Wiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

The Properties module by monkey_05_06 provides methods for the user to create, edit, and delete custom properties via the script at run-time.

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 Enumerated Values and 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.

eProperties_StringDefault

This value is for autocomplete purposes only. To set this value, see the macro by the same name below.

See Also: 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: 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: eProperties_MaxProperties

Macros (#define-s)

eProperties_StringDefault

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: 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=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: Properties.CreateText, Properties.Delete

Properties.CreateText

static int Properties::CreateText(String property, optional String defaultValue=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: Properties.Create, 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: Properties.Create, Properties.CreateText

Properties.Exists

static bool Properties::Exists(String property)

Returns whether PROPERTY exists.

See Also: Properties.IsTextProperty

Properties.GetDefaultValue

static int Properties::GetDefaultValue(String property)

Returns the default value of PROPERTY. If the property does not exist this returns eProperties_IntDefault. Note that this property obeys 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 eProperties_StringDefault. Note that this property obeys 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 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 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

GetCustomProperty

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: GetCustomTextProperty, SetCustomProperty

GetCustomTextProperty

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: GetCustomProperty, SetCustomTextProperty

SetCustomProperty

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: GetCustomProperty, SetCustomTextProperty

SetCustomTextProperty

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 PROPERTIES_DEFAULTINTERACTION macro is defined. See Macros (#define-s) for more information.

GetDefaultInteraction

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: SetDefaultInteraction, GetDefaultInteractionAtScreenXY

SetDefaultInteraction

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: GetDefaultInteraction, 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.




Retrieved from ‘https://www.adventuregamestudio.co.uk/w/index.php?title=Properties&oldid=9829’