feat: test & doc support

.codespellrc

@@ -1,3 +1,2 @@
 [codespell]
-skip = assets/**
-ignore-words-list = lod,LOD
+skip = addons/gd-plug/**,addons/gut/**

.env

@@ -2,7 +2,7 @@
 
 # Godot
 
-GODOT_VERSION=4.2
+GODOT_VERSION=4.2.1
 
 # Addon
 

.gitattributes

@@ -1,12 +1,18 @@
+# Properly detect languages on Github.
+*.gd linguist-language=GDScript
+
 # Normalize EOL for all files that Git considers text files.
 * text=auto eol=lf
-*.gd linguist-language=GDScript
+
+# The above only works properly for Git 2.10+, so for older versions
+# we need to manually list the binary files we don't want modified.
+*.mp3 binary
+*.png binary
 *.hdr binary
 
 # Exclude all top-level files and directories (except addons) from zip downloads.
 # This makes installing through the AssetLib easier, because no files and folders
 # need to be unchecked.
-
-/**				export-ignore
+/**				        export-ignore
 /addons/greeter			!export-ignore
 /addons/greeter/**		!export-ignore

.github/actions/setup-godot/action.yml

@@ -0,0 +1,64 @@
+name: Setup Godot
+description: Setup Godot dependencies.
+runs:
+  using: "composite"
+  steps:
+
+    ############
+    # Windows  #
+    ############
+
+    - name: Installing Mesa3D
+      if: ${{ runner.os == 'Windows' }}
+      uses: ssciwr/setup-mesa-dist-win@v1
+
+    - name: Installing Scream, a virtual sound card
+      if: ${{ runner.os == 'Windows' }}
+      shell: powershell
+      run: |
+        <# Script to install Scream, a dummy sound card for Windows: https://github.com/duncanthrax/scream
+        Taken from comment by Aleksandr Chebotov (al-cheb) at: https://github.com/actions/virtual-environments/issues/2528#issuecomment-766883233 #>
+        Start-Service audio*
+        Invoke-WebRequest https://github.com/duncanthrax/scream/releases/download/3.6/Scream3.6.zip -OutFile C:\Scream3.6.zip
+        Expand-Archive C:\Scream3.6.zip -DestinationPath C:\Scream
+        $cert = (Get-AuthenticodeSignature C:\Scream\Install\driver\Scream.sys).SignerCertificate
+        $store = [System.Security.Cryptography.X509Certificates.X509Store]::new("TrustedPublisher", "LocalMachine")
+        $store.Open("ReadWrite")
+        $store.Add($cert)
+        $store.Close()
+        cd C:\Scream\Install\driver
+        C:\Scream\Install\helpers\devcon install Scream.inf *Scream
+
+    ############
+    # Linux    #
+    ############
+
+    - name: Installing Linux dependencies
+      if: ${{ runner.os == 'Linux' }}
+      shell: bash
+      run: sudo apt-get install -y pulseaudio xvfb x11-xserver-utils mesa-vulkan-drivers
+
+    - name: Starting X11 server on :0
+      if: ${{ runner.os == 'Linux' }}
+      shell: bash
+      run: xset -q || /bin/bash -c "sudo Xvfb -ac :0 -screen 0 1920x1080x24 > /dev/null 2>&1 &"
+      env:
+        DISPLAY: ":0"
+
+    - name: Check that X11 server is running
+      if: ${{ runner.os == 'Linux' }}
+      uses: nick-fields/retry@v2
+      with:
+        timeout_minutes: 1
+        max_attempts: 5
+        command: /bin/bash -c "xset -q > /dev/null 2>&1"
+      env:
+        DISPLAY: ":0"
+
+    - name: Starting dummy sound device
+      if: ${{ runner.os == 'Linux' }}
+      uses: nick-fields/retry@v2
+      with:
+        timeout_minutes: 1
+        max_attempts: 3
+        command: pulseaudio --check || pulseaudio -D

.github/workflows/release-packaging.yml

@@ -19,18 +19,55 @@ jobs:
       - name: Load dotenv
         run: just ci-load-dotenv
 
+      # Retry multiple times, sometimes in CI, gdlint raise "file exists"
       - name: Check
-        run: just fmt
+        uses: nick-fields/retry@v2
+        with:
+          timeout_minutes: 1
+          max_attempts: 3
+          command: just fmt
 
       - name: Ensure version is equal to tag
         if: startsWith(github.ref, 'refs/tags/')
         run: |
-          [ "${{ env.game_version }}" == "${{ env.BRANCH_NAME }}" ] || exit 2
+          [ "${{ env.addon_version }}" == "${{ env.BRANCH_NAME }}" ] || exit 2
+
+  test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+
+    strategy:
+      fail-fast: true
+      matrix:
+        os: [ ubuntu-22.04, windows-2022, macos-12 ]
+        godot_version: [ '4.0.4', '4.1.3', '4.2.1' ]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: extractions/setup-just@v1
+
+      - name: Setup Godot dependencies
+        uses: ./.github/actions/setup-godot
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Run unit tests
+        run: just unit
+        env:
+          GODOT_VERSION: ${{ matrix.godot_version }}
+
+      - name: Run integration tests
+        if: ${{ runner.os == 'Linux' }}
+        run: just integration
+        env:
+          GODOT_VERSION: ${{ matrix.godot_version }}
 
   publish:
     runs-on: ubuntu-22.04
     timeout-minutes: 30
-    needs: [check]
+    needs: [check, test]
 
     if: startsWith(github.ref, 'refs/tags/')
 

.gitignore

@@ -10,14 +10,15 @@ gfxrecon_capture_*
 .mono/
 data_*/
 
