GDF3 File and Data Specifications for GCA4
Root FileSpec Page

Functions

Functions are feature of the math engine that provide you access to sometimes complex features, in a simple fashion. All functions start with the @ sign to tell GCA that it's a function.

@fac - Factorial of a number.
@fix - Integer part of a number.
@hasmod - The level of the modifier specified, if 'owned' by the current item.
@if - Select one of two options depending on the value of an expression.
@indexedvalue - Select a list item according to the value of an index number.
@int - First integer less than or equal to a number.
@log - Log base 10 of a number.
@max - Select the highest value in a list of numbers.
@min - Select the lowest value in a list of numbers.
@nlog - Natural log of a number.
@power - Raise x to the y^th power.
@sqr - Square root of a number.

Not yet done:

@itemhasmod - The level of the modifier specified, if the item specified has the modifier applied.
@ownerhasmod - The level of the modifier specified, if the owning item has the modifier applied.
@sametext - Does a simple string comparison of two text items, and returns 1 if both are the same (ignores case).
@textindexedvalue - Select a list item according to a comparison of text items.
@baseswdice - The number of dice of swing damage the given value would do if it was a ST score.
@basethdice - The number of dice of thrust damage the given value would do if it was a ST score.

Templates

The documentation below uses templates to demonstrate the structure of the various functions. The templates are meant to provide a quick way to see how the functions are formatted. Trying to do this, however, is not always easy, and we have made some formatting decisions that may take some getting used to. So here's an explanation of how things work.

All items in the template are printed using a monospaced font.
The item being templated, and the parens marking the beginning and end of its parameter section , are all bold.
Optional items or blocks are enclosed in square [] brackets. The square brackets are not a part of the function, and are only used here as a visual aid.
Where one item out of several options must be selected, the choices are enclosed in curly {} braces, separated by | signs. The curly {} braces and | signs are not considered part of the function, and the structure they represent is used only as a visual aid. Remember that only one of the listed options should be used in place of the whole structure when actually writing out the function.
Items that are placeholders for text or values that you should include at that position are in italics. You should include only the text or value that is necessary, not the placeholder, when creating the function.

	@fac
Description:	This function returns the factorial of a given number.
Template:	`@fac( number )`
Detail:	A factorial is the product of all positive integers less than or equal to `number`. The function returns `1` for any number less than two.
Examples:
Example:	`@fac(5)` This example will return a value of 120 (54321 = 120).

	@fix
Description:	This function returns the integer part of a number.
Template:	`@fix( number )`
Detail:	The `@fix` function removes the fractional part of `number` and returns the resulting integer value.
Examples:
Examples:	`@fix(8.45)` // returns 8 `@fix(-8.45)` // returns -8 Negative numbers are effectively rounded up (-8 is greater than -8.45). If you always want to round down, use @int.

	@hasmod
Description:	This function returns the level of the modifier specified, if 'owned' by the current item.
Template:	`@hasmod( modifier name )`
Detail:	If the modifier name modifier has been applied to the trait being evaluated, then the level of that modifier will be returned. Otherwise, 0 will be returned.
Examples:
Example:	`@hasmod(XXXXXXXX)` This example will return the level of XXXXXXXXXX, or 0 if it does not exist.

	@if
Description:	This function evaluates an expression and returns one of two possible results depending on the value of the expression.
Template:	`@if( expression THEN result [ELSE altresult] )`
Detail:	The `expression` placeholder is an expression, such as `IQ > 10`, a bit of math, or whatever. The `result` and `altresult` placeholders are values or math that results in a value. If `expression` is any non-zero result, including a true evaluation (such as `3>2`), then `result` is used as the result of the function, otherwise `altresult` is used as the result of the function. If there is no `ELSE` part, then 0 would be returned for any false, or zero, result of `expression`.
Examples:
Example 1:	`upto( @if(ST:IQ > 10 then 10 else 5) )` In this case, if the character's IQ is more than 10, upto() would be 10, otherwise it would be 5. Watch those parens to make sure they match!
Example 2:	`gives( @if(ST:IQ < 11 then 0 else @if(ST:IQ < 13 then +1 else +2 )) )` This example gives 0 to an item if IQ is less than 10, +1 if IQ is 11 or 12, and +2 if IQ is 13 or greater. Be very cautious when you nest one @if function within another. It can be very easy to loose track of the parens, and thereby crash GCA when loading your data file because of unmatched pairs.

	@indexedvalue
