Custom X-Change Life macros you can use in mods

Javascript Macros

X-Change Life uses a customized version of the Twine Harlowe engine. The following custom macros are for modders – these are some macros we have added to Twine Harlowe in order to extend its functionality.

1. `average`

Function: Calculates the average of a series of numbers.
Usage:

(set: $avg to (average: 1, 2, 3, 4, 5))  <!-- $avg will be 3 -->

2. `rnd`

Function: Rounds a number to a specified precision.
Usage:

(set: $rounded to (rnd: 3.14159, 2))  <!-- $rounded will be 3.14 -->

3. `indexof`

Function: Finds the 1-based index of an item in an array. Returns -1 if the item is not found.
Usage:

(set: $index to (indexof: (a: "apple", "banana", "cherry"), "banana"))  <!-- $index will be 2 -->

4. `intersection`

Function: Calculates the intersection of two arrays, returning their common elements.
Usage:

(set: $common to (intersection: (a: "apple", "banana"), (a: "banana", "cherry")))  <!-- $common will be (a: "banana") -->

5. `savegameto`

Function: Saves the game to the specified slot name.
Usage:

(savegameto: "slot1")  <!-- Saves the game to slot "slot1" -->

6. `win`

Function: Checks if the variable $result is “pass”.
Usage:

(set: $result to "pass")
(set: $didWin to (win:))  <!-- $didWin will be true -->

7. `is_fem`

Function: Checks if the character’s gender is female.
Usage:

(set: $character to (dm: "gender", "female"))
(set: $isFemale to (is_fem:))  <!-- $isFemale will be true -->

8. `is_male`

Function: Checks if the character’s gender is male.
Usage:

(set: $character to (dm: "gender", "male"))
(set: $isMale to (is_male:))  <!-- $isMale will be true -->

9. `is_preg`

Function: Checks if the character is pregnant.
Usage:

(set: $character to (dm: "pregnant", "true"))
(set: $isPregnant to (is_preg:))  <!-- $isPregnant will be true -->

10. `knows_preg`

Function: Checks if the character’s pregnancy is known.
Usage:

(set: $character to (dm: "pregnancy known", "true"))
(set: $knowsPregnancy to (knows_preg:))  <!-- $knowsPregnancy will be true -->

11. `is_bim`

Function: Checks if the character has the “bimbo” side effect.
Usage:

(set: $character to (dm: "side effects", (a: "bimbo")))
(set: $isBimbo to (is_bim:))  <!-- $isBimbo will be true -->

12. `is_pp`

Function: Checks if the character has the “people pleaser” side effect.
Usage:

(set: $character to (dm: "side effects", (a: "people pleaser")))
(set: $isPeoplePleaser to (is_pp:))  <!-- $isPeoplePleaser will be true -->

13. `pill`

Function: Checks if the value of $pill_taken matches the provided pill name (case-insensitive).
Usage:

(set: $pill_taken to "Cum-Cure")
(set: $isCumCure to (pill: "cum-cure"))  <!-- $isCumCure will be true -->

14. `clamp`

Function: Clamps a number within a specified range.
Usage:

(set: $clampedValue to (clamp: 15, 10, 20))  <!-- $clampedValue will be 15 -->
(set: $clampedValue to (clamp: 25, 10, 20))  <!-- $clampedValue will be 20 -->

15. `currency`

Function: Formats a number as currency (USD) without cents.
Usage:

(set: $formattedCurrency to (currency: 1234))  <!-- $formattedCurrency will be "$1,234" -->

16. `del`

Function: Deletes the specified variables.
Usage:

(del: "$variable1", "$variable2")  <!-- Deletes $variable1 and $variable2 -->

17. `outfitdb`

Function: Retrieves a list of outfits for a specified character, optionally filtered by outfit IDs.
Usage:

(set: $outfits to (outfitdb: "characterName"))  <!-- Retrieves all outfits for "characterName" -->
(set: $filteredOutfits to (outfitdb: "characterName", (a: "outfit1", "outfit2")))  <!-- Retrieves specific outfits for "characterName" -->

18. `getoutfit`

Function: Retrieves details of a specific outfit by its ID.
Usage:

(set: $outfitDetails to (getoutfit: "characterName category outfitName"))  <!-- Retrieves details of the specified outfit -->

19. `checkdm`

Function: Checks if a datamap contains a specified value based on an operation.
Usage:

(set: $dm to (dm: "key1", "value1", "key2", (a: "value2", "value3")))
(set: $result1 to (checkdm: $dm, "key1", "is", "value1"))  <!-- $result1 will be true -->
(set: $result2 to (checkdm: $dm, "key2", "contains", "value2"))  <!-- $result2 will be true -->

20. `newseed`

Function: Generates a new seed based on the current time.
Usage:

(set: $seed to (newseed:))  <!-- Generates a seed string based on the current time -->

21. `clearstandardvars`

Function: Clears standard variables.
Usage:

(clearstandardvars:)  <!-- Clears standard variables -->

22. `twist`

Function: Generates a random integer between a specified minimum and maximum value (inclusive) using the Mersenne Twister algorithm.
Usage:

(set: $randomNumber to (twist: 1, 10))  <!-- Generates a random number between 1 and 10 using Mersenne Twister algorithm -->

Note: This macro uses the Mersenne Twister algorithm, which provides a higher degree of randomness compared to Harlowe’s native randomness functions.

23. `twirl`

Function: Picks a random value from a list of arguments using the Mersenne Twister algorithm.
Usage:

(set: $randomValue to (twirl: "apple", "banana", "cherry"))  <!-- Picks a random fruit from the list using Mersenne Twister algorithm -->

Note: This macro uses the Mersenne Twister algorithm, which provides a higher degree of randomness compared to Harlowe’s native randomness functions.

24. `twisted`

Function: Shuffles an array using the Fisher-Yates algorithm with the Mersenne Twister algorithm for randomness.
Usage:

(set: $shuffledArray to (twisted: (a: "apple", "banana", "cherry")))  <!-- Shuffles the array using Fisher-Yates algorithm with Mersenne Twister algorithm -->

Note: This macro uses the Mersenne Twister algorithm, which provides a higher degree of randomness compared to Harlowe’s native randomness functions.

25. `remove`

Function: Removes a specified number of occurrences of an item from an array.
Usage:

(set: $originalArray to (a: "apple", "banana", "cherry", "apple"))
(set: $modifiedArray to (remove: $originalArray, "apple", 1))  <!-- Removes one occurrence of "apple" -->

Harlowe Macros

There are custom harlowe macros that you can also use. These are slightly different than the ones above since they perform native harlowe functions, opposed to the ones above that do background things in javascript. These are usually utility macros that shorten other functions or allows you to cut out repeated tasks.

🎥 Media & Visuals

`$pic`

Parameters:
(str) image_path, (str) position = "left", (str) css_class = "small"

Function:
Displays an image from the img/ folder. Optional parameters adjust position and CSS class. "small" sets width to 50%.

Usage Examples:

($pic:"places/gym/locker room.jpg") ($pic:"places/gym/locker room.jpg","left") ($pic:"places/gym/locker room.jpg","right","small")

`$vid`

Parameters:
(str) video_path, (str) position = "left"

Function:
Embeds an autoplaying, looping video with mute behavior determined by $audio_toggle. Optional "left" or "right" positions it using top_left_pic or top_right_pic.

Usage Examples:

($vid:"scenes/characters/jade/sex/workout/02 get towel.mp4") ($vid:"scenes/characters/jade/sex/workout/02 get towel.mp4","left")