Difference between revisions of "General Functions"

From ADRIFT 5 Manual Wiki
Jump to: navigation, search
(Deleted some dots from item function examples that should not have been there)
(Moved %ListExits% from "General Item Functions" as it has different functionality to the item function.)
Line 85: Line 85:
 
  %LCase[string]%  
 
  %LCase[string]%  
 
'''Parameters'''
 
'''Parameters'''
* ''string'' - The text string you wish to convert to lower case.  
+
* ''string'' - The text string you wish to convert to lower case.
  
 +
== ListExits Function ==
 +
Lists all the exits currently available to a particular [[Characters|character]].
 +
 +
This function checks the restrictions of each of the exits from the character's current location and only lists those which are currently available for them to use.
 +
 +
'''Syntax'''
 +
%ListExits[key]%
 +
'''Parameters'''
 +
* ''key'' - The [[key]] of the character you wish to list the exits for.
 +
'''Use the following item function to list ALL of the exits, including those blocked by restrictions'''
 +
<font color="red">Key</font>.<font color="darkred">Location.Exits.List</font>
  
 
== ListObjectsIn Function ==
 
== ListObjectsIn Function ==

Revision as of 04:08, 16 March 2017

There are quite a few general functions that can be added to any text within ADRIFT 5. These functions must always be within percent (%) symbols. Any arguments must be provided in square brackets. If multiple arguments are required, these should be separated by comma's.

It is also possible to create your own general functions, which are called User functions.

If you create a user function with the same name as one of the general functions, then your function overrides it. This allows you to easily customise some of the messages generated by the standard library, and would also be useful for language translations.

The general functions which were previously used to access item properties now have equivalent Item functions which are easier to use and offer extra functionality. These functions can be found on the General item functions page: CharacterDescriptor, CharacterProper, DisplayCharacter, DisplayLocation, DisplayObject, ListCharactersIn, ListCharactersOn, ListCharactersOnAndIn, ListHeld, ListExits, ListObjectsAtLocation, ListWorn, LocationName, LocationOf, ParentOf, TheObject.


AloneWithChar Function

Returns the key of the character in the same location as the player.

Always use the restriction "The player character must be alone with any character" to check if this function will return a valid result, before using the result of this function in any equation.

This function can be used as the %character% parameter for an Execute-Task action. The executed task will then be applied to the character that is currently in the same location as the player.

Syntax

%AloneWithChar% 

Parameters

  • none


CharacterName Function

If the character is known to the Player (i.e. the Known property of the character is selected) or the Known property does not exist in your game, then this function will return the Proper name of the character.

If the Known property exists in your game but is not set for the character in question, this function will return the Descriptor of the character.

In any one turn, if the CharacterName function is used more than once for a particular character, it will be substituted with a pronoun. The default pronoun type to be substituted with is the subjective pronoun, however, this can be altered by providing an additional parameter to the function.

For further details of this function, see Character Name substitution.

Syntax

%CharacterName%
%CharacterName[key]%
%CharacterName[key, pronoun_type]% 

Parameters

  • key - The key of the character you wish to display the name of. If this parameter is omitted then the function applies to the Player character, except in a description or property of a character, in which case it will apply to that character.
  • pronoun_type - Specifies the type of pronoun the character name should be substituted with. If this parameter is omitted, the pronoun is assumed to be subjective. Possible values for this parameter are subject(ive) (I, you, he, she, it), object(ive)/target (me, you, him, her, it) and possessive (my, your, his, her, its).

