Build actions: run your own scripts during a build

What you can do

• Generate code before the compile: stamp the version and commit into a source file, or build a config file from data.
• Bake assets: run your own asset pipeline between checkout and build.
• Add files to the package: anything a post_build script adds to the build output is signed, zipped and uploaded with the rest of the build.
• Publish the result: upload the finished zip to your own store or asset server once it exists.
• Report how it went: on_end runs last on every build, success or failure, and is told the result.

Scripts are read from the commit being built, so they are versioned with your code. Changing a script changes what the next build of the new commit does, and rebuilding an old commit runs that commit's scripts.

Turn build actions on

If a commit has scripts in .dsl/build_actions/ but build actions are not turned on for the project, the build fails and says so. It does not build without your scripts, because that could produce a working-looking build that is missing their changes. A repository without the folder builds as normal either way.

Quick start

This first script writes a C# class holding the version and commit, so the game can show which build it is.

1. Create the folder at the repository root

   In the root of your repository, create .dsl/build_actions/. It always goes at the root, even when your project lives in a subfolder.

2. Add a script named after its hook

   Save this as .dsl/build_actions/pre_build.py. The file name picks the hook: pre_build runs after the engine is ready and before the build starts.

   pre_build.pyCopy

   import os, pathlib
   
   out = pathlib.Path(os.environ["DSL_PROJECT_DIR"]) / "Generated" / "BuildInfo.cs"
   out.parent.mkdir(parents=True, exist_ok=True)
   out.write_text(
       f'public static class BuildInfo {{ public const string Version = "{os.environ["DSL_VERSION"]}.{os.environ["DSL_BUILD_NUMBER"]}"; '
       f'public const string Commit = "{os.environ["DSL_COMMIT"]}"; }}\n'
   )
   print(f"wrote {out}")
   

3. Commit and push

   The next build runs the script before compiling. Its output appears in the build log under the step build action pre_build.

The script reads DSL_PROJECT_DIR, DSL_VERSION, DSL_BUILD_NUMBER and DSL_COMMIT, four of the variables every script receives. The full list is on What your script is told.

The pages in this guide

• Build actions: run your own scripts during a build This page: what build actions are, how to turn them on, and a first script.
• Scripts, hooks and runtimes Where scripts go, how they are named, the nine hooks and when each runs, the Python and Node versions, and installing packages.
• What your script is told Every environment variable a script receives, the JSON build context file, and short examples that use them.
• Secrets in build actions Storing tokens and keys in Build Action Secrets, reading them from a script, and how the build log masks them.
• Failures, on_end and limits What counts as a failure, how it shows in the log, reporting results from on_end, and the time limits.
• Build actions troubleshooting Every build actions message with its cause and fix.

Setting up Build Stream itself, connecting a repository and reading the build log are covered in the Build Stream guide.