Description:	This function uses an index number to select a value from a list.
Template:	`@indexedvalue( index, return1, return2 [, ..., returnN ] )`
Detail:	This function uses the value of `index` to select a corresponding return value from a list. For instance, if the value of `index` is `2`, then `return2` will be selected. If the value of `index` is greater than the number of items in the list, the last item in the list will be selected. `index` must be a number or numeric expression greater than zero. The `returnX` items can be any appropriate number or numeric expression.
Examples:
Example:	`Appearance, 5/15/25, gives( =@indexedvalue(%level, +1, +4, +6) to GR:Reaction )` The system variable `%level` will frequently be used as the value of `index`. In this example, the Appearance advantage gives +1 to reaction rolls at level 1, +4 at level 2, and +6 at level 3.

	@int
Description:	This function returns the first integer less than or equal to a number.
Template:	`@int( number )`
Detail:	The `@int` function always rounds down to the nearest whole number.
Examples:
Examples:	`@fix(8.45)` // returns 8 `@fix(-8.45)` // returns -9 This function always rounds down (-9 is less than -8.45). If you just want to remove the fractional part of a number, use @fix.

	@log
Description:	This function returns the base 10 log of a number.
Template:	`@log( number )`
Detail:	`number` must be a number or numeric expression greater than zero. When a number is expressed as a power of 10 (`10^x`), the exponent `x` is the base 10 log of the number.
Examples:
Examples:	`@log(1000)` //returns 3 (1000 = 10³) `@log(500)` // returns 2.6989 (500 = 10^2.6989) `@log(0.001)` // returns -3 (0.001 = 10^-3)

	@max
Description:	This function returns the highest value from a list of values.
Template:	`@max( value1, value2 [, ..., valueN ] )`
Detail:	The list of values can contain any number of items. A value can be either a number or a numeric expression. When the function is part of a Skill definition, list items can include references to the `prereq` and `default` values of the skill. Also see the related function @min, which works just like `@max` except that it returns the lowest value in the list rather than the highest.
Examples:
Example 1:	`upto(@max(12, prereq-2, default-5))` This example defines an upto() tag in a skill. GCA evaluates the expressions in the list, then selects the highest value among the three items. For example, if `prereq` and `default` are both 15, then `prereq-2 = 13` and `default-5 = 10`. The final list of values would be (12, 13, 10), and the value returned by `@max` would be 13.
Example 2:	`gives(=@max(0,ST:ST-13) to SK:Blacksmith)` This example gives a bonus to the Blacksmith skill if ST is greater than 13, but doesn't subtract anything from the skill if ST-13 is a negative number.

	@min
Description:	This function returns the lowest value from a list of values.
Template:	`@min( value1, value2 [, ..., valueN ] )`
Detail:	This function works exactly like @max except that it returns the lowest value in the list rather than the highest.
Examples:
Example:	`upto( @min(16, @max(12, prereq-2, default-5)) )` This example uses `@min` to put an upper limit on the first example given above in @max. The combined expression can never be less than 12 or greater than 16.

	@nlog
Description:	This function returns the natural log of a number.
Template:	`@nlog( number )`
Detail:	`number` must be a number or numeric expression greater than zero. The `@nlog` function can be used to compute a log in any base. Use the formula: `@nlog(number)/@nlog(base)`, as demonstrated in the following examples.
Examples:
Examples:	`@nlog(1000)/@nlog(10)` //returns 3 (1000 = 10³) `@nlog(25)/@nlog(5)` // returns 2 (25 = 5²) Since GCA expressions don't use double precision arithmetic, small rounding errors are to be expected. For example, `@nlog(125)/@nlog(5)` returns `3.001` rather than `3`.

	@power
Description:	This function returns a number raised to a given power.
Template:	`@power( number, exponent )`
Detail:	`number` must be a number or numeric expression greater than zero.
Examples:
Example:	`@power(10,2)` //returns 100 (100 = 10²) `@power(5,3)` // returns 125 (125 = 5³) `@power(2,-2)` //returns 0.25 (0.25 = 2^-2 = 1/2²)

	@sqr
Description:	This function returns the square root of a number.
Template:	`@sqr( number )`
Detail:	`number` must be a number or numeric expression greater than zero.
Examples:
Example:	`@sqr(9)` //returns 3

Functions

Contents

Templates

@fac

@fix

@hasmod

@if

@indexedvalue

@int

@log

@max

@min

@nlog

@power

@sqr