More tweaks to the scripting guide

Author: richardwilkes

Library/Markdown/Help/Interface/Overview.md

@@ -66,7 +66,7 @@ Any panel with a question mark icon ( ![](./img/q.png "Help") ) will open Help r
    21. [Container](./Container.md)
    22. [Toggle State](./Toggle%20State.md)
 7. [Markdown Guide](../Markdown%20Guide.md)
-8. [Scripting](../Scripting.md)
+8. [Scripting Guide](../Scripting%20Guide.md)
 9. [Expression Function Reference](../Expression%20Functions.md)
 10. [Expression Operators Reference](../Expression%20Operators.md)
 

Library/Markdown/Help/Scripting.md Library/Markdown/Help/Scripting Guide.mdLibrary/Markdown/Help/Scripting.md renamed to Library/Markdown/Help/Scripting Guide.md

@@ -1,31 +1,28 @@
-# Scripting
+# Scripting Guide
 
 > Available in GCS 5.36.0 and later.
 
 Some fields, such as notes, support using Javascript to resolve their content. Versions of GCS prior to v5.36.0 used a
 simple expression evaluator instead. Expressions from those old data files will be automatically transformed into the
 equivalent Javascript.
 
-For fields that aren't exclusively a script, such as note fields, you must embed your scripts by wrapping them in script
-tags, like this:
+Fields that are intended to resolve to a number and either contain a number or a script. Fields that are intended to
+resolve to text, however, must have the scripting portion(s) wrapped in tags, like this:
 
 ```
-My ST + DX is <script>$st + $dx</script>!
+My ST + DX is <script>$st + $dx</script> and my name is <script>entity.name</script>.
 ```
 
 When your Javascript code is called, the following globals will be available for you to use:
 
 - `console`
 - `dice`
 - `entity`
-- `fixed`
 - `iff`
-- `length`
 - `Math.exp2`
+- `measure`
 - `self`
 - `signedValue`
-- `ssrt`
-- `weight`
 
 In addition, any attributes you've defined for the sheet are available as globals using their ID prefixed with a dollar
 sign, e.g. `$st` refers to the Strength attribute.
@@ -114,6 +111,29 @@ This object holds encumbrance-related data for an entity.
 
 This object represents the current character sheet data.
 
+### Properties for entity
+
+- `exists: boolean`: true if this script is being run on a sheet.
+- `playerName: string`: The player's name.
+- `name: string`: The entity's name.
+- `title: string`: The entity's title.
+- `organization: string`: The entity's organization.
+- `religion: string`: The entity's religion.
+- `techLevel: string`: The entity's tech level.
+- `gender: string`: The entity's gender.
+- `age: string`: The entity's age.
+- `birthday: string`: The entity's birthday.
+- `eyes: string`: The entity's eyes.
+- `hair: string`: The entity's hair.
+- `skin: string`: The entity's skin.
+- `handedness: string`: The entity's handedness.
+- `displayHeightUnits: string`: The height units that should be used for display.
+- `displayWeightUnits: string`: The weight units that should be used for display.
+- `heightInInches: number`: The entity's height, in inches.
+- `weightInPounds: number`: The entity's weight, in pounds,
+- `sizeModifier: number`: The entity's size modifier.
+- `extraDiceFromModifiers: boolean`: true if the Modifying Dice + Adds option from B269 is in use.
+
 ### Methods for entity
 
 - `attribute(idOrName: string): attribute`: Returns the attribute that matches the given ID or name. IDs are checked
@@ -124,8 +144,6 @@ This object represents the current character sheet data.
   modifier is adjusted to account for equipment that has been marked as not having its weight counting against skills.
 - `encumbrance(): encumbrance`: Returns the encumbrance data.
 - `equipment(): Array<equipment>`: Returns the top-level carried equipment with a quantity greater than 0.
-- `exists(): boolean`: Returns true if this script is being run on a sheet.
-- `extraDiceFromModifiers(): boolean`: Returns true if the Modifying Dice + Adds option from B269 is in use.
 - `findEquipment(name: string, tag: string): Array<equipment>`: Returns the carried equipment that match the given
   'name' and has the given 'tag', case-insensitively. When matching, an empty or undefined value passed in will match
   everything. Note that only equipment with a quantity greater than 0 is considered and if all parents of that equipment
@@ -139,13 +157,12 @@ This object represents the current character sheet data.
 - `findTraits(name: string, tag: string): Array<trait>`: Returns the enabled traits that match the given 'name' and have
   the given 'tag', case-insensitively. When matching, an empty or undefined value passed in will match everything.
 - `hasTrait(name: string): boolean`: Returns true if the named trait is present and enabled.
