.. _doc_pages_templating:

Templating
===========

W4build provides a flexible way to configure deployments and notification payloads, allowing you to access context-specific values. For example, if you want to store an artifact in a bucket named either 'Godot' or 'Game', you don’t need separate deployments. Instead, you can use variables like ${job_name} to dynamically assign the bucket name based on the job context


Job Context
-------------

Understanding the context is crucial when using variables. You need to know whether the job is a Game export or a Godot compilation job. Each type of job has its own set of specific variables, so make sure you're using the right ones for the task at hand

**Job Context**

In deployments and notifications, the job context can be determined by the rules. If you add a rule that matches a matrix, you can identify the job type by checking which job the matrix is building. For example

- The following rule filters builds belonging to a specific matrix. Since this matrix only triggers jobs for exporting games, the context is set to GAME

    .. image:: img/filter_matrix.png
       :alt: filter matrix

- The following rule filters builds that are exporting games, regardless of the matrix. The context is set to GAME

    .. image:: img/job_game.png
       :alt: filter game

- The following rule filters builds that are compiling Godot, regardless of the matrix. The context is set to GODOT

    .. image:: img/job_godot.png
       :alt: filter godot

Variables
---------

Now that you are aware of the context, you can use any of the following variables


Generic variables
----------------------------

These variables are available on all builds, no matter the context

- ``${id}``: The build id: uuid
- ``${team}``: The UUID of the team associated with the build: uuid
- ``${event}``: The UUID of the event this build is associated with: uuid
- ``${start_date}``: The start date of the build, in ISO 8601 format: 'YYYY-MM-DD HH:MM:SS.ffffff'.
- ``${end_date}``: The completion date, or null if the build is not finished, in ISO 8601 format: 'YYYY-MM-DD HH:MM:SS.ffffff'.
- ``${build_status}``: The ID number representing the build status: number
- ``${job_name}``: The job name as a string ``godot`` or ``game`` : string
- ``${current_stage}``: The current stage name of the build: string
- ``${dispatch_data}``: If the build was triggered by a webhook, it contains the JSON data from that webhook: json
- ``${matrix}``: If the build was triggered by a matrix, this variable contains the matrix UUID

Godot context specific variables
--------------------------------
Godot context contains the generic variables plus:


- ``${platform}``: The target platform godot is compiled for linux, windows etc :string
- ``${cpu_architecture}``: The target cpu architecture godot is copiled for, x86_64 or Universal: string
- ``${build_target}``: editor, template_release or template_debug
- ``${ref}``: The Git ref containing the specific branch name, tag or sha: string
- ``${git_repo}``: The Git repository URL
- ``${scons_params}``: the list of scon variables for compiling godot : string
- ``${profile}``: The UUID of the profile file used for compiling godot: uuid

Game context specific variables
--------------------------------

Game context contains the generic variables plus:

- ``${ref}``: The Git ref containing the specific branch name, tag or sha: string
- ``${git_repo}``: The Git repository URL
- ``${export}``: The export type for your game, release or debug: string
- ``${export_name}``: the given export name for your game: string
- ``${preset_name}``: The given Godot export configuration name


Examples
--------

- itch.io: When deploying to itch.io its useful to have the channel created by game name followed by the platform.

    .. code-block:: helm

        myamazingame/game:${export_name}-${preset_name}

    Will result in

    .. code-block:: helm

        myamazingame/game:tps_demo-windows

    The itch.io deployment configuration looks like

    .. image:: img/itchio.png
        :alt: filter matrix

- S3: Sometimes it’s useful to back up all files to an S3 service. To make this easier, you can specify the bucket name based on the ``${job_name}``. This way, all game-related files are stored in a bucket called 'game', while compiled Godot files are stored in a bucket called 'Godot'.


    .. code-block:: helm

        ${job_name}-backup

    Will result in

    .. code-block:: helm

        godot-backup

    The S3 deployment configuration looks like, every file will be stored on a on a bucket given the job name and a subfolder with the ref value

    .. image:: img/s3.png
        :alt: filter matrix

|

    In backblaze the resulting storage will look like

    .. image:: img/backblaze.png
        :alt: filter matrix