.. _doc_pages_export_game_matrix:

Matrix Blueprints
=================

Matrix game blueprints provide a streamlined way to configure common attributes across multiple builds. For instance, when exporting your game to Windows, Linux, and Android, each platform shares common elements like the Git repository and Git reference, but they vary in preset names and export templates.

This is where the matrix becomes incredibly useful. You can set up the common attributes in the matrix configuration while specifying the unique details for each job.

Why Use Matrix Operations?
-----------------------------------

1. Efficiency: By running multiple jobs simultaneously, matrix operations reduce the time it takes to compile Godot to different platforms.

2. Early Detection of Issues: With matrix builds, potential problems can be identified quickly across different scenarios, leading to faster fixes and higher code quality.


Create Game Matrix
-------------------

1. Click "Matrix Blueprints" under the Triggers menu.
2. Click "+ Create Game matrix"

    .. image:: ../img/matrix/home.png
       :alt: Matrix home page

3. Click the Cog icon button

    .. image:: ../img/matrix/mtrxhome.png
       :alt: Matrix home page

4. Complete the form with the required information (detailed below).

    .. image:: ../img/matrix/emptyform.png
       :alt: Matrix home page


Each field is:

Name
    A brief and descriptive name for the blueprint.

Game Name
    The title of the game.

.NET
    Check this checkbox in case you game is built using C#/.NET

Repository
    The repository where the code for the engine is located. in this case `Godot fork <https://github.com/svelezw4games/godot-4-3d-third-person-controller.git>`_.
    Remember to add the full url, including .git

Git Ref
    The name of the Git branch (such as “main” or “development”), a tag (like “v1.0.0”), or a specific commit hash for the version of the game you wish to compile.

Game Directory
    The directory where your project.godot file is located. Leave this field blank if the project.godot file is in the root directory of your repository.

Godot Export Preset Name
    - The name you've assigned to your export preset in Godot (found under Project > Export > Your Preset > Name).
    - For this scenario, we are using the following export presets `export_presets <https://github.com/svelezw4games/godot-4-3d-third-person-controller/blob/main/export_presets.cfg>`_.

Secret Token
    If your repository is private, select the SSH token required to clone it.

Export
    Games can be exported with

    * Debug
        - Developing: You're actively writing code and testing features.
        - Finding Bugs: You want to track down errors and see detailed information.
        - Performance Tuning: You need to analyze performance metrics to optimize your game.
    * Release
        - Publishing: You're ready to share your game with the world.
        - Final Testing: You've finished development and want to test the final product under realistic conditions.
        - Performance Optimization: You've made optimizations and want to verify they work correctly.


5. Select Editor and Export template Versions

    TAB: Custom Godot Templates (your compiled godot binaries)

        To use custom Godot editor and templates, select the name of the matrix that was used to build them.

        .. image:: ../img/matrix/customv.png
            :alt: Matrix home page

    TAB: Godot Official Export Templates

        To use Official Godot editor and templates, Select the desired godot official version

        .. image:: ../img/matrix/officialv.png
            :alt: Matrix home page

.. note::
    To export games from Godot, you need two main ingredients:

    - Editor:
        Your magical toolbox for crafting the game world.
    - Export Templates:
        Special recipes for packaging your game onto various platforms.

    The editor helps you make the game.
    The templates help you share it with others.

The completed matrix form should look like

    .. image:: ../img/matrix/full_form.png
        :alt: Matrix home page



Add MacOS build
-------------

1. Click "+ Add Job"
2. Type "WebT" (please check how you called this export preset)
3. Select the export template related to linux release

    .. image:: ../img/matrix/macos_form.png
       :alt: Matrix home page

Add Linux build
-------------------

1. Click "+ Add Job"
2. Type "Linux" (please check how you called this export preset)
3. Select the export template related to linux release

    .. image:: ../img/matrix/linux_form.png
       :alt: Matrix home page


Add Web build
-------------

1. Click "+ Add Job"
2. Type "WebT" (please check how you called this export preset)
3. Select the export template related to linux release

    .. image:: ../img/matrix/web_form.png
       :alt: Matrix home page


The matrix home page should look like this

The completed matrix form should look like

    .. image:: ../img/matrix/completed_form.png
        :alt: Matrix home page