+# gd-plug
+.plugged/
+addons/*
+!addons/gd-plug/
+!addons/greeter/
+
 # Python-specific ignores
 venv/
 
-# Export output
-dist/
-build/
-override.cfg
-
 # Docs output
 reference.json
 site/

.gutconfig.json

@@ -0,0 +1,10 @@
+{
+  "dirs": [
+    "res://test"
+  ],
+  "prefix": "",
+  "suffix": ".test.gd",
+  "include_subdirs": true,
+  "log_level": 1,
+  "should_exit": true
+}

.pre-commit-config.yaml

@@ -46,6 +46,11 @@ repos:
     entry: gdformat
     language: system
     files: \.gd$
+    exclude: |
+      (?x)^(
+          addons/gd-plug/|
+          plug.gd
+      )
   - id: check-shaders
     name: check shaders
     entry: clang-format
@@ -55,9 +60,13 @@ repos:
       - -i
     language: system
     files: \.gdshader$
-    exclude: ^addons/
   - id: lint-gdscript
     name: lint gdscript
     entry: gdlint
     language: system
     files: \.gd$
+    exclude: |
+      (?x)^(
+          addons/gd-plug/|
+          plug.gd
+      )

.reuse/dep5

@@ -6,3 +6,15 @@ Source: https://github.com/MechanicalFlower/godot-addons-template
 Files: *
 Copyright: 2023-present Florian Vazelle
 License: MIT
+
+# Addons
+
+Files: addons/gd-plug/*
+Copyright: 2021 Tan Jian Ping
+License: MIT
+Source: https://github.com/imjp94/gd-plug
+
+Files: addons/gut/*
+Copyright: 2018 Tom "Butch" Wesley
+License: MIT
+Source: https://github.com/bitwes/Gut

Justfile

@@ -23,9 +23,34 @@ bin_dir := main_dir / "bin"
 
 # Godot variables
 godot_version := env_var('GODOT_VERSION')
-godot_platform := if arch() == "x86" { "linux.x86_32" } else { if arch() == "x86_64" { "linux.x86_64" } else { "" } }
+godot_platform := if os() == "windows" {
+    if arch() == "x86" {
+        "win32.exe"
+    } else if arch() == "x86_64" {
+        "win64.exe"
+    } else {
+        error("Architecture not supported")
+    }
+} else if os() == "macos" {
+    "macos.universal"
+} else if os() == "linux" {
+    if arch() == "x86" {
+        "linux.x86_32"
+    } else if arch() == "x86_64" {
+        "linux.x86_64"
+    } else if arch() == "arm" {
+        "linux.arm32"
+    } else if arch() == "aarch64" {
+        "linux.arm64"
+    } else {
+        error("Architecture not supported")
+    }
+} else {
+    error("OS not supported")
+}
 godot_filename := "Godot_v" + godot_version + "-stable_" + godot_platform
 godot_bin := bin_dir / godot_filename
+use_x11_wrapper := if godot_platform =~ "x11*" { env("CI", "false") } else { "false" }
 
 # Addon variables
 addon_name := env_var('ADDON_NAME')
@@ -38,7 +63,7 @@ venv_dir := justfile_directory() / "venv"
 
 # Display all commands
 @default:
-    echo "OS: {{ os() }} - ARCH: {{ arch() }}\n"
+    echo "OS: {{ os() }} - ARCH: {{ arch() }}"
     just --list
 
 # Create directories
@@ -56,45 +81,55 @@ venv_dir := justfile_directory() / "venv"
 [private]
 install-godot:
     #!/usr/bin/env sh
-    if [ ! -e {{ godot_bin }} ]
-    then
+    if [ ! -e {{ godot_bin }} ]; then
         curl -X GET "https://downloads.tuxfamily.org/godotengine/{{ godot_version }}/{{ godot_filename }}.zip" --output {{ cache_dir }}/{{ godot_filename }}.zip
-        unzip {{ cache_dir }}/{{ godot_filename }}.zip -d {{ cache_dir }}
+        unzip -o {{ cache_dir }}/{{ godot_filename }}.zip -d {{ cache_dir }}
         cp {{ cache_dir }}/{{ godot_filename }} {{ godot_bin }}
     fi
 
 # Download plugins
 install-addons:
     [ -f plug.gd ] && just godot --headless --script plug.gd install || true
 
+# Import game resources
+import-resources:
+    just godot --headless --editor --quit
+
 # Updates the addon version
 @bump-version:
     echo "Update version in the plugin.cfg"
     sed -i "s,version=.*$,version=\"{{ addon_version }}\",g" ./addons/{{ addon_name }}/plugin.cfg
+    echo "Update version in the README.md"
+    sed -i "s,tag = ".*"$,tag = \"{{ addon_version }}\"\, include = [\"addons/{{ addon_name }}\"]}),g" ./README.md
 
 # Godot binary wrapper
 @godot *ARGS: makedirs install-godot
-    {{ godot_bin }} {{ ARGS }}
+    #!/usr/bin/env sh
+    if [ "{{ use_x11_wrapper }}" = "true" ]; then
+        just ci-godot-x11 {{ ARGS }}
+    else
+        {{ godot_bin }} {{ ARGS }}
+    fi
 
 # Open the Godot editor
 editor:
     just godot --editor
 
 # Run files formatters
 fmt:
-    just venv pip install pre-commit==3.3.3 reuse==2.1.0 gdtoolkit==4.*
+    just venv pip install pre-commit==3.5.0 reuse==2.1.0 gdtoolkit==4.*
     just venv pre-commit run -a
 
 # Remove cache and binaries created by this Justfile
 [private]
-clean-mkflower:
+clean-glam-cache:
     rm -rf {{ main_dir }}
     rm -rf {{ venv_dir }}
 
 # Remove plugins
 clean-addons:
     rm -rf .plugged
-    [ -f plug.gd ] && find addons/ -type d -not -name 'addons' -not -name 'gd-plug' -not -name '{{ addon_name }}' -exec rm -rf {} \; || true
+    [ -f plug.gd ] && find addons/ -maxdepth 1 -type d -not -name 'addons' -not -name 'gd-plug' -not -name '{{ addon_name }}' -exec rm -rf {} \; || true
 
 # Remove any unnecessary files
 clean: clean-addons
@@ -105,7 +140,42 @@ ci-load-dotenv:
     echo "addon_name={{ addon_name }}" >> $GITHUB_ENV
     echo "addon_version={{ addon_version }}" >> $GITHUB_ENV
 
+# Starts godot using Xvfb and pulseaudio
+ci-godot-x11 *ARGS:
+    #!/bin/bash
+    set -e
+    # Set locale to 'en' if locale is not already set.
+    # Godot will fallback to this locale anyway and it
+    # prevents an error message being printed to console.
+    [ "$LANG" == "C.UTF-8" ] && LANG=en || true
+
+    # Start dummy sound device.
+    pulseaudio --check || pulseaudio -D
+
+    # Running godot with X11 Display.
+    xvfb-run --auto-servernum {{ godot_bin }} {{ ARGS }}
+
+    # Cleanup (allowed to fail).
+    pulseaudio -k || true
+
 # Upload the addon on Github
 publish:
     gh release create "{{ addon_version }}" --title="v{{ addon_version }}" --generate-notes
-    # TODO: Add a asset-lib publish step
+    # TODO: Add an asset-lib publish step
+
+# Generate documentation
+doc:
+    sed -i "s,res://src,res://addons/{{ addon_name }},g" ./addons/godot-autogen-docs/reference_collector.gd
+    just godot --editor --headless --quit --script addons/godot-autogen-docs/reference_collector_cli.gd
+    just godot --headless --quit --script addons/godot-autogen-docs/markdown.gd
+    just venv pip install mkdocs==1.5.3 mkdocs-literate-nav==0.6.1
+    just venv mkdocs build
+
+# Start serving the documentation
+serve:
+    just venv pip install mkdocs==1.5.3 mkdocs-literate-nav==0.6.1
+    just venv mkdocs serve
+
+# Run unit tests
+unit: install-addons import-resources
+    just godot --headless --script addons/gut/gut_cmdln.gd -gconfig=.gutconfig.json

README.md

@@ -1,7 +1,7 @@
 
 <div align="center">
 
-# Greeter
+# 🔌 Greeter
 
 ![Godot Badge](https://img.shields.io/badge/godot-4.2-blue?logo=Godot-Engine&logoColor=white)
 ![license](https://img.shields.io/badge/license-MIT-green?logo=open-source-initiative&logoColor=white)