Introduction

What’s Scaffscript?

ScaffScript is a minimal superset of GML (GameMaker Language) that adds a TypeScript-like module system. Write organized, modular GML in .ss files. ScaffScript compiles to GML and can inject it directly into your GameMaker project.

Exports & Module System

Code Generation & Integration

Write TypeScript-flavored GML, ship as an actual GML

Don’t forget to leave a star on the GitHub repository! ⭐

DISCLAIMER

• ScaffScript is not affiliated with or endorsed by YoYo Games Ltd. GameMaker and GML are trademarks of YoYo Games Ltd. This project is an independent effort by community members and is not officially supported by YoYo Games Ltd.
• Furthermore, ScaffScript won’t work if you don’t provide GameMaker project file. It’s just a compiler that compiles ScaffScript code to GML and injects it into your GameMaker project.

Caution

ScaffScript is currently in early development. Though it’s ready for basic use, it’s not stable yet. You should follow the guide provided here to use it without issues, and be aware that the API is subject to change without notice. Use at your own risk.

Why ScaffScript Exists?

GML is perfect for fast prototyping with its functional and event-driven nature. But, this paradigm may be limiting when your project grows. Yes, you can split your code into multiple script assets. But, it becomes verbose fast and pollutes your global-scoped code (functions, macros, enums). Like, creating function mylib_create(), function mylib_*, function and function over and over again. And it become the worst nightmare if you want to create “one-gigantic-library-in-one-script” that contains everything, moreover, if you want OOP approach with GML.

ScaffScript exists to fill that gap. It adds a module system to GML, so you can write organized, maintainable GML code. It’s designed to “free” you from the that verbose code, while still keeping the flexibility of GML. You can think of it as a “preprocessor” for GML. It’s not a full-blown language, it’s a minimal superset language to help you write better GML code, especially for creating GML libraries.

How It Works?

1. ScaffScript scans your source directory for *.ss and *.gml files.
2. Resolves all export / import / include references across files.
3. Reads intg statements to know which blocks go to which GameMaker asset.
4. Generates .gml output.
   • If noIntegration is false, ScaffScript writes and integrates it directly into your GameMaker project.
   • Otherwise, ScaffScript only writes the output to the .out/ directory for you to review and integrate manually.

That’s ScaffScript in a nutshell. It’s designed to be as simple and lightweight as possible, while still providing a powerful module system that you can use to organize your GML code. You’ll learn more about how to use it later in the Your First Script guide.

Limitations

1. No AST

   ScaffScript currently uses a regex-based parser for rapid development. It’s not very reliable for complex code structures. For example, it may not work well with nested code blocks, such as nested struct literals in @use directives. It may also not work well with other edge cases. We may change to AST-based parser in the future.

2. No test for GameMaker 1.x

   ScaffScript is currently designed and tested only for GameMaker 2.3+. It may or may not work with GameMaker 1.x.

Code Preview

Let’s say, we’re going to create a library for handling CSV files easily called EzCSV.

Project Structure

GML

With only using GML, your project structure in the GameMaker IDE may look like this:

• DirectoryEzCSV/

  • DirectoryFile-System/

    • scrEzCSVFSRead
    • scrEzCSVFSWrite
  • DirectoryGenerate/

    • scrEzCSVGenArray
    • scrEzCSVGenDS
    • scrEzCSVGenPrimitive
    • scrEzCSVGenStruct
  • DirectoryParse/

    • scrEzCSVParseArray
    • scrEzCSVParseDS
    • scrEzCSVParsePrimitive
    • scrEzCSVParseStruct
  • scrEzCSVGet
  • scrEzCSVUtils

All of them are script assets. That’s the simplest way to organize your code in GameMaker IDE. Of course, you can split them again into folders, but, it’s not very maintainable when your project grows, as all of the “modules” are actually just a global functions, enums, and macros.

ScaffScript

With ScaffScript, your ScaffScript project structure may look like this:

