feat(shooter): qualify bounded receiver decals with atlas and fade [VQ11]

.github/workflows/integration-decals.yml

@@ -0,0 +1,105 @@
+name: Integration bounded decals
+on:
+  pull_request:
+    paths:
+      - 'packages/create-threenative/templates/shooter/src/render/decals.ts'
+      - 'packages/create-threenative/templates/shooter/src/scenes/Play.ts'
+      - 'packages/create-threenative/__tests__/shooter-decals*.spec.ts'
+      - 'packages/create-threenative/__tests__/fixtures/bounded-decals/**'
+      - '.github/workflows/integration-decals.yml'
+  push:
+    branches: ['fix/vq11-decal-material-lifetime']
+permissions:
+  contents: read
+concurrency:
+  group: integration-decals-${{ github.event.pull_request.head.ref || github.ref_name }}
+  cancel-in-progress: true
+jobs:
+  decals:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - uses: ./.github/actions/pnpm
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: '22'
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - uses: ./.github/actions/workspace-dist
+        with:
+          pack-archives: 'false'
+          save-bundles: 'false'
+      - uses: ./.github/actions/playwright-chromium
+      - run: pnpm exec vitest run --maxWorkers=1 packages/create-threenative/__tests__/shooter-decals-projection.spec.ts packages/create-threenative/__tests__/shooter-decals-fixture.spec.ts packages/create-threenative/__tests__/shooter-decals-lifetime.spec.ts packages/create-threenative/__tests__/template-runtime-cost.spec.ts
+      - name: Capture actual receiver projection, motion, removal and restart
+        run: node --import tsx packages/create-threenative/__tests__/fixtures/bounded-decals/verify.ts
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: vq11-decals-${{ github.event.pull_request.head.sha || github.sha }}
+          path: artifacts/vq11-decals
+          if-no-files-found: error
+  native:
+    name: Linux native decal correctness
+    needs: [decals]
+    # Reuse the proven native-platforms / native-assets ARM QuickJS route without changing defaults.
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 60
+    env:
+      CMAKE_BUILD_PARALLEL_LEVEL: '2'
+      TN_PLAYTEST_ALLOW_SOFTWARE: '1'
+      TN_PLAYTEST_NATIVE_SCREENSHOT_TIMEOUT_MS: '30000'
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - uses: ./.github/actions/pnpm
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: '22'
+          cache: pnpm
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+      - run: pnpm install --frozen-lockfile
+      - name: Build this source's public JavaScript packages
+        uses: ./.github/actions/workspace-dist
+        with:
+          save-bundles: 'false'
+          pack-archives: 'false'
+      - name: Verify native preflight and capture rejection controls
+        run: pnpm exec vitest run packages/create-threenative/__tests__/shooter-decals-native.spec.ts --maxWorkers=1
+      - name: Restore checksum-provisioned native dependencies
+        uses: actions/cache/restore@v4
+        with:
+          path: packages/runtime-native/third_party
+          key: native-third-party-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('packages/runtime-native/scripts/download-deps.mjs', 'packages/runtime-native/scripts/package-android.mjs') }}
+      - name: Install the existing native lane's system prerequisites
+        run: >-
+          sudo apt-get update && sudo apt-get install -y
+          libasound2-dev libcurl4-openssl-dev libfontconfig1-dev libfreetype6-dev
+          libpulse-dev libudev-dev libx11-dev libxext-dev libxrandr-dev
+          libxcursor-dev libxi-dev libxfixes-dev libxss-dev libxkbcommon-dev
+          libgtk-3-dev libwebkit2gtk-4.1-dev libxcomposite-dev xcompmgr
+          libvulkan1 mesa-vulkan-drivers vulkan-tools xvfb zlib1g-dev
+      - name: Build the ordinary ARM desktop host
+        run: pnpm --filter @threenative/runtime-native native:build
+      - name: Run the same packaged decal scenarios and unchanged pixel gates
+        env:
+          THREENATIVE_RUNTIME_BINARY: ${{ github.workspace }}/packages/runtime-native/build/tn-linux/mystral
+        run: node --import tsx packages/create-threenative/__tests__/fixtures/bounded-decals/verify-native.ts
+      - name: Retain native screenshots, host console and executable identities
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: vq11-decals-native-${{ github.event.pull_request.head.sha || github.sha }}
+          path: |
+            artifacts/vq11-decals-native/
+            !artifacts/vq11-decals-native/variants/**
+          retention-days: 30
+          if-no-files-found: warn