Game Maker Hub · Catalyst

About Catalyst

Catalyst is a tool to manage dependencies within GameMakerStudio2 projects, and speed up certain processes. If you need a library inside of your project you can use this tool to declare the dependency and install all dependencies. The dependencies will be recursively solved, so multiple libraries can require multiple dependencies, and they can be shared. Adding and removing packages is very easy, as is updating existing included packages. Upgrading to new versions of libraries has never been so easy! Installing dependencies will exclude them (to the best extent possible) from version control, keeping your source code clean. Unfortunately, due to the format of Game Maker Studio 2 project, there will be some changes in the main project file as well as some view files. Inside the GameMaker project, all external files (vendored files) will reside in the `vendor` folders.

How does it work?

You create a catalyst.json file in your project's folder. Either by using catalyst init or manually writing a JSON file. You declare the name of your package, the license format, and the dependencies. Running catalyst install will recursively solve all dependencies and install the required packages.

When other people check out your source, and it requires dependencies, it will not run. They will first have to run catalyst install to download and install the dependencies to the project.
This way we can make sure that vendored code is not included in version control. Stating the obvious: files inside of the vendor folders should never be edited, as your changes are not included in version control.

Initialize a project

Lets enhance a project with Catalyst. After installing Catalyst we open up a command line tool and navigate to our project. There, we run catalyst init to setup our main catalyst file.

The program will ask for some input like package a name and a description. Please note that this is also required for personal, private projects that you do not intend to share. The catalyst file is needed for catalyst to run!

Make sure you have your project running in version control, like git. This means that if anything goes wrong, we can always revert the changes. It also doubles as an off-site backup!

Require dependencies

Now that we have a catalyst.json file, we can declare dependencies in it. For example, we need some code from the project dukesoft/dscpu-mercy - we simply write catalyst require dukesoft/dscpu-mercy.
If you want to require a certain version of a package, you can also add constraints: catalyst require dukesoft/dscpu-mercy@">=1.0 <2".
After running the command, the catalyst.json file will be updated with our required package.

Installing dependencies

After we have added a package to our require list, its time to install. When we run the command catalyst install, the program will try to solve all dependencies and mark the proper projects for installation. If this is successful, the packages will be installed into your GameMaker Studio 2 project.

After installing, you can see that only a minimal amount of files has been changed - some view files (main folders of your project), the YYP, and the .gitignore file.
The views are the "root" folders in which a new vendor folder has been made. Files in the vendor folder should not be tracked, because they are "external dependencies" that are being used by your project. Most of the files will not show up in source control as added - that is because the `.gitignore` file has been edited by Catalyst, so that those files do not show up in your repository. Due to GMS2's directory setup it unfortunately is not possible to ignore all vendored files on directory-level, and thus they have to be ignored file-by-file.

When we open our GMS IDE again, we will see that it noticed some changed files and will ask us to reload. Click "Reload" to load the changes Catalyst made.

Now thats it! The dependencies have been recursively resolved and installed into your project, ready to use.

Note that everything in the vendor folder is excluded from version control, and it will be deleted / overwritten upon reinstalling / upgrading using Catalyst. If you want to make changes to files within the vendor directory - write around it, extend, or better yet: update the library, and contribute to the world of open-source software :)

Making a package

Making a package is very easy. All you have to do is create a GMS2 project, and in the root folder, run catalyst init like above. If you want to publicly share the project, be sure to initialize it as a git repository as well.
Once your project with your catalyst.json is ready, you can use it as either a local package (see below), or share it with the world.

Using local packages

After you have initialized a project with Catalyst, you are ready to use it in other projects. In your main project, you can add folders for local packages, like so:

{
    "name": "robquistnl/my-personal-game",
    "description": "A game I'm working on",
    "license": "proprietary",
    "homepage": "https://github.com/robquistnl",
    "yyp": "My Personal Game.yyp",
    "repositories": {
        "../": "directory"
    },
    "require": {
        "robquistnl/my-personal-project": "*",
        "dukesoft/dscpu-mercy": ">=1.2"
    }
}

The given repository should be a folder containing project folders. Generally C:\Users\Username\Documents\GameMakerStudio2 would be good - it will include any projects you have locally initialized with a catalyst file.
Note the requirement being a wildcard - since there is no version information available, the local directory repository forces every package to be on version 1.0.0.

Sharing packages

Sharing your packages is easy. First make sure you have your project initialized with catalyst, and inside git.
Now make a tag for the version you want it to be (using Semantic Versioning) and push it to your remote branch;

git tag 1.1.0
git push origin master --tags

Once its available on your github page, submit the package for indexation on the Game Maker Hub repository; Submit packages
Thats it! After indexation, the world is ready to include your packages in their projects.