build.yml

# Build the mod for every Stonecutter variant, then launch-test the built jars
# on EVERY supported Minecraft version concurrently: each launch job boots a
# real production Fabric client under XVFB with the covering variant's jar and
# version-matched runtime mods, enters a survival singleplayer world with the
# HUD active, screenshots it, and fails if anything crashes on the way.
# The screenshot report job embeds all screenshots in a PR comment (via the
# ci-screenshots branch) and in the job summary, and the modrinth bundle job
# packages the release jars with their per-jar Minecraft version lists.
#
# Both job matrices are generated from supported-versions.json — add a version
# there (see README) and every job picks it up.

name: build
on: push

# contents: write lets the screenshot report push to the ci-screenshots branch,
# pull-requests: write lets it comment on the associated pull request.
permissions:
  contents: write
  pull-requests: write

jobs:
  matrices:
    name: compute matrices
    runs-on: ubuntu-24.04
    outputs:
      build: ${{ steps.gen.outputs.build }}
      launch: ${{ steps.gen.outputs.launch }}
    steps:
      - name: checkout repository
        uses: actions/checkout@v6

      - name: generate matrices from supported-versions.json
        id: gen
        run: bash .github/scripts/generate-matrices.sh

  build:
    name: build mc${{ matrix.mc }}
    runs-on: ubuntu-24.04
    needs: matrices
    strategy:
      fail-fast: false
      matrix:
        include: ${{ fromJson(needs.matrices.outputs.build) }}
    steps:
      - name: checkout repository
        uses: actions/checkout@v6

      - name: validate gradle wrapper
        uses: gradle/actions/wrapper-validation@v6

      - name: setup jdk ${{ matrix.java }}
        uses: actions/setup-java@v5
        with:
          java-version: ${{ matrix.java }}
          distribution: 'microsoft'

      - name: setup gradle with dependency caching
        # Caches Gradle dependencies between runs (written on the default
        # branch, read everywhere), so a flaky maven rarely has to be hit.
        uses: gradle/actions/setup-gradle@v6

      - name: make gradle wrapper executable
        run: chmod +x ./gradlew

      - name: build :${{ matrix.mc }}:build
        # retry.sh reruns the build on transient failures (flaky maven downloads).
        run: bash .github/scripts/retry.sh ./gradlew :${{ matrix.mc }}:build --stacktrace

      - name: upload jar
        uses: actions/upload-artifact@v7
        with:
          name: betterhud-mc${{ matrix.mc }}
          path: versions/${{ matrix.mc }}/build/libs/*.jar

  # One job per supported Minecraft version (not per build variant): the
  # 1.21 variant jar is launch-tested on 1.21-1.21.5, the 1.21.6 variant jar
  # on 1.21.6-1.21.11, and so on.
  #
  # pregen_world marks versions whose Fabric API has no client gametest module
  # (before 1.21.4): for those a vanilla world save is generated first with
  # that version's dedicated server, and the client auto-joins it instead of
  # creating one through the gametest API.
  launch-test:
    name: launch mc${{ matrix.mc }}
    runs-on: ubuntu-24.04
    needs: matrices
    timeout-minutes: 40
    strategy:
      fail-fast: false
      matrix:
        include: ${{ fromJson(needs.matrices.outputs.launch) }}
    steps:
      - name: checkout repository
        uses: actions/checkout@v6

      - name: validate gradle wrapper
        uses: gradle/actions/wrapper-validation@v6

      - name: setup jdk ${{ matrix.java }}
        uses: actions/setup-java@v5
        with:
          java-version: ${{ matrix.java }}
          distribution: 'microsoft'

      - name: setup gradle with dependency caching
        uses: gradle/actions/setup-gradle@v6

      - name: make gradle wrapper executable
        run: chmod +x ./gradlew

      - name: install xvfb
        # Provides a virtual display so the Minecraft client can launch headlessly.
        run: sudo apt-get update && sudo apt-get install -y xvfb

      - name: generate singleplayer test world
        if: ${{ matrix.pregen_world }}
        run: bash .github/scripts/generate-test-world.sh ${{ matrix.mc }}

      - name: launch minecraft ${{ matrix.mc }} with mod
        # Two attempts (not the default three): a real game crash fails both,
        # and a second full launch still fits the 40-minute job timeout.
        env:
          RETRY_ATTEMPTS: '2'
        run: bash .github/scripts/retry.sh ./gradlew :launchtest:runProductionClientGameTest -PtestMcVersion=${{ matrix.mc }} --stacktrace

      - name: check survival world screenshot was taken
        run: test -n "$(find launchtest/run/screenshots -name '*betterhud-survival-world.png' -print -quit 2>/dev/null)"

      - name: upload screenshots
        # Consumed by the screenshot-report job below.
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: launch-screenshots-mc${{ matrix.mc }}
          path: launchtest/run/screenshots/
          if-no-files-found: ignore

      - name: upload game logs
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: launch-logs-mc${{ matrix.mc }}
          path: launchtest/run/logs/
          if-no-files-found: ignore

  screenshot-report:
    name: screenshot report
    runs-on: ubuntu-24.04
    needs: launch-test
    if: ${{ always() }}
    steps:
      - name: checkout repository
        uses: actions/checkout@v6

      - name: publish screenshots to the ci-screenshots branch
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: bash .github/scripts/publish-screenshots.sh

      - name: post screenshot grid to pull request and job summary
        uses: actions/github-script@v8
        with:
          script: |
            const fs = require('fs');

            const versions = Object.keys(JSON.parse(fs.readFileSync('supported-versions.json', 'utf8')));
            const dir = `screenshots-publish/${context.sha}`;
            const base = `https://raw.githubusercontent.com/${context.repo.owner}/${context.repo.repo}/ci-screenshots/${context.sha}`;

            const cells = versions.map(v => {
              const file = `mc-${v}-survival.png`;
              const ok = fs.existsSync(`${dir}/${file}`);
              return ok
                ? `<td align="center"><b>${v}</b><br><a href="${base}/${file}"><img src="${base}/${file}" width="200" alt="BetterHUD on Minecraft ${v}"></a></td>`
                : `<td align="center"><b>${v}</b><br>❌ no screenshot</td>`;
            });
            let rows = '';
            for (let i = 0; i < cells.length; i += 4) {
              rows += `<tr>${cells.slice(i, i + 4).join('')}</tr>\n`;
            }

            const marker = '<!-- betterhud-launch-screenshots -->';
            const body = [
              marker,
              `The game launched and entered a survival singleplayer world with the HUD active, on every supported Minecraft version, for \`${context.sha.slice(0, 7)}\`. A ❌ means that version's launch test did not produce a screenshot — check its job. Title-screen screenshots and game logs are in the run artifacts.`,
              '',
              `<table>\n${rows}</table>`,
            ].join('\n');

            // Always show the grid in the job summary, even without a PR.
            await core.summary.addRaw(body).write();

            const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
              owner: context.repo.owner,
              repo: context.repo.repo,
              commit_sha: context.sha,
            });
            const pr = prs.find(p => p.state === 'open');
            if (!pr) {
              core.info('No open pull request for this commit, skipping comment');
              return;
            }

            // Keep a single comment up to date instead of posting one per push.
            const { data: comments } = await github.rest.issues.listComments({
              owner: context.repo.owner, repo: context.repo.repo,
              issue_number: pr.number, per_page: 100,
            });
            const existing = comments.find(c => c.body && c.body.includes(marker));
            if (existing) {
              await github.rest.issues.updateComment({
                owner: context.repo.owner, repo: context.repo.repo,
                comment_id: existing.id, body,
              });
            } else {
              await github.rest.issues.createComment({
                owner: context.repo.owner, repo: context.repo.repo,
                issue_number: pr.number, body,
              });
            }

  # Builds every variant and bundles the release jars together with UPLOAD.md,
  # which lists exactly which Minecraft versions to select for each jar when
  # uploading to Modrinth. Download the "modrinth-upload" artifact and follow it.
  modrinth-bundle:
    name: modrinth bundle
    runs-on: ubuntu-24.04
    steps:
      - name: checkout repository
        uses: actions/checkout@v6

      - name: validate gradle wrapper
        uses: gradle/actions/wrapper-validation@v6

      - name: setup jdk 21 and 25
        uses: actions/setup-java@v5
        with:
          java-version: |
            21
            25
          distribution: 'microsoft'

      - name: setup gradle with dependency caching
        uses: gradle/actions/setup-gradle@v6

      - name: make gradle wrapper executable
        run: chmod +x ./gradlew

      - name: build all variants and write the upload guide
        run: bash .github/scripts/retry.sh ./gradlew modrinthBundle --stacktrace "-Porg.gradle.java.installations.paths=$JAVA_HOME_21_X64,$JAVA_HOME_25_X64"

      - name: upload modrinth bundle
        uses: actions/upload-artifact@v7
        with:
          name: modrinth-upload
          path: build/modrinth/