Reflective pronouns (myself, yourself, himself, herself, itself) will automatically be substituted if the target of a sentence is also the subject (e.g. "I (subject) throw the ball at me (target)" will become "I (subject) throw the ball at myself (reflective)".

The relevant pronoun will also be selected depending whether the character in question is male, female or unknown, and whether the game is being played in first-person (I, me, my, myself), second-person (you, your, yourself, you) or third-person perspective (him/her/it, his/her/its, himself/herself/itself, he/she/it).

To prevent pronoun substitution from occurring, use the ProperName or CharacterDescriptor functions.

Equivalent item function (except keyless version)

Key.Name(pronoun_type)


ConvCharacter Function

Returns the key of the character the player is currently in conversation with.

Always use the restriction "The player character must be in conversation with any character" to check if this function will return a valid result, before using the result of this function in any equation.

This function can be used as the %character% parameter for an Execute-Task action. The executed task will then be applied to the character that the player is currently in conversation with.

Syntax

%ConvCharacter% 

Parameters

  • none


LCase Function

Returns a string that has been converted to lower case.

Syntax

%LCase[string]% 

Parameters

  • string - The text string you wish to convert to lower case.

ListExits Function

Lists all the exits currently available to a particular character.

This function checks the restrictions of each of the exits from the character's current location and only lists those which are currently available for them to use.

Syntax

%ListExits[key]% 

Parameters

  • key - The key of the character you wish to list the exits for.

Use the following item function to list ALL of the exits, including those blocked by restrictions

Key.Location.Exits.List

ListObjectsIn Function

Lists all the objects inside of a particular container object.

Syntax

%ListObjectsIn[key]% 

Parameters

  • key - The key of the object you wish to list the objects that are in.

This function is the equivalent of the following text using two item functions:

Inside Key.Name is Key.Contents(Objects).List


ListObjectsOn Function

Lists all the objects on the surface of a particular object.

Syntax

%ListObjectsOn[key]% 

Parameters

  • key - The key of the object you wish to list the objects that are on.

This function is the equivalent of the following text using two item functions:

On Key.Name is Key.Children(Objects, On).List


ListObjectsOnAndIn Function

Lists all the objects on and inside a particular object. This is basically the same as ListObjectsOn and ListObjectsIn, but it gives the response in a nicer syntax when there are objects both on and in the object.

A plastic cup is on the cabinet, and inside is a gold coin

Syntax

%ListObjectsOnAndIn[key]% 

Parameters

  • key - The key of the object you wish to list the objects that are on and in.

See also the similar item function %object%.Children(Objects).List.

NumberAsText Function

Returns a number written out as text.

Syntax

%NumberAsText[number]% 

Parameters

  • number - Any non-negative integer value


PCase Function

Returns a string that has been converted to proper case (i.e. the first letter will be capitalised, and all other letters will be converted to lower case).

Syntax

%PCase[string]% 

Parameters

  • string - The text string you wish to convert to proper case.


Player Function

This function returns the key of the player character. This will normally always be known at design time, but if you switch characters during the game, it may be necessary.

Syntax

%Player% 

Parameters

  • none


PopUpChoice

Causes an input box to popup on the screen, displaying a short message prompt and two choices. The player chooses one of the two options and this becomes the value returned by the function. This is used in the expression field of a set variable action to allow the player to choose which of two text strings is written to the variable.

See [| Ask player to enter their gender when the game starts] for an example.

  • Do NOT use directly in a restriction. If you need to do this then call PopupChoice in an action which stores result in a variable and then execute a system task (with another action) which checks the variable with a restriction.

Syntax

%PopUpChoice[prompt, choice1, choice2]% 

Parameters

  • prompt - An expression (typically a quoted string) to display as a message in the inputbox.
  • choice1 - An expression returned in the function if the user selects this option.
  • choice2 - An expression returned in the function if the user selects this option.


PopUpInput

Causes an input box to popup on the screen, displaying a short message prompt and a single-line text entry field. The player can accept the default text or enter a new line of text, then press OK. This could be used to allow the player to enter their own name, which is then used in the game. If the player presses cancel then this function will return a zero-length string. This function should be used in the expression field of either a "Variables" action or a "Set Properties" action.

  • Do NOT use directly in a restriction. If you need to do this then call PopUpInput in an action which stores the result in a variable, and then execute a system task (with another action) which checks the variable with a restriction.

Syntax

%PopUpInput[prompt, default]%

Parameters

  • prompt - An expression (typically a quoted string) to display as a message in the inputbox.
  • default - Optional. An expression (typically a quoted string) to display in the text field of the inputbox.


Example

To ask the player for their name at the start of the game we would create a system task set to run "Immediately", and add the following action to use the PopupInput function to ask them to enter it, then write the name they entered to the "Name" property of the player character.

ActionEnterYourName.jpg


PropertyValue Function

OBSOLETE

Returns the current value of a property of an object, Location or character.

The item functions should be used instead of this function as they are much shorter, have a popup menu to select properties so you dont need to remember the keys, and offer extra functionality.

Syntax

%PropertyValue[key, propertykey]% 

Parameters

  • key - The key of the location, object or character you wish to obtain the property value of.
  • propertykey - The key of the property you wish to obtain the value of.

Equivalent item function

Key.PropertyKey


Rand Function

The Rand function returns a random value between two integers.

Syntax

RAND(value1, value2)

Parameters

  • value1 - The lowest possible value you wish the function to return.
  • value2 - The highest possible value you wish the function to return.


UCase Function

Returns a string that has been converted to upper case

Syntax

%UCase[string]% 

Parameters

  • string - The text string you wish to convert to upper case.


<<< Boolean functionsMain PageGeneral item functions >>>