-- `randomHeight(strength: number): number`: Returns a height in inches based on the given 'strength' using the chart
-  from B18.
-- `randomWeight(strength: number, shift: number): number`: Returns a weight in pounds based on the given 'strength'
-  using the chart from B18. Adjusts appropriately for the traits Skinny, Overweight, Fat, and Very Fat, if present on
-  the sheet. 'shift' causes a shift towards a lighter value if negative and a heavier value if positive, similar to
-  having one of the traits Skinny, Overweight, Fat, and Very Fat applied, but is additive to them.
-- `sizeModifier(): number`: Returns the size modifier of the entity.
+- `randomHeightInInches(strength: number): number`: Returns a height in inches based on the given 'strength' using the
+  chart from B18.
+- `randomWeightInPounds(strength: number, shift: number): number`: Returns a weight in pounds based on the given
+  'strength' using the chart from B18. Adjusts appropriately for the traits Skinny, Overweight, Fat, and Very Fat, if
+  present on the sheet. 'shift' causes a shift towards a lighter value if negative and a heavier value if positive,
+  similar to having one of the traits Skinny, Overweight, Fat, and Very Fat applied, but is additive to them.
 - `skills(): Array<skill>`: Returns the top-level enabled skills.
 - `skillLevel(name: string, specialization: string, relative: boolean): number`: Returns the level of the skill with the
   given 'name' and 'specialization'. If 'relative' is true, returns the relative level instead.
@@ -155,7 +172,6 @@ This object represents the current character sheet data.
 - `traits(): Array<trait>`: Returns the top-level enabled traits.
 - `weaponDamage(name: string, usage: string): string`: Returns the weapon damage for the weapon entry that matches the
   given 'name' and 'usage', or an empty string if none is found.
-- `weightUnits(): weightUnit`: Returns the default weight units to use for the entity.
 
 ## equipment
 
@@ -187,122 +203,62 @@ This object holds data for equipment.
 - `value(): number`: The value of one of these items.
 - `weight(): number`: The weight in pounds of one of these items.
 
-## fixed
-
-This object provides a fixed-point numeric data type, which is used for all potentially non-integer calculations within GCS so that various floating-point errors don't occur. It is provided here so that you can do fixed-point calculations where needed.
-
-### Static Properties for fixed
-
-- `maxSafeMultiply: fixed`: The maximum value that can be safely multiplied without overflow.
-- `maxValue: fixed`: The maximum value that a fixed value can hold.
-- `minValue: fixed`: The minimum value that a fixed value can hold.
-- `zero: fixed`: Convenience for the constant 0.
-- `tenth: fixed`: Convenience for the constant 0.1.
-- `eighth: fixed`: Convenience for the constant 0.125.
-- `quarter: fixed`: Convenience for the constant 0.25.
-- `half: fixed`: Convenience for the constant 0.5.
-- `one: fixed`: Convenience for the constant 1.
-- `two: fixed`: Convenience for the constant 2.
-- `three: fixed`: Convenience for the constant 3.
-- `four: fixed`: Convenience for the constant 4.
-- `five: fixed`: Convenience for the constant 5.
-- `ten: fixed`: Convenience for the constant 10.
-- `hundred: fixed`: Convenience for the constant 100.
-- `thousand: fixed`: Convenience for the constant 1000.
-
-### Static Methods for fixed
-
-- `asInteger(value: fixed): number`: Returns the value converted to an integer.
-- `asFloat(value: fixed): number`: Returns the value converted to a float.
-- `fromString(str: string): fixed`: Parses the string and returns the fixed value from it.
-- `fromInteger(value: number): fixed`: Returns the integer value converted to a fixed-point value.
-- `fromFloat(value: number): fixed`: Returns the floating-point value converted to a fixed-point value.
-- `applyRounding(value: fixed, roundDown: boolean): fixed`: Rounds a value in the positive direction if 'roundDown' is
-  false, or in the negative direction if 'roundDown' is true, returning the result.
-
-### Methods for fixed
-
-- `add(value: fixed): fixed`: Returns the result of adding the supplied value to this value.
-- `sub(value: fixed): fixed`: Returns the result of subtracting the supplied value from this value.
-- `mul(value: fixed): fixed`: Returns the result of multiplying the supplied value with this value.
-- `div(value: fixed): fixed`: Returns the result of dividing this value by the supplied value.
-- `mod(value: fixed): fixed`: Returns the remainder after subtracting all full multiples of the provided value from this
-  value.
-- `abs(): fixed`: Returns the absolute value of this value.
-- `trunc(): fixed`: Returns this value with everything to the right of the decimal place truncated.
-- `ceil(): fixed`: Returns the value rounded up to the nearest whole number.
-- `round(): fixed`: Returns the nearest integer, rounding half away from zero.
-- `min(value: fixed) fixed`: Returns the minimum of the provided value or this value.
-- `max(value: fixed) fixed`: Returns the maximum of the provided value or this value.
-- `inc(): fixed`: Returns this value incremented by 1.
-- `dec(): fixed`: Returns this value decremented by 1.
-- `string(): string`: Returns the text representation of this value.
-- `stringWithSign(): string`: Returns the same value as '.string()', but with a leading '+' if the value is positive.
-- `comma(): string`: Returns a text representation of this value with commas separating every third digit before the
-  decimal place.
-- `commaWithSign(): string`: Returns the same value as '.comma()', but with a leading '+' if the value is positive.
-
 ## iff
 
 This is a top-level function.
 
 - `iff(condition: boolean, trueValue: any, falseFalue: any): any`: Returns 'trueValue' if 'condition' is true, otherwise
   returns 'falseFalue'.
 
