Add root archive packaging, weapon sound shaders

Introduce root package archive support and weapon sound shader handling, plus release tooling enhancements. Adds Makefile targets and scripts to build a FnQuake3-pkg.fnz root archive and includes many pkg assets (.azb maps, sound shader). Integrates a SoundShaderLibrary that parses sound/fnq3-weapon-sounds.sndshd and applies per-sample settings (gain, distance/range scales, wet/pitch) throughout the OpenAL audio pipeline; SoundSample now carries shader settings and spatial/gain computations and OpenAL source configuration are scaled accordingly. Update qcommon file handling to recognize and enumerate allowed root-archive entries and search candidate paths. CI and dev tools updated: GitHub Actions now verify release layout and optionally generate Copilot highlights, release notes workflow saves/consumes highlights and clears pending changelog; VSCode build/release script and tasks support producing and verifying the root archive. Also add related scripts and tests, and update documentation links to the Releases page.

Author: themuffinator

.github/release-notes-instructions.md

@@ -0,0 +1,25 @@
+# FnQuake3 Release Notes Instructions
+
+Use `docs/fnquake3/CHANGELOG.md`, merged PRs, commit messages, and relevant diffs as raw material. Write for players, server operators, mod users, and testers.
+
+## Categories
+
+Use third-level Markdown headings and omit empty categories:
+
+- `### Highlights` for the most important user-facing changes.
+- `### Compatibility` for retail Quake III Arena, demo, protocol, VM, pak, or asset-loading behavior.
+- `### Rendering and Display` for renderer, display, screenshot, texture, lighting, shader, GLx, OpenGL, or Vulkan changes.
+- `### Audio` for audio backend, device, codec, HRTF, EFX, or streaming changes.
+- `### Builds and Packaging` for release archives, platform builds, dependencies, CI outputs, and install layout.
+- `### Fixes` for bugs, crashes, regressions, and stability work.
+- `### Documentation and Tooling` only for user-visible docs or tools.
+
+## Cleanup Rules
+
+- Remove duplicates and merge near-duplicates.
+- Prefer the changelog entry when it is clearer than the raw commit or PR title.
+- Keep the final notes under 12 bullets unless the release genuinely needs more.
+- Skip internal-only refactors, test reshuffling, generated-file churn, and maintainer planning docs unless they change a player-visible result or release package.
+- Do not invent features, fixes, platforms, compatibility claims, or performance claims.
+- Use concise present-tense bullets with no author attributions.
+- Do not include a top-level release title; the release workflow adds build details separately.

.github/workflows/release.yml

@@ -96,6 +96,10 @@ jobs:
           meson compile -C meson/build-${{ matrix.arch }}
           meson install -C meson/build-${{ matrix.arch }} --no-rebuild
 
+      - name: Verify release layout
+        shell: msys2 {0}
+        run: python scripts/verify_release_layout.py bin
+
       - uses: actions/upload-artifact@v7
         with:
           name: windows-mingw-${{ matrix.arch }}
@@ -151,6 +155,9 @@ jobs:
           meson compile -C meson\build-${{ matrix.arch }} || exit /b
           meson install -C meson\build-${{ matrix.arch }} --no-rebuild || exit /b
 
+      - name: Verify release layout
+        run: python scripts/verify_release_layout.py bin
+
       - uses: actions/upload-artifact@v7
         with:
           name: windows-msvc-${{ matrix.pkg_suffix }}
@@ -237,6 +244,9 @@ jobs:
       - name: Check glibc baseline
         run: python3 scripts/check_elf_glibc.py --max-glibc "$FNQ3_LINUX_GLIBC_MAX" --require-elf bin
 
+      - name: Verify release layout
+        run: python3 scripts/verify_release_layout.py bin
+
       - uses: actions/upload-artifact@v7
         with:
           name: linux-${{ matrix.arch }}
@@ -273,6 +283,9 @@ jobs:
       - name: Check glibc baseline
         run: python3 scripts/check_elf_glibc.py --max-glibc "$FNQ3_LINUX_GLIBC_MAX" --require-elf bin
 
+      - name: Verify release layout
+        run: python3 scripts/verify_release_layout.py bin
+
       - uses: actions/upload-artifact@v7
         with:
           name: linux-arm64