• Directorysrc/

  • Directoryfile-system/

    • index.ss
    • read.ss
    • write.ss
  • Directoryparse/

    • index.ss
    • array.ss
    • data-structure.ss
    • primitive.ss
    • struct.ss
  • Directorygenerate/

    • index.ss
    • array.ss
    • data-structure.ss
    • primitive.ss
    • struct.ss
  • Directoryutils/

    • index.ss
    • log.ss
    • normalize.ss
  • index.ss

You may notice that the structure is not much different with the GML approach. That’s correct, because the real difference is the “design” of the code itself. We’ll cover that in the next section.

Code Comparison

We will only cover the general logic of some files/modules, not the actual implementation, so you can get the idea of how ScaffScript works.

GML

scrEzCSVRead

scrEzCSVRead.gml

function ezcsv_read(file_path) {
    var result = "";
    // implementation...
    return result;
}

scrEzCSVParseArray

scrEzCSVParseArray.gml

function ezcsv_parse_array(csv_string) {
    var result = [];
    // implementation...
    return result;
}

scrEzCSVGenStruct

scrEzCSVGenStruct.gml

function ezcsv_generate_struct(data) {
    var result = "";
    // implementation...
    return result;
}

scrEzCSVGet

scrEzCSVGet.gml

function ezcsv_get(file_path) {
    var result;
    var csv_data = ezcsv_read("data.csv");
    // implementation...
    return result;
}

The function “endpoint” of the library. It uses other functions to do it’s job.

As you can see, all of the functions are in the global scope. They are not “connected” to each other in any way. You can “connect” them by calling the functions directly, as shown in the scrEzCSVGet example. But, it may become painful to manage when your project grows.

ScaffScript

src/file-system/read.ss

src/file-system/read.ss

export function read(file_path) {
    var result = "";
    // implementation...
    return result;
}

src/parse/array.ss

src/parse/array.ss

export function parse_array(csv_string) {
    var result = [];
    // implementation...
    return result;
}

src/generate/struct.ss

src/generate/struct.ss

export function generate_struct(data) {
    var result = "";
    // implementation...
    return result;
}

src/index.ss

src/index.ss

intg { main } to "./scripts/Libraries/EzCSV"

import * from "./parse"

#[main]
include { read } from "./file-system"
include { generate_struct } from "./generate"
@content parse_array

function ezcsv_get(file_path) {
    var result;
    var csv_data = read(file_path);
    // implementation...
    return result;
}

As you can see, we’re using export keyword to export the functions from each module. Then, in the src/index.ss, we’re using import and include statement to import and inline the exported functions from other modules. The ezcsv_get function is the “endpoint” of the library. It uses other functions to do it’s job.

Why the Code Becomes Longer?

Yes, what you see is correct! ScaffScript code is longer and more complex than the GML code. It makes sense, because we’re using ScaffScript’s module system to connect the exports from different modules (in this case, functions).

Each export can be used by other modules using import and include statement. So, you have more control over your code organization, such as:

• What should be “private” and “public”.
• What should be inlined and what should be called.
• Where should the code be put.
• What should be the final output.
• Etc.

You don’t need to “throwing” everything into the global scope anymore. It’s like an overkill for a simple library like this, but it’s worth it in the long run.

Tip

We just show a little “taste” of what ScaffScript can do. You can do more with ScaffScript, like, implements OOP using class and impl syntax, or using interface to define a struct shape/skeleton. You can learn more about it in the Module System page, or see the Real-World Examples page for more examples.

File Types

Extension	Description
.ss	ScaffScript source, supports the full module system
.gml	Standard GML, can be included as raw content via include

Extras

Questions & Feedback

If you have any questions or feedback, feel free to join the Discord server or open an issue on the GitHub repository.

License

ScaffScript is licensed under the MIT License.

Contributing

Contributions are welcome! Please see the Contributing guide for more information.

Support

If ScaffScript is useful to you, please consider sponsoring or supporting this project through Ko-Fi or Trakteer. Your support helps keep the project alive and thriving!