-## length
-
-This object provides handling of lengths.
-
-### Static Properties for length
-
-- `feetAndInches: lengthUnit`: The feet and inches unit, which dynamically adjusts to one of three displays, depending
-  on the value:
-  1. Showing feet and inches, e.g. 5'9"
-  2. Showing feet, e.g. 5'
-  3. Showing inches, e.g. 3"
-- `inch: lengthUnit`: The inches unit, represented as 'in'.
-- `feet: lengthUnit`: The feet unit, represented as 'ft'.
-- `yard: lengthUnit`: The yards unit, represented as 'yd'.
-- `mile: lengthUnit`: The miles unit, represented as 'mi'.
-- `centimeter: lengthUnit`: The centimeters unit, represented as 'cm'.
-- `meter: lengthUnit`: The meters unit, represented as 'm'.
-- `kilometer: lengthUnit`: The kilometers unit, represented as 'km'.
-
-### Static Methods for length
-
-- `unitsFromString(str: string): lengthUnit`: Returns the length unit whose key matches 'str', or length.feetAndInches
-  if there is no match.
-- `fromString(value: string, defaultUnits: lengthUnit): length`: Returns a new length object by parsing the input
-  string. If no units are present in the string, then 'defaultUnits' is used. If 'defaultUnits' isn't provided, uses
-  length.feetAndInches.
-- `fromInteger(value: number, units: lengthUnit): length`: Returns a new length object. If no 'units' are provided, uses
-  length.feetAndInches.
-- `fromFixed(value: fixed, units: lengthUnit): length`: Returns a new length object. If no 'units' are provided, uses
-  length.feetAndInches.
-- `fromFloat(value: number, units: lengthUnit): length`: Returns a new length object. If no 'units' are provided, uses
-  length.feetAndInches.
-- `asFixedInches(value: length): fixed`: Returns the 'length' as a fixed value of inches.
-
-### Methods for length
-
-- `string(): string`: Returns the length formatted in feet and inches.
-
-## lengthUnit
-
-This object provides conversion of length values to specific units.
-
-### Methods for lengthUnit
-
-- `key(): string`: Returns the key representing this length unit.
-- `format(value: length): string`: Returns a string representation of the 'value' in these units, e.g. '12 yd'.
-- `toInches(value: fixed): fixed`: Returns the 'value' in these units converted to inches.
-
 ## Math.exp2
 
 This is actually just an addition to the standard Javascript Math object.
 
 - `Math.exp2(value: number): number`: Returns 2 raised to the power of the `value`.
 
+## measure
+
+This object provides measurement utilities.
+
+Valid units for lengths are:
+
+- in
+- ft
+- ft_in
+- yd
+- mi
+- cm
+- m
+- km
+
+Valid units for weights are:
+
+- oz
+- lb
+- \#
+- tn
+- t
+- g
+- kg
+
+### Static Methods for measure
+
+- `formatLength(inches: number, toUnits: string): string`: Formats a length (in inches) into a string with the given
+  units.
+- `lengthToInches(value: number, fromUnits: string): number`: Converts a length value of the given units into inches.
+- `stringLengthToInches(str: string, defaultUnits: string): number`: Converts a string containing a length into inches.
+  If no units are found in the string, then 'defaultUnits' will be used to interpret the value.
+- `formatWeight(pounds: number, toUnits: string): string`: Formats a weight (in pounds) into a string with the given
+  units.
+- `weightToPounds(value: number, fromUnits: string): number`: Converts a weight value of the given units into pounds.
+- `stringWeightToPounds(str: string, defaultUnits: string): number`: Converts a string containing a weight into pounds.
+  If no units are found in the string, then 'defaultUnits' will be used to interpret the value.
+- `rangeModifier(yards: number): number`: Converts the given yards into a range modifier.
+- `sizeModifier(yards: number): number`: Converts the given yards into a size modifier.
+- `modifier(length: number, units: string, forSize: boolean): number`: Converts the given length into either a range
+  modifier (if 'forSize' is false) or a size modifier (if 'forSize' is true).
+- `modifierToYards(modifier: number): number`: Converts a range or size modifier into yards.
+
 ## self
 
 This will be set to the object that the script is attached to. Note that in some cases, this will be `undefined`, such