@@ -326,6 +339,9 @@ jobs:
           VORBIS_LIBS="$(pkg-config --libs vorbisfile)" \
             gmake install -j$(sysctl -n hw.logicalcpu) ARCH=${{ matrix.arch }} CC=clang DESTDIR=bin INSTALL=ginstall USE_LOCAL_HEADERS=0 USE_SYSTEM_JPEG=1 USE_SYSTEM_OGG=1 USE_SYSTEM_VORBIS=1 USE_RENDERER_DLOPEN=1 USE_OPENGL=1 USE_GLX=1 USE_VULKAN=1 STRIP=echo
 
+      - name: Verify release layout
+        run: python3 scripts/verify_release_layout.py bin
+
       - uses: actions/upload-artifact@v7
         with:
           name: macos-${{ matrix.arch }}
@@ -369,6 +385,9 @@ jobs:
     permissions:
       contents: write
       models: read
+      pull-requests: read
+    env:
+      HAS_COPILOT_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN != '' }}
     steps:
       - uses: actions/checkout@v6
         with:
@@ -394,6 +413,25 @@ jobs:
         run: |
           python scripts/release.py --channel manual --artifact-root artifacts --build-number "${{ needs.prepare.outputs.build_number }}" --build-date "${{ needs.prepare.outputs.build_date }}" --commit "${{ needs.prepare.outputs.head_commit }}"
 
+      - name: Build Copilot changelog cleanup
+        id: copilot_notes
+        if: ${{ env.HAS_COPILOT_TOKEN == 'true' && needs.prepare.outputs.previous_release_commit != '' }}
+        uses: github/copilot-release-notes@v1.0.1
+        with:
+          base-ref: ${{ needs.prepare.outputs.previous_release_commit }}
+          head-ref: ${{ needs.prepare.outputs.head_commit }}
+          instructions: .github/release-notes-instructions.md
+        env:
+          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+
+      - name: Save Copilot highlights
+        if: ${{ steps.copilot_notes.outputs.release-notes != '' }}
+        env:
+          COPILOT_RELEASE_NOTES: ${{ steps.copilot_notes.outputs.release-notes }}
+        run: |
+          mkdir -p .tmp
+          printf '%s\n' "$COPILOT_RELEASE_NOTES" > .tmp/copilot-release-notes.md
+
       - name: Build release notes
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -402,11 +440,16 @@ jobs:
           if [ -n "${{ needs.prepare.outputs.previous_release_commit }}" ]; then
             FROM_ARGS+=(--from-commit "${{ needs.prepare.outputs.previous_release_commit }}")
           fi
+          HIGHLIGHTS_ARGS=()
+          if [ -s .tmp/copilot-release-notes.md ]; then
+            HIGHLIGHTS_ARGS+=(--highlights-file .tmp/copilot-release-notes.md)
+          fi
           python scripts/manual_release.py release-notes \
             --build-number "${{ needs.prepare.outputs.build_number }}" \
             --build-date "${{ needs.prepare.outputs.build_date }}" \
             --to-commit "${{ needs.prepare.outputs.head_commit }}" \
             "${FROM_ARGS[@]}" \
+            "${HIGHLIGHTS_ARGS[@]}" \
             --output .tmp/release-notes.md
 
       - name: Create release
@@ -420,3 +463,17 @@ jobs:
             --target "${{ needs.prepare.outputs.head_commit }}" \
             --title "${FNQ3_RELEASE_TITLE}" \
             --notes-file .tmp/release-notes.md
+
+      - name: Clear pending changelog
+        if: ${{ github.ref_type == 'branch' }}
+        run: |
+          python scripts/changelog.py clear-unreleased
+          if git diff --quiet -- docs/fnquake3/CHANGELOG.md; then
+            echo "Pending changelog already clean."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add docs/fnquake3/CHANGELOG.md
+          git commit -m "Reset pending changelog after release"
+          git push origin "HEAD:${GITHUB_REF_NAME}"

.install/README.html

@@ -374,7 +374,7 @@ <h3>Player guides</h3>
             <li><a href="https://github.com/themuffinator/FnQ3/blob/main/docs/AUDIO.md">Audio Guide</a> for backend selection, devices, HRTF, fallback behavior, and troubleshooting.</li>
             <li><a href="https://github.com/themuffinator/FnQ3/blob/main/docs/CONSOLE.md">Console Guide</a> for console layout, scaling, completion, and interaction.</li>
             <li><a href="https://github.com/themuffinator/FnQ3/blob/main/docs/SCREENSHOTS.md">Screenshot Guide</a> for capture commands, naming, metadata sidecars, watermarks, and cube-map export.</li>
