Working with Modules

Let’s dive deeper into how to use the module system properly in ScaffScript.

Exporting Modules

Module in ScaffScript is a .ss file that only used for exporting variables, functions, etc. These are called exports. Here’s the common exports you can use in ScaffScript:

Export	Description
export var	Export a variable. Compiles to local variable (var) in GML.
export let	Export an instance variable. Compiles to instance variable in GML.
export const	Export a constant. Compiles to global constant (#macro) in GML.
export function	Export a function. Compiles to global function in GML, like when you’re creating a function in a script asset in the GameMaker IDE.
export enum	Export an enum. Compiles to enum in GML.
export class	Export a class. Compiles to struct constructor in GML.

Tip

Check out the Best Practices page for more information.

import vs include

ScaffScript provides two ways to import modules: import and include. They both serve the same purpose of importing modules, but they have different syntax and behavior. Here’s the difference between them:

	import	include
Syntax	import { ExportsName } from "path/to/file"	include { ExportsName } from "path/to/file" | include { "filename" } from "path/to/dir"
Content Directives	✅	❌
Inline Content	Need @content directive	Direct inlining
Use Case	General purpose	Inlining module content
Exports Alias	✅	❌
.gml Inlining	❌	✅

Example

Let’s use my-file module as an example. It exports a variable and a function.

my-file.ss

export var x_point = 10;

export function hello() {
    show_debug_message("Hello, World!");
}

Using Exports

import

index.ss

import { x_point, hello } from "./my-file"

@content hello
hello();

@content x_point
show_debug_message($"x_point = @:x_point");

include

index.ss

include { hello } from "./my-file"
hello();

include { x_point } from "./my-file"
show_debug_message($"x_point = @:x_point");     // can't use content directives!

Note

All paths used in import, include, and export ... from are resolved relative to the current file’s directory. If you set path aliases in scaff.config.*, you can use the aliases instead.

Compiled Result

import

index.ss

 import { x_point, hello } from "./my-file"

 @content hello
 function hello() {
     show_debug_message("Hello, World!");
 }
hello();

 @content x_point
 show_debug_message($"x_point = x_point");
 var x_point = 10;
 show_debug_message($"x_point = 10");

include

index.ss

 include { hello } from "./my-file"
 function hello() {
     show_debug_message("Hello, World!");
 }
hello();

 include { x_point } from "./my-file"
 var x_point = 10;
show_debug_message($"x_point = @:x_point");

Final Result

import

index.gml

function hello() {
    show_debug_message("Hello, World!");
}
hello();

var x_point = 10;
show_debug_message($"x_point = 10");

include

index.gml

function hello() {
    show_debug_message("Hello, World!");
}
hello();

var x_point = 10;
show_debug_message($"x_point = @:x_point");

---

export * from

export * from is called barrel export. It’s useful for re-exporting modules from a deep path with a more convenient path.

Example

Let’s say you have this structure:

• Directorysrc/

  • Directorylib/

    • Directorymath/

      • Directorysimple/

        • vector2.ss
        • vector3.ss
      • Directorycomplex/

        • matrix2-2.ss
        • matrix3-3.ss
      • index.ss
    • Directoryutils/

      • my-utils.ss
      • other-utils.ss
      • yet-another-utils.ss
    • index.ss
  • index.ss

Without the re-export, you would have to import the modules from the deep path, like this:

src/index.ss

import { read_multi_file } from "./lib/utils/my-utils"

import { Vector2, Vector3 } from "./lib/math/simple/vector2"

import * from "./lib/math/complex/matrix3-3"

It’s tedious and error-prone, especially when you’re working with a large project. This is where export * from shines. You can re-export all exports from a module in lib/index.ss, like this:

src/lib/math/index.ss

export * from "./simple/vector2"
export * from "./simple/vector3"

export * from "./complex/matrix2-2"
export * from "./complex/matrix3-3"

src/lib/index.ss

// ./utils doesn't have index.ss, so we import the exports from the deep path
export * from "./utils/my-utils"
export * from "./utils/other-utils"
export * from "./utils/yet-another-utils"

// ./math has index.ss, and we already re-export all exports from it in math/index.ss
export * from "./math"

Now you can import the exports from lib/index.ss like this:

src/index.ss

import { read_multi_file } from "./lib"

import { Vector2, Vector3 } from "./lib"

import * from "./lib"

Caution

Though it’s convenient, it’s recommended to only re-export modules from a single level deep (in other words, doing the barrel export in the index.ss for each directory). Re-exporting from multiple levels deep can lead to naming conflicts and makes it harder to understand where the exports are coming from. For example:

src/lib/file-system/fs.ss

export function read_multi_file() {
    show_debug_message("Reading multi file...");
    show_debug_message("This one is from fs.ss");
    // ...
}

src/lib/utils/my-utils.ss

export function read_multi_file() {
    show_debug_message("Reading multi file...");
    show_debug_message("This one is from my-utils.ss");
    // ...
}

Bad

src/lib/index.ss

export * from "./file-system/fs"
export * from "./utils/my-utils"

src/index.ss

import * from "./lib"

@content read_multi_file
read_multi_file();

We don’t know which read_multi_file is being inlined, and it leads to naming conflicts.

Good

src/lib/file-system/index.ss

export * from "./fs"

src/lib/utils/index.ss

export * from "./my-utils"

src/index.ss

import { read_multi_file: read_multi_file_from_fs } from "./lib/file-system"
import { read_multi_file: read_multi_file_from_utils } from "./lib/utils"

@content read_multi_file_from_fs
@content read_multi_file_from_utils

read_multi_file_from_fs();
read_multi_file_from_utils();

Though it’s longer, it’s more explicit and easier to understand. With this approach, you can also avoid naming conflicts by aliasing the imports.

---

Path Aliases

You have a deeply nested module, but you don’t want either to use the full path, or re-export it? Path aliases are here to help you!

Example

Let’s use the same structure as the export * from example above:

• Directorysrc/

  • Directorylib/

    • Directorymath/

      • Directorysimple/

        • vector2.ss
        • vector3.ss
      • Directorycomplex/

        • matrix2-2.ss
        • matrix3-3.ss
      • index.ss
    • Directoryutils/

      • my-utils.ss
      • other-utils.ss
      • yet-another-utils.ss
    • index.ss
  • index.ss

You can add path aliases in scaff.config.* to make it easier to import the modules. Here’s an example:

scaff.config.cjs

scaff.config.cjs

module.exports = {
    clearOutputDir: false,
    noIntegration: true,
    path: {
        "@vec2": "./lib/math/simple/vector2",
        "~vec3": "~/lib/math/simple/vector3",
        "Math": "./lib/math",
        "@utils-1": "./lib/utils/my-utils",
        "Utils-other": "./lib/utils/other-utils",
        "Lib": "./lib",
    },
    production: false,
    tabType: "1t",
    targetPlatform: "all",
    useGmAssetPath: true
    // other options...
};

scaff.config.ts

scaff.config.ts

export default {
    clearOutputDir: false,
    noIntegration: true,
    path: {
        "@vec2": "./lib/math/simple/vector2",
        "~vec3": "~/lib/math/simple/vector3",
        "Math": "./lib/math",
        "@utils-1": "./lib/utils/my-utils",
        "Utils-other": "./lib/utils/other-utils",
        "Lib": "./lib",
    },
    production: false,
    tabType: "1t",
    targetPlatform: "all",
    useGmAssetPath: true
    // other options...
} satisfies Partial<ScaffConfig>;

And then, you can use the aliases in your modules:

src/index.ss

import { Vector2 } from "@vec2"
import { Vector3 } from "~vec3"

import * from "Math"

import { read_multi_file: read_multi_file_from_utils_1 } from "@utils-1"
import { read_multi_file: read_multi_file_from_utils_other } from "Utils-other"

Tip

When a path is used in import, include, or export ... from statement, ScaffScript will check if the path is exists in the path aliases first. If it does, it will use the aliased path instead.

Relative Paths

A path that starts with ./ or without any prefix, will be resolved relative to the importing file’s directory.

Example

scaff.config.*

    // --- snip ---
    path: {
        "@vec2": "./lib/math/simple/vector2",
        "Math": "./lib/math",
        "@utils": "lib/utils"
    },
    // --- snip ---

src/index.ss

src/index.ss

import { Vector2 } from "@vec2"
import { Vector3 } from "Math"

Explanation

1. Current directory is ./src.
2. The @vec2 path alias is resolved to "./src/lib/math/simple/vector2".
   • So, it’ll import Vector2 from "./src/lib/math/simple/vector2".
3. The Math path alias is resolved to "./src/lib/math".
   • So, it’ll import Vector3 from "./src/lib/math".

src/my-folder/index.ss

src/my-folder/index.ss

import { Vector2 } from "@vec2"
import { Vector3 } from "Math"

Explanation

1. Current directory is ./src/my-folder.
2. The @vec2 path alias is resolved to "./src/my-folder/lib/math/simple/vector2".
   • So, it’ll import Vector2 from "./src/my-folder/lib/math/simple/vector2".
   • It’ll throw an error, because the module ("./src/my-folder/lib/math/simple/vector2") doesn’t exist.
3. The Math path alias is resolved to "./src/my-folder/lib/math".
   • So, it’ll import Vector3 from "./src/my-folder/lib/math".
   • It’ll throw an error, because the module ("./src/my-folder/lib/math") doesn’t exist.

Tip

• ./ means current directory of the importing file.
• Use ../ to go up one directory of the importing file.
• You can combine ./ and ../ to navigate to the desired directory. For example, ../../ goes up two directories.

Absolute Paths

Opposite to relative paths, absolute paths are resolved from the root of the project. It uses tilde (~) as the prefix. The root itself is based on the source option in scaff.config.*.

Example

scaff.config.*

    // --- snip ---
    path: {
        "~vec2": "~/lib/math/simple/vector2",
        "Math": "~/lib/math",
        "~utils": "~/lib/utils"
    },
    source: "./src",
    // --- snip ---

src/index.ss

src/index.ss

import { Vector2 } from "~vec2"
import { Vector3 } from "Math"

Explanation

1. Absolute path doesn’t care about the importing file’s directory.
2. The ~vec2 path alias is resolved to "/src/lib/math/simple/vector2".
   • So, it’ll import Vector2 from "/src/lib/math/simple/vector2".
3. The Math path alias is resolved to "/src/lib/math".
   • So, it’ll import Vector3 from "/src/lib/math".

src/my-folder/index.ss

src/my-folder/index.ss

import { Vector2 } from "~vec2"
import { Vector3 } from "Math"

Explanation

1. Current directory is ./src/my-folder, but absolute path doesn’t care about the current directory.
2. The ~vec2 path alias is resolved to "./src/lib/math/simple/vector2".
   • So, it’ll import Vector2 from "./src/lib/math/simple/vector2".
   • It’ll work, because the module ("./src/lib/math/simple/vector2") exists.
3. The Math path alias is resolved to "./src/lib/math".
   • So, it’ll import Vector3 from "./src/lib/math".
   • It’ll work, because the module ("./src/lib/math") exists.

Tip

• Absolute paths will work everywhere, as long as the path is correct.
• The tilde (~) prefix is only required for the resolved path, not the path alias itself. See the "Math" path alias in the example above.

Wildcard Paths

ScaffScript supports wildcard paths in path aliases. It uses * as the wildcard character. Here are the rules:

• * must be the last character of both the path alias name and the resolved path alias.
• * matches any number of characters and path segments, including none.
• You can use * in both relative and absolute paths.

Example

scaff.config.*

    // --- snip ---
    path: {
        "@math/*": "./lib/math/*",
        "~utils/*": "~/lib/utils/*"
    },
    source: "./src",
    // --- snip ---

src/index.ss

src/index.ss

import { Vector2 } from "@math/simple/vector2"
import { Matrix33 } from "@math/complex/matrix3-3"
import { read_file } from "~utils/my-utils"

Explanation

1. Current directory is ./src.
2. The @math/simple/vector2 path alias is resolved to "./src/lib/math/simple/vector2".
   • So, it’ll import Vector2 from "./src/lib/math/simple/vector2".
   • It’ll work, because the module ("./src/lib/math/simple/vector2") exists.
3. The @math/complex/matrix3-3 path alias is resolved to "./src/lib/math/complex/matrix3-3".
   • So, it’ll import Matrix33 from "./src/lib/math/complex/matrix3-3".
   • It’ll work, because the module ("./src/lib/math/complex/matrix3-3") exists.
4. The ~utils/my-utils path alias is resolved to "/src/lib/utils/my-utils".
   • So, it’ll import read_file from "/src/lib/utils/my-utils".
   • It’ll work, because the module ("/src/lib/utils/my-utils") exists.

src/my-folder/index.ss

src/my-folder/index.ss

import { Vector2 } from "@math/simple/vector2"
import { Matrix33 } from "@math/complex/matrix3-3"
import { read_file } from "~utils/my-utils"

Explanation

1. Current directory is ./src/my-folder.
2. The @math/simple/vector2 path alias is resolved to "./src/my-folder/lib/math/simple/vector2".
   • So, it’ll import Vector2 from "./src/my-folder/lib/math/simple/vector2".
   • It’ll throw an error, because the module ("./src/my-folder/lib/math/simple/vector2") doesn’t exist.
3. The @math/complex/matrix3-3 path alias is resolved to "./src/my-folder/lib/math/complex/matrix3-3".
   • So, it’ll import Matrix33 from "./src/my-folder/lib/math/complex/matrix3-3".
   • It’ll throw an error, because the module ("./src/my-folder/lib/math/complex/matrix3-3") doesn’t exist.
4. The ~utils/my-utils path alias is resolved to "/src/lib/utils/my-utils". Absolute paths are not affected by the current directory.
   • So, it’ll import read_file from "/src/lib/utils/my-utils".
   • It’ll work, because the module ("/src/lib/utils/my-utils") exists.

Best Practices

1. Use @ prefix, ~ prefix, or uppercase for path alias names to avoid conflicts with normal paths.
2. Use absolute paths over relative paths, as its persistent behavior makes it more predictable.
3. Use * wildcard character to make your path aliases more flexible. So, you won’t waste your time remapping your path aliases when your project grows.

---

Using Content Directives in import

After importing a module with import, you can use the content directives to inline the module’s content. Here are the commonly used content directives:

Directive	Usage
@content	Inlines the full compiled GML declaration of the module.
@valueof	Inlines the right hand side or the body of the module.
@:	Shorthand for @valueof.

Example

my-file.ss

export var x_point = 10;

export function hello() {
    show_debug_message("Hello, World!");
}

index.ss

import { x_point, hello } from "./my-file"

@content hello
hello();

var my_method = function() {
    show_debug_message("This is my method!");

    @content x_point
    var my_x = @:x_point;
    show_debug_message($"my_x * x_point = {my_x * x_point}");
}

Result

index.ss

 import { x_point, hello } from "./my-file"

 @content hello
 function hello() {
     show_debug_message("Hello, World!");
 }
hello();

var my_method = function() {
    show_debug_message("This is my method!");

   @content x_point
   var my_x = @:x_point;
   var x_point = 10;
   var my_x = 10;
    show_debug_message($"my_x * x_point = {my_x * x_point}");
}

Tip

Check out the available content directives in the Content Directives page.

---

Common Gotchas

• import alone doesn’t emit anything.
• If you set a path alias target to "./some/path", the resolved paths are relative to the importing file, not from the root of the project.
• Forgetting that include inlines the full declaration, not just the value.
• Using export * from recklessly leads to naming conflicts.