@@ -380,18 +336,6 @@ This object holds data for a spell.
 - `level(): number`: The computed level.
 - `relativeLevel(): number`: The computed level relative to the controlling attribute.
 
-## ssrt
-
-This object provides calculations on the Size and Speed/Range Table from Basic, page 550.
-
-### Static Methods for ssrt
-
-- `modifier(length: number, units: string, forSize: bool): number`: Calculates the number of yards from the given
-  'length' and 'units', then returns the size modifier if 'forSize' is true or the range modifier if it is false.
-- `modifierToYards(ssrtValue: number): number`: Returns the yards for the given 'ssrtValue'.
-- `rangeModifier(yards: number): number`: Returns the range modifier for the given number of 'yards'.
-- `sizeModifier(yards: number): number`: Returns the size modifier for the given number of 'yards'.
-
 ## trait
 
 This object holds data for a trait.
@@ -402,7 +346,7 @@ This object holds data for a trait.
 - `parentID: string`: The parent's object ID.
 - `name: string`: The name.
 - `kind: string`: The kind of container, one of 'group', 'alternative abilities', 'ancestry', 'attributes', or 'meta trait'.
-- `levels: fixed`: The levels, if any.
+- `levels: number`: The levels, if any.
 - `tags: Array<string>`: The associated tags.
 - `container: boolean`: If true, this trait is a container.
 - `hasChildren: boolean`: If true, this trait has children.
@@ -414,49 +358,6 @@ This object holds data for a trait.
   given 'name' and have the given 'tag', case-insensitively. When matching, an empty or undefined value passed in will
   match everything.
 
-## weight
-
-This object provides handling of weights.
-
-### Static Properties for weight
-
-- `pound: weightUnit`: The pounds unit, represented as 'lb'.
-- `poundAlt: weightUnit`: An alternate pounds unit, represented as '#'.
-- `ounce: weightUnit`: The ounces unit, represented as 'oz'.
-- `ton: weightUnit`: The tons unit, represented as 'tn'.
-- `tonAlt: weightUnit`: An alternate tons unit, represented as 't'.
-- `kilogram: weightUnit`: The kilograms unit, represented as 'kg'.
-- `gram: weightUnit`: The grams unit, represented as 'g'.
-
-### Static Methods for weight
-
-- `unitsFromString(str: string): weightUnit`: Returns the weight unit whose key matches 'str', or weight.pound if there
-  is no match.
-- `fromString(value: string, defaultUnits: weightUnit): weight`: Returns a new weight object by parsing the input
-  'value'. If no units are present in the string, then 'defaultUnits' is used. If 'defaultUnits' isn't provided, uses
-  weight.pound.
-- `fromInteger(value: number, units: weightUnit): weight`: Returns a new 'weight' object. If no 'units' are provided,
-  uses weight.pound.
-- `fromFixed(value: fixed, units: weightUnit): weight`: Returns a new 'weight' object. If no 'units' are provided, uses
-  weight.pound.
-- `fromFloat(value: number, units: weightUnit): weight`: Returns a new 'weight' object. If no 'units' are provided, uses
-  weight.pound.
-- `asFixedPounds(value: weight): fixed`: Returns the 'value' as a fixed-point number of pounds.
-
-### Methods for weight
-
-- `string(): string`: Returns the weight formatted as pounds.
-
-## weightUnit
-
-This object provides conversion of weight values to specific units.
-
-### Methods for weightUnit
-
-- `key(): string`: Returns the key representing this weight unit.
-- `format(value: weight): string`: Returns a string representation of the 'value' in the given units, e.g. '12 kg'.
-- `toPounds(value: fixed): fixed`: Returns the 'value' of this unit converted to pounds.
-
 ---
 
 ***Last updated for v5.36.0***