-            <li><a href="https://github.com/themuffinator/FnQ3/blob/main/docs/fnquake3/CHANGELOG.md">Changelog</a> for release-facing change history.</li>
+            <li><a href="https://github.com/themuffinator/FnQ3/releases">Release History</a> for published changelogs and downloads.</li>
           </ul>
         </article>
         <article class="doc-column">

.vscode/build-release.ps1

@@ -19,7 +19,9 @@ param(
 	[switch]$SetupOnly,
 	[switch]$RunTests,
 	[switch]$Install,
-	[string]$DestDir = $(if ($env:FNQ3_MESON_DESTDIR) { $env:FNQ3_MESON_DESTDIR } else { '' })
+	[string]$DestDir = $(if ($env:FNQ3_MESON_DESTDIR) { $env:FNQ3_MESON_DESTDIR } else { '' }),
+	[switch]$Archive,
+	[string]$RootArchiveName = $(if ($env:FNQ3_MESON_ROOT_ARCHIVE_NAME) { $env:FNQ3_MESON_ROOT_ARCHIVE_NAME } else { 'FnQuake3-pkg.fnz' })
 )
 
 $ErrorActionPreference = 'Stop'
@@ -181,6 +183,28 @@ function Clear-StaleMesonArchive {
 	}
 }
 
+function Invoke-MesonInstall {
+	param(
+		[string]$MesonPath,
+		[string]$BuildPath,
+		[string]$SelectedDestDir,
+		[string]$InstallTags = ''
+	)
+
+	$installArgs = @('install', '-C', $BuildPath, '--no-rebuild')
+	if ($SelectedDestDir) {
+		$installArgs += @('--destdir', $SelectedDestDir)
+	}
+	if ($InstallTags) {
+		$installArgs += @('--tags', $InstallTags)
+	}
+	Write-Host "==> $MesonPath $($installArgs -join ' ')"
+	& $MesonPath @installArgs
+	if ($LASTEXITCODE -ne 0) {
+		throw 'Meson install failed.'
+	}
+}
+
 $workspaceRoot = Split-Path -Parent $PSScriptRoot
 $buildPath = Resolve-BuildPath -WorkspaceRoot $workspaceRoot -SelectedBuildDir $BuildDir
 $buildType = Convert-BuildType -SelectedConfiguration $Configuration
@@ -197,6 +221,9 @@ Write-Host "Target: $Target"
 Write-Host "Build directory: $buildPath"
 Write-Host "Renderer modules: $rendererCsv"
 Write-Host "Renderer default: $RendererDefault"
+if ($Archive) {
+	Write-Host "Root package archive: $(Join-Path $buildPath $RootArchiveName)"
+}
 
 $coreDataPath = Join-Path $buildPath 'meson-private\coredata.dat'
 $setupArgs = @(
@@ -233,6 +260,7 @@ if ($SetupOnly) {
 }
 
 Clear-StaleMesonArchive -BuildPath $buildPath -ArchiveName 'libbotlib.a'
+Clear-StaleMesonArchive -BuildPath $buildPath -ArchiveName $RootArchiveName
 
 $compileArgs = @('compile', '-C', $buildPath)
 Write-Host "==> $mesonPath $($compileArgs -join ' ')"
@@ -253,15 +281,22 @@ if ($RunTests) {
 }
 
 if ($Install) {
-	$installArgs = @('install', '-C', $buildPath)
-	if ($DestDir) {
-		$installArgs += @('--destdir', $DestDir)
+	Invoke-MesonInstall -MesonPath $mesonPath -BuildPath $buildPath -SelectedDestDir $DestDir
+}
+
+if ($Archive) {
+	$archivePath = Join-Path $buildPath $RootArchiveName
+	if (-not (Test-Path $archivePath)) {
+		throw "Root package archive was not produced: $archivePath"
 	}
-	Write-Host "==> $mesonPath $($installArgs -join ' ')"
-	& $mesonPath @installArgs
+	$verifyScript = Join-Path $workspaceRoot 'scripts\verify_release_layout.py'
+	Write-Host "==> python $verifyScript $archivePath"
+	& python $verifyScript $archivePath
 	if ($LASTEXITCODE -ne 0) {
-		throw 'Meson install failed.'
+		throw 'Root package archive verification failed.'
 	}
+
+	Write-Host "Root package archive ready: $archivePath"
 }
 
 Write-Host 'Meson release build completed.'

.vscode/tasks.json

@@ -31,7 +31,8 @@
         "-Target",
         "both",
         "-Renderers",
-        "opengl,glx,vulkan,opengl2"
+        "opengl,glx,vulkan,opengl2",
+        "-Archive"
       ],
       "problemMatcher": [
         "$gcc",

Makefile

@@ -139,6 +139,10 @@ ifndef BUILD_DIR
 BUILD_DIR=build
 endif
 
+ifndef PYTHON
+PYTHON=python3
+endif
+
 ifndef GENERATE_DEPENDENCIES
 GENERATE_DEPENDENCIES=1
 endif
@@ -729,6 +733,47 @@ TARGET_RENDV = $(RENDERER_PREFIX)_vulkan_$(SHLIBNAME)
 
 TARGET_SERVER = $(DNAME)$(ARCHEXT)$(BINEXT)
 
+STANDARD_AUDIO_ZONE_MAPS = \
+  pro-q3dm13 \
+  pro-q3dm6 \
+  pro-q3tourney2 \
+  pro-q3tourney4 \
+  q3ctf1 \
+  q3ctf2 \
+  q3ctf3 \
+  q3ctf4 \
+  q3dm0 \
+  q3dm1 \
+  q3dm10 \
+  q3dm11 \
+  q3dm12 \
+  q3dm13 \
+  q3dm14 \
+  q3dm15 \
+  q3dm16 \
+  q3dm17 \
+  q3dm18 \
+  q3dm19 \
+  q3dm2 \
+  q3dm3 \
+  q3dm4 \
+  q3dm5 \
+  q3dm6 \
+  q3dm7 \
+  q3dm8 \
+  q3dm9 \
+  q3tourney1 \
+  q3tourney2 \
+  q3tourney3 \
+  q3tourney4 \
+  q3tourney5 \
+  q3tourney6 \
+  q3tourney6_ctf
+PKG_ROOT = pkg
+STANDARD_AUDIO_ZONE_FILES = $(addprefix $(PKG_ROOT)/baseq3/maps/,$(addsuffix .azb,$(STANDARD_AUDIO_ZONE_MAPS)))
+PKG_FILES = $(shell find $(PKG_ROOT) -type f 2>/dev/null)
+ROOT_ARCHIVE = FnQuake3-pkg.fnz
+
 STRINGIFY = $(B)/rend2/stringify$(BINEXT)
 
 TARGETS =
@@ -921,10 +966,9 @@ endif
 	do \
 		echo "    $$i"; \
 	done
+	@echo "    $(B)/$(ROOT_ARCHIVE)"
 	@echo ""
-ifneq ($(TARGETS),)
-	+@$(RECURSIVE_MAKE) $(TARGETS) V=$(V)
-endif
+	+@$(RECURSIVE_MAKE) $(TARGETS) $(B)/$(ROOT_ARCHIVE) V=$(V)
 
 makedirs:
 	@if [ ! -d $(BUILD_DIR) ];then $(MKDIR) $(BUILD_DIR);fi
@@ -1766,6 +1810,10 @@ $(B)/ded/%.o: $(W32DIR)/%.cpp
 $(B)/ded/%.o: $(W32DIR)/%.rc
 	$(DO_WINDRES)
 
+$(B)/$(ROOT_ARCHIVE): $(TARGETS) $(PKG_FILES) scripts/build_root_archive.py scripts/root_archive.py scripts/fnq3_meta.py
+	$(echo_cmd) "ROOTARCHIVE $@"
+	$(Q)$(PYTHON) scripts/build_root_archive.py --package-root "$(PKG_ROOT)" --output "$@"
+
 #############################################################################
 # MISC
 #############################################################################
@@ -1777,6 +1825,7 @@ install: release
 			$(STRIP) "$(DESTDIR)$$i"; \
 		fi \
 	done
+	$(INSTALL) -D -m 0644 "$(BR)/$(ROOT_ARCHIVE)" "$(DESTDIR)/$(ROOT_ARCHIVE)"
 
 clean: clean-debug clean-release
 

README.md

@@ -67,7 +67,7 @@ If you want to compile FnQuake3 yourself instead, start with the [Build Guide](B
 - [Audio Guide](docs/AUDIO.md) for backend selection, devices, HRTF, fallback behavior, and troubleshooting.
 - [Console Guide](docs/CONSOLE.md) for console layout, scaling, completion, and interaction.
 - [Screenshot Guide](docs/SCREENSHOTS.md) for capture commands, naming, metadata sidecars, watermarks, and cube-map export.
-- [Changelog](docs/fnquake3/CHANGELOG.md) for release-facing change history.
+- [Release History](https://github.com/themuffinator/FnQ3/releases) for published changelogs and downloads.
 
 ### Technical and build docs