Libraries

There may come a time, and hopefully quite soon that time may come, that you wish to organize duplicated values between your patches, or values duplicated between patch files and the like into one spot that you can import them from, this is where libraries come in! Libraries are special patch files that don't contain any patches and are not executed by default but only when they are imported into another patch file, or even into patch files in other mods.

Libraries are great places to store the following:

Constant values used across your patches, especially ones other mods may want to use if they are trying to do stuff after you
Common functions used in your patches, and functions for other mods to use as well. Described in Functions and Closures
Common mixins used in your patches, and mixins for other mods to use as well. Described in Mixins

Creating Libraries

Libraries are created quite easily, just prepend the name of a patch file with an _, for example _constants.patch and _functions.patch, and for organization purposes these should go under the patches/libraries folder. In these files you can put any top level statement described in Top Level Statements except for selection blocks. (yes this includes importing other libraries).

An example library file is as follows: _constants.patch

$example-CONSTANT_A: 5;
$example-CONSTANT_B: 3.14159;

This library defines 2 constants, $example-CONSTANT_A and $example-CONSTANT_B.

Using Libraries

Using libraries in your patch files couldn't be simpler, just do a use statement at the top level, the syntax of which is @use followed by the library file name (without the _ prefix, or the .patch file extension) as a string, and a ;. Then every single declaration in that library should be imported into your current patch file.

An example of using the library described earlier is as follows:

@use "constants";
$tau: $example-CONSTANT_B * 2; // Define tau as 2 pi, where pi is defined in the library.

Using Libraries from Other Mods

Using libraries from other mods is similar to the above, but you have to prefix the library name with the mod id of the mod you are importing from followed by a colon, for example example:constants.

An example of using the library described earlier from another mod is as follows:

@use "example:constants";
$tau: $example-CONSTANT_B * 2; // Define tau as 2 pi, where pi is defined in the library.

If you want to use every library from a mod you can do @use "mod_id:*"

Using Builtin Libraries

Using builtin libraries is exactly the same as using libraries from other mods, except the prefix is builtin:. All the builtin libraries that exist are defined in the Builtin Library Reference.

An example of using the builtin:math library is as follows:

@use "builtin:math";
$half-pi: $PI/2; // Defines half-pi as pi/2

Similary to using libraries from other mods, if you wish to use every builtin, you can do @use "builtin:*"

Last modified: 26 April 2024