mirror of
https://github.com/Cesarus85/ringfall-mjolnir-vr.git
synced 2026-10-27 00:00:42 +01:00
Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Stefan MaierandClaude Opus 5.5
|
28fdc704c6 |
No files matched your search
@@ -1,4 +0,0 @@
|
||||
# Files that a Linux shell runs directly must keep LF line endings in a
|
||||
# Windows checkout (core.autocrlf): a CRLF shebang line does not start.
|
||||
*.sh text eol=lf
|
||||
port/android/gradlew text eol=lf
|
||||
@@ -1,38 +0,0 @@
|
||||
name: Problem report
|
||||
description: Something does not work as it should
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thanks for reporting! Please do **not** ask for, link to or attach game files or disc images; such issues are closed and deleted.
|
||||
- type: dropdown
|
||||
id: headset
|
||||
attributes:
|
||||
label: Headset
|
||||
options:
|
||||
- Meta Quest 3
|
||||
- Meta Quest 3S
|
||||
- Steam Frame
|
||||
- Other
|
||||
validations:
|
||||
required: true
|
||||
- type: input
|
||||
id: build
|
||||
attributes:
|
||||
label: Build number
|
||||
description: The release you installed, e.g. "build 180".
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: what
|
||||
attributes:
|
||||
label: What happened
|
||||
description: What you did, what you expected and what happened instead.
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: log
|
||||
attributes:
|
||||
label: Log
|
||||
description: |
|
||||
Attach `debug.txt`. Quest: `Android/data/io.github.cesarus85.ringfall/files/debug.txt` (SideQuest's file manager). Steam Frame: `Documents/RingfallMjolnirVR/debug.txt`, and `logcat.txt` and `install.log` beside it.
|
||||
@@ -1,5 +0,0 @@
|
||||
blank_issues_enabled: true
|
||||
contact_links:
|
||||
- name: How to install
|
||||
url: https://github.com/Cesarus85/mjolnir-vr#install-on-meta-quest-3--3s
|
||||
about: Step-by-step installation for the Quest 3 / 3S and the Steam Frame.
|
||||
+14
-475
@@ -1,41 +1,26 @@
|
||||
name: Build
|
||||
|
||||
# Debug and release builds of the native ports (Linux, Windows, Android) and
|
||||
# the web port for every pushed commit, uploaded as artifacts.
|
||||
# tools/ci_build.py does each build; see it for the options.
|
||||
# Debug and release builds of the native ports (Linux, Windows, Android) for
|
||||
# every pushed commit, uploaded as artifacts. tools/ci_build.py does each
|
||||
# build; see it for the options.
|
||||
#
|
||||
# Kept cheap:
|
||||
# - one job per platform builds both configurations, so its set-up (tools,
|
||||
# downloads, caches) is paid once;
|
||||
# - compiles go through ccache, whose cache carries over from run to run, so
|
||||
# a commit only recompiles what it changed; downloads (SDL, musl, Gradle,
|
||||
# the Linux build's system root) are cached too;
|
||||
# a commit only recompiles what it changed; downloads (SDL, musl, Gradle)
|
||||
# are cached too;
|
||||
# - a newer push to the same branch cancels a run still going;
|
||||
# - pushes that only change documentation do not build;
|
||||
# - Windows, whose minutes cost twice Linux's, builds only Windows;
|
||||
# - Mjolnir VR builds only Android (the VR app): the Linux and
|
||||
# Windows jobs are kept, off (if: false), so that upstream's changes to
|
||||
# them still merge;
|
||||
# - artifacts are kept for three days.
|
||||
#
|
||||
# A successful build of main is also published as a GitHub release, the
|
||||
# newest marked latest, so that
|
||||
# https://github.com/<repository>/releases/latest/download/<file> always
|
||||
# gives the latest build; the last five are kept. Its web build is then the
|
||||
# site on GitHub Pages (https://halocombatevolved.com/, port/web/README.md).
|
||||
on:
|
||||
# (Mjolnir VR: main only; its branches are tried on the headsets
|
||||
# from local builds)
|
||||
push:
|
||||
branches: [main]
|
||||
paths-ignore:
|
||||
- "**.md"
|
||||
- "docs/**"
|
||||
- "research/**"
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
profile:
|
||||
description: "Also build the profiling flavour (configure.py --profile) on Linux"
|
||||
type: boolean
|
||||
default: false
|
||||
|
||||
concurrency:
|
||||
group: build-${{ github.ref }}
|
||||
@@ -52,14 +37,8 @@ env:
|
||||
|
||||
jobs:
|
||||
linux:
|
||||
# (off: Mjolnir VR ships the Android app only)
|
||||
if: ${{ false }}
|
||||
# Arch Linux has what the build needs as packages: clang 22 (for the
|
||||
# profile-guided optimisation in pgo/), and CMake, pkg-config and
|
||||
# wayland-scanner for the SDL 3 that the portable build brings. The build
|
||||
# links against Debian 11's 32-bit glibc (tools/linux_sysroot.py), not
|
||||
# Arch's, so that it starts on SteamOS and older distributions; Arch's
|
||||
# 32-bit glibc is for the tests.
|
||||
# profile-guided optimisation in pgo/) and 32-bit SDL 3.
|
||||
runs-on: ubuntu-24.04
|
||||
container: archlinux:latest
|
||||
timeout-minutes: 40
|
||||
@@ -68,7 +47,7 @@ jobs:
|
||||
run: |
|
||||
printf '\n[multilib]\nInclude = /etc/pacman.d/mirrorlist\n' >> /etc/pacman.conf
|
||||
pacman -Syu --noconfirm --needed git zstd python python-pytest ninja ccache \
|
||||
clang lld gcc lib32-glibc lib32-gcc-libs cmake pkgconf wayland
|
||||
clang lld gcc lib32-glibc lib32-gcc-libs lib32-sdl3
|
||||
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
@@ -78,29 +57,14 @@ jobs:
|
||||
key: ccache-linux-${{ github.sha }}
|
||||
restore-keys: ccache-linux-
|
||||
|
||||
# the system root and SDL's source, which the build downloads
|
||||
- uses: actions/cache@v4
|
||||
with:
|
||||
path: build/linux/third_party
|
||||
key: linux-third-party-${{ hashFiles('tools/linux_sysroot.py') }}
|
||||
|
||||
- name: Debug
|
||||
run: python tools/ci_build.py linux debug
|
||||
|
||||
# (the profiling build, configure.py --profile, which no other step
|
||||
# compiles: only when a run started by hand asks for it, as it costs a
|
||||
# build of its own)
|
||||
- name: Profile
|
||||
if: github.event_name == 'workflow_dispatch' && inputs.profile
|
||||
run: python tools/ci_build.py linux profile
|
||||
|
||||
- name: Release
|
||||
run: python tools/ci_build.py linux release
|
||||
|
||||
- name: Test
|
||||
run: |
|
||||
python -m pytest -q tools/test_linux_port.py tools/test_android_asm_convert.py tools/test_android_mirror_uploads.py tools/test_android_ce_texture_cache.py tools/test_host_watch_hash.py tools/test_touch_menu.py tools/harness tools/test_profile.py tools/stagekit/tests tools/test_net_compare.py
|
||||
python tools/test_light_storage.py
|
||||
run: python -m pytest -q tools/test_linux_port.py
|
||||
|
||||
- name: Compile cache
|
||||
run: ccache --show-stats
|
||||
@@ -125,15 +89,10 @@ jobs:
|
||||
- name: Install the toolchain
|
||||
run: |
|
||||
mkdir -p "$RUNNER_TEMP/tools"
|
||||
# (each download checked against the hash it had when it was pinned)
|
||||
curl -fsSL -o ninja.zip https://github.com/ninja-build/ninja/releases/download/v1.12.1/ninja-linux.zip
|
||||
curl -fsSL -o ccache.tar.xz https://github.com/ccache/ccache/releases/download/v4.10.2/ccache-4.10.2-linux-x86_64.tar.xz
|
||||
sha256sum -c - <<'EOF'
|
||||
6f98805688d19672bd699fbbfa2c2cf0fc054ac3df1f0e6a47664d963d530255 ninja.zip
|
||||
80cab87bd510eca796467aee8e663c398239e0df1c4800a0b5dff11dca0b4f18 ccache.tar.xz
|
||||
EOF
|
||||
unzip -q ninja.zip -d "$RUNNER_TEMP/tools" && rm ninja.zip
|
||||
tar -xJf ccache.tar.xz -C "$RUNNER_TEMP/tools" --strip-components=1 ccache-4.10.2-linux-x86_64/ccache && rm ccache.tar.xz
|
||||
curl -fsSL https://github.com/ccache/ccache/releases/download/v4.10.2/ccache-4.10.2-linux-x86_64.tar.xz \
|
||||
| tar -xJ -C "$RUNNER_TEMP/tools" --strip-components=1 ccache-4.10.2-linux-x86_64/ccache
|
||||
echo "$RUNNER_TEMP/tools" >> "$GITHUB_PATH"
|
||||
|
||||
- uses: actions/checkout@v4
|
||||
@@ -148,7 +107,7 @@ jobs:
|
||||
- uses: actions/cache@v4
|
||||
with:
|
||||
path: build/android/third_party
|
||||
key: android-third-party-${{ hashFiles('tools/android_build.py', 'port/android/patches/**') }}
|
||||
key: android-third-party-${{ hashFiles('tools/android_build.py') }}
|
||||
|
||||
- uses: actions/cache@v4
|
||||
with:
|
||||
@@ -157,36 +116,12 @@ jobs:
|
||||
~/.gradle/wrapper
|
||||
key: gradle-${{ hashFiles('port/android/**/*.gradle*', 'port/android/gradle/wrapper/gradle-wrapper.properties') }}
|
||||
|
||||
# the app's signing key, from the ANDROID_KEYSTORE_BASE64 secret (a
|
||||
# keystore, base64) and ANDROID_KEYSTORE_PASSWORD (its password, and
|
||||
# the key's, alias halo): every build signed with it installs over the
|
||||
# one before, as the app's self-updater (Updater.java) needs. Without
|
||||
# them each build is signed with the runner's own debug key.
|
||||
- name: Signing key
|
||||
env:
|
||||
KEYSTORE: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
|
||||
run: |
|
||||
if [ -n "$KEYSTORE" ]; then
|
||||
printf '%s' "$KEYSTORE" | base64 -d > "$RUNNER_TEMP/halo.keystore"
|
||||
echo "HALO_ANDROID_KEYSTORE=$RUNNER_TEMP/halo.keystore" >> "$GITHUB_ENV"
|
||||
else
|
||||
echo "::warning::no ANDROID_KEYSTORE_BASE64 secret: the Android builds cannot update over each other"
|
||||
fi
|
||||
|
||||
- name: Debug
|
||||
env:
|
||||
HALO_ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
|
||||
run: python3 tools/ci_build.py android debug
|
||||
|
||||
- name: Release
|
||||
env:
|
||||
HALO_ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
|
||||
run: python3 tools/ci_build.py android release
|
||||
|
||||
# the touch controls' layout and gyroscope maths (the runner's JDK)
|
||||
- name: Test the touch layout
|
||||
run: python3 tools/test_touch_layout.py
|
||||
|
||||
- name: Compile cache
|
||||
run: ccache --show-stats
|
||||
|
||||
@@ -203,8 +138,6 @@ jobs:
|
||||
retention-days: 3
|
||||
|
||||
windows:
|
||||
# (off: Mjolnir VR ships the Android app only)
|
||||
if: ${{ false }}
|
||||
# The runner image has LLVM, Python and Visual Studio's x86 libraries and
|
||||
# Windows SDK.
|
||||
runs-on: windows-2025
|
||||
@@ -217,11 +150,8 @@ jobs:
|
||||
shell: pwsh
|
||||
run: |
|
||||
Invoke-WebRequest -OutFile ninja.zip https://github.com/ninja-build/ninja/releases/download/v1.12.1/ninja-win.zip
|
||||
Invoke-WebRequest -OutFile ccache.zip https://github.com/ccache/ccache/releases/download/v4.10.2/ccache-4.10.2-windows-x86_64.zip
|
||||
# (each download checked against the hash it had when it was pinned)
|
||||
if ((Get-FileHash ninja.zip -Algorithm SHA256).Hash -ne "F550FEC705B6D6FF58F2DB3C374C2277A37691678D6ABA463ADCBB129108467A") { throw "ninja.zip: unexpected SHA-256" }
|
||||
if ((Get-FileHash ccache.zip -Algorithm SHA256).Hash -ne "6252F081876A9A9F700FAE13A5AEC5D0D486B28261D7F1F72AC11C7AD9DF4DA9") { throw "ccache.zip: unexpected SHA-256" }
|
||||
Expand-Archive ninja.zip -DestinationPath "$env:RUNNER_TEMP\tools"
|
||||
Invoke-WebRequest -OutFile ccache.zip https://github.com/ccache/ccache/releases/download/v4.10.2/ccache-4.10.2-windows-x86_64.zip
|
||||
Expand-Archive ccache.zip -DestinationPath $env:RUNNER_TEMP
|
||||
Copy-Item "$env:RUNNER_TEMP\ccache-4.10.2-windows-x86_64\ccache.exe" "$env:RUNNER_TEMP\tools"
|
||||
Remove-Item ninja.zip, ccache.zip
|
||||
@@ -247,9 +177,6 @@ jobs:
|
||||
- name: Release
|
||||
run: python tools/ci_build.py windows release
|
||||
|
||||
- name: Test light storage
|
||||
run: python tools/test_light_storage.py
|
||||
|
||||
- name: Compile cache
|
||||
run: ccache --show-stats
|
||||
|
||||
@@ -264,391 +191,3 @@ jobs:
|
||||
name: halo-windows-release
|
||||
path: dist/halo-windows-release
|
||||
retention-days: 3
|
||||
|
||||
# the PDBs, for crash reports' backtraces (tools/ci_build.py)
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: halo-windows-debug-symbols
|
||||
path: dist/halo-windows-debug-symbols
|
||||
retention-days: 3
|
||||
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: halo-windows-release-symbols
|
||||
path: dist/halo-windows-release-symbols
|
||||
retention-days: 3
|
||||
|
||||
web:
|
||||
# (off: Mjolnir VR ships the Android app only)
|
||||
if: ${{ false }}
|
||||
# Emscripten (emsdk, the version below, cached) builds the web port's
|
||||
# site (port/web/README.md); the tests check its graph, the page's
|
||||
# importer and service worker, its sockets, that it starts in a
|
||||
# headless Chromium (with no game data, as far as the menus' map), and
|
||||
# that two browsers join a room through a local MQTT broker.
|
||||
runs-on: ubuntu-24.04
|
||||
timeout-minutes: 40
|
||||
env:
|
||||
EMSDK_VERSION: 6.0.10
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: actions/cache@v4
|
||||
with:
|
||||
path: ~/emsdk
|
||||
key: emsdk-${{ env.EMSDK_VERSION }}-${{ hashFiles('port/web/halo_sdl3.py') }}
|
||||
|
||||
- name: Install the toolchain
|
||||
run: |
|
||||
if [ ! -x ~/emsdk/upstream/emscripten/emcc ]; then
|
||||
rm -rf ~/emsdk
|
||||
git clone --depth 1 https://github.com/emscripten-core/emsdk.git ~/emsdk
|
||||
~/emsdk/emsdk install "$EMSDK_VERSION"
|
||||
fi
|
||||
~/emsdk/emsdk activate "$EMSDK_VERSION"
|
||||
sudo apt-get update -q
|
||||
sudo apt-get install -y -q ninja-build ccache python3-pytest mosquitto
|
||||
|
||||
- uses: actions/cache@v4
|
||||
with:
|
||||
path: .ccache
|
||||
key: ccache-web-${{ github.sha }}
|
||||
restore-keys: ccache-web-
|
||||
|
||||
- name: Debug
|
||||
run: |
|
||||
source ~/emsdk/emsdk_env.sh
|
||||
python3 tools/ci_build.py web debug
|
||||
|
||||
- name: Release
|
||||
run: |
|
||||
source ~/emsdk/emsdk_env.sh
|
||||
python3 tools/ci_build.py web release
|
||||
|
||||
- name: Test
|
||||
run: |
|
||||
source ~/emsdk/emsdk_env.sh
|
||||
node --test "port/web/tests/*.test.js"
|
||||
python3 -m pytest -q tools/test_web_build.py
|
||||
|
||||
- name: Test in Chromium and Firefox
|
||||
run: |
|
||||
npm install --no-save --prefix "$RUNNER_TEMP/playwright" playwright@1.58
|
||||
"$RUNNER_TEMP/playwright/node_modules/.bin/playwright" install --with-deps chromium firefox
|
||||
NODE_PATH="$RUNNER_TEMP/playwright/node_modules" node port/web/tests/smoke.mjs dist/halo-web-release
|
||||
NODE_PATH="$RUNNER_TEMP/playwright/node_modules" node port/web/tests/rooms.mjs dist/halo-web-release
|
||||
# (the native builds' WebRTC, port/linux/src/p2p_webrtc.c, with both)
|
||||
NODE_PATH="$RUNNER_TEMP/playwright/node_modules" node port/web/tests/webrtc_native.mjs chromium firefox
|
||||
|
||||
- name: Compile cache
|
||||
run: ccache --show-stats
|
||||
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: halo-web-debug
|
||||
path: dist/halo-web-debug
|
||||
include-hidden-files: true
|
||||
retention-days: 3
|
||||
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: halo-web-release
|
||||
path: dist/halo-web-release
|
||||
include-hidden-files: true
|
||||
retention-days: 3
|
||||
|
||||
release:
|
||||
# The eight builds (and the Windows builds' PDBs) as a release, tagged
|
||||
# build-<run number> and marked latest
|
||||
# (every file keeps its name from release to release, for the README's
|
||||
# latest/download links); then all but the newest five build-* releases
|
||||
# go, tags and all. Only for main, and only when every platform built.
|
||||
needs: [android]
|
||||
if: ${{ github.ref == 'refs/heads/main' }}
|
||||
runs-on: ubuntu-24.04
|
||||
timeout-minutes: 15
|
||||
permissions:
|
||||
contents: write
|
||||
outputs:
|
||||
tag: ${{ steps.publish.outputs.tag }}
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
GH_REPO: ${{ github.repository }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
sparse-checkout: |
|
||||
port/android
|
||||
tools
|
||||
|
||||
- uses: actions/download-artifact@v4
|
||||
with:
|
||||
pattern: halo-*
|
||||
path: artifacts
|
||||
|
||||
- name: Package
|
||||
run: |
|
||||
mkdir release
|
||||
# (Mjolnir VR publishes its Android builds only, under
|
||||
# its own name: Updater.java looks for them; the desktop ports are
|
||||
# built to keep them building)
|
||||
for config in debug release; do
|
||||
(cd "artifacts/halo-android-$config" &&
|
||||
zip -qr "$GITHUB_WORKSPACE/release/mjolnir-vr-android-$config.zip" .)
|
||||
done
|
||||
# the Steam Frame's installer (port/android/STEAM_FRAME.md): its
|
||||
# bundle with the release APK, and the desktop file that fetches it
|
||||
python3 tools/steam_frame_bundle.py artifacts/halo-android-release/app-release.apk release "$GH_REPO"
|
||||
# the APK itself, for sideloading on the Quest (SideQuest, adb)
|
||||
cp artifacts/halo-android-release/app-release.apk release/MjolnirVR.apk
|
||||
# the same under the names before "Mjolnir VR" (Ringfall: Mjolnir
|
||||
# VR, builds 302 to 313): their updaters (Updater.java, the Frame's
|
||||
# launcher) and the links already shared ask for them
|
||||
cp release/mjolnir-vr-android-debug.zip release/ringfall-mjolnir-vr-android-debug.zip
|
||||
cp release/mjolnir-vr-android-release.zip release/ringfall-mjolnir-vr-android-release.zip
|
||||
cp release/mjolnir-vr-steam-frame.zip release/ringfall-mjolnir-vr-steam-frame.zip
|
||||
cp release/Install-Mjolnir-VR.desktop release/Install-Ringfall-Mjolnir-VR.desktop
|
||||
cp release/MjolnirVR.apk release/RingfallMjolnirVR.apk
|
||||
ls -l release
|
||||
|
||||
- name: Publish
|
||||
id: publish
|
||||
env:
|
||||
MESSAGE: ${{ github.event.head_commit.message }}
|
||||
COMMIT_URL: ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}
|
||||
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
|
||||
run: |
|
||||
tag="build-$GITHUB_RUN_NUMBER"
|
||||
subject="$(printf '%s' "${MESSAGE:-manual run}" | head -n 1)"
|
||||
readme="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY"
|
||||
{
|
||||
printf '%s\n\n' "$subject"
|
||||
printf '**Mjolnir VR** is an unofficial VR mod for Halo: Combat Evolved. It needs a disc image of your own, purchased Xbox copy of the game; no game files are included.\n\n'
|
||||
printf '| Headset | Download | How to install |\n| --- | --- | --- |\n'
|
||||
printf '| Meta Quest 3 / 3S | `MjolnirVR.apk` | [Install on Quest](%s#install-on-meta-quest-3--3s) |\n' "$readme"
|
||||
printf '| Steam Frame | `Install-Mjolnir-VR.desktop` (open it in Desktop Mode) | [Install on Steam Frame](%s#install-on-steam-frame) |\n\n' "$readme"
|
||||
printf 'The other files are for the built-in updater and the Steam Frame installer (those named `ringfall-…` / `Ringfall…`: the same, for the builds before the name Mjolnir VR).\n\n'
|
||||
printf 'Commit: %s\nBuild: %s\n' "$COMMIT_URL" "$RUN_URL"
|
||||
} > notes.md
|
||||
gh release create "$tag" release/* --target "$GITHUB_SHA" --latest \
|
||||
--title "Mjolnir VR, build $GITHUB_RUN_NUMBER (${GITHUB_SHA:0:7})" --notes-file notes.md
|
||||
echo "tag=$tag" >> "$GITHUB_OUTPUT"
|
||||
|
||||
# The Windows builds' executables and PDBs to Sentry, which turns the
|
||||
# crash reports of these builds (port/windows/src/win32_crash.c) into
|
||||
# backtraces with function names and lines. Needs the SENTRY_AUTH_TOKEN
|
||||
# secret: an organization auth token of the Sentry organization, which
|
||||
# names the organization and its region itself. The SENTRY_PROJECT
|
||||
# variable can name the project (its slug), else the id in the DSN of
|
||||
# win32_crash.c; SENTRY_ORG and SENTRY_URL (https://de.sentry.io) are
|
||||
# for a personal token instead. A failed upload does not stop the
|
||||
# release.
|
||||
- name: Upload Windows symbols to Sentry
|
||||
continue-on-error: true
|
||||
env:
|
||||
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
|
||||
SENTRY_PROJECT: ${{ vars.SENTRY_PROJECT || '4512207917744208' }}
|
||||
ORG: ${{ vars.SENTRY_ORG }}
|
||||
URL: ${{ vars.SENTRY_URL }}
|
||||
SENTRY_CLI_VERSION: 2.46.0
|
||||
run: |
|
||||
if [ -z "$SENTRY_AUTH_TOKEN" ]; then
|
||||
echo "::warning::no SENTRY_AUTH_TOKEN secret: crash reports of this build will have no function names"
|
||||
exit 0
|
||||
fi
|
||||
if [ -n "$ORG" ]; then export SENTRY_ORG="$ORG"; fi
|
||||
if [ -n "$URL" ]; then export SENTRY_URL="$URL"; fi
|
||||
curl -fsSL -o sentry-cli "https://github.com/getsentry/sentry-cli/releases/download/$SENTRY_CLI_VERSION/sentry-cli-Linux-x86_64"
|
||||
chmod +x sentry-cli
|
||||
./sentry-cli debug-files upload --wait \
|
||||
artifacts/halo-windows-release artifacts/halo-windows-release-symbols \
|
||||
artifacts/halo-windows-debug artifacts/halo-windows-debug-symbols
|
||||
|
||||
- name: Keep the last five
|
||||
run: |
|
||||
gh release list --limit 100 --json tagName,createdAt \
|
||||
--jq '[.[] | select(.tagName | startswith("build-"))] | sort_by(.createdAt) | reverse | .[5:] | .[].tagName' |
|
||||
while read -r tag; do
|
||||
gh release delete "$tag" --cleanup-tag --yes
|
||||
done
|
||||
|
||||
pages:
|
||||
# (off: Mjolnir VR ships the Android app only)
|
||||
if: ${{ false }}
|
||||
# The release's web build to GitHub Pages, which serves it at
|
||||
# https://halocombatevolved.com/ (port/web/README.md, "Hosting"). Only
|
||||
# main, only once every platform built and the release is out (the site
|
||||
# and the release are one build), and a deployment is never cancelled
|
||||
# halfway. The repository's Pages source must be GitHub Actions.
|
||||
needs: [release]
|
||||
runs-on: ubuntu-24.04
|
||||
timeout-minutes: 10
|
||||
permissions:
|
||||
contents: write
|
||||
pages: write
|
||||
id-token: write
|
||||
concurrency:
|
||||
group: pages
|
||||
cancel-in-progress: false
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deploy.outputs.page_url }}
|
||||
steps:
|
||||
- uses: actions/download-artifact@v4
|
||||
with:
|
||||
name: halo-web-release
|
||||
path: site
|
||||
|
||||
# The game's wasm, most of a build, from jsDelivr rather than GitHub
|
||||
# Pages, which serves 100 GB a month: the wasm alone in a commit of the
|
||||
# web-wasm branch (pushed over the last, so the repository keeps one),
|
||||
# which jsDelivr serves by its hash (with CORS; GitHub's release
|
||||
# downloads have none, so a page cannot fetch them), and version.json
|
||||
# names that copy and its SHA-256. The site's service worker takes the
|
||||
# wasm from there, checked, and from the site only when it cannot
|
||||
# (port/web/site/sw.js). A failure here leaves the site serving it.
|
||||
- name: The wasm on jsDelivr
|
||||
continue-on-error: true
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
run: |
|
||||
sha256="$(sha256sum site/halo.wasm | cut -d' ' -f1)"
|
||||
mkdir wasm
|
||||
cp site/halo.wasm wasm/
|
||||
cd wasm
|
||||
git init -q -b web-wasm
|
||||
git -c user.name="github-actions[bot]" -c user.email="41898282+github-actions[bot]@users.noreply.github.com" \
|
||||
add halo.wasm
|
||||
git -c user.name="github-actions[bot]" -c user.email="41898282+github-actions[bot]@users.noreply.github.com" \
|
||||
commit -q -m "The web build's wasm (build $GITHUB_RUN_NUMBER, $GITHUB_SHA)"
|
||||
git push -q --force "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" HEAD:refs/heads/web-wasm
|
||||
url="https://cdn.jsdelivr.net/gh/${GITHUB_REPOSITORY}@$(git rev-parse HEAD)/halo.wasm"
|
||||
# (jsDelivr fetches it now, and it must be the same file: it serves
|
||||
# files of at most 20 MB from GitHub)
|
||||
curl -fsSL --retry 6 --retry-delay 10 --retry-all-errors -o served.wasm "$url"
|
||||
echo "$sha256 served.wasm" | sha256sum -c -
|
||||
cd ..
|
||||
python3 - "$url" "$sha256" <<'EOF'
|
||||
import json, sys
|
||||
with open("site/version.json") as file:
|
||||
stamp = json.load(file)
|
||||
stamp["wasm"] = {"url": sys.argv[1], "sha256": sys.argv[2]}
|
||||
with open("site/version.json", "w") as file:
|
||||
json.dump(stamp, file, indent=1)
|
||||
EOF
|
||||
echo "the wasm from $url"
|
||||
|
||||
- uses: actions/configure-pages@v5
|
||||
|
||||
- uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: site
|
||||
|
||||
- id: deploy
|
||||
uses: actions/deploy-pages@v4
|
||||
|
||||
notify:
|
||||
# A Discord embed for the run, to the DISCORD_WEBHOOK secret (nothing
|
||||
# without it): green when every platform built, red when one did not,
|
||||
# with each platform's result, this run's release (main only), and links
|
||||
# to the latest release's builds.
|
||||
needs: [android, release]
|
||||
if: ${{ !cancelled() }}
|
||||
runs-on: ubuntu-24.04
|
||||
timeout-minutes: 5
|
||||
steps:
|
||||
- name: Post to Discord
|
||||
env:
|
||||
WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
|
||||
LINUX: ${{ needs.linux.result }}
|
||||
ANDROID: ${{ needs.android.result }}
|
||||
WINDOWS: ${{ needs.windows.result }}
|
||||
WEB: ${{ needs.web.result }}
|
||||
PAGES: ${{ needs.pages.result }}
|
||||
SITE_URL: https://halocombatevolved.com/
|
||||
RELEASE_TAG: ${{ needs.release.outputs.tag }}
|
||||
SERVER: ${{ github.server_url }}
|
||||
REPOSITORY: ${{ github.repository }}
|
||||
BRANCH: ${{ github.ref_name }}
|
||||
SHA: ${{ github.sha }}
|
||||
ACTOR: ${{ github.actor }}
|
||||
MESSAGE: ${{ github.event.head_commit.message }}
|
||||
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
|
||||
COMMIT_URL: ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}
|
||||
run: |
|
||||
if [ -z "$WEBHOOK" ]; then
|
||||
echo "no DISCORD_WEBHOOK secret: nothing to post"
|
||||
exit 0
|
||||
fi
|
||||
status() {
|
||||
case "$1" in
|
||||
success) echo "✅ Built" ;;
|
||||
failure) echo "❌ Failed" ;;
|
||||
cancelled) echo "⏹️ Cancelled" ;;
|
||||
*) echo "➖ Skipped" ;;
|
||||
esac
|
||||
}
|
||||
if [ "$ANDROID" = success ]; then
|
||||
title="Build succeeded"; color=5763719
|
||||
else
|
||||
title="Build failed"; color=15548997
|
||||
fi
|
||||
latest="$SERVER/$REPOSITORY/releases/latest"
|
||||
downloads="[Quest]($latest/download/mjolnir-vr-android-release.zip) · [Steam Frame]($latest/download/Install-Mjolnir-VR.desktop) ([all builds]($latest))"
|
||||
if [ -n "$RELEASE_TAG" ]; then
|
||||
release="[$RELEASE_TAG]($SERVER/$REPOSITORY/releases/tag/$RELEASE_TAG)"
|
||||
if [ "$PAGES" = success ]; then
|
||||
release="$release, on [the site]($SITE_URL)"
|
||||
fi
|
||||
else
|
||||
release="None (only a successful build of main makes one)"
|
||||
fi
|
||||
subject="$(printf '%s' "${MESSAGE:-manual run}" | head -n 1 | cut -c1-200)"
|
||||
jq -n \
|
||||
--arg title "$title" --argjson color "$color" --arg url "$RUN_URL" \
|
||||
--arg description "[\`${SHA:0:7}\`]($COMMIT_URL) $subject — $ACTOR ($BRANCH)" \
|
||||
--arg release "$release" --arg downloads "$downloads" \
|
||||
--arg linux "$(status "$LINUX")" --arg windows "$(status "$WINDOWS")" --arg android "$(status "$ANDROID")" \
|
||||
--arg web "$(status "$WEB")" \
|
||||
--arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
|
||||
'{embeds: [{
|
||||
title: $title, url: $url, color: $color, description: $description, timestamp: $timestamp,
|
||||
fields: [
|
||||
{name: "Linux", value: $linux, inline: true},
|
||||
{name: "Windows", value: $windows, inline: true},
|
||||
{name: "Android", value: $android, inline: true},
|
||||
{name: "Web", value: $web, inline: true},
|
||||
{name: "Release", value: $release},
|
||||
{name: "Latest release builds", value: $downloads}
|
||||
]
|
||||
}]}' > payload.json
|
||||
# Discord rate limits webhooks (HTTP 429, with how many seconds to
|
||||
# wait in retry_after): wait and try again, a few times. A post
|
||||
# still limited, or a network or Discord error, is a warning rather
|
||||
# than a failed run; any other answer (a deleted webhook) fails. (At
|
||||
# most 5 tries of 15 seconds and 4 waits of 30: inside the job's 5
|
||||
# minutes.)
|
||||
for attempt in 1 2 3 4 5; do
|
||||
code=$(curl -sS --max-time 15 -o response.json -w '%{http_code}' \
|
||||
-H "Content-Type: application/json" -d @payload.json "$WEBHOOK") || code=000
|
||||
case "$code" in
|
||||
2??)
|
||||
exit 0
|
||||
;;
|
||||
429)
|
||||
wait=$(jq -r '.retry_after // 5' response.json 2>/dev/null || echo 5)
|
||||
wait=$(awk -v w="$wait" 'BEGIN { w += 0; if (w < 1) w = 1; if (w > 30) w = 30; printf "%d", w + 0.999 }')
|
||||
echo "Discord is rate limiting the webhook; trying again in ${wait}s (attempt $attempt of 5)"
|
||||
;;
|
||||
000|5??)
|
||||
wait=5
|
||||
echo "Discord answered HTTP $code; trying again in ${wait}s (attempt $attempt of 5)"
|
||||
;;
|
||||
*)
|
||||
echo "::error::Discord answered HTTP $code: $(cat response.json 2>/dev/null)"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
[ "$attempt" -lt 5 ] && sleep "$wait"
|
||||
done
|
||||
echo "::warning::The Discord post did not go through after 5 attempts (HTTP $code)"
|
||||
@@ -1,199 +0,0 @@
|
||||
name: Server image
|
||||
|
||||
# The dedicated server's container image (deploy/docker), made from a
|
||||
# release's halo-linux-release.zip, and the Helm chart's checks
|
||||
# (deploy/helm/opence-server).
|
||||
#
|
||||
# - After each successful Build of main (which publishes release build-<n>):
|
||||
# the image of that release, checked, pushed to
|
||||
# ghcr.io/opencommunityedition/opence-server as sha-<commit>, build-<n> and
|
||||
# latest, and signed keyless with cosign (this workflow's GitHub identity).
|
||||
# - Weekly, the latest release's image again, for Debian's fixes.
|
||||
# - By hand, any release's (latest moves only for the newest).
|
||||
#
|
||||
# The checks (no game data in CI: it is never published): the image runs as
|
||||
# 10001:10001; started on a read-only root without maps it writes its
|
||||
# settings to /state, says "server: no usable maps" and exits 2; halo
|
||||
# --version answers; the health check fails with nothing listening.
|
||||
#
|
||||
# Verify:
|
||||
# cosign verify ghcr.io/opencommunityedition/opence-server:latest \
|
||||
# --certificate-identity-regexp '^https://github\.com/OpenCommunityEdition/OpenCE/\.github/workflows/server-image\.yml@' \
|
||||
# --certificate-oidc-issuer https://token.actions.githubusercontent.com
|
||||
on:
|
||||
workflow_run:
|
||||
workflows: [Build]
|
||||
types: [completed]
|
||||
branches: [main]
|
||||
schedule:
|
||||
- cron: "23 5 * * 1"
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
release:
|
||||
description: "The release to build the image of: a tag (build-206) or latest"
|
||||
default: latest
|
||||
|
||||
concurrency:
|
||||
group: server-image-${{ github.event_name }}-${{ github.ref }}
|
||||
cancel-in-progress: false
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
env:
|
||||
IMAGE: ghcr.io/opencommunityedition/opence-server
|
||||
|
||||
jobs:
|
||||
chart:
|
||||
# (off: Mjolnir VR ships no dedicated server image)
|
||||
if: ${{ false }}
|
||||
runs-on: ubuntu-24.04
|
||||
timeout-minutes: 10
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
ref: ${{ github.event.workflow_run.head_sha || github.sha }}
|
||||
|
||||
- uses: azure/setup-helm@v4
|
||||
|
||||
- name: Lint
|
||||
run: |
|
||||
set -euo pipefail
|
||||
chart=deploy/helm/opence-server
|
||||
for values in "$chart"/ci/*-values.yaml; do
|
||||
helm lint "$chart" --strict -f "$values"
|
||||
helm template ci "$chart" -f "$values" > /dev/null
|
||||
done
|
||||
# the maps are never in the image: without game data the chart refuses to render
|
||||
if helm template ci "$chart" > /dev/null 2>&1; then
|
||||
echo "::error::the chart renders without gameData"; exit 1
|
||||
fi
|
||||
|
||||
- name: Unit tests
|
||||
run: |
|
||||
set -euo pipefail
|
||||
# (Helm 4 checks plugins' signatures, which helm-unittest does not publish)
|
||||
if helm version --short | grep -q '^v3'; then verify=; else verify=--verify=false; fi
|
||||
helm plugin install https://github.com/helm-unittest/helm-unittest $verify
|
||||
helm unittest deploy/helm/opence-server
|
||||
|
||||
image:
|
||||
# (off: Mjolnir VR ships no dedicated server image)
|
||||
if: ${{ false }}
|
||||
runs-on: ubuntu-24.04
|
||||
timeout-minutes: 20
|
||||
permissions:
|
||||
contents: read
|
||||
packages: write
|
||||
# keyless signing: the workflow's OIDC token gets a short-lived Sigstore certificate
|
||||
id-token: write
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
ref: ${{ github.event.workflow_run.head_sha || github.sha }}
|
||||
|
||||
- name: Release
|
||||
id: release
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
EVENT: ${{ github.event_name }}
|
||||
RUN_NUMBER: ${{ github.event.workflow_run.run_number }}
|
||||
WANTED: ${{ inputs.release }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
case "$EVENT" in
|
||||
workflow_run) tag="build-$RUN_NUMBER" ;;
|
||||
workflow_dispatch) tag="${WANTED:-latest}" ;;
|
||||
*) tag=latest ;;
|
||||
esac
|
||||
newest="$(gh release view --repo "$GITHUB_REPOSITORY" --json tagName -q .tagName)"
|
||||
if [ "$tag" = latest ]; then
|
||||
tag="$newest"
|
||||
fi
|
||||
commit="$(gh release view "$tag" --repo "$GITHUB_REPOSITORY" --json targetCommitish -q .targetCommitish)"
|
||||
gh release download "$tag" --repo "$GITHUB_REPOSITORY" --pattern halo-linux-release.zip --dir deploy/docker
|
||||
echo "tag=$tag" >> "$GITHUB_OUTPUT"
|
||||
echo "commit=$commit" >> "$GITHUB_OUTPUT"
|
||||
echo "newest=$([ "$tag" = "$newest" ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
|
||||
echo "Release $tag (commit $commit; the newest: $newest)"
|
||||
|
||||
- name: Build
|
||||
env:
|
||||
TAG: ${{ steps.release.outputs.tag }}
|
||||
COMMIT: ${{ steps.release.outputs.commit }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
docker build --pull -t opence-server:ci \
|
||||
--build-arg RELEASE=halo-linux-release.zip \
|
||||
--label org.opencontainers.image.source="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY" \
|
||||
--label org.opencontainers.image.revision="$COMMIT" \
|
||||
--label org.opencontainers.image.version="$TAG" \
|
||||
--label org.opencontainers.image.licenses=AGPL-3.0-or-later \
|
||||
--label org.opencontainers.image.title="OpenCE dedicated server" \
|
||||
deploy/docker
|
||||
|
||||
- name: Smoke test
|
||||
run: |
|
||||
set -euo pipefail
|
||||
[ "$(docker image inspect -f '{{.Config.User}}' opence-server:ci)" = 10001:10001 ] \
|
||||
|| { echo "::error::the image does not run as 10001:10001"; exit 1; }
|
||||
docker run --rm --read-only --entrypoint /opt/opence/halo opence-server:ci --version | tee version.txt
|
||||
grep -Eq '^OpenCE build-[0-9]+ \(network version [0-9]+\)$' version.txt \
|
||||
|| { echo "::error::halo --version did not answer"; exit 1; }
|
||||
# without maps, on a read-only root with /state the one writable folder
|
||||
docker volume create smoke-state > /dev/null
|
||||
status=0
|
||||
timeout 60 docker run --name smoke --read-only --cap-drop ALL --security-opt no-new-privileges \
|
||||
--tmpfs /tmp -v smoke-state:/state -e HALO_SERVER_WEB_PASSWORD=ci-smoke-password \
|
||||
opence-server:ci > server.log 2>&1 || status=$?
|
||||
cat server.log
|
||||
docker rm -f smoke > /dev/null
|
||||
[ "$status" = 2 ] || { echo "::error::the server without maps exited with $status, not 2"; exit 1; }
|
||||
grep -qF 'server: no usable maps' server.log \
|
||||
|| { echo "::error::no 'server: no usable maps' line"; exit 1; }
|
||||
if grep -qF 'server: ready' server.log; then echo "::error::the server said it was ready"; exit 1; fi
|
||||
docker run --rm -v smoke-state:/state --entrypoint /bin/bash opence-server:ci -c 'test -s /state/config.toml' \
|
||||
|| { echo "::error::no /state/config.toml"; exit 1; }
|
||||
# the health check, with nothing listening
|
||||
if docker run --rm --entrypoint /opt/opence/healthz.sh opence-server:ci; then
|
||||
echo "::error::the health check passed with no server"; exit 1
|
||||
fi
|
||||
docker volume rm smoke-state > /dev/null
|
||||
|
||||
- uses: docker/login-action@v3
|
||||
if: github.repository == 'OpenCommunityEdition/OpenCE'
|
||||
with:
|
||||
registry: ghcr.io
|
||||
username: ${{ github.actor }}
|
||||
password: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- uses: sigstore/cosign-installer@v3
|
||||
if: github.repository == 'OpenCommunityEdition/OpenCE'
|
||||
|
||||
- name: Push and sign
|
||||
if: github.repository == 'OpenCommunityEdition/OpenCE'
|
||||
env:
|
||||
TAG: ${{ steps.release.outputs.tag }}
|
||||
COMMIT: ${{ steps.release.outputs.commit }}
|
||||
NEWEST: ${{ steps.release.outputs.newest }}
|
||||
IDENTITY: ^https://github\.com/${{ github.repository }}/\.github/workflows/server-image\.yml@
|
||||
run: |
|
||||
set -euo pipefail
|
||||
tags=("sha-${COMMIT:0:7}" "$TAG")
|
||||
if [ "$NEWEST" = true ]; then
|
||||
tags+=(latest)
|
||||
fi
|
||||
for tag in "${tags[@]}"; do
|
||||
docker tag opence-server:ci "$IMAGE:$tag"
|
||||
docker push "$IMAGE:$tag"
|
||||
done
|
||||
ref="$(docker image inspect -f '{{index .RepoDigests 0}}' "$IMAGE:$TAG")"
|
||||
test -n "$ref"
|
||||
cosign sign --yes "$ref"
|
||||
cosign verify "$ref" --certificate-identity-regexp "$IDENTITY" \
|
||||
--certificate-oidc-issuer https://token.actions.githubusercontent.com > /dev/null
|
||||
{
|
||||
echo "Pushed and signed $ref as ${tags[*]}."
|
||||
echo
|
||||
echo "Verify: cosign verify $IMAGE:$TAG --certificate-identity-regexp '$IDENTITY' --certificate-oidc-issuer https://token.actions.githubusercontent.com"
|
||||
} >> "$GITHUB_STEP_SUMMARY"
|
||||
+17
-9
@@ -9,29 +9,37 @@ __pycache__
|
||||
|
||||
# Build files
|
||||
build/
|
||||
projects/
|
||||
.ninja_*
|
||||
build.ninja
|
||||
*.vcxproj*
|
||||
*.sln*
|
||||
|
||||
# decompctx output
|
||||
ctx.*
|
||||
*.ctx
|
||||
|
||||
# Generated configs
|
||||
objdiff.json
|
||||
compile_commands.json
|
||||
|
||||
# The January build and the Xbox SDK (tools/xdk_headers.py reads the
|
||||
# build's PDB); never commit
|
||||
# Miscellaneous
|
||||
*.exe
|
||||
*.pdb
|
||||
*.idb
|
||||
*.i64
|
||||
*.id0
|
||||
*.id1
|
||||
*.id2
|
||||
*.nam
|
||||
*.til
|
||||
*.bndb
|
||||
xbox/
|
||||
!source/**/xbox/
|
||||
|
||||
# Locally extracted proprietary game data (never commit)
|
||||
assets/
|
||||
# (but the high-res assets, drawn for the port: tools/hud_assets.py)
|
||||
!port/assets/
|
||||
original/
|
||||
|
||||
# CI build outputs (tools/ci_build.py)
|
||||
dist/
|
||||
|
||||
# The app signing key's local settings and keys (port/android/app/build.gradle; never commit)
|
||||
port/android/signing.properties
|
||||
*.jks
|
||||
*.keystore
|
||||
@@ -1,251 +0,0 @@
|
||||
# Notes for agents
|
||||
|
||||
This repository ports the Halo: Combat Evolved decompilation (Xbox build
|
||||
01.01.14.2342, `cachebeta.exe`) to Linux, Windows, Android and the web. The game's C
|
||||
sources are the decompilation; the port adds a platform layer that
|
||||
implements the Xbox APIs the game calls, and features the Xbox game did not
|
||||
have (a new netcode, internet play, the PC version's menus, Custom Edition
|
||||
maps, touch controls). The project is published as OpenCE.
|
||||
|
||||
Start with [README.md](README.md). The other documents are listed at the
|
||||
end.
|
||||
|
||||
## Layout
|
||||
|
||||
| Path | Contents |
|
||||
| --- | --- |
|
||||
| `source/` | The game: 466 C files of the decompilation, compiled as they are with few changes (each marked, below) |
|
||||
| `port/linux/src/` | The platform layer the three ports share: Direct3D 8 on OpenGL (`d3d8_gl.c`), DirectSound and XInput on SDL3, files, threads, memory, sockets, settings (`port_config.c`), the mods folder (`port_mods.c`), internet play (`p2p*.c`), the dedicated server's platform side (`server_*.c`: the mode, the log, the rotation's grammar, HTTP, RCON, the master servers' publisher) and the master servers' list (`master_list.c`) |
|
||||
| `port/linux/game/` | The port's game-side code, compiled as the game's sources are: the distributed netcode (`network_*.c`), co-op, OpenCE's gametypes (`game_modes.c`, `infection.c`, `gun_game.c`), map sharing (`map_share*.c`), the menus (`menu_tags.c`, `menu_functions.c`), Custom Edition maps (`custom_edition_*.c`, `cache_file_formats.c`), the tag validator (`tag_validate.c`, `tag_schema_*.c`), mods (`mods.c`, `mod_*.c`), streamer mode's word filter (`text_filter*.c`), the dedicated server's director, commands, gametypes and status (`server_*.c`), touch, FOV and more |
|
||||
| `port/linux/include/` | The port's headers: the limits (`halo_port_limits.h`, with `HALO_PORT_NETWORK_VERSION`), capacities (`halo_port_capacity.h`), the prefix header, `halo_linux_source_fixups.h` (port functions the game's sources call) |
|
||||
| `port/include/xdk/` | Stand-ins for the Xbox SDK's headers (declarations only) |
|
||||
| `port/windows/` | The Windows build's own files (`win32_*.c`, headers) |
|
||||
| `port/android/` | The Android app: the guest runtime, the host library (`host/`), the Java app (`app/`), host imports (`host_imports.list`) |
|
||||
| `port/web/` | The web build: its runtime (`src/`: entry, sockets inside the page, memory watch), the page and its service worker (`site/`), the SDL port, tests |
|
||||
| `port/assets/` | What the builds embed or ship: high-res HUD (`hud/`), fonts, titles, menus (`menus/`), icons, network brokers and master servers, the dedicated server's web page (`server_ui/`) |
|
||||
| `port/third_party/` | Vendored libraries, each with a README naming its upstream, version and checksum |
|
||||
| `port/tools/` | Stand-alone tools (`cache_file_report.c`) |
|
||||
| `tools/` | Build scripts (`linux_build.py`, `windows_build.py`, `android_build.py`, `web_build.py`, `ci_build.py`, `web_serve.py`), generators (`ce_menus.py`, `port_settings.py`, `hud_assets.py`, `title_assets.py`, `embed_assets.py`, `server_ui_embed.py`, `xdk_headers.py`), the dedicated server's protocol simulator and remote console (`server_sim.py`, `opence_rcon.py`), tests, and `stagekit/` (scenarios staged and instrumented on the real engine, no retail assets) |
|
||||
| `docs/` | Longer design notes (`custom_edition_caches.md`, `mods.md`, `dedicated_server.md`, `master_protocol.md`) |
|
||||
| `pgo/` | Profile-guided optimisation profiles |
|
||||
| `deploy/` | Running a dedicated server: systemd, Docker, Pterodactyl, Helm, PufferPanel, MCSManager, example gametypes |
|
||||
| `assets/` | Game data for local runs (gitignored: `maps/`, `custom_maps/`) |
|
||||
| `.github/workflows/` | CI: builds every platform on each push, publishes releases from `main` |
|
||||
|
||||
## Building
|
||||
|
||||
```sh
|
||||
python configure.py # debug build; add --release, --portable, --profile, --pgo=off, --lto=off
|
||||
ninja linux # build/linux/halo
|
||||
ninja android # the Android guest image and native libraries
|
||||
ninja android_apk # the APK (Gradle)
|
||||
ninja web # build/web/site (Emscripten: port/web/README.md)
|
||||
ninja windows # on Windows, or on Linux after configure.py --windows-cross
|
||||
python tools/ci_build.py linux release # what CI builds
|
||||
```
|
||||
|
||||
- `configure.py` writes `build.ninja`; `configure_args` at its top records
|
||||
the options it was run with. Restore them after trying other options.
|
||||
- The Linux and Windows builds are 32-bit x86 with clang, in MSVC's ABI
|
||||
(`-fms-extensions -fshort-wchar -malign-double -fcommon`), C89 (`gnu89`):
|
||||
declarations come before statements.
|
||||
- Every native build compiles without fused multiply-add and with the
|
||||
vendored musl maths (`halo_math.h`), so that every machine of a network
|
||||
game computes the same results. Do not call the system's maths functions.
|
||||
- Android: the game is an ILP32 AArch64 guest (`arm64_32`) in a 64-bit app.
|
||||
Guest code can call only the host imports declared in
|
||||
`port/android/host_imports.list` and `port/android/guest/runtime/guest_host.h`,
|
||||
and only the SDL functions `guest_sdl.c` bridges. Run `ninja android`
|
||||
after changing anything it compiles: `port/linux/src`, `port/linux/game`,
|
||||
`port/android`, `source/`, the build scripts.
|
||||
- Web: the game is `wasm32` (also ILP32), run on a Web Worker; calls must
|
||||
match their callee's type exactly (the link fails on a mismatch), and
|
||||
WebGL 2 is ES 3.0. Run `ninja web` after changing what it compiles (as
|
||||
for Android, and `port/web`). Refer to [port/web/README.md](port/web/README.md).
|
||||
|
||||
### Defines
|
||||
|
||||
| Define | Set by | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `HALO_ANDROID` | Android | The app: its display, input, files and lifecycle |
|
||||
| `HALO_GLES` | Android, web | The OpenGL ES renderer |
|
||||
| `HALO_ARM64_GUEST` | Android | The guest's ABI (ILP32 AArch64) |
|
||||
| `HALO_WEB` | Web | The browser: its frames, storage, sockets and WebGL 2's limits (with `HALO_GLES`, not `HALO_ANDROID`) |
|
||||
| `HALO_WINDOWS` | Windows (`halo_windows_prefix.h`) | The Windows build |
|
||||
| `HALO_RELEASE` | `--release` | No assertions checked |
|
||||
| `HALO_PROFILE` | `--profile` | The profiling build; a normal build must be unchanged by it |
|
||||
|
||||
`HALO_LINUX` and `HALO_CUSTOM_EDITION` are **not** defined by any build:
|
||||
code guarded by them compiles to nothing. Custom Edition support is a
|
||||
setting (`game.custom_edition`), checked at run time with
|
||||
`custom_edition_cache_tags_loaded()`.
|
||||
|
||||
## Testing
|
||||
|
||||
```sh
|
||||
python -m pytest -q tools/harness tools/test_touch_menu.py # the engine's functions in a fake world
|
||||
python -m pytest -q tools/stagekit/tests # scenarios on the real engine, no retail assets (Linux)
|
||||
python -m pytest -q tools/test_linux_port.py # the build, the maps' checks (needs assets/maps)
|
||||
python -m pytest -q tools/test_mods.py # mods played over a map (needs assets/maps)
|
||||
python -m pytest -q tools/test_bots.py # the bots in local games (needs assets/maps)
|
||||
python -m pytest -q tools/test_cache_file_formats.py tools/test_bmp_files.py tools/test_profile.py
|
||||
python tools/test_touch_layout.py # the Android touch layout (JDK 17+)
|
||||
python tools/test_light_storage.py
|
||||
python tools/test_death_timing.py
|
||||
python -m pytest -q tools/test_web_build.py # the web build's graph, sockets, menus
|
||||
node --test "port/web/tests/*.test.js" # the web page's importer and service worker
|
||||
node port/web/tests/webrtc_native.mjs chromium firefox # the native builds' WebRTC with browsers (Playwright)
|
||||
python -m pytest -q tools/test_dedicated_server.py # the dedicated server with clients (needs assets/maps)
|
||||
python -m pytest -q tools/test_server_sim.py tools/test_egg.py # the server's web page and protocol simulator, the egg
|
||||
python -m pytest -q tools/test_net_compare.py # net_compare.py's judging of logs, its copies and their processes
|
||||
python tools/net_compare.py --a build/linux/halo --b <other build> --data <game data> --swap
|
||||
# two builds in one network game, in step (retail maps: local only)
|
||||
```
|
||||
|
||||
`tools/harness/README.md` explains how to add an asset-free test: the code
|
||||
under test is taken from the sources, not copied. `tools/stagekit/README.md`
|
||||
explains how to add a scenario: the real engine, with no retail assets.
|
||||
|
||||
Running the game without a person at it:
|
||||
|
||||
- `debug.network_test` (`HALO_NETWORK_TEST=host:<map>` or `join`) hosts or
|
||||
joins a game without the menus and logs each player's state every second;
|
||||
several copies play on one machine on different loopback addresses
|
||||
(`HALO_NET_ADDRESS`, `HALO_NET_BROADCAST`). `NETCODE.md` describes the
|
||||
test settings.
|
||||
- `halo --server` is a dedicated server (`docs/dedicated_server.md`), and
|
||||
`halo --probe [<invite>]` prints a game's advertisement as JSON and exits;
|
||||
`tools/test_dedicated_server.py` runs both with clients.
|
||||
- `debug.exit_after`, `debug.hidden_window`, `debug.null_renderer`,
|
||||
`debug.menu_open` (start on one menu screen), `debug.telnet_console`.
|
||||
- Use a virtual display (Xvfb, with `SDL_VIDEO_DRIVER=x11`) for windowed
|
||||
runs, never the desktop of the person you work for, and stop only the
|
||||
processes you started.
|
||||
|
||||
## Rules of the project
|
||||
|
||||
### The game's sources
|
||||
|
||||
- Change `source/` as little as possible, and mark each change from the
|
||||
original with a comment that starts `port:`. Write like the surrounding
|
||||
code: its naming, its comment density, and the project's plain,
|
||||
descriptive comment style.
|
||||
- A port function the game's sources call is declared in
|
||||
`halo_linux_source_fixups.h` or included with a note naming its file
|
||||
(`#include "view_fov.h" /* port: port/linux/game/view_fov.c */`).
|
||||
- Notes such as `BUG (original, preserved for exact matching)` mark the
|
||||
original's bugs. Fixing one is allowed; say so in a `port:` comment.
|
||||
|
||||
### The Xbox SDK
|
||||
|
||||
`port/include/xdk` was written without the SDK's headers, from the January
|
||||
build's debug information and public documentation. Never read the SDK's
|
||||
headers or anything derived from them, never copy from them, and do not
|
||||
read `xbox/include`. To add a name, follow `port/include/xdk/README.md`.
|
||||
|
||||
### Networking
|
||||
|
||||
- Raise `HALO_PORT_NETWORK_VERSION` (`port/linux/include/halo_port_limits.h`)
|
||||
with any change to what the machines send each other, or to anything they
|
||||
must agree on, and say why in the commit. Machines of different versions
|
||||
do not play together.
|
||||
- Only the host decides; clients predict their own players. Read
|
||||
`port/linux/NETCODE.md` before changing the netcode.
|
||||
- Internet play is the same code in every build, the web's too: a browser's
|
||||
tunnel is a WebRTC data channel (`port/web/src/web_p2p.c`), which the
|
||||
native builds take on their tunnel's socket (`p2p_webrtc.c`, `posix_dtls.c`).
|
||||
Check a change with both (`port/web/tests/webrtc_native.mjs`, and with the
|
||||
maps `port/web/tests/internet.mjs`).
|
||||
- Anything another machine sends is untrusted: check sizes, indices and
|
||||
rates, as the existing handlers do. `debug.network_corrupt` tests this.
|
||||
|
||||
### Menus
|
||||
|
||||
- The menus must match Halo Custom Edition's. Their XML (`port/assets/menus/ce/`)
|
||||
is generated by `tools/ce_menus.py` from the PC version's tags; the
|
||||
settings screens come from `tools/port_settings.py`. Do not edit the XML
|
||||
by hand: change the generator and run it (the command is in
|
||||
`port/assets/menus/README.md`, "Writing them again"), then check that
|
||||
`git status` shows only the screens meant to change.
|
||||
- Functions the menus call but the port has not wired are listed in
|
||||
`port/assets/menus/UNWIRED.md`.
|
||||
|
||||
### Art and credit
|
||||
|
||||
- Replacement HUD, title and menu art is made of hand-drawn redraws.
|
||||
- Prefer an existing redraw (the ui-svg-handmade set), then a new redraw. A
|
||||
Custom Edition picture that cannot reasonably be redrawn (a 3D render, a
|
||||
screenshot, a logo) may be used only if it is listed in
|
||||
`port/assets/menus/NON_HANDDRAWN.md`.
|
||||
- `AUTHORS.md` credits art only.
|
||||
- Fonts: Overpass and OpenCE (Newtown, respaced) only; see
|
||||
`port/assets/fonts/README.md`. Never ship the maps' commercial typefaces.
|
||||
|
||||
### Custom Edition maps
|
||||
|
||||
Custom Edition maps live in the data root's `custom_maps` folder with
|
||||
`bitmaps.map`, `sounds.map` and `loc.map`; their level names are
|
||||
`custom_maps\<name>`. OpenSauce features are not supported and must not be
|
||||
added: a map that needs them is refused, and one that only carries
|
||||
OpenSauce's header runs as stock Custom Edition runs it. Map files are
|
||||
untrusted input: read them through bounds-checked readers. See
|
||||
`docs/custom_edition_caches.md`.
|
||||
|
||||
### Settings
|
||||
|
||||
A setting is an entry in `port/linux/src/port_config.c`, with a default, an
|
||||
environment variable and a comment that `config.toml` gets. Document it in
|
||||
the settings table of `port/linux/README.md` (and the Android README for an
|
||||
Android-only one). A departure from the stock game's look or behaviour
|
||||
should be a setting, off or stock by default, unless the project decides
|
||||
otherwise.
|
||||
|
||||
### Third-party code and licences
|
||||
|
||||
The repository is `AGPL-3.0-or-later` (`LICENSE`); the commits before the
|
||||
change, and the releases built from them, stay CC0 (`LICENSES/CC0-1.0.txt`).
|
||||
The README's "Licence" section says what each part is under. Vendored code
|
||||
goes in `port/third_party/<name>`, copied unchanged, with a README naming
|
||||
the upstream, the version or commit, the licence, the checksum and what uses
|
||||
it. Its licence must let it be combined with the AGPL 3.0: MIT, BSD (without
|
||||
an advertising clause), ISC, zlib, Apache 2.0, MPL 2.0, LGPL or GPL 3.0 or
|
||||
later, public domain. GPL-2.0-only code and the 4-clause BSD licence cannot
|
||||
be. Code taken from another project, GPL 3.0 code included, keeps its
|
||||
notices and its licence, and says where it came from.
|
||||
The decompilation's upstream, punpckhdq/halo, is AGPL 3.0 from 17 October
|
||||
2026; bnunu/halo-1 is CC0.
|
||||
|
||||
### Commits and pull requests
|
||||
|
||||
- Commit subjects are plain sentences saying what changed; the body says
|
||||
why and what was checked.
|
||||
- A pull request is merged with a merge commit (`Merge pull request #N from
|
||||
<owner>/<branch>`), and follow-up changes go in separate commits whose
|
||||
subject ends with `(#N)`.
|
||||
- A commit taken from a fork keeps its author and is made with
|
||||
`git cherry-pick -x`.
|
||||
|
||||
## Documents
|
||||
|
||||
| Document | About |
|
||||
| --- | --- |
|
||||
| [README.md](README.md) | Downloads, game data, building, build options, profiling builds |
|
||||
| [port/linux/README.md](port/linux/README.md) | The Linux build, controls, menus, every setting, updates, frame rate, field of view, system link, internet play, voice chat, the server browser, map sharing, security, map checks, how the port operates, the game source changes |
|
||||
| [port/linux/NETCODE.md](port/linux/NETCODE.md) | The distributed netcode, network versions, joining a game in progress, map sharing, transport, testing |
|
||||
| [port/windows/README.md](port/windows/README.md) | The Windows build, its headers, inline functions, crash reports |
|
||||
| [port/android/README.md](port/android/README.md) | The Android build, the guest and host, touch controls, Android settings, finding problems |
|
||||
| [port/web/README.md](port/web/README.md) | The web build, the page, the game data in the browser, limits, how it operates, hosting on GitHub Pages |
|
||||
| [port/include/xdk/README.md](port/include/xdk/README.md) | How the SDK declarations were written and are checked |
|
||||
| [docs/custom_edition_caches.md](docs/custom_edition_caches.md) | Loading and converting Custom Edition maps, and the evidence for each layout |
|
||||
| [docs/dedicated_server.md](docs/dedicated_server.md) | The dedicated server: its command line, exit codes, commands, HTTP API, RCON, events and files |
|
||||
| [docs/master_protocol.md](docs/master_protocol.md) | The master servers' protocol: publishing, the probe, the signed list |
|
||||
| [docs/mods.md](docs/mods.md) | Mods: folders of Halo PC tag files whose sounds, bitmaps, text and models play over a map's on one machine |
|
||||
| [port/assets/text_filter/README.md](port/assets/text_filter/README.md) | Streamer mode's words: Surge AI's list, the review, the allowed words |
|
||||
| [port/assets/menus/README.md](port/assets/menus/README.md) | The menu files' format and how to write them again |
|
||||
| [port/assets/menus/NON_HANDDRAWN.md](port/assets/menus/NON_HANDDRAWN.md) | Menu pictures that are not redraws |
|
||||
| [port/assets/menus/UNWIRED.md](port/assets/menus/UNWIRED.md) | Menu functions that do nothing yet |
|
||||
| [port/assets/fonts/README.md](port/assets/fonts/README.md) | The fonts and their licences |
|
||||
| [tools/harness/README.md](tools/harness/README.md) | Asset-free regression tests |
|
||||
| [tools/stagekit/README.md](tools/stagekit/README.md) | Scenarios staged and instrumented on the real engine, no retail assets |
|
||||
| `port/third_party/*/README.md` | Each vendored library |
|
||||
| [AUTHORS.md](AUTHORS.md) | Art credits |
|
||||
-25
@@ -1,25 +0,0 @@
|
||||
# Authors
|
||||
|
||||
## Art
|
||||
|
||||
- **The game's icon** (the Android app's launcher icon, `halo.exe`'s icon
|
||||
and the desktop windows' icon): by ORION (`port/assets/icon`).
|
||||
- **The controller's A, B, X and Y buttons** (the menus' button icons and
|
||||
the HUD messages'): redraws by saulob (`port/assets/buttons`).
|
||||
- **The high-res HUD** (its meters, icons, scopes and messages, and the
|
||||
weapons' reticles): redraws by MrBruh (`port/assets/hud`), based on
|
||||
reference photos by Aerocatia. The sniper rifle's zoom labels (2x, 10x)
|
||||
are set in Overpass (`port/assets/fonts`).
|
||||
- **The menus' mouse cursor** (the blue arrow the menus show for the
|
||||
mouse): by pugzysixtyfour (`port/assets/cursor`).
|
||||
|
||||
## Third-party art
|
||||
|
||||
- **Voice chat's speaker icons** (who talks, and who is muted, in the lobby,
|
||||
on the scoreboard and in the game): `volume-2` and `volume-x` from
|
||||
[Lucide](https://lucide.dev) 1.53.0, copyright (c) 2026 Lucide Icons and
|
||||
Contributors, under the ISC licence
|
||||
(`port/assets/icons/lucide/LICENSE`).
|
||||
- **The Mods menu's warning icons** (a mod out of its requested order, and
|
||||
a mod that cannot be played): `triangle-alert` and `circle-x` from
|
||||
[Lucide](https://lucide.dev) 1.53.0, under the same licence.
|
||||
@@ -1,661 +0,0 @@
|
||||
GNU AFFERO GENERAL PUBLIC LICENSE
|
||||
Version 3, 19 November 2007
|
||||
|
||||
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
|
||||
Everyone is permitted to copy and distribute verbatim copies
|
||||
of this license document, but changing it is not allowed.
|
||||
|
||||
Preamble
|
||||
|
||||
The GNU Affero General Public License is a free, copyleft license for
|
||||
software and other kinds of works, specifically designed to ensure
|
||||
cooperation with the community in the case of network server software.
|
||||
|
||||
The licenses for most software and other practical works are designed
|
||||
to take away your freedom to share and change the works. By contrast,
|
||||
our General Public Licenses are intended to guarantee your freedom to
|
||||
share and change all versions of a program--to make sure it remains free
|
||||
software for all its users.
|
||||
|
||||
When we speak of free software, we are referring to freedom, not
|
||||
price. Our General Public Licenses are designed to make sure that you
|
||||
have the freedom to distribute copies of free software (and charge for
|
||||
them if you wish), that you receive source code or can get it if you
|
||||
want it, that you can change the software or use pieces of it in new
|
||||
free programs, and that you know you can do these things.
|
||||
|
||||
Developers that use our General Public Licenses protect your rights
|
||||
with two steps: (1) assert copyright on the software, and (2) offer
|
||||
you this License which gives you legal permission to copy, distribute
|
||||
and/or modify the software.
|
||||
|
||||
A secondary benefit of defending all users' freedom is that
|
||||
improvements made in alternate versions of the program, if they
|
||||
receive widespread use, become available for other developers to
|
||||
incorporate. Many developers of free software are heartened and
|
||||
encouraged by the resulting cooperation. However, in the case of
|
||||
software used on network servers, this result may fail to come about.
|
||||
The GNU General Public License permits making a modified version and
|
||||
letting the public access it on a server without ever releasing its
|
||||
source code to the public.
|
||||
|
||||
The GNU Affero General Public License is designed specifically to
|
||||
ensure that, in such cases, the modified source code becomes available
|
||||
to the community. It requires the operator of a network server to
|
||||
provide the source code of the modified version running there to the
|
||||
users of that server. Therefore, public use of a modified version, on
|
||||
a publicly accessible server, gives the public access to the source
|
||||
code of the modified version.
|
||||
|
||||
An older license, called the Affero General Public License and
|
||||
published by Affero, was designed to accomplish similar goals. This is
|
||||
a different license, not a version of the Affero GPL, but Affero has
|
||||
released a new version of the Affero GPL which permits relicensing under
|
||||
this license.
|
||||
|
||||
The precise terms and conditions for copying, distribution and
|
||||
modification follow.
|
||||
|
||||
TERMS AND CONDITIONS
|
||||
|
||||
0. Definitions.
|
||||
|
||||
"This License" refers to version 3 of the GNU Affero General Public License.
|
||||
|
||||
"Copyright" also means copyright-like laws that apply to other kinds of
|
||||
works, such as semiconductor masks.
|
||||
|
||||
"The Program" refers to any copyrightable work licensed under this
|
||||
License. Each licensee is addressed as "you". "Licensees" and
|
||||
"recipients" may be individuals or organizations.
|
||||
|
||||
To "modify" a work means to copy from or adapt all or part of the work
|
||||
in a fashion requiring copyright permission, other than the making of an
|
||||
exact copy. The resulting work is called a "modified version" of the
|
||||
earlier work or a work "based on" the earlier work.
|
||||
|
||||
A "covered work" means either the unmodified Program or a work based
|
||||
on the Program.
|
||||
|
||||
To "propagate" a work means to do anything with it that, without
|
||||
permission, would make you directly or secondarily liable for
|
||||
infringement under applicable copyright law, except executing it on a
|
||||
computer or modifying a private copy. Propagation includes copying,
|
||||
distribution (with or without modification), making available to the
|
||||
public, and in some countries other activities as well.
|
||||
|
||||
To "convey" a work means any kind of propagation that enables other
|
||||
parties to make or receive copies. Mere interaction with a user through
|
||||
a computer network, with no transfer of a copy, is not conveying.
|
||||
|
||||
An interactive user interface displays "Appropriate Legal Notices"
|
||||
to the extent that it includes a convenient and prominently visible
|
||||
feature that (1) displays an appropriate copyright notice, and (2)
|
||||
tells the user that there is no warranty for the work (except to the
|
||||
extent that warranties are provided), that licensees may convey the
|
||||
work under this License, and how to view a copy of this License. If
|
||||
the interface presents a list of user commands or options, such as a
|
||||
menu, a prominent item in the list meets this criterion.
|
||||
|
||||
1. Source Code.
|
||||
|
||||
The "source code" for a work means the preferred form of the work
|
||||
for making modifications to it. "Object code" means any non-source
|
||||
form of a work.
|
||||
|
||||
A "Standard Interface" means an interface that either is an official
|
||||
standard defined by a recognized standards body, or, in the case of
|
||||
interfaces specified for a particular programming language, one that
|
||||
is widely used among developers working in that language.
|
||||
|
||||
The "System Libraries" of an executable work include anything, other
|
||||
than the work as a whole, that (a) is included in the normal form of
|
||||
packaging a Major Component, but which is not part of that Major
|
||||
Component, and (b) serves only to enable use of the work with that
|
||||
Major Component, or to implement a Standard Interface for which an
|
||||
implementation is available to the public in source code form. A
|
||||
"Major Component", in this context, means a major essential component
|
||||
(kernel, window system, and so on) of the specific operating system
|
||||
(if any) on which the executable work runs, or a compiler used to
|
||||
produce the work, or an object code interpreter used to run it.
|
||||
|
||||
The "Corresponding Source" for a work in object code form means all
|
||||
the source code needed to generate, install, and (for an executable
|
||||
work) run the object code and to modify the work, including scripts to
|
||||
control those activities. However, it does not include the work's
|
||||
System Libraries, or general-purpose tools or generally available free
|
||||
programs which are used unmodified in performing those activities but
|
||||
which are not part of the work. For example, Corresponding Source
|
||||
includes interface definition files associated with source files for
|
||||
the work, and the source code for shared libraries and dynamically
|
||||
linked subprograms that the work is specifically designed to require,
|
||||
such as by intimate data communication or control flow between those
|
||||
subprograms and other parts of the work.
|
||||
|
||||
The Corresponding Source need not include anything that users
|
||||
can regenerate automatically from other parts of the Corresponding
|
||||
Source.
|
||||
|
||||
The Corresponding Source for a work in source code form is that
|
||||
same work.
|
||||
|
||||
2. Basic Permissions.
|
||||
|
||||
All rights granted under this License are granted for the term of
|
||||
copyright on the Program, and are irrevocable provided the stated
|
||||
conditions are met. This License explicitly affirms your unlimited
|
||||
permission to run the unmodified Program. The output from running a
|
||||
covered work is covered by this License only if the output, given its
|
||||
content, constitutes a covered work. This License acknowledges your
|
||||
rights of fair use or other equivalent, as provided by copyright law.
|
||||
|
||||
You may make, run and propagate covered works that you do not
|
||||
convey, without conditions so long as your license otherwise remains
|
||||
in force. You may convey covered works to others for the sole purpose
|
||||
of having them make modifications exclusively for you, or provide you
|
||||
with facilities for running those works, provided that you comply with
|
||||
the terms of this License in conveying all material for which you do
|
||||
not control copyright. Those thus making or running the covered works
|
||||
for you must do so exclusively on your behalf, under your direction
|
||||
and control, on terms that prohibit them from making any copies of
|
||||
your copyrighted material outside their relationship with you.
|
||||
|
||||
Conveying under any other circumstances is permitted solely under
|
||||
the conditions stated below. Sublicensing is not allowed; section 10
|
||||
makes it unnecessary.
|
||||
|
||||
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
|
||||
|
||||
No covered work shall be deemed part of an effective technological
|
||||
measure under any applicable law fulfilling obligations under article
|
||||
11 of the WIPO copyright treaty adopted on 20 December 1996, or
|
||||
similar laws prohibiting or restricting circumvention of such
|
||||
measures.
|
||||
|
||||
When you convey a covered work, you waive any legal power to forbid
|
||||
circumvention of technological measures to the extent such circumvention
|
||||
is effected by exercising rights under this License with respect to
|
||||
the covered work, and you disclaim any intention to limit operation or
|
||||
modification of the work as a means of enforcing, against the work's
|
||||
users, your or third parties' legal rights to forbid circumvention of
|
||||
technological measures.
|
||||
|
||||
4. Conveying Verbatim Copies.
|
||||
|
||||
You may convey verbatim copies of the Program's source code as you
|
||||
receive it, in any medium, provided that you conspicuously and
|
||||
appropriately publish on each copy an appropriate copyright notice;
|
||||
keep intact all notices stating that this License and any
|
||||
non-permissive terms added in accord with section 7 apply to the code;
|
||||
keep intact all notices of the absence of any warranty; and give all
|
||||
recipients a copy of this License along with the Program.
|
||||
|
||||
You may charge any price or no price for each copy that you convey,
|
||||
and you may offer support or warranty protection for a fee.
|
||||
|
||||
5. Conveying Modified Source Versions.
|
||||
|
||||
You may convey a work based on the Program, or the modifications to
|
||||
produce it from the Program, in the form of source code under the
|
||||
terms of section 4, provided that you also meet all of these conditions:
|
||||
|
||||
a) The work must carry prominent notices stating that you modified
|
||||
it, and giving a relevant date.
|
||||
|
||||
b) The work must carry prominent notices stating that it is
|
||||
released under this License and any conditions added under section
|
||||
7. This requirement modifies the requirement in section 4 to
|
||||
"keep intact all notices".
|
||||
|
||||
c) You must license the entire work, as a whole, under this
|
||||
License to anyone who comes into possession of a copy. This
|
||||
License will therefore apply, along with any applicable section 7
|
||||
additional terms, to the whole of the work, and all its parts,
|
||||
regardless of how they are packaged. This License gives no
|
||||
permission to license the work in any other way, but it does not
|
||||
invalidate such permission if you have separately received it.
|
||||
|
||||
d) If the work has interactive user interfaces, each must display
|
||||
Appropriate Legal Notices; however, if the Program has interactive
|
||||
interfaces that do not display Appropriate Legal Notices, your
|
||||
work need not make them do so.
|
||||
|
||||
A compilation of a covered work with other separate and independent
|
||||
works, which are not by their nature extensions of the covered work,
|
||||
and which are not combined with it such as to form a larger program,
|
||||
in or on a volume of a storage or distribution medium, is called an
|
||||
"aggregate" if the compilation and its resulting copyright are not
|
||||
used to limit the access or legal rights of the compilation's users
|
||||
beyond what the individual works permit. Inclusion of a covered work
|
||||
in an aggregate does not cause this License to apply to the other
|
||||
parts of the aggregate.
|
||||
|
||||
6. Conveying Non-Source Forms.
|
||||
|
||||
You may convey a covered work in object code form under the terms
|
||||
of sections 4 and 5, provided that you also convey the
|
||||
machine-readable Corresponding Source under the terms of this License,
|
||||
in one of these ways:
|
||||
|
||||
a) Convey the object code in, or embodied in, a physical product
|
||||
(including a physical distribution medium), accompanied by the
|
||||
Corresponding Source fixed on a durable physical medium
|
||||
customarily used for software interchange.
|
||||
|
||||
b) Convey the object code in, or embodied in, a physical product
|
||||
(including a physical distribution medium), accompanied by a
|
||||
written offer, valid for at least three years and valid for as
|
||||
long as you offer spare parts or customer support for that product
|
||||
model, to give anyone who possesses the object code either (1) a
|
||||
copy of the Corresponding Source for all the software in the
|
||||
product that is covered by this License, on a durable physical
|
||||
medium customarily used for software interchange, for a price no
|
||||
more than your reasonable cost of physically performing this
|
||||
conveying of source, or (2) access to copy the
|
||||
Corresponding Source from a network server at no charge.
|
||||
|
||||
c) Convey individual copies of the object code with a copy of the
|
||||
written offer to provide the Corresponding Source. This
|
||||
alternative is allowed only occasionally and noncommercially, and
|
||||
only if you received the object code with such an offer, in accord
|
||||
with subsection 6b.
|
||||
|
||||
d) Convey the object code by offering access from a designated
|
||||
place (gratis or for a charge), and offer equivalent access to the
|
||||
Corresponding Source in the same way through the same place at no
|
||||
further charge. You need not require recipients to copy the
|
||||
Corresponding Source along with the object code. If the place to
|
||||
copy the object code is a network server, the Corresponding Source
|
||||
may be on a different server (operated by you or a third party)
|
||||
that supports equivalent copying facilities, provided you maintain
|
||||
clear directions next to the object code saying where to find the
|
||||
Corresponding Source. Regardless of what server hosts the
|
||||
Corresponding Source, you remain obligated to ensure that it is
|
||||
available for as long as needed to satisfy these requirements.
|
||||
|
||||
e) Convey the object code using peer-to-peer transmission, provided
|
||||
you inform other peers where the object code and Corresponding
|
||||
Source of the work are being offered to the general public at no
|
||||
charge under subsection 6d.
|
||||
|
||||
A separable portion of the object code, whose source code is excluded
|
||||
from the Corresponding Source as a System Library, need not be
|
||||
included in conveying the object code work.
|
||||
|
||||
A "User Product" is either (1) a "consumer product", which means any
|
||||
tangible personal property which is normally used for personal, family,
|
||||
or household purposes, or (2) anything designed or sold for incorporation
|
||||
into a dwelling. In determining whether a product is a consumer product,
|
||||
doubtful cases shall be resolved in favor of coverage. For a particular
|
||||
product received by a particular user, "normally used" refers to a
|
||||
typical or common use of that class of product, regardless of the status
|
||||
of the particular user or of the way in which the particular user
|
||||
actually uses, or expects or is expected to use, the product. A product
|
||||
is a consumer product regardless of whether the product has substantial
|
||||
commercial, industrial or non-consumer uses, unless such uses represent
|
||||
the only significant mode of use of the product.
|
||||
|
||||
"Installation Information" for a User Product means any methods,
|
||||
procedures, authorization keys, or other information required to install
|
||||
and execute modified versions of a covered work in that User Product from
|
||||
a modified version of its Corresponding Source. The information must
|
||||
suffice to ensure that the continued functioning of the modified object
|
||||
code is in no case prevented or interfered with solely because
|
||||
modification has been made.
|
||||
|
||||
If you convey an object code work under this section in, or with, or
|
||||
specifically for use in, a User Product, and the conveying occurs as
|
||||
part of a transaction in which the right of possession and use of the
|
||||
User Product is transferred to the recipient in perpetuity or for a
|
||||
fixed term (regardless of how the transaction is characterized), the
|
||||
Corresponding Source conveyed under this section must be accompanied
|
||||
by the Installation Information. But this requirement does not apply
|
||||
if neither you nor any third party retains the ability to install
|
||||
modified object code on the User Product (for example, the work has
|
||||
been installed in ROM).
|
||||
|
||||
The requirement to provide Installation Information does not include a
|
||||
requirement to continue to provide support service, warranty, or updates
|
||||
for a work that has been modified or installed by the recipient, or for
|
||||
the User Product in which it has been modified or installed. Access to a
|
||||
network may be denied when the modification itself materially and
|
||||
adversely affects the operation of the network or violates the rules and
|
||||
protocols for communication across the network.
|
||||
|
||||
Corresponding Source conveyed, and Installation Information provided,
|
||||
in accord with this section must be in a format that is publicly
|
||||
documented (and with an implementation available to the public in
|
||||
source code form), and must require no special password or key for
|
||||
unpacking, reading or copying.
|
||||
|
||||
7. Additional Terms.
|
||||
|
||||
"Additional permissions" are terms that supplement the terms of this
|
||||
License by making exceptions from one or more of its conditions.
|
||||
Additional permissions that are applicable to the entire Program shall
|
||||
be treated as though they were included in this License, to the extent
|
||||
that they are valid under applicable law. If additional permissions
|
||||
apply only to part of the Program, that part may be used separately
|
||||
under those permissions, but the entire Program remains governed by
|
||||
this License without regard to the additional permissions.
|
||||
|
||||
When you convey a copy of a covered work, you may at your option
|
||||
remove any additional permissions from that copy, or from any part of
|
||||
it. (Additional permissions may be written to require their own
|
||||
removal in certain cases when you modify the work.) You may place
|
||||
additional permissions on material, added by you to a covered work,
|
||||
for which you have or can give appropriate copyright permission.
|
||||
|
||||
Notwithstanding any other provision of this License, for material you
|
||||
add to a covered work, you may (if authorized by the copyright holders of
|
||||
that material) supplement the terms of this License with terms:
|
||||
|
||||
a) Disclaiming warranty or limiting liability differently from the
|
||||
terms of sections 15 and 16 of this License; or
|
||||
|
||||
b) Requiring preservation of specified reasonable legal notices or
|
||||
author attributions in that material or in the Appropriate Legal
|
||||
Notices displayed by works containing it; or
|
||||
|
||||
c) Prohibiting misrepresentation of the origin of that material, or
|
||||
requiring that modified versions of such material be marked in
|
||||
reasonable ways as different from the original version; or
|
||||
|
||||
d) Limiting the use for publicity purposes of names of licensors or
|
||||
authors of the material; or
|
||||
|
||||
e) Declining to grant rights under trademark law for use of some
|
||||
trade names, trademarks, or service marks; or
|
||||
|
||||
f) Requiring indemnification of licensors and authors of that
|
||||
material by anyone who conveys the material (or modified versions of
|
||||
it) with contractual assumptions of liability to the recipient, for
|
||||
any liability that these contractual assumptions directly impose on
|
||||
those licensors and authors.
|
||||
|
||||
All other non-permissive additional terms are considered "further
|
||||
restrictions" within the meaning of section 10. If the Program as you
|
||||
received it, or any part of it, contains a notice stating that it is
|
||||
governed by this License along with a term that is a further
|
||||
restriction, you may remove that term. If a license document contains
|
||||
a further restriction but permits relicensing or conveying under this
|
||||
License, you may add to a covered work material governed by the terms
|
||||
of that license document, provided that the further restriction does
|
||||
not survive such relicensing or conveying.
|
||||
|
||||
If you add terms to a covered work in accord with this section, you
|
||||
must place, in the relevant source files, a statement of the
|
||||
additional terms that apply to those files, or a notice indicating
|
||||
where to find the applicable terms.
|
||||
|
||||
Additional terms, permissive or non-permissive, may be stated in the
|
||||
form of a separately written license, or stated as exceptions;
|
||||
the above requirements apply either way.
|
||||
|
||||
8. Termination.
|
||||
|
||||
You may not propagate or modify a covered work except as expressly
|
||||
provided under this License. Any attempt otherwise to propagate or
|
||||
modify it is void, and will automatically terminate your rights under
|
||||
this License (including any patent licenses granted under the third
|
||||
paragraph of section 11).
|
||||
|
||||
However, if you cease all violation of this License, then your
|
||||
license from a particular copyright holder is reinstated (a)
|
||||
provisionally, unless and until the copyright holder explicitly and
|
||||
finally terminates your license, and (b) permanently, if the copyright
|
||||
holder fails to notify you of the violation by some reasonable means
|
||||
prior to 60 days after the cessation.
|
||||
|
||||
Moreover, your license from a particular copyright holder is
|
||||
reinstated permanently if the copyright holder notifies you of the
|
||||
violation by some reasonable means, this is the first time you have
|
||||
received notice of violation of this License (for any work) from that
|
||||
copyright holder, and you cure the violation prior to 30 days after
|
||||
your receipt of the notice.
|
||||
|
||||
Termination of your rights under this section does not terminate the
|
||||
licenses of parties who have received copies or rights from you under
|
||||
this License. If your rights have been terminated and not permanently
|
||||
reinstated, you do not qualify to receive new licenses for the same
|
||||
material under section 10.
|
||||
|
||||
9. Acceptance Not Required for Having Copies.
|
||||
|
||||
You are not required to accept this License in order to receive or
|
||||
run a copy of the Program. Ancillary propagation of a covered work
|
||||
occurring solely as a consequence of using peer-to-peer transmission
|
||||
to receive a copy likewise does not require acceptance. However,
|
||||
nothing other than this License grants you permission to propagate or
|
||||
modify any covered work. These actions infringe copyright if you do
|
||||
not accept this License. Therefore, by modifying or propagating a
|
||||
covered work, you indicate your acceptance of this License to do so.
|
||||
|
||||
10. Automatic Licensing of Downstream Recipients.
|
||||
|
||||
Each time you convey a covered work, the recipient automatically
|
||||
receives a license from the original licensors, to run, modify and
|
||||
propagate that work, subject to this License. You are not responsible
|
||||
for enforcing compliance by third parties with this License.
|
||||
|
||||
An "entity transaction" is a transaction transferring control of an
|
||||
organization, or substantially all assets of one, or subdividing an
|
||||
organization, or merging organizations. If propagation of a covered
|
||||
work results from an entity transaction, each party to that
|
||||
transaction who receives a copy of the work also receives whatever
|
||||
licenses to the work the party's predecessor in interest had or could
|
||||
give under the previous paragraph, plus a right to possession of the
|
||||
Corresponding Source of the work from the predecessor in interest, if
|
||||
the predecessor has it or can get it with reasonable efforts.
|
||||
|
||||
You may not impose any further restrictions on the exercise of the
|
||||
rights granted or affirmed under this License. For example, you may
|
||||
not impose a license fee, royalty, or other charge for exercise of
|
||||
rights granted under this License, and you may not initiate litigation
|
||||
(including a cross-claim or counterclaim in a lawsuit) alleging that
|
||||
any patent claim is infringed by making, using, selling, offering for
|
||||
sale, or importing the Program or any portion of it.
|
||||
|
||||
11. Patents.
|
||||
|
||||
A "contributor" is a copyright holder who authorizes use under this
|
||||
License of the Program or a work on which the Program is based. The
|
||||
work thus licensed is called the contributor's "contributor version".
|
||||
|
||||
A contributor's "essential patent claims" are all patent claims
|
||||
owned or controlled by the contributor, whether already acquired or
|
||||
hereafter acquired, that would be infringed by some manner, permitted
|
||||
by this License, of making, using, or selling its contributor version,
|
||||
but do not include claims that would be infringed only as a
|
||||
consequence of further modification of the contributor version. For
|
||||
purposes of this definition, "control" includes the right to grant
|
||||
patent sublicenses in a manner consistent with the requirements of
|
||||
this License.
|
||||
|
||||
Each contributor grants you a non-exclusive, worldwide, royalty-free
|
||||
patent license under the contributor's essential patent claims, to
|
||||
make, use, sell, offer for sale, import and otherwise run, modify and
|
||||
propagate the contents of its contributor version.
|
||||
|
||||
In the following three paragraphs, a "patent license" is any express
|
||||
agreement or commitment, however denominated, not to enforce a patent
|
||||
(such as an express permission to practice a patent or covenant not to
|
||||
sue for patent infringement). To "grant" such a patent license to a
|
||||
party means to make such an agreement or commitment not to enforce a
|
||||
patent against the party.
|
||||
|
||||
If you convey a covered work, knowingly relying on a patent license,
|
||||
and the Corresponding Source of the work is not available for anyone
|
||||
to copy, free of charge and under the terms of this License, through a
|
||||
publicly available network server or other readily accessible means,
|
||||
then you must either (1) cause the Corresponding Source to be so
|
||||
available, or (2) arrange to deprive yourself of the benefit of the
|
||||
patent license for this particular work, or (3) arrange, in a manner
|
||||
consistent with the requirements of this License, to extend the patent
|
||||
license to downstream recipients. "Knowingly relying" means you have
|
||||
actual knowledge that, but for the patent license, your conveying the
|
||||
covered work in a country, or your recipient's use of the covered work
|
||||
in a country, would infringe one or more identifiable patents in that
|
||||
country that you have reason to believe are valid.
|
||||
|
||||
If, pursuant to or in connection with a single transaction or
|
||||
arrangement, you convey, or propagate by procuring conveyance of, a
|
||||
covered work, and grant a patent license to some of the parties
|
||||
receiving the covered work authorizing them to use, propagate, modify
|
||||
or convey a specific copy of the covered work, then the patent license
|
||||
you grant is automatically extended to all recipients of the covered
|
||||
work and works based on it.
|
||||
|
||||
A patent license is "discriminatory" if it does not include within
|
||||
the scope of its coverage, prohibits the exercise of, or is
|
||||
conditioned on the non-exercise of one or more of the rights that are
|
||||
specifically granted under this License. You may not convey a covered
|
||||
work if you are a party to an arrangement with a third party that is
|
||||
in the business of distributing software, under which you make payment
|
||||
to the third party based on the extent of your activity of conveying
|
||||
the work, and under which the third party grants, to any of the
|
||||
parties who would receive the covered work from you, a discriminatory
|
||||
patent license (a) in connection with copies of the covered work
|
||||
conveyed by you (or copies made from those copies), or (b) primarily
|
||||
for and in connection with specific products or compilations that
|
||||
contain the covered work, unless you entered into that arrangement,
|
||||
or that patent license was granted, prior to 28 March 2007.
|
||||
|
||||
Nothing in this License shall be construed as excluding or limiting
|
||||
any implied license or other defenses to infringement that may
|
||||
otherwise be available to you under applicable patent law.
|
||||
|
||||
12. No Surrender of Others' Freedom.
|
||||
|
||||
If conditions are imposed on you (whether by court order, agreement or
|
||||
otherwise) that contradict the conditions of this License, they do not
|
||||
excuse you from the conditions of this License. If you cannot convey a
|
||||
covered work so as to satisfy simultaneously your obligations under this
|
||||
License and any other pertinent obligations, then as a consequence you may
|
||||
not convey it at all. For example, if you agree to terms that obligate you
|
||||
to collect a royalty for further conveying from those to whom you convey
|
||||
the Program, the only way you could satisfy both those terms and this
|
||||
License would be to refrain entirely from conveying the Program.
|
||||
|
||||
13. Remote Network Interaction; Use with the GNU General Public License.
|
||||
|
||||
Notwithstanding any other provision of this License, if you modify the
|
||||
Program, your modified version must prominently offer all users
|
||||
interacting with it remotely through a computer network (if your version
|
||||
supports such interaction) an opportunity to receive the Corresponding
|
||||
Source of your version by providing access to the Corresponding Source
|
||||
from a network server at no charge, through some standard or customary
|
||||
means of facilitating copying of software. This Corresponding Source
|
||||
shall include the Corresponding Source for any work covered by version 3
|
||||
of the GNU General Public License that is incorporated pursuant to the
|
||||
following paragraph.
|
||||
|
||||
Notwithstanding any other provision of this License, you have
|
||||
permission to link or combine any covered work with a work licensed
|
||||
under version 3 of the GNU General Public License into a single
|
||||
combined work, and to convey the resulting work. The terms of this
|
||||
License will continue to apply to the part which is the covered work,
|
||||
but the work with which it is combined will remain governed by version
|
||||
3 of the GNU General Public License.
|
||||
|
||||
14. Revised Versions of this License.
|
||||
|
||||
The Free Software Foundation may publish revised and/or new versions of
|
||||
the GNU Affero General Public License from time to time. Such new versions
|
||||
will be similar in spirit to the present version, but may differ in detail to
|
||||
address new problems or concerns.
|
||||
|
||||
Each version is given a distinguishing version number. If the
|
||||
Program specifies that a certain numbered version of the GNU Affero General
|
||||
Public License "or any later version" applies to it, you have the
|
||||
option of following the terms and conditions either of that numbered
|
||||
version or of any later version published by the Free Software
|
||||
Foundation. If the Program does not specify a version number of the
|
||||
GNU Affero General Public License, you may choose any version ever published
|
||||
by the Free Software Foundation.
|
||||
|
||||
If the Program specifies that a proxy can decide which future
|
||||
versions of the GNU Affero General Public License can be used, that proxy's
|
||||
public statement of acceptance of a version permanently authorizes you
|
||||
to choose that version for the Program.
|
||||
|
||||
Later license versions may give you additional or different
|
||||
permissions. However, no additional obligations are imposed on any
|
||||
author or copyright holder as a result of your choosing to follow a
|
||||
later version.
|
||||
|
||||
15. Disclaimer of Warranty.
|
||||
|
||||
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
|
||||
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
|
||||
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
|
||||
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
|
||||
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
||||
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
|
||||
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
|
||||
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
|
||||
|
||||
16. Limitation of Liability.
|
||||
|
||||
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
|
||||
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
|
||||
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
|
||||
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
|
||||
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
|
||||
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
|
||||
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
|
||||
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
|
||||
SUCH DAMAGES.
|
||||
|
||||
17. Interpretation of Sections 15 and 16.
|
||||
|
||||
If the disclaimer of warranty and limitation of liability provided
|
||||
above cannot be given local legal effect according to their terms,
|
||||
reviewing courts shall apply local law that most closely approximates
|
||||
an absolute waiver of all civil liability in connection with the
|
||||
Program, unless a warranty or assumption of liability accompanies a
|
||||
copy of the Program in return for a fee.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
How to Apply These Terms to Your New Programs
|
||||
|
||||
If you develop a new program, and you want it to be of the greatest
|
||||
possible use to the public, the best way to achieve this is to make it
|
||||
free software which everyone can redistribute and change under these terms.
|
||||
|
||||
To do so, attach the following notices to the program. It is safest
|
||||
to attach them to the start of each source file to most effectively
|
||||
state the exclusion of warranty; and each file should have at least
|
||||
the "copyright" line and a pointer to where the full notice is found.
|
||||
|
||||
<one line to give the program's name and a brief idea of what it does.>
|
||||
Copyright (C) <year> <name of author>
|
||||
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU Affero General Public License as published by
|
||||
the Free Software Foundation, either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU Affero General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU Affero General Public License
|
||||
along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||
|
||||
Also add information on how to contact you by electronic and paper mail.
|
||||
|
||||
If your software can interact with users remotely through a computer
|
||||
network, you should also make sure that it provides a way for users to
|
||||
get its source. For example, if your program is a web application, its
|
||||
interface could display a "Source" link that leads users to an archive
|
||||
of the code. There are many ways you could offer source, and different
|
||||
solutions will be better for different programs; see section 13 for the
|
||||
specific requirements.
|
||||
|
||||
You should also get your employer (if you work as a programmer) or school,
|
||||
if any, to sign a "copyright disclaimer" for the program, if necessary.
|
||||
For more information on this, and how to apply and follow the GNU AGPL, see
|
||||
<https://www.gnu.org/licenses/>.
|
||||
File renamed without changes.
@@ -1,227 +1,77 @@
|
||||
<p align="center">
|
||||
<img src="port/android/steam_frame_grid/library.png" width="640" alt="Mjolnir VR">
|
||||
</p>
|
||||
Halo 1 xbox decomp, ported to Linux, Windows and Android
|
||||
=============
|
||||
|
||||
# Mjolnir VR
|
||||
This is a port of the decompilation of Halo: Combat Evolved build 2342 (`cachebeta.exe`, sha256 `4cc87b45f721270392a96f1674ed2b5cd4a7bb4355faeab4531d1cf1884d9520`) to Linux, Windows and Android.
|
||||
|
||||
**A VR mod for Halo: Combat Evolved** (the original Xbox game) on the
|
||||
**Meta Quest 3 / 3S** and the **Steam Frame**. Play the campaign and
|
||||
multiplayer in full 6DoF virtual reality, with your hands in the game.
|
||||
<img width="1289" height="995" alt="image" src="https://github.com/user-attachments/assets/0d3ad50f-f8b8-46cf-aef8-e3661da2a7d7" />
|
||||
|
||||
Mjolnir VR runs on your headset by itself, without a PC. It
|
||||
brings no game files: it uses a disc image of **your own, purchased copy**
|
||||
of the game.
|
||||
This is based on [bnunu](https://github.com/bnunu/halo)'s decompilation project, which itself is a fork of [punpckhdq/halo](https://github.com/punpckhdq/halo).
|
||||
|
||||
> **Unofficial fan project.** Mjolnir VR is a free,
|
||||
> non-commercial fan project. It is not affiliated with, endorsed,
|
||||
> sponsored or approved by Microsoft, Xbox Game Studios, Halo Studios or
|
||||
> Bungie. See [Legal](#legal).
|
||||
## Agent quick references
|
||||
|
||||
Until build 313 it was called *Ringfall: Mjolnir VR*. Installed builds
|
||||
update to the new name by themselves, and the old links lead here.
|
||||
- [Current campaign house rules and batch/treemap cadence](docs/campaign_house_rules.md)
|
||||
- [Common constants, types, float patterns, tag IDs, and flag conventions](docs/common_constants.md)
|
||||
- [Shared assertion macros and byte-matching examples](docs/assertions.md)
|
||||
- [Supplied CE source maps, recovered names, and next reconstruction packets](docs/user_source_reconstruction_map_20260906.md)
|
||||
- [Matching methodology and source-credibility rules](docs/matching_methodology.md)
|
||||
|
||||
## Contents
|
||||
## Build instructions
|
||||
|
||||
- [What you get](#what-you-get)
|
||||
- [What you can play](#what-you-can-play)
|
||||
- [What you need](#what-you-need)
|
||||
- [Install on Meta Quest 3 / 3S](#install-on-meta-quest-3--3s)
|
||||
- [Install on Steam Frame](#install-on-steam-frame)
|
||||
- [Playing](#playing)
|
||||
- [Problems and questions](#problems-and-questions)
|
||||
- [Credits](#credits)
|
||||
- [Legal](#legal)
|
||||
You need Python and [ninja-build](https://ninja-build.org/) on your PATH; run `configure.py` from the repository root, then `ninja` with the target below (plain `ninja` builds the one for the computer you are on). No part of the Xbox SDK is needed: the SDK declarations the game uses are in [port/include/xdk](port/include/xdk/README.md).
|
||||
|
||||
## What you get
|
||||
Every pushed commit is built by GitHub Actions ([.github/workflows/build.yml](.github/workflows/build.yml)): debug and release builds for Linux, Windows and Android, made by `tools/ci_build.py` (which also works locally, e.g. `python tools/ci_build.py linux release`) and kept as artifacts for three days.
|
||||
|
||||
- **Full VR**: stereo 6DoF at your headset's refresh rate (72 to 120 Hz);
|
||||
the HUD, menus, scope and crosshair float as layers of their own.
|
||||
- **Your hands in the game**: the weapon sits in your hand and fires
|
||||
where you point it; arms and fingers follow your controllers;
|
||||
two-handed weapons, melee by swinging, grenades thrown with your hand,
|
||||
crouching and leaning with your body.
|
||||
- **Vehicles**: steer the Warthog by turning its wheel with both hands;
|
||||
turrets with handles.
|
||||
- **Comfort**: snap or smooth turning in fine steps, comfort vignettes,
|
||||
left-handed mode, buttons remapped freely, graphics presets, refresh
|
||||
rate and resolution, all in the in-game VR options (**Y**).
|
||||
- **The PC version's menus**, clicked with a laser pointer, and an
|
||||
on-screen keyboard for names, codes and passwords.
|
||||
### Native Linux build
|
||||
|
||||
## What you can play
|
||||
`ninja linux` compiles the game with clang into a native 32-bit Linux executable, `build/linux/halo`. It needs clang, 32-bit glibc development files and 32-bit SDL3. It renders with OpenGL, plays sound through SDL3 audio, and takes keyboard, mouse and gamepad input. Put the PAL game data (build 01.01.14.2342) under `assets/` so that `assets/maps` exists, then run `build/linux/halo`. See [port/linux/README.md](port/linux/README.md) for controls and settings.
|
||||
|
||||
- **The whole campaign**: all ten missions, on every difficulty, saved as
|
||||
you go.
|
||||
- **Co-op campaign** with friends, online or on your local network, with
|
||||
settings for friendly fire and extra enemies per player.
|
||||
- **LAN multiplayer** (system link) with everyone on your network.
|
||||
- **Online multiplayer**, no server of your own needed: host a game and
|
||||
share its join code, find public games in the server browser, or protect
|
||||
a lobby with a password. Up to 128 players.
|
||||
- **Bots** to fill a game, on foot, in vehicles and at turrets; they make
|
||||
room when a person joins.
|
||||
- **All 13 multiplayer maps** and the Xbox game's game types: Slayer,
|
||||
Capture the Flag, King of the Hill, Oddball and Race.
|
||||
- **Cross-play**: VR players on the Quest and the Steam Frame, together with
|
||||
players of the PC and phone builds of
|
||||
[OpenCE](https://github.com/OpenCommunityEdition/OpenCE).
|
||||
### Debug and release
|
||||
|
||||
## What you need
|
||||
The native builds (Linux, Windows, Android) are debug builds by default: like the build the decompilation reproduces, they stop at the first failed assertion and log it. `python configure.py --release` configures release builds instead, which, like the retail game, do not check assertions. The byte-matching build is unaffected.
|
||||
|
||||
- A **Meta Quest 3 / 3S** or a **Steam Frame**.
|
||||
- A **disc image** (`.iso` or `.xiso`) of **Halo: Combat Evolved for the
|
||||
original Xbox**, made from **a disc you own**. Any region and version
|
||||
works. The game plays in the disc's language; on the European disc in
|
||||
Spanish and Italian it takes your headset's language (else the first).
|
||||
### Optimisation
|
||||
|
||||
This project does not include, link to or help find game files. Please
|
||||
do not ask for or share disc images in issues or discussions; such posts
|
||||
are deleted.
|
||||
The Linux and Windows builds are optimised for the processor of the computer that builds them (`-march=native`), and may not start on another. `python configure.py --portable` targets the x86-64 baseline instead (SSE2, which every 64-bit x86 processor has): use it for builds you share.
|
||||
|
||||
## Install on Meta Quest 3 / 3S
|
||||
They also use full link-time optimisation by default, which makes the final link take a minute or so; `--lto=thin` links in parallel and incrementally, `--lto=off` not at all.
|
||||
|
||||
You install the game once with a computer (Windows, macOS or Linux); after
|
||||
that it updates itself.
|
||||
They are also optimised with profiles of the game at play, recorded by an instrumented build playing the main menu and the opening minute of every campaign level by itself: `pgo/halo_linux.profdata` for Linux (and Android, whose code is almost the same) and `pgo/halo_windows.profdata` for Windows. The profiles need clang 22 or later; with an older clang, and with `--pgo=off`, the builds do without. A profile stays useful as the code changes (functions it does not know simply go without). To record a new one, delete it and configure with `--pgo=train`: `ninja linux` or `ninja windows` then builds the instrumented game and plays the levels (about fifteen minutes, in a window, silently; it needs the game data in `assets/`) before the real build. Over ssh, Windows plays them on the logged-in user's desktop, through a scheduled task. `--pgo-profile <file>` uses another profile.
|
||||
|
||||
1. **Turn on Developer Mode** for your Quest, once: in the Meta Horizon
|
||||
app on your phone, open your headset's settings, then *Developer
|
||||
Mode* (Meta asks you to create a free developer account first).
|
||||
2. **Install [SideQuest](https://sidequestvr.com/setup-howto)** (the
|
||||
"Advanced Installer") on your computer and connect the Quest with a
|
||||
USB cable. In the headset, allow USB debugging for this computer.
|
||||
3. **Download `MjolnirVR.apk`** from the
|
||||
[latest release](../../releases/latest) and drag it onto the SideQuest
|
||||
window. It installs the game.
|
||||
4. **Copy your disc image** to the Quest's `Download` folder: in
|
||||
SideQuest, open the file manager (the folder icon), go to `Download`
|
||||
and drag the `.iso` file in.
|
||||
5. **In the headset**, open your *Library*, choose *Unknown Sources* and
|
||||
start **Mjolnir VR**. Select **Choose disc image** and pick
|
||||
your file in `Download`. The game copies what it needs (about 1.8 GB,
|
||||
a minute or two) and starts.
|
||||
With Mesa drivers the Linux build makes its GL calls through Mesa's GL thread (`mesa_glthread`), which takes them off the game's thread.
|
||||
|
||||
You can delete the disc image from `Download` afterwards. When a new
|
||||
version comes out, the game asks you at start whether to update.
|
||||
Frames per second at the opening of a30, uncapped (`vsync = false` in `config.toml`, or `HALO_NO_VSYNC=1`), about 510 draws per frame; each row adds one change to the one above (Linux: a laptop with an Intel Core i7-1355U and Iris Xe graphics, median of three runs; Android: a Pixel 9 Pro XL, Tensor G4, median of three runs):
|
||||
|
||||
## Install on Steam Frame
|
||||
| Change | Linux | Android |
|
||||
| --- | ---: | ---: |
|
||||
| Original | 103 | 132 |
|
||||
| GL state set only when it changes | 139 | 156 |
|
||||
| Vertex and index buffers from a GL copy of the Xbox memory | 171 | 193 |
|
||||
| Full link-time optimisation | 189 | not applicable |
|
||||
| Profile-guided optimisation | 201 | 197 |
|
||||
| `-march=native` (`--portable`, x86-64: 212; Android: `-mcpu=cortex-x3`, not used) | 224 | 191 |
|
||||
| Mesa's GL thread | 257 | not applicable |
|
||||
| Sound obstruction tested once per game tick, cheaper per-draw bookkeeping | 303 | 220 |
|
||||
|
||||
No computer and no keyboard needed.
|
||||
Android has no equivalent of `-march=native`: the build runs on any 64-bit phone, and compiling for the Pixel's big cores made it slower there anyway, so its last row builds on the profile-guided one. On the laptop the game's own thread no longer sets the frame rate: it spends about as long waiting for the GL and driver threads and the GPU (which the laptop's power management keeps at a low clock for this load) as they spend waiting for it. The same holds in heavier scenes such as b30, at about 190.
|
||||
|
||||
1. **Switch to Desktop Mode**: press the Steam button, then *Power* >
|
||||
*Switch to Desktop*.
|
||||
2. **Put your disc image** in the `Downloads` folder (for example from a
|
||||
USB stick or memory card with the file manager, Dolphin).
|
||||
3. **Download `Install-Mjolnir-VR.desktop`** from the
|
||||
[latest release](../../releases/latest) with the web browser.
|
||||
4. **Open it**: in Dolphin, open `Downloads` and double-click the file.
|
||||
If you are asked whether to run it, choose to continue.
|
||||
5. **Answer the dialogs.** The installer finds your disc image, copies
|
||||
what the game needs, adds **Mjolnir VR** to your Steam
|
||||
library and offers to switch back to Gaming Mode.
|
||||
6. Start **Mjolnir VR** from your library (under *Non-Steam*).
|
||||
Unity ("jumbo") builds, which compile many files as one, would give the compiler nothing full link-time optimisation does not already see, and the decompiled sources declare too many conflicting local types for it anyway. `-O3` and profile-driven function splitting measured no faster than `-O2`.
|
||||
|
||||
The game updates itself: when a new version is out, it is downloaded
|
||||
while you play and used from the next start on. Your settings, saves and
|
||||
game data stay. More about the Steam Frame:
|
||||
[port/android/STEAM_FRAME.md](port/android/STEAM_FRAME.md).
|
||||
### Frame rate
|
||||
|
||||
## Playing
|
||||
The native builds draw a frame at every refresh of the display (60, 90, 120, 240 Hz, ...), paced by vsync, while the game still simulates at 30 Hz as on the Xbox: each frame blends the last two ticks. To see the frame rate, open the developer console (the \` key) and enter `display_framerate true`; the frames per second, averaged over half a second, appear at the bottom right of the screen. `interpolation = false` in `config.toml` (written next to the executable, or in the data folder on Android, on the first run) restores the original 30 frames per second. See [port/linux/README.md](port/linux/README.md#frame-rate).
|
||||
|
||||
- **Y** opens the VR options in the main and pause menus: turning,
|
||||
comfort, weapon hand, buttons, graphics, refresh rate and resolution.
|
||||
*Quit the game* is on its last page.
|
||||
- In the menus, point with a controller and pull the trigger to click.
|
||||
- The controller layout is on the VR options' *Controller buttons* page.
|
||||
- **Voice chat** in network games: hold the grip of the hand without the
|
||||
weapon to talk (not while it holds the weapon or the Warthog's wheel).
|
||||
The *BUTTONS* page can put push to talk on another button.
|
||||
### Native Windows build
|
||||
|
||||
## Problems and questions
|
||||
`ninja windows`, run on Windows, compiles the game with clang into a native 32-bit Windows executable, `build/windows/halo.exe` (with `SDL3.dll`), sharing the Linux build's platform layer. It needs LLVM, Python and ninja, plus Visual Studio's x86 C++ libraries and a Windows SDK. Put the game data under `assets/` as for Linux. See [port/windows/README.md](port/windows/README.md).
|
||||
|
||||
Please open an [issue](../../issues) and include:
|
||||
### Android build
|
||||
|
||||
- your headset and the build number of the release you installed;
|
||||
- what you did and what happened;
|
||||
- the game's log, `debug.txt`:
|
||||
- Quest: `Android/data/io.github.cesarus85.ringfall/files/debug.txt`
|
||||
(SideQuest's file manager);
|
||||
- Steam Frame: `Documents/RingfallMjolnirVR/debug.txt` (and
|
||||
`logcat.txt` and `install.log` beside it).
|
||||
`ninja android_apk` builds an arm64 Android app (`port/android/app/build/outputs/apk/debug/app-debug.apk`) that runs the game natively on 64-bit ARM phones, with OpenGL ES 3 rendering at the device's aspect ratio, SDL3 audio and game controller support (including a PS5 DualSense over Bluetooth). It needs the Android NDK and a clang with the `arm64_32` target in addition to the Linux build's requirements. The game data goes in the app's storage (the app offers to import it). See [port/android/README.md](port/android/README.md).
|
||||
|
||||
What is done and what comes next: [port/android/VR_ROADMAP.md](port/android/VR_ROADMAP.md).
|
||||
### Matching build
|
||||
|
||||
**Network use.** The game connects to the internet only for what you
|
||||
use: the update check (GitHub), online games (to other players
|
||||
directly), and join codes and lobby lists through public MQTT brokers
|
||||
(listed in [brokers.txt](port/assets/network/brokers.txt)). There is no
|
||||
telemetry.
|
||||
This fork builds only the native ports. The upstream project's byte-matching build, which compiles the game with the Xbox SDK's own compiler and compares it with `cachebeta.exe`, needs the August 2001 Xbox SDK, which cannot be redistributed, so `configure.py` no longer writes it. Its sources, configuration and `#ifdef`s are kept as they are, so that upstream's matching work still merges; `SolutionConfig.matching` in `tools/project_x86.py` turns it back on, for a checkout with the SDK's `XDK/xbox` folder extracted to `xbox/` and `cachebeta.exe` in the repository root. See [port/linux/README.md](port/linux/README.md#the-matching-build-on-a-linux-host) for running it on Linux.
|
||||
|
||||
## Credits
|
||||
## Where's all the type information?
|
||||
|
||||
Mjolnir VR stands on the work of others:
|
||||
|
||||
- **[OpenCE](https://github.com/OpenCommunityEdition/OpenCE)** (Open
|
||||
Community Edition): the port of the decompiled game to Linux, Windows
|
||||
and Android, with its renderer, netcode, PC menus and multiplayer, that
|
||||
this project builds on and follows.
|
||||
- **The decompilation**: [bnunu/halo-1](https://github.com/bnunu/halo-1),
|
||||
a fork of [punpckhdq/halo](https://github.com/punpckhdq/halo).
|
||||
- **[HaloCE-Quest-VR](https://github.com/moistman42069/HaloCE-Quest-VR)**
|
||||
by moistman42069 (CC0): the arm IK, the forearm's twist and the
|
||||
fingers' poses are taken from it (`port/linux/game/vr_arms.c`); the
|
||||
left-handed mode and the graphics presets follow its ideas.
|
||||
- **[HaloCE-VR](https://github.com/astromaddie/HaloCE-VR)** by astromaddie
|
||||
(CC0): the Steam Frame work, whose findings (such as quieting Mesa's
|
||||
trace markers) are used here.
|
||||
- **[xboxdevwiki](https://xboxdevwiki.net/XDVDFS)**: its description of
|
||||
the Xbox's disc file system, which the disc image readers are written
|
||||
from.
|
||||
- The libraries and fonts in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|
||||
|
||||
Thank you all.
|
||||
|
||||
## Building it
|
||||
|
||||
`python3 configure.py --release`, then `ninja android_apk` (Android SDK
|
||||
and NDK needed). See [port/android/README.md](port/android/README.md) for
|
||||
the details and [docs/OPENCE_README.md](docs/OPENCE_README.md) for the
|
||||
port it is built on.
|
||||
|
||||
## Legal
|
||||
|
||||
Mjolnir VR is an unofficial, free, non-commercial fan project.
|
||||
It is not affiliated with, endorsed, sponsored or approved by Microsoft
|
||||
Corporation, Xbox Game Studios, Halo Studios or Bungie. Halo, Halo: Combat
|
||||
Evolved and Xbox are trademarks of Microsoft Corporation; they are named
|
||||
here only to say which game this mod works with. Meta Quest is a trademark
|
||||
of Meta Platforms, Inc.; Steam and Steam Frame are trademarks of Valve
|
||||
Corporation.
|
||||
|
||||
No game data, art, music or other content of the game is included or
|
||||
distributed. You need your own, legally purchased copy of the game. If
|
||||
you enjoy this mod, please support the creators of the original by buying
|
||||
their games.
|
||||
|
||||
### Licence
|
||||
|
||||
Mjolnir VR is free software: you can give it to others and change
|
||||
it under the terms of the GNU Affero General Public License as published by
|
||||
the Free Software Foundation, version 3 of the License or (at your option)
|
||||
any later version (`AGPL-3.0-or-later`), as OpenCE, which it builds on, is.
|
||||
It comes with no warranty. The full text is in [LICENSE](LICENSE).
|
||||
|
||||
- **From build 312 on.** The AGPL applies from the commit that took in
|
||||
OpenCE's change of licence (19 October 2026), and to each release built
|
||||
from it or a later one. Earlier releases, and the source at every earlier
|
||||
commit, were released under [CC0 1.0](LICENSES/CC0-1.0.txt) and stay
|
||||
that way.
|
||||
- **Hosts and servers.** If you change the game and let other persons play
|
||||
with your version over a network (for example, as the host of an
|
||||
internet game), the AGPL asks you to offer them the source of your
|
||||
version. The game as released has its source here, and each release's
|
||||
source is its tag (`build-<n>`).
|
||||
- **Third-party code and fonts** keep their own licences: see
|
||||
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|
||||
- **Halo is not covered.** The licence covers the work of this project's
|
||||
and OpenCE's authors. It gives no rights in Halo, its maps or anything
|
||||
else that Microsoft owns.
|
||||
We use debug symbols from later Halo games to help map structures, enums, type definitions, function signatures and some variable names. You should obtain a copy of the Halo CEA beta and run it through [pdb-decompiler](https://github.com/camden-smallwood/pdb-decompiler) to obtain debug info for yourself. Note that CEA is based off of Halo PC and has its own modifications which make it not 100% accurate to the original Xbox title.
|
||||
@@ -1,48 +0,0 @@
|
||||
# Third-party notices
|
||||
|
||||
Mjolnir VR is released under the GNU Affero General Public
|
||||
License, version 3 or later ([LICENSE](LICENSE)); releases before build 312
|
||||
were released under [CC0 1.0](LICENSES/CC0-1.0.txt). It includes or builds
|
||||
on the following, under their own licenses; each license's full text is in
|
||||
the file named.
|
||||
|
||||
## Code
|
||||
|
||||
| Component | Used for | License | Text |
|
||||
| --- | --- | --- | --- |
|
||||
| [OpenCE](https://github.com/OpenCommunityEdition/OpenCE) and the decompilation ([bnunu/halo-1](https://github.com/bnunu/halo-1), [punpckhdq/halo](https://github.com/punpckhdq/halo)) | the game's code, the port | AGPL 3.0 or later (OpenCE from 19 October 2026, punpckhdq/halo from 17 October 2026; CC0 1.0 before); bnunu/halo-1: CC0 1.0 | [LICENSE](LICENSE), [LICENSES/CC0-1.0.txt](LICENSES/CC0-1.0.txt) |
|
||||
| [HaloCE-Quest-VR](https://github.com/moistman42069/HaloCE-Quest-VR) | the arm IK, forearm twist and finger poses (`port/linux/game/vr_arms.c`) | CC0 1.0 | (its repository) |
|
||||
| [HaloCE-VR](https://github.com/astromaddie/HaloCE-VR) | Steam Frame findings | CC0 1.0 | (its repository) |
|
||||
| [SDL 3](https://libsdl.org) | windows, input, sound | zlib | (in SDL's source, `LICENSE.txt`) |
|
||||
| [Khronos OpenXR loader](https://github.com/KhronosGroup/OpenXR-SDK) | VR runtime access | Apache 2.0 | (in the loader's package) |
|
||||
| [musl](https://musl.libc.org) | the C library of the game's code on Android, its maths | MIT | [port/third_party/musl-math](port/third_party/musl-math/README.md) |
|
||||
| [Expat](https://libexpat.github.io) | the PC menus' definitions | MIT | [port/third_party/expat/COPYING](port/third_party/expat/COPYING) |
|
||||
| [Mbed TLS](https://www.trustedfirmware.org/projects/mbed-tls/) | HTTPS for the desktop builds' updater (not in the Android app) | Apache 2.0 | [port/third_party/mbedtls/LICENSE](port/third_party/mbedtls/LICENSE) |
|
||||
| [miniupnpc](https://miniupnp.tuxfamily.org) | router port forwarding for online games | BSD 3-Clause | [port/third_party/miniupnpc/LICENSE](port/third_party/miniupnpc/LICENSE) |
|
||||
| [KCP](https://github.com/skywind3000/kcp) | reliable transport for online games | MIT | [port/third_party/kcp/LICENSE](port/third_party/kcp/LICENSE) |
|
||||
| [Monocypher](https://monocypher.org) | signing public games' listings (Ed25519); online play's other cryptography is the port's own | CC0 1.0 or BSD 2-Clause | [port/third_party/monocypher/LICENCE.md](port/third_party/monocypher/LICENCE.md) |
|
||||
| [tomlc17](https://github.com/cktan/tomlc17) | reading `config.toml` | MIT | [port/third_party/tomlc17/LICENSE](port/third_party/tomlc17/LICENSE) |
|
||||
| [stb](https://github.com/nothings/stb) | drawing the game's text sharply (stb_truetype) | MIT or public domain | [port/third_party/stb/LICENSE](port/third_party/stb/LICENSE) |
|
||||
| [SMAA](https://www.iryoku.com/smaa/) | anti-aliasing (flat screens; off in VR) | MIT | [port/third_party/smaa/LICENSE](port/third_party/smaa/LICENSE) |
|
||||
|
||||
The disc image readers (`XisoExtractor.java`, `steam_frame_xiso.py`,
|
||||
`xiso.c`) are written from a description of the Xbox's disc file system
|
||||
([xboxdevwiki's XDVDFS page](https://xboxdevwiki.net/XDVDFS)), not from
|
||||
extract-xiso, which earlier releases followed.
|
||||
|
||||
## Fonts
|
||||
|
||||
| Font | Used for | License | Text |
|
||||
| --- | --- | --- | --- |
|
||||
| Overpass (Red Hat, Delve Withrington) | the game's text, the library pictures | SIL Open Font License 1.1 | [port/assets/fonts/Overpass-OFL.txt](port/assets/fonts/Overpass-OFL.txt) |
|
||||
| OpenCE (after Newtown) | the menus' titles | SIL Open Font License 1.1 | [port/assets/fonts/OpenCE-OFL.txt](port/assets/fonts/OpenCE-OFL.txt) |
|
||||
| Newtown (Roger White) | OpenCE's source | public domain | [port/assets/fonts/Newtown-LICENSE.txt](port/assets/fonts/Newtown-LICENSE.txt) |
|
||||
|
||||
See [port/assets/fonts/README.md](port/assets/fonts/README.md) for where
|
||||
each font is used.
|
||||
|
||||
## Not included
|
||||
|
||||
No file of Halo: Combat Evolved (maps, sounds, art, music, fonts or
|
||||
executables) is part of this repository or its releases. The game reads
|
||||
them from the player's own disc image.
|
||||
+1304
File diff suppressed because it is too large.
Load diff
+22457
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,45 @@
|
||||
{
|
||||
"version": 1,
|
||||
"entries": [
|
||||
{
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox_profile",
|
||||
"class": "source-layout-incomplete",
|
||||
"symbol": "_rasterizer_profile_globals",
|
||||
"reason": "All 16 target functions and all 2234 target data bytes are exact. The three stock SDK select-any tables (D3DTEXTUREDIRECTENCODE 16 bytes, D3DSIMPLERENDERSTATEENCODE 328, D3DPRIMITIVETOVERTEXCOUNT 88) come from D3D8.h's unconditional extern const selectany definitions, which January's TU included (its object imports _D3DDevice_InsertCallback@12 and QueryPerformance*). Each copy is byte-identical to January's selected provider and passes the selected-provider pair links in both orders, the standard under which collision_debug and the other Matching emitters carry the same tables. Canonical's dynavobgeom reconciliation (641e1466, docs/object_matching_logs/claude_fifty_objects_canonical_reconciliation.md) still leaves stock SDK-table coalescing open pending a uniform owner policy audit, so this object inherits that decision. Whole-object admission also fails source authenticity. The private state is written as four invented file-static aggregates (rasterizer_profile_globals, rasterizer_profile_elapsed_state, rasterizer_profile_frame_state, rasterizer_profile_state). Their pad02/pad06/pad12/pad16 members only spell out VC7's per-static 4-byte alignment padding, and reserved06[6] hides one unattested 4-byte object at .bss +0x45c. Loose file statics reproduce every code byte and every other data offset, and the later /Od build places elapsed_times before callback_start_times, contradicting the elapsed_state member order. The rasterizer_profile_check NONE branch reproduces January's format/varargs defect (%s consumes the NONE profile value), which awaits the owner's original-bug ruling. Three load-bearing volatile qualifiers have no first-party attestation. The TU also still declares global_window_parameters with a consumer-local extern: moving it to the owner header rasterizer_xbox_internal.h keeps every exact section byte-identical but declares the name earlier in rasterizer_xbox_models, which moves the residual __rasterizer_model_draw by one instruction.",
|
||||
"evidence": "research/fifty_objects_20260925/w/review3_rasterizer_xbox_profile/REVIEW.md",
|
||||
"reopen": "Recover the genuine January private state shape: replace the invented aggregates with authentic separate file statics, or first-party-attested structures, without fabricated pad/reserved members. Identify the unreferenced 4-byte January object at .bss +0x45c from first-party evidence rather than a filler. Obtain the owner's rulings on the BUG-marked NONE-branch varargs defect and the three volatile qualifiers. Any new private names need the owner's descriptive-name policy (as for the held rasterizer_xbox .bss split). Preserve all 16 target functions and all data sections, land the pinned 132-byte .data entry only with the Matching flip, move the window extern to its owner header with a full consumer sweep (re-baselining the rasterizer_xbox_models __rasterizer_model_draw park it perturbs), and apply the owner's uniform stock SDK-table decision from the open dynavobgeom reconciliation."
|
||||
},
|
||||
{
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox_dynavobgeom",
|
||||
"class": "candidate-only-comdat-owner",
|
||||
"symbol": "_D3DSIMPLERENDERSTATEENCODE",
|
||||
"reason": "All 17 January code functions and all 31 January-owned sections/symbols match after replacing local debug, window and pixel-shader views with genuine owner types. Nine D3DINLINE wrappers have January's file-static storage. The two surplus color-conversion helpers are byte-identical to January's selected providers, and all 17 surplus symbols pass selected-provider links in both orders. The global_window_parameters extern still lives in consumer C files, with incompatible partial views in other consumers rather than a common owner declaration. Three stock SDK tables and other candidate-only constants/literals remain absent from January's split; the selected-provider test ignores unrelated unresolved symbols. A complete ordinary final-link ownership proof has not been established, so exact function credit does not imply Matching.",
|
||||
"evidence": "docs/object_matching_logs/rasterizer_xbox_dynavobgeom_owner_layout_reconciliation.md",
|
||||
"reopen": "Move global_window_parameters to its authentic owner declaration and reconcile the partial consumer views with a full regression sweep. Establish selected ownership/coalescing of candidate-only SDK tables and helper data through a complete compatible ordinary link or equally decisive January source/link evidence, without losing target exactness. Do not suppress genuine header emissions, alter selection metadata, force-inline, hand-copy helpers or count candidate-only bytes as January-owned."
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/hud_draw",
|
||||
"class": "candidate-only-comdat-owner",
|
||||
"symbol": "_fast_ftol",
|
||||
"reason": "The exact flash-duration leaf uses the authentic shared conversion helper and naturally emits an additional unreferenced select-any32-byte fast_ftol copy absent from January HUD Draw. January's identical selected Actor Combat copy is no-duplicates; its ordinary XDK duplicate-owner failure is already documented. The two newly exact drawing helpers receive valid target-function credit, but no whole-object or linked-coalescing claim follows.",
|
||||
"evidence": "docs/object_matching_logs/hud_draw_obj_two_exact_leaves_integration_20260904.md#complete-owner-boundary",
|
||||
"reopen": "Require authentic source topology or an ordinary base/base link with an authenticated compatible canonical selected helper before clearing this veto. Do not force inline, manually expand math, alter target/COMDAT metadata, invent a discard pass, or credit candidate-only helper bytes. All remaining HUD Draw functions/data/linkage/source checks must independently pass before whole-object Matching."
|
||||
},
|
||||
{
|
||||
"unit": "source/effects/decals",
|
||||
"class": "candidate-only-comdat-owner",
|
||||
"symbol": "_vector_from_points2d",
|
||||
"reason": "The exact typed decal_projection_create body naturally inlines vector_from_points2d as January requires, but VC7 also emits an unreferenced select-any helper body absent from the January Decals split. January's selected Action Obey copy is no-duplicates. The exact target function receives valid credit; the surplus helper receives none and blocks whole-object Matching.",
|
||||
"evidence": "docs/object_matching_logs/decals_obj_color_projection_packet_20260912.md#inline-helper-ownership-boundary",
|
||||
"reopen": "Remove only when authentic source topology or an ordinary compatible canonical link preserves decal_projection_create while preventing or safely coalescing the extra helper. Do not force inline, manually expand the helper for code shaping, alter COMDAT metadata, or count the candidate-only bytes."
|
||||
},
|
||||
{
|
||||
"unit": "source/effects/decals",
|
||||
"class": "candidate-only-comdat-owner",
|
||||
"symbol": "_cross_product2d",
|
||||
"reason": "The exact typed decal_projection_create body naturally inlines cross_product2d as January requires, but VC7 also emits an unreferenced select-any helper body absent from the January Decals split. January's selected Actor Combat copy is no-duplicates. The exact target function receives valid credit; the surplus helper receives none and blocks whole-object Matching.",
|
||||
"evidence": "docs/object_matching_logs/decals_obj_color_projection_packet_20260912.md#inline-helper-ownership-boundary",
|
||||
"reopen": "Remove only when authentic source topology or an ordinary compatible canonical link preserves decal_projection_create while preventing or safely coalescing the extra helper. Do not force inline, manually expand the helper for code shaping, alter COMDAT metadata, or count the candidate-only bytes."
|
||||
}
|
||||
]
|
||||
}
|
||||
+1162
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,20 @@
|
||||
{
|
||||
"debug_sections": [
|
||||
{
|
||||
"after_fingerprint_sha256": "8e07b48ebedfa52de730be35f0b56d2fadb9b72e51a1edd029e20b5bb5cddc23",
|
||||
"before_fingerprint_sha256": "92288b56cfbca8760857b38d5fb34cdfe3b56c092891ebfa6c00dc9cfc68b395",
|
||||
"recipe": "xdk-stock-d3dinline",
|
||||
"section": ".debug$F|anonymous=2",
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox_plasma_energy"
|
||||
},
|
||||
{
|
||||
"after_fingerprint_sha256": "5b79f3d7f6d7cd9eca0a4324f66baf87dff523b69e917689707607178a0b48ab",
|
||||
"before_fingerprint_sha256": "fd054221f7d9970be62ba370272c65e7c78a8a116110be3a5796fb06a8127ece",
|
||||
"recipe": "xdk-stock-d3dinline",
|
||||
"section": ".debug$S|anonymous=0",
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox_plasma_energy"
|
||||
}
|
||||
],
|
||||
"functions": [],
|
||||
"schema_version": 1
|
||||
}
|
||||
@@ -0,0 +1,102 @@
|
||||
{
|
||||
"debug_sections": [
|
||||
{
|
||||
"after_fingerprint_sha256": "8e07b48ebedfa52de730be35f0b56d2fadb9b72e51a1edd029e20b5bb5cddc23",
|
||||
"before_fingerprint_sha256": "92288b56cfbca8760857b38d5fb34cdfe3b56c092891ebfa6c00dc9cfc68b395",
|
||||
"recipe": "xdk-stock-d3dinline",
|
||||
"section": ".debug$F|anonymous=2",
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox_text"
|
||||
}
|
||||
],
|
||||
"functions": [
|
||||
{
|
||||
"after_comdat_selection": 2,
|
||||
"after_fingerprint_sha256": "458fb5bd5e078ea76d95e47dd9632bb3bb0b3a25c8aa64efba41fd359a99b2cf",
|
||||
"before_comdat_selection": 1,
|
||||
"before_fingerprint_sha256": "9ff19872aa908361445bece0a21cab0ca4c93f68cb7bad1bcc70e77f0de6c6c8",
|
||||
"function": "_D3DDevice_SetRenderState",
|
||||
"recipe": "xdk-stock-d3dinline",
|
||||
"source_recipe": "stock XDK D3DINLINE (static __forceinline)",
|
||||
"target_evidence_sha256": "ef767bb47681ea399daf6f8720f056e523790d105bcea1f634d71c3e3611d192",
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox_text"
|
||||
},
|
||||
{
|
||||
"after_comdat_selection": 2,
|
||||
"after_fingerprint_sha256": "459f5d33ded34255e79f255c42a193c74066bdad08fc9116b2dd82eaf16ee094",
|
||||
"before_comdat_selection": 1,
|
||||
"before_fingerprint_sha256": "142d63782a1e9e3a41a5f722084b8681b1bf765912c4dd91784299a280112204",
|
||||
"function": "_D3DDevice_SetTextureStageState",
|
||||
"recipe": "xdk-stock-d3dinline",
|
||||
"source_recipe": "stock XDK D3DINLINE (static __forceinline)",
|
||||
"target_evidence_sha256": "ef19cb2f99aa7c1ad0f06f57c44a2dbace4b75ba6c779e68a1885e832d50d6c4",
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox_text"
|
||||
},
|
||||
{
|
||||
"after_comdat_selection": 2,
|
||||
"after_fingerprint_sha256": "5382805b884f0d40e945936f88f42d2b3c9f0c5ca0f83098312bc5a8444c3d66",
|
||||
"before_comdat_selection": 1,
|
||||
"before_fingerprint_sha256": "8f5385e5727b96b51ea06b98ff74fc9ba2f57802f0118f6f759e32ed3bb60797",
|
||||
"function": "_IDirect3DDevice8_Begin@8",
|
||||
"recipe": "xdk-stock-d3dinline",
|
||||
"source_recipe": "stock XDK D3DINLINE (static __forceinline)",
|
||||
"target_evidence_sha256": "f9f8776473104153fbb44b071659641050b0ef17ffde33740e053f1d31598d86",
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox_text"
|
||||
},
|
||||
{
|
||||
"after_comdat_selection": 2,
|
||||
"after_fingerprint_sha256": "a6c5208bf1949404ef5f4340bb14eff5ffab46a37c3aa041c2d5e4523b1dd8c2",
|
||||
"before_comdat_selection": 1,
|
||||
"before_fingerprint_sha256": "7916c2492802dcf917429ec316aefe67fbd8c96ef60bad99e12e26c38271342a",
|
||||
"function": "_IDirect3DDevice8_End@4",
|
||||
"recipe": "xdk-stock-d3dinline",
|
||||
"source_recipe": "stock XDK D3DINLINE (static __forceinline)",
|
||||
"target_evidence_sha256": "2acf41df227cc5ab56a634bc22b9a1af2f3594aa640b8a26e2126783c6802ed2",
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox_text"
|
||||
},
|
||||
{
|
||||
"after_comdat_selection": 2,
|
||||
"after_fingerprint_sha256": "09a181160ca4a0cec88563ed68f170bb7562d98e07cae82eb6ede383067e867c",
|
||||
"before_comdat_selection": 1,
|
||||
"before_fingerprint_sha256": "41c0a05e408be665a1bb43ea64bc56c1dbca0c5ef460f81b4248f6d02a2999d3",
|
||||
"function": "_IDirect3DDevice8_SetTextureStageState@16",
|
||||
"recipe": "xdk-stock-d3dinline",
|
||||
"source_recipe": "stock XDK D3DINLINE (static __forceinline)",
|
||||
"target_evidence_sha256": "b53ab8eb325c14f08df0e98df7b272a3dceb09921ed0d1dbeea49b69e07557f2",
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox_text"
|
||||
},
|
||||
{
|
||||
"after_comdat_selection": 2,
|
||||
"after_fingerprint_sha256": "13ff5c4aa2773bc0df32f62fce0afe58261ebabf2b2ca76426ef01a613fa7bf0",
|
||||
"before_comdat_selection": 1,
|
||||
"before_fingerprint_sha256": "7bb9a9967e3ddbbadfd0667b85c8f52ee06137a1f0b0cd4a0e45a4e1247d1815",
|
||||
"function": "_IDirect3DDevice8_SetVertexData2f@16",
|
||||
"recipe": "xdk-stock-d3dinline",
|
||||
"source_recipe": "stock XDK D3DINLINE (static __forceinline)",
|
||||
"target_evidence_sha256": "1303752bb188cf6b5a00adb8c2c49092f22408c2c38203e8daddf5b61aa61153",
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox_text"
|
||||
},
|
||||
{
|
||||
"after_comdat_selection": 2,
|
||||
"after_fingerprint_sha256": "78b5829871e22251b4e266bd81caa2eda338a6e93f43c2a592c93eaad8808e6b",
|
||||
"before_comdat_selection": 1,
|
||||
"before_fingerprint_sha256": "464ecff7dc1e2d1a1c18d02c467dcbe893baedfebfa42920922583cde75b9331",
|
||||
"function": "_IDirect3DDevice8_SetVertexDataColor@12",
|
||||
"recipe": "xdk-stock-d3dinline",
|
||||
"source_recipe": "stock XDK D3DINLINE (static __forceinline)",
|
||||
"target_evidence_sha256": "e4a0591ba36b4fdad4a24f1009fed7b141c8acf919c8a4bca421435760c2e38a",
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox_text"
|
||||
},
|
||||
{
|
||||
"after_comdat_selection": 2,
|
||||
"after_fingerprint_sha256": "c936826f1cdc47b8e52662c867164d8fa9063b86bd7050db06a3992a0414dba7",
|
||||
"before_comdat_selection": 1,
|
||||
"before_fingerprint_sha256": "db0e0cd1dc136a05abf97c28072edfda4b9cd8de3a0bf1e45fd45747655dcef5",
|
||||
"function": "_IDirect3DDevice8_SetVertexShaderConstant@16",
|
||||
"recipe": "xdk-stock-d3dinline",
|
||||
"source_recipe": "stock XDK D3DINLINE (static __forceinline)",
|
||||
"target_evidence_sha256": "cc42796796437d1eaee75aa6b6a300dc712d6d48cb2571820adf13f5eea7a3bd",
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox_text"
|
||||
}
|
||||
],
|
||||
"schema_version": 1
|
||||
}
|
||||
+113827
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"version": 1,
|
||||
"entries": []
|
||||
}
|
||||
@@ -0,0 +1,581 @@
|
||||
[
|
||||
{
|
||||
"unit": "source/shell/shell_xbox",
|
||||
"group": "aligned-rdata",
|
||||
"reason": "the complete rebuilt object owns the exact two string COMDATs and compiler-generated SEH scope table; the grouped verifier proves each payload, alignment-derived padded extent, flags, owner snapshot, relocation address/type, and source-relative handler destination while objdiff merges the aligned sections and attributes the private scope-table labels differently",
|
||||
"members": [
|
||||
{
|
||||
"symbol": "??_C@_06GAOAIMNN@xdemo?5?$AA@",
|
||||
"measurements": {
|
||||
"target": {
|
||||
"section": ".rdata",
|
||||
"size": 7,
|
||||
"padded_size": 8,
|
||||
"flags": 1076891712,
|
||||
"relocation_count": 0,
|
||||
"normalized_sha256": "2d636beaf6ef18262eb352ea8a00f3b1b0ee3628666eb07e679892eca5f08b5e",
|
||||
"owner": { "value": 0, "type": 0, "storage": 2 }
|
||||
},
|
||||
"base": {
|
||||
"section": ".rdata",
|
||||
"size": 7,
|
||||
"padded_size": 8,
|
||||
"flags": 1076891712,
|
||||
"relocation_count": 0,
|
||||
"normalized_sha256": "2d636beaf6ef18262eb352ea8a00f3b1b0ee3628666eb07e679892eca5f08b5e",
|
||||
"owner": { "value": 0, "type": 0, "storage": 2 }
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"symbol": "??_C@_06PFFNFMJI@XDEMOS?$AA@",
|
||||
"measurements": {
|
||||
"target": {
|
||||
"section": ".rdata",
|
||||
"size": 7,
|
||||
"padded_size": 8,
|
||||
"flags": 1076891712,
|
||||
"relocation_count": 0,
|
||||
"normalized_sha256": "798ec2f79c908eed7153344688b0def452386891f2deae50826a2658182e9bd5",
|
||||
"owner": { "value": 0, "type": 0, "storage": 2 }
|
||||
},
|
||||
"base": {
|
||||
"section": ".rdata",
|
||||
"size": 7,
|
||||
"padded_size": 8,
|
||||
"flags": 1076891712,
|
||||
"relocation_count": 0,
|
||||
"normalized_sha256": "798ec2f79c908eed7153344688b0def452386891f2deae50826a2658182e9bd5",
|
||||
"owner": { "value": 0, "type": 0, "storage": 2 }
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"symbol": "_rdata_002a0a88",
|
||||
"base_symbol": "$T18302",
|
||||
"source_function": "_main",
|
||||
"measurements": {
|
||||
"target": {
|
||||
"section": ".rdata",
|
||||
"size": 12,
|
||||
"padded_size": 16,
|
||||
"flags": 1077940288,
|
||||
"relocation_count": 2,
|
||||
"normalized_sha256": "3414421b183188342209566fad4e0c0723070b4030630dde685ba70281e92725",
|
||||
"owner": { "value": 0, "type": 0, "storage": 2 }
|
||||
},
|
||||
"base": {
|
||||
"section": ".rdata",
|
||||
"size": 12,
|
||||
"padded_size": 16,
|
||||
"flags": 1077940288,
|
||||
"relocation_count": 2,
|
||||
"normalized_sha256": "3414421b183188342209566fad4e0c0723070b4030630dde685ba70281e92725",
|
||||
"owner": { "value": 0, "type": 0, "storage": 3 }
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"unit": "libs/libcmt/crt0msg",
|
||||
"symbol": "_rterrs",
|
||||
"reason": "The first-party XDK names the private runtime-error table rterrs. January and the rebuilt object have identical 144-byte data, all 18 relocation sites and types, and independently resolved string destinations; objdiff undercredits the aggregate despite exact COFF section comparison.",
|
||||
"measurements": {
|
||||
"size": 144,
|
||||
"relocation_count": 18,
|
||||
"normalized_sha256": "25298d4d1ea85dfa6a4696577658216429876d7b7b59ed245667db872d9d79d2"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/camera/editor_flying_camera",
|
||||
"group": "camera-static-sections",
|
||||
"allow_incomplete_unit": true,
|
||||
"credit_raw_size": true,
|
||||
"reason": "January and the rebuilt object have identical 124-byte private .bss and 52-byte .data payloads, flags, alignments, and owner storage. The nine .data relocations resolve to the same image destinations. HCEX names the separate file statics and their definition order; the January .bss offsets corroborate their exact layout. Objdiff undercredits the two sections after the authentic private-state split. Credit raw sizes because its report scores .bss as 124 bytes, not the 128-byte alignment-derived padded extent.",
|
||||
"members": [
|
||||
{
|
||||
"symbol": "_is_scripted",
|
||||
"measurements": {
|
||||
"target": {
|
||||
"section": ".bss", "size": 124, "padded_size": 128,
|
||||
"flags": 3225419904, "relocation_count": 0,
|
||||
"normalized_sha256": "7b8ec8dd836b564f0c85ad088fc744de820345204e154bc1503e04e9d6fdd9f1",
|
||||
"owner": { "value": 0, "type": 0, "storage": 3 }
|
||||
},
|
||||
"base": {
|
||||
"section": ".bss", "size": 124, "padded_size": 128,
|
||||
"flags": 3225419904, "relocation_count": 0,
|
||||
"normalized_sha256": "7b8ec8dd836b564f0c85ad088fc744de820345204e154bc1503e04e9d6fdd9f1",
|
||||
"owner": { "value": 0, "type": 0, "storage": 3 }
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"symbol": "_editor_camera_speed",
|
||||
"measurements": {
|
||||
"target": {
|
||||
"section": ".data", "size": 52, "padded_size": 52,
|
||||
"flags": 3224371264, "relocation_count": 9,
|
||||
"normalized_sha256": "22486dfe6b955caf557fcbca418621432912c2d3012afd4e6031fe22b880d07b",
|
||||
"owner": { "value": 0, "type": 0, "storage": 3 }
|
||||
},
|
||||
"base": {
|
||||
"section": ".data", "size": 52, "padded_size": 52,
|
||||
"flags": 3224371264, "relocation_count": 9,
|
||||
"normalized_sha256": "22486dfe6b955caf557fcbca418621432912c2d3012afd4e6031fe22b880d07b",
|
||||
"owner": { "value": 0, "type": 0, "storage": 3 }
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"unit": "source/units/unit_dialogue",
|
||||
"symbol": "_global_speech_priority_names",
|
||||
"reason": "January and the rebuilt 44-byte speech-name table have identical payload, 11 relocation sites and types, and independently resolved literal destinations; objdiff undercredits the table because the executable split assigns nine folded SELECT_ANY strings to other objects",
|
||||
"measurements": {
|
||||
"size": 44,
|
||||
"relocation_count": 11,
|
||||
"normalized_sha256": "85759b3811ff7dc47b03792ac85317be51431a3f9e01dcafce317ed736a391b0"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/game/game_allegiance",
|
||||
"symbol": "_global_game_team_names",
|
||||
"reason": "The 40-byte January and rebuilt team-name tables have identical normalized payload, owner storage and flags, and all ten relocations resolve independently to the same image destinations; objdiff undercredits this sole unmatched section.",
|
||||
"measurements": {
|
||||
"size": 40,
|
||||
"relocation_count": 10,
|
||||
"normalized_sha256": "2c34ce1df23b838c5abf2a7f6437cca3d3067ed509ff25f11df6b11b582b51eb"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/game/game_engine_slayer",
|
||||
"symbol": "_slayer_engine",
|
||||
"reason": "The 136-byte January and rebuilt engine tables have identical normalized payload, external owner storage and section flags, and all 24 relocations resolve independently to the same image destinations; objdiff undercredits this sole unmatched section.",
|
||||
"measurements": {
|
||||
"size": 136,
|
||||
"relocation_count": 24,
|
||||
"normalized_sha256": "cd47b29508fea4e4c11451792c17f629a9ad240b3c3df5c889c0d416c378bc78"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/hud_definitions",
|
||||
"symbol": "_global_hud_anchor_names",
|
||||
"reason": "The 20-byte January and rebuilt HUD anchor-name tables have identical normalized payload, owner storage and flags, and all five relocations resolve independently to the same image destinations; objdiff undercredits this sole unmatched section.",
|
||||
"measurements": {
|
||||
"size": 20,
|
||||
"relocation_count": 5,
|
||||
"normalized_sha256": "de47c9b27eb8d300dbb5f2c353e632c393262cf06340c4fa7f1b40c4cbd36f90"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/structures/leaf_map",
|
||||
"symbol": "_leaf_map_initialize_section",
|
||||
"allow_incomplete_unit": true,
|
||||
"reason": "January and rebuilt profile-section data have identical 2512-byte payload, section flags and static owner, with all 28 relocations independently resolving to the same image destinations; objdiff undercredits this sole unmatched section.",
|
||||
"measurements": {
|
||||
"size": 2512,
|
||||
"relocation_count": 28,
|
||||
"normalized_sha256": "34570fc43b6cae2795503a6a62861e9a42ce856cb74d895ba7fa6174f1bda68b"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/game/game_engine_race",
|
||||
"symbol": "_race_engine",
|
||||
"reason": "January and rebuilt race-engine tables have identical 136-byte payload, section flags and external owner, with all 25 relocations independently resolving to the same image destinations; objdiff undercredits this sole unmatched section.",
|
||||
"measurements": {
|
||||
"size": 136,
|
||||
"relocation_count": 25,
|
||||
"normalized_sha256": "97a4c632a978acafd20933da4504d8ec3fdf3c5afd2f78934bced57dc8f746f4"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/game/game_engine_ctf",
|
||||
"symbol": "_ctf_engine",
|
||||
"reason": "January and rebuilt CTF-engine tables have identical 136-byte payload, section flags and external owner, with all 28 relocations independently resolving to the same image destinations; objdiff undercredits this sole unmatched section.",
|
||||
"measurements": {
|
||||
"size": 136,
|
||||
"relocation_count": 28,
|
||||
"normalized_sha256": "45c41730d038fd3f985f7ccfd8a7e04aa02e2db549ac941386e7cd04c1e1d8c1"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_print",
|
||||
"symbol": "_tif_print_rcsid",
|
||||
"reason": "The 164-byte January and rebuilt libtiff data section has identical payload, flags and external owner, and all 18 relocations independently resolve to the same image destinations; objdiff undercredits its sole unmatched section.",
|
||||
"measurements": {
|
||||
"size": 164,
|
||||
"relocation_count": 18,
|
||||
"normalized_sha256": "a81bb4fa00f599a245c1e6b636a2a630629557f2c86f92e2960cf3e16ed94e23"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/memory/zlib/zutil",
|
||||
"symbol": "_z_errmsg",
|
||||
"reason": "The 44-byte January and rebuilt zlib error table has identical payload, flags and external owner, and all ten relocations independently resolve to the same image destinations; objdiff undercredits its sole unmatched section.",
|
||||
"measurements": {
|
||||
"size": 44,
|
||||
"relocation_count": 10,
|
||||
"normalized_sha256": "966ef500de11387122d16ed112b63eb8562f81fc0e67d6f8f4d190766cf1e6ae"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/memory/zlib/deflate",
|
||||
"symbol": "?my_version@?1??deflateInit2_@@9@9",
|
||||
"reason": "The four-byte January and rebuilt zlib version pointer has identical payload, flags and static owner; its relocation independently resolves to the same image destination despite objdiff's alias attribution.",
|
||||
"measurements": {
|
||||
"size": 4,
|
||||
"relocation_count": 1,
|
||||
"normalized_sha256": "df3f619804a92fdb4057192dc43dd748ea778adc52bc498ce80524c014b81119"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/networking/network_server_manager",
|
||||
"symbol": "_network_game_server_memory_do_not_use_directly_in_use",
|
||||
"reason": "January and rebuilt eight-byte BSS owner have identical extent, flags, external storage and section-relative layout with no relocations; objdiff undercredits this sole unmatched section.",
|
||||
"measurements": {
|
||||
"size": 8,
|
||||
"relocation_count": 0,
|
||||
"normalized_sha256": "af5570f5a1810b7af78caf4bc70a660f0df51e42baf91d4de5b2328de0e83dfc"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/game/game_engine_oddball",
|
||||
"symbol": "_oddball_engine",
|
||||
"reason": "January and rebuilt Oddball engine tables have identical 136-byte payload, flags and owner storage, with all 27 relocations independently resolving to the same image destinations; objdiff undercredits the sole unmatched data section.",
|
||||
"measurements": {
|
||||
"size": 136,
|
||||
"relocation_count": 27,
|
||||
"normalized_sha256": "ffe1ef0aa827017276299f3a497655019d91f94374129c31634061500e5ae4b9"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/game/game_globals",
|
||||
"symbol": "_global_material_type_strings",
|
||||
"reason": "January and rebuilt material-name tables have identical 132-byte payload, flags and owner storage, with all 33 relocations independently resolving to the same image destinations; objdiff undercredits the sole unmatched data section.",
|
||||
"measurements": {
|
||||
"size": 132,
|
||||
"relocation_count": 33,
|
||||
"normalized_sha256": "115bad14f1c9f2c027a84de21b107015722cb76be8d0abf3760ad8e00d6c24a5"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/items/projectile_definitions",
|
||||
"symbol": "_default_projectile_material_response",
|
||||
"reason": "January and rebuilt projectile material tables have identical 160-byte payload, flags and owner storage, with all three relocations independently resolving to the same image destinations; objdiff undercredits the sole unmatched data section.",
|
||||
"measurements": {
|
||||
"size": 160,
|
||||
"relocation_count": 3,
|
||||
"normalized_sha256": "b71e2246c2d39831ad65f2b9570fecb59a1a0d743278b63cc125b118c148f6b9"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/memory/byte_swapping",
|
||||
"symbol": "_byte_bs_codes",
|
||||
"reason": "January and rebuilt byte-swap tables have identical 144-byte payload, flags and owner storage, with all eight relocations independently resolving to the same image destinations; objdiff undercredits the sole unmatched data section.",
|
||||
"measurements": {
|
||||
"size": 144,
|
||||
"relocation_count": 8,
|
||||
"normalized_sha256": "fc892f5c359e0165aa8cdbd745b191928baac3213935c79d8699cdcba32468d0"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/physics/collision_bsp_definitions",
|
||||
"symbol": "_global_collision_bsp_definition_data",
|
||||
"reason": "January and rebuilt collision BSP definition tables have identical 900-byte payload, flags and owner storage, with all 68 relocations independently resolving to the same image destinations; objdiff undercredits the sole unmatched data section.",
|
||||
"measurements": {
|
||||
"size": 900,
|
||||
"relocation_count": 68,
|
||||
"normalized_sha256": "3ed97b7cf09b09837ca36461d74c21909d34106d563a7b914aaffd7c51cf3e56"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/physics/collision_usage",
|
||||
"symbol": "_global_collision_function_names",
|
||||
"reason": "January and rebuilt collision function-name tables have identical 138-byte payload, flags and owner storage, with all 30 relocations independently resolving to the same image destinations; objdiff undercredits the sole unmatched data section.",
|
||||
"measurements": {
|
||||
"size": 138,
|
||||
"relocation_count": 30,
|
||||
"normalized_sha256": "804797955ced17a1f6b1e4b86c0a83a5d25fcb03fa846e690dae51ef13bc5c2f"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/render/render_particles",
|
||||
"symbol": "_render_particles_section",
|
||||
"reason": "The January and rebuilt render-particles profile-section owners have equal 1528-byte payload, section flags and external storage, and their sole relocation independently resolves to the same image string; objdiff undercredits the complete section. All three target functions are strict exact, and base-only SELECT_ANY literals have byte-identical January-selected providers with passing ordinary pair links.",
|
||||
"measurements": {
|
||||
"size": 1528,
|
||||
"relocation_count": 1,
|
||||
"normalized_sha256": "806638334fff1341360b4dec7db0987871f376bc3999e26ff4bcd3a1755d2955"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/bitmaps",
|
||||
"symbol": "_global_vector_palette",
|
||||
"reason": "January and rebuilt 1116-byte palette data have equal payload, section flags, owner storage and offsets, and all 21 relocations resolve to the same image destinations. All 34 target functions are strict exact; the sole extra fast_ftol COMDAT is byte-identical to its selected January provider and pair-links in either order.",
|
||||
"measurements": {
|
||||
"size": 1116,
|
||||
"relocation_count": 21,
|
||||
"normalized_sha256": "443063631e6958ff5026be3038f8785d61eee4073cb01b8eaa4fdfcc3b620002"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/game/cheats",
|
||||
"symbol": "_cheat_strings",
|
||||
"reason": "January and rebuilt cheats BSS have equal 3201-byte extent, section flags, external owner, zero relocations and matching section-relative symbol layout. The two private function names come from the first-party HCEA SHIP PDB; the string array has a descriptive inferred name, and the trailing unreferenced byte is disclosed as name-unknown rather than credited as a separate owner. All 14 target functions are strict exact and candidate-only providers pass bounded links in both orders.",
|
||||
"measurements": {
|
||||
"size": 3201,
|
||||
"relocation_count": 0,
|
||||
"normalized_sha256": "76d6c353527d212ec3799ea375f945e3ae3760257bd2ef5a75441090df0ddfac"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/items/items",
|
||||
"symbol": "_item_update_section",
|
||||
"reason": "January and rebuilt item-update profile owners have equal 1528-byte payload, section flags, external owner and one resolved image relocation. All 18 target functions and eight target-owned noncode symbols are strict exact. The only former link conflict was the hand-written add_vectors3d provider in ActorCombat; its genuine shared-header inline now emits the same code as SELECT_ANY without changing any ActorCombat function or park. All 42 candidate-only helper/literal copies equal their January-selected providers and 26 ordinary provider-pair links pass in both orders.",
|
||||
"measurements": {
|
||||
"size": 1528,
|
||||
"relocation_count": 1,
|
||||
"normalized_sha256": "806638334fff1341360b4dec7db0987871f376bc3999e26ff4bcd3a1755d2955"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/hud",
|
||||
"symbol": "_default_string",
|
||||
"reason": "January and rebuilt HUD own the same four-byte external data pointer, section flags and relocation destination: the two-zero-byte string selected from GameEngine. All 22 target functions are strict exact. Five candidate-only genuine shared-header inline helpers match their January-selected copies byte-for-byte and ordinary provider-pair links pass in both orders, so these folded copies receive no separate credit.",
|
||||
"measurements": {
|
||||
"size": 4,
|
||||
"relocation_count": 1,
|
||||
"normalized_sha256": "df3f619804a92fdb4057192dc43dd748ea778adc52bc498ce80524c014b81119"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/effects/particles",
|
||||
"symbol": "_particles_update_section",
|
||||
"reason": "January and rebuilt particles own the same 1536-byte static data section with three image-equivalent relocations, flags and payload. Its eight-byte collision-scale bounds also have identical payload, flags and the external linkage January requires. All 20 target functions are strict exact; genuine shared-header helper providers now link in both orders after removing duplicate hand-written bodies from DebugMemory, Contrails and BoredCamera. Candidate-only folded helper copies receive no separate credit.",
|
||||
"measurements": {
|
||||
"size": 1536,
|
||||
"relocation_count": 3,
|
||||
"normalized_sha256": "6d9398e131ef72b9a6ffc2321c22d27a3e2db1a458385b77b08ba0657a56c74f"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/ai_scenario_definitions",
|
||||
"symbol": "_global_ai_default_state_names",
|
||||
"reason": "January and rebuilt 48-byte AI default-state name table (sole .data section) have identical normalized payload and flags (c0300040), a PDB-public external owner at offset 0, and all 12 relocations resolve to the same image addresses. The whole object otherwise matches: 4/4 functions strict exact, every January-owned section and symbol equal, and all candidate-only literals pair-link with their selected providers in both orders. objdiff 3.3.1 misreads the identical '$' literal names.",
|
||||
"measurements": {
|
||||
"size": 48,
|
||||
"relocation_count": 12,
|
||||
"normalized_sha256": "17b0761f87b081d5cf10757ccc89f12be355c70e2e29df288b65b30710dcbcd1"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/ai_profile",
|
||||
"symbol": "_global_ai_meter_definitions",
|
||||
"reason": "January and rebuilt 236-byte AI meter/profile-name .data section (sole data section; _ai_profile_render_spray_names static at +224 on both sides) have identical normalized payload and flags (c0400040), and all 10 relocations resolve to the same image addresses. The whole object otherwise matches: 23/23 functions strict exact, every January-owned section and symbol equal and consistent with cachebeta.pdb publics, and candidate-only literals pair-link with their selected providers in both orders.",
|
||||
"measurements": {
|
||||
"size": 236,
|
||||
"relocation_count": 10,
|
||||
"normalized_sha256": "3a69a8b8a83037c3277fa86c09c7aa4e9b9da8b480e3facb87275548ee4c88b8"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/shaders/shader_definitions",
|
||||
"symbol": "_global_shader_effect_additive",
|
||||
"reason": "January and rebuilt 364-byte shader-effect .data section (the additive and alpha-blended effect definitions, the latter at +184 on both sides) have identical normalized payload and flags (c0400040), and both relocations resolve to the same image addresses. The whole object otherwise matches: 1/1 function strict exact, every January-owned section and symbol equal and consistent with cachebeta.pdb publics, and candidate-only literals pair-link with their selected providers in both orders.",
|
||||
"measurements": {
|
||||
"size": 364,
|
||||
"relocation_count": 2,
|
||||
"normalized_sha256": "8bbb21a994d2ec5051de3ea76497f648469fe42d5f6aa7da85f3b598bf16bcd0"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/units/dialogue_definitions",
|
||||
"symbol": "_dialogue_vocalization_type_name",
|
||||
"reason": "January and rebuilt 1,672-byte dialogue .data section have identical normalized payload and flags (c0400040), and all 418 relocations resolve to the same image addresses. The whole object otherwise matches: 2/2 functions strict exact, all 298 January symbols equal in section, offset and storage and consistent with cachebeta.pdb publics, and all candidate-only literals pair-link with their selected providers in both orders.",
|
||||
"measurements": {
|
||||
"size": 1672,
|
||||
"relocation_count": 418,
|
||||
"normalized_sha256": "256984cb62bc879971463ff0ff7567042dc95d8b0fb2bc676f246c2293c77ae8"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/actor_types",
|
||||
"symbol": "_global_actor_type_names",
|
||||
"reason": "January and rebuilt 128-byte actor-type .data section (the static actor_type_definitions table at +0 and the public global_actor_type_names at +64) have identical normalized payload and flags (c0400040), and all 32 relocations resolve to the same image addresses. Ownership was corrected first: cachebeta.pdb publics prove actor_type_definitions and its accessor actor_type_definition_get file-static. January's own assert strings name actor_type_definitions; the Halo CE atlas names the accessor at the same 0x140-byte span. All 13 functions are strict exact and every January-owned section and symbol matches.",
|
||||
"measurements": {
|
||||
"size": 128,
|
||||
"relocation_count": 32,
|
||||
"normalized_sha256": "38723a2e5e8a17aa7950dc008209944e898f69a7bd10a23c839d341e935fd5ca"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/cutscene/recorded_animation_definitions",
|
||||
"symbol": "_recorded_animation_event_stream_data",
|
||||
"reason": "January and rebuilt 180-byte recorded-animation tag .data section have identical normalized payload and flags (c0400040), and all 11 relocations resolve to the same image addresses. Ownership was corrected first: byte_swap_recording is absent from cachebeta.pdb publics and referenced by no other January object, so it is file-static. Both functions are strict exact and every January-owned section and symbol matches.",
|
||||
"measurements": {
|
||||
"size": 180,
|
||||
"relocation_count": 11,
|
||||
"normalized_sha256": "c83e71991a0ac6309173102325bf6a194d27d5d80cdc9a395ed954c80bae3d5d"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/models/model_animation_definitions",
|
||||
"symbol": "_weapon_type_animation_list",
|
||||
"reason": "January and rebuilt 1,288-byte animation-list .data section have identical normalized payload and flags (c0400040), and all 170 relocations resolve to the same image addresses. Ownership was corrected first: the seven *_animation_list_entries arrays are absent from cachebeta.pdb publics and referenced by no other January object, so they are file-static beside their public animation_list wrappers. All three functions are strict exact and all 139 January symbols match.",
|
||||
"measurements": {
|
||||
"size": 1288,
|
||||
"relocation_count": 170,
|
||||
"normalized_sha256": "76f074030d3cb6940a74673504f664555bd5d02087282c01338c8b83fe3d1654"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/sound/sound_classes",
|
||||
"symbol": "_sound_classes",
|
||||
"reason": "January and rebuilt 2,452-byte sound-class .data section have identical normalized payload and flags (c0400040), and all 51 relocations resolve to the same image addresses. Ownership was corrected first: the static accessor at 0x1b84c0 is absent from cachebeta.pdb publics and is named sound_class_datum_get by the Halo CE atlas, anchored on six already-exact sound_classes symbols. All 12 functions are strict exact and every January-owned section and symbol matches.",
|
||||
"measurements": {
|
||||
"size": 2452,
|
||||
"relocation_count": 51,
|
||||
"normalized_sha256": "1ae64de7abb95c40952d3aacf88c68232070d4c19906bf32dfc8877bd6725abc"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/objects/object_types",
|
||||
"symbol": "_object_data_definition",
|
||||
"reason": "January and rebuilt 2,608-byte object-type tag .data section have identical normalized payload and flags (c0400040), and all 190 relocations resolve to the same image addresses. Ownership was corrected first: HCEX.pdb names the sole object_types file static processed_bsp_flags (unsigned short), absent from cachebeta.pdb publics. All 31 functions are strict exact and all 66 January symbols match. All eight candidate-only helper COMDATs are byte-identical to January's selected copies and pair-link in both orders; items' hand-written valid_real_matrix4x3/valid_real_vector3d_axes3 NODUP providers were replaced by the genuine real_math.h inlines.",
|
||||
"measurements": {
|
||||
"size": 2608,
|
||||
"relocation_count": 190,
|
||||
"normalized_sha256": "205043014fcdf8e45147d168ae70e43cda7814dfc63f1c1dade93f2c0f9f4341"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/hs/hs_scenario_definitions",
|
||||
"symbol": "_hs_script_types_enum",
|
||||
"reason": "January and rebuilt HS scenario .data have identical 628-byte normalized payload, all 33 relocation identities, and 8-byte section alignment (c0400040). The original nine public definitions retain their target offsets and storage. Separate typed field and byte-swap arrays replace invented packed aggregates and padding; the byte-swap function is genuinely file-static. The one target function remains strict exact, and there are no surplus external definitions.",
|
||||
"measurements": {
|
||||
"size": 628,
|
||||
"relocation_count": 33,
|
||||
"normalized_sha256": "a1add12fc2ddd7afb3935997f9e1532b27a3887f8e85e914db954d1665547c09"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/hs/hs_globals_external",
|
||||
"symbol": "_screenshot_size_definition",
|
||||
"reason": "January and rebuilt HS external-global .data have identical 7,076-byte normalized payload, section flags (c0400040), and all 1,322 relocation identities. The invented 442-element definition aggregate has been replaced by 442 separate file-static typed definitions in January's proven 12-byte record order; the public hs_external_globals table remains at +5304. The 2011 first-party HCEX PDB independently attests 427 unique definition names and their type; the 15 older-only names are descriptive names derived from their January string records, not claimed originals. January and rebuilt first-record storage are file-static, and the unit emits no code or candidate-only external owner.",
|
||||
"measurements": {
|
||||
"size": 7076,
|
||||
"relocation_count": 1322,
|
||||
"normalized_sha256": "1e4346aef4491a55772f4f51a6989e06074dc5245a2c01aa1be97fb2e221ae8c"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"symbol": "_event_handler_functions",
|
||||
"reason": "January and rebuilt 934-byte event-handler .data section (the static event_handler_function_list name/function table at +0 and the public event_handler_functions at +816) have identical normalized payload and flags (c0400040), and all 228 relocations resolve to the same image addresses. The 366-byte .bss is also identical. Ownership was corrected first: 98 handler functions, event_handler_function_list and new_campaign_profile_name are absent from cachebeta.pdb publics and referenced by no other January object, so they are file-static. All 100 functions are strict exact and all 452 January symbols match. The three stock D3D SDK .rdata tables it also emits are byte-identical to January's selected copies and pair-link in both orders, as in the 54 already-admitted objects that emit them.",
|
||||
"measurements": {
|
||||
"size": 934,
|
||||
"relocation_count": 228,
|
||||
"normalized_sha256": "c1040d667c392fd772fab34335ade456dac49ae864a8200c4560df63cec186fd"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/objects/objects",
|
||||
"symbol": "?section@?1??objects_update@@9@9",
|
||||
"reason": "objects_update's function-static section table: January and the rebuilt object have identical 1,530-byte .data, relocation site/type and independently resolved string destination; objdiff 3.3.1's '$'-literal relocation-name defect undercredits it despite exact COFF section comparison. Whole object admitted after the Layer 1 provider repairs (action_charge, player_control, bored_camera, path_obstacles, decals) replaced hand-written NODUP helper copies with the genuine real_math.h inlines: all 121 functions strict exact, 225 symbols match storage/offsets and cachebeta.pdb publics, 26 candidate-only helper COMDATs byte-identical to January's selected copies and pair-linking in both orders.",
|
||||
"measurements": {
|
||||
"size": 1530,
|
||||
"relocation_count": 1,
|
||||
"normalized_sha256": "e94bb79478c95dce11c4a1f720a07ccbaa3a8d18b84acbe5605472d6f8635b74"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/units/units",
|
||||
"symbol": "_magic_base_animation_seat_index",
|
||||
"reason": "units' writable .data section (magic_base_animation_seat_index, unit_update_section, unit_update's last_time and base_seat_labels): January and the rebuilt object have identical 1,564-byte payload, 7 relocation sites/types and independently resolved string destinations (5 of the 7 base_seat_labels strings are selected in other January objects and pair-link cleanly); objdiff 3.3.1's '$'-literal relocation-name defect undercredits it despite exact COFF section comparison. Whole object admitted: all 189 functions strict exact; the 25 code_ placeholders carry their first-party names (HCEX_Release.pdb units compiland, Sept-2001 map, January atlas) and all 50 file-statics carry static storage per cachebeta.pdb publics, so 321 symbols match storage/offsets; 97 candidate-only surplus definitions (31 helper COMDATs byte-identical to January's selected copies, SDK tables, literals) pair-link with their selected providers in both orders; _point_from_line3d is referenced out of line by January's units.obj (owner ruling 20260921 #1).",
|
||||
"measurements": {
|
||||
"size": 1564,
|
||||
"relocation_count": 7,
|
||||
"normalized_sha256": "6ed61c39a648905cf23b12b916e2adadfe97b6e5aa492c29a14c7265809ef1a7"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/items/projectiles",
|
||||
"symbol": "_projectile_update_section",
|
||||
"allow_incomplete_unit": true,
|
||||
"reason": "January and rebuilt projectile-update profile-section data have identical 1548-byte payload, section flags and static owners (_projectile_update_section at 0, _effect_marker_names at 1528), with all six relocations independently resolving to the same image destinations; January's split leaves the pooled normal and gravity literals undefined while the rebuilt object emits identical select-any copies, and objdiff 3.3.1's '$'-literal name defect undercredits this sole unmatched section. The unit's .rdata is already 100%; the parked _projectile_new residual keeps the unit incomplete and receives no credit from this entry.",
|
||||
"measurements": {
|
||||
"size": 1548,
|
||||
"relocation_count": 6,
|
||||
"normalized_sha256": "7bfaf5fb0b0c9e0593153885a81788bc8b118a9651a60a8a94e5ffd9fd203cf2"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/math/periodic_functions",
|
||||
"symbol": "_global_periodic_functions_enum_strings",
|
||||
"allow_incomplete_unit": true,
|
||||
"reason": "The January and rebuilt 96-byte periodic/transition enum .data have identical normalized payload, owner storage and flags, and all 20 relocations resolve to the same image destinations. Objdiff 3.3.1 undercredits folded string literals. The variable-period builder remains parked and earns no code credit.",
|
||||
"measurements": {
|
||||
"size": 96,
|
||||
"relocation_count": 20,
|
||||
"normalized_sha256": "8fdd4bf9e8be002fe8938ee0849dfec244c27138f7b77eff28ec8ba7b4538614"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/objects/object_lights",
|
||||
"symbol": "_lights_section",
|
||||
"allow_incomplete_unit": true,
|
||||
"reason": "object_lights' writable .data (the static lights_section profile section at +0 and the four public object_light_* tuning globals at +1528..+1540): January and the rebuilt object have identical 1,541-byte payload, owner storage and flags (c0400040), and its single relocation (the 'render_lights' string, selected in hs) resolves independently to the same image destination; objdiff 3.3.1's '$'-literal relocation-name defect undercredits it despite exact COFF section comparison. All 43 functions are strict exact; should_render_lights, light_attenuation and cluster_get_first/next_light are file-static per cachebeta.pdb publics (no January reference outside the object; should_render_lights is the /Od-attested call in lights_render_diffuse and lights_render_specular), so all 71 January symbols match storage and offsets; the 12 candidate-only helper COMDATs pair-link with their selected providers in both orders. The unit is not marked Matching only because its _object_get_bounding_sphere COMDAT differs from action_vehicle's selected copy in its two __FILE__ literal relocations (January object_lights' own 'c:\\halo\\source\\objects\\objects.h' literal; held owner item), so this sole unmatched section is credited with an explicit incomplete-unit opt-in.",
|
||||
"measurements": {
|
||||
"size": 1541,
|
||||
"relocation_count": 1,
|
||||
"normalized_sha256": "527b43a173f528444fa4423af92d7d58a83f2afe7fc1661b6d297401b2760f71"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/bitmap_group",
|
||||
"symbol": "_global_bitmap_reference",
|
||||
"allow_incomplete_unit": true,
|
||||
"reason": "January and rebuilt bitmap_group writable .data (the public global_bitmap_reference/_optional, bitmap_pixel_data, color_plate_data and bitmap_group tag definitions plus their static field/enum tables, 31 owners) have identical 1,424-byte payload, flags (c0400040) and owner storage, and all 152 relocations independently resolve to the same image destinations. January's split leaves the empty-string and 'default' literals undefined (linker-selected in other objects) while the rebuilt object emits identical select-any copies, so objdiff 3.3.1's '$'-literal name defect undercredits this sole unmatched section; renaming only the '$' inside literal names on both sides scores it 100.0 with the production objdiff binary. The parked _bitmap_group_add_bitmap residual keeps the unit incomplete, so this entry opts in explicitly as an incomplete unit and grants no function or object credit.",
|
||||
"measurements": {
|
||||
"size": 1424,
|
||||
"relocation_count": 152,
|
||||
"normalized_sha256": "df5c6d69f4e13ea6df9398e2b5cc5c4455410b077b5ba6763930c4dd748505cb"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/ai_communication",
|
||||
"symbol": "_global_communication_priority_names",
|
||||
"allow_incomplete_unit": true,
|
||||
"reason": "January and rebuilt ai_communication .data (the public global_communication_priority_names, global_communication_team_names and global_communication_type_names string tables at +0/+32/+48) have identical 276-byte payload, flags (c0400040) and owner storage, and all 69 relocations independently resolve to the same image destinations. January's split leaves six literals ('none', 'shout', 'damage', 'cover', 'flee', 'berserk') undefined because the linker selected other objects' copies, while the rebuilt object emits identical select-any copies, so objdiff 3.3.1's '$'-literal name defect undercredits this sole unmatched section; renaming only the '$' inside literal names on both sides scores it 100.0 with the production objdiff binary. _ai_communication_actor_talk_weight (parked) and _ai_communication_event remain residual, so this entry opts in explicitly as an incomplete unit and grants no function or object credit.",
|
||||
"measurements": {
|
||||
"size": 276,
|
||||
"relocation_count": 69,
|
||||
"normalized_sha256": "d489001ff88ed206b56f44bd0789a8332510f33bf40a312a7b2e5d60c3fe3e03"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/ai_debug",
|
||||
"symbol": "_global_ai_debug_firing_position_color_count",
|
||||
"allow_incomplete_unit": true,
|
||||
"reason": "January and rebuilt ai_debug .data (the public global_ai_debug_firing_position_color_count at +0, the file-static postcombat type-name table at +4 and the two file-static selected-squad globals at +48/+52) have identical 56-byte payload, flags (c0300040) and owner storage, and all 11 relocations independently resolve to the same image destinations. January's split leaves the 'none' literal undefined because the linker selected another object's copy, while the rebuilt object emits an identical select-any copy, so objdiff 3.3.1's '$'-literal name defect undercredits this sole unmatched section; renaming only the '$' inside literal names on both sides scores it 100.0 with the production objdiff binary. _ai_debug_render_actor remains residual, so this entry opts in explicitly as an incomplete unit and grants no function or object credit.",
|
||||
"measurements": {
|
||||
"size": 56,
|
||||
"relocation_count": 11,
|
||||
"normalized_sha256": "3ba0a54a0875e71a01972b13dcf574a4d16d0f1ea3531ef51d98311b5ac7eee5"
|
||||
}
|
||||
},
|
||||
{
|
||||
"unit": "source/game/game_engine_king",
|
||||
"symbol": "_king_engine",
|
||||
"allow_incomplete_unit": true,
|
||||
"reason": "January and rebuilt King engine tables have identical 136-byte payload, section flags (c0400040) and public owner storage (_king_engine is a cachebeta.pdb public), and all 23 relocations (22 engine callbacks and the 'king' name literal) independently resolve to the same image destinations. January's split leaves the 'king' literal undefined because the linker selected game_engine's copy, while the rebuilt object emits an identical select-any copy, so objdiff 3.3.1's '$'-literal name defect undercredits this sole unmatched section; renaming only the '$' inside literal names on both sides scores it 100.0 with the production objdiff binary. All 29 functions are strict exact; the unit stays NonMatching until the owner rules on the whole-object packet (owner queue #13: _find_next_hill's preserved uninitialised no-candidate return, plus the cachebeta storage fix), so this entry opts in explicitly as an incomplete unit, credits only the table's data bytes and certifies nothing about _find_next_hill or object completion.",
|
||||
"measurements": {
|
||||
"size": 136,
|
||||
"relocation_count": 23,
|
||||
"normalized_sha256": "4009f5b6117e9f00cb001a23b9a56b9dc51a694206c442ce715e2bed2d5465a7"
|
||||
}
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,587 @@
|
||||
[
|
||||
{
|
||||
"unit": "source/devices/devices",
|
||||
"function": "_device_export_function_values",
|
||||
"reason": "The scoped Opus reconciliation proves all 512 padded bytes, 21 ordered relocations and normalized SHA-256 7bf0963941ed36b13676536592a3af9d2786f5d4970b56f1129d24c3a35cc968 exact. Objdiff's 94.405594 percent is a compiler-local switch-label representation false negative; credit only the target report's 505 meaningful bytes. The ordinary typed mode loop preserves January's unordered delay predicate and uses the proper devices.h public declaration. No comparator relaxation, byte patch, extra helper, parameter-width trick or whole-object completion claim. See docs/object_matching_logs/devices_obj_export_function_values_opus_reconciliation_20260906.md."
|
||||
},
|
||||
{
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox",
|
||||
"function": "_rasterizer_set_stencil_mode",
|
||||
"reason": "The scoped Opus reconciliation proves all 784 padded/meaningful bytes, 78 ordered relocations and normalized SHA-256 903201d61d15f0c4dcad96fd81acb8049e8bfc201883061924dc95f3eaea8852 exact. Objdiff's 96.65072 percent is a compiler-local switch-label representation false negative. Source applies the debug policy in the public long input domain before narrowing once to the short cached mode, as January's entry dataflow corroborates; no declaration permutation or type/ABI change. Existing data and helper ownership remain separate from this function credit. See docs/object_matching_logs/rasterizer_xbox_obj_three_natural_opus_closures_20260906.md."
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/action_obey",
|
||||
"function": "_action_obey_command_end",
|
||||
"reason": "Independent frozen January/actual COFF comparison proves all 560 padded bytes, 24 ordered relocations and normalized SHA-256 f59f0185a672ce6409fe3d3c3a439e517483593f6ffc9bf5eff4b18dd4420a61 exact. Objdiff reports 85.26786 percent because compiler-local switch labels are represented differently. The ledger credits only the target's 549 meaningful bytes, with no byte/comparator exception. The genuine private body is retained through individual_end, not a fake external ABI. Fable's earlier case-order correction remains documented; this is independently authenticated reconstruction, not a claim of first-shot source. Whole-object math-owner and remaining-source boundaries are separate. See docs/object_matching_logs/action_obey_obj_partial_graph_reconciliation_20260905.md."
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/action_obey",
|
||||
"function": "_action_obey_directmovement_update_facing",
|
||||
"reason": "Independent frozen January/actual COFF comparison proves all 336 meaningful/padded bytes, 17 ordered relocations and normalized SHA-256 17b28fabb3ad4366074689d2f9be1364ccf07cdc0c7a185dbd4dff25b00e3f97 exact. Objdiff reports 96.77419 percent due to compiler-local switch labels. This is strict target-function credit only; no comparator weakening or surplus helper credit. Its real individual_update caller naturally preserves the target cross_product3d/negate_vector3d owners after removing their manual wrapper aliases. Five additional header math owners are explicitly audited and remain a whole-object link/admission boundary. See docs/object_matching_logs/action_obey_obj_partial_graph_reconciliation_20260905.md."
|
||||
},
|
||||
{
|
||||
"unit": "source/input/input_xbox",
|
||||
"function": "_input_key_is_down",
|
||||
"reason": "Independent root and reviewer COFF gates prove all 192 meaningful/padded bytes and 19 ordered relocations exact, normalized SHA-256 c1ab3b0043e411c7e6695fb129837501c3bca12a2477d9497b5123f3eaf17805. Objdiff reports 93.93939 percent because compiler-local switch labels are represented differently. A natural result variable and single terminal return satisfy the house rules without a bogus unreachable fallback and reproduce January; no target-byte exception or declaration-order tuning. See docs/object_matching_logs/input_xbox_obj_public_leaves_independent_review_20260904.md."
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/player_ui",
|
||||
"function": "_set_local_player_controls_from_player_profile",
|
||||
"reason": "Independent strict COFF comparison proves all 528 meaningful/padded bytes and 14 ordered relocations exact, normalized SHA-256 ff47c65c6eda0c31b625817bb914f77ad790244d2be44109e484d10664685ee5. Raw objdiff reports 95.89041 percent due to compiler-local switch labels. This repairs existing function credit only; it does not count fresh reconstruction or waive the object's public playlist-layout/coalescing boundary. See docs/object_matching_logs/player_ui_obj_owner_house_rule_reconciliation_20260904.md."
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/hud_unit",
|
||||
"function": "_hud_render_damage_indicators",
|
||||
"reason": "Independent root/worker COFF gates prove all 688 padded bytes and 39 ordered relocations exact, normalized SHA-256 cf7cb8af78f4f4f9fb2a11c7bb67c2e5fb0e31cedcbe8b062ef7aa7fad4cacd0. Objdiff reports 95.85253 percent because compiler-local switch labels are represented differently; no byte or target exception. The independently PDB/type/ABI-reviewed source and complete emitted-owner audit are documented in docs/object_matching_logs/hud_unit_obj_damage_indicators_exact_20260904.md."
|
||||
},
|
||||
{
|
||||
"unit": "source/networking/network_client_message_handler",
|
||||
"function": "_network_game_client_handle_message",
|
||||
"reason": "Audited January dispatcher is strict exact: 1088 padded/logical bytes, 84 ordered relocations, normalized SHA-256 32ca599a7f9f3eb44546bcd119ce77eb705e9fc745f9d852c16295cbe1f3850f. Objdiff differs only on compiler-local switch labels; no byte or target exception. See docs/object_matching_logs/network_client_message_handler_obj_admission_review_20260904.md."
|
||||
},
|
||||
{
|
||||
"unit": "source/cache/cache_files",
|
||||
"function": "_cache_files_map_directory",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/units/units",
|
||||
"function": "_unit_is_busy",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/text/international_strings",
|
||||
"function": "_double_byte_character",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/shaders/shaders",
|
||||
"function": "_numeric_countdown_timer_get",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/shaders/shaders",
|
||||
"function": "_shader_get_vertex_shader_permutation",
|
||||
"reason": "hardened COFF comparison proves all 288 padded bytes and all 18 semantic relocations exact; objdiff reports a local jump-table label encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/shaders/shaders",
|
||||
"function": "_shader_is_decal",
|
||||
"reason": "hardened COFF comparison proves all 144 padded bytes and all 10 semantic relocations exact; objdiff reports a local jump-table label encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox_errors",
|
||||
"function": "_rasterizer_error",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/networking/network_messages",
|
||||
"function": "_create_network_game_message",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/networking/network_game_globals",
|
||||
"function": "_network_game_client_start_frame",
|
||||
"reason": "hardened COFF comparison proves all 560 padded bytes and all 57 semantic relocations exact; objdiff reports a local jump-table label encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/memory/data_encoding",
|
||||
"function": "_data_decode_array",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/memory/data_encoding",
|
||||
"function": "_data_decode_memory",
|
||||
"reason": "hardened COFF comparison proves all 304 padded bytes and all 19 semantic relocations exact; objdiff reports a local jump-table label encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/memory/data_encoding",
|
||||
"function": "_data_encode_memory",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/memory/data_encoding",
|
||||
"function": "_data_encode_array",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/memory/data_packets",
|
||||
"function": "__data_packet_verify",
|
||||
"reason": "hardened COFF comparison proves all 464 padded bytes and all 27 semantic relocations exact; objdiff reports a local jump-table label encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/memory/data_packets",
|
||||
"function": "__data_packet_encode",
|
||||
"reason": "hardened COFF comparison proves all 768 padded bytes and all 44 semantic relocations exact; objdiff reports a local jump-table label encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/memory/data_packets",
|
||||
"function": "__data_packet_decode",
|
||||
"reason": "hardened COFF comparison proves all 672 padded bytes and all 28 semantic relocations exact; objdiff reports a local jump-table label encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/memory/byte_swapping",
|
||||
"function": "__byte_swap_data",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/memory/zlib/inflate",
|
||||
"function": "_inflate",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/main/console",
|
||||
"function": "_console_update",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_text_search_and_replace_functions",
|
||||
"function": "_widget_controller",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/attract_mode",
|
||||
"function": "_attract_mode_get_localized_movie_path",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/game/game_time",
|
||||
"function": "_game_time_start",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/game/game_time",
|
||||
"function": "_game_time_update",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/devices/device_controls",
|
||||
"function": "_code_00083e30",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/cseries/cseries_windows",
|
||||
"function": "_code_0007cb70",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bungie_net/network/transport_address",
|
||||
"function": "_transport_error_to_string",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_print",
|
||||
"function": "_TIFFPrintDirectory",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_packbits",
|
||||
"function": "_PackBitsEncode",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_next",
|
||||
"function": "_NeXTDecode",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_dir",
|
||||
"function": "_code_00053960",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_dir",
|
||||
"function": "_code_00054160",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_dirwrite",
|
||||
"function": "_TIFFWriteNormalTag",
|
||||
"reason": "hardened COFF comparison proves all 800 padded bytes and all 30 semantic relocations exact; objdiff reports an internal jump-table relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_dirwrite",
|
||||
"function": "_TIFFWriteDirectory",
|
||||
"reason": "hardened COFF comparison proves all 1760 padded bytes and all 56 semantic relocations exact; objdiff reports internal jump-table relocation encoding false negatives"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_aux",
|
||||
"function": "_TIFFVGetFieldDefaulted",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_lzw",
|
||||
"function": "_horizontalAccumulate8",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_lzw",
|
||||
"function": "_horizontalAccumulate16",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_lzw",
|
||||
"function": "_horizontalDifference8",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_lzw",
|
||||
"function": "_horizontalDifference16",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_getimage",
|
||||
"function": "_setorientation",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_getimage",
|
||||
"function": "_code_00058a20",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_getimage",
|
||||
"function": "_code_00058c40",
|
||||
"reason": "hardened COFF comparison proves all 832 padded bytes and all 18 semantic relocations exact; objdiff reports static BSS symbol/relocation ownership false negatives"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_getimage",
|
||||
"function": "_code_00059180",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_getimage",
|
||||
"function": "_put1bitbwtile",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_getimage",
|
||||
"function": "_code_00059df0",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_getimage",
|
||||
"function": "_code_0005a6f0",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_getimage",
|
||||
"function": "_TIFFReadRGBAImage",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_dirread",
|
||||
"function": "_TIFFFetchData",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_dirread",
|
||||
"function": "_TIFFFetchByteArray",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_dirread",
|
||||
"function": "_TIFFFetchNormalTag",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_dirread",
|
||||
"function": "_TIFFReadDirectory",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/actor_type_sentinel",
|
||||
"function": "_sentinel_decide_action",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/actor_type_mounted_weapon",
|
||||
"function": "_mounted_weapon_decide_action",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/actor_type_marine",
|
||||
"function": "_marine_decide_action",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/actor_type_jackal",
|
||||
"function": "_jackal_decide_action",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/actor_type_infection",
|
||||
"function": "_infection_decide_action",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/actor_type_hunter",
|
||||
"function": "_hunter_decide_action",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/actor_type_grunt",
|
||||
"function": "_grunt_decide_action",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/actor_type_flood",
|
||||
"function": "_flood_decide_action",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/actor_type_engineer",
|
||||
"function": "_engineer_decide_action",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/actor_type_elite",
|
||||
"function": "_elite_decide_action",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/actor_type_crew",
|
||||
"function": "_crew_decide_action",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/actor_type_carrier",
|
||||
"function": "_carrier_decide_action",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/action_guard",
|
||||
"function": "_action_guard_speak_post_combat",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/action_guard",
|
||||
"function": "_action_guard_setup_postcombat",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/action_guard",
|
||||
"function": "_action_guard_control",
|
||||
"reason": "hardened COFF comparison proves exact bytes and semantic relocations; objdiff reports a local-label/relocation encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_fax3",
|
||||
"function": "_skiptoeol",
|
||||
"reason": "hardened COFF comparison proves exact bytes and internal jump-table relocations; objdiff reports a local-label ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/bitmaps/libtiff/tif_fax3",
|
||||
"function": "_Fax3Decode2DRow",
|
||||
"reason": "hardened COFF comparison proves exact bytes and uniquely anchored non-code relocation destinations; objdiff reports csplit data-anchor naming false negatives"
|
||||
},
|
||||
{
|
||||
"unit": "source/objects/objects",
|
||||
"function": "_object_compute_node_matrices",
|
||||
"reason": "hardened COFF comparison proves all 6560 padded bytes and all 318 semantic relocations exact; objdiff reports a local-label encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/objects/objects",
|
||||
"function": "$L11841",
|
||||
"owner_function": "_attachments_new",
|
||||
"reason": "the exact owning COMDAT and an internal relocation prove this differently named jump-table label is the same destination"
|
||||
},
|
||||
{
|
||||
"unit": "source/objects/objects",
|
||||
"function": "$L9776",
|
||||
"owner_function": "_object_export_function_values",
|
||||
"reason": "the exact owning COMDAT and an internal relocation prove this differently named jump-table label is the same destination"
|
||||
},
|
||||
{
|
||||
"unit": "source/objects/objects",
|
||||
"function": "$L9764",
|
||||
"owner_function": "_object_export_function_values",
|
||||
"reason": "the exact owning COMDAT and an internal relocation prove this differently named jump-table label is the same destination"
|
||||
},
|
||||
{
|
||||
"unit": "source/objects/objects",
|
||||
"function": "$L10620",
|
||||
"owner_function": "_attachments_delete",
|
||||
"reason": "the exact owning COMDAT and an internal relocation prove this differently named jump-table label is the same destination"
|
||||
},
|
||||
{
|
||||
"unit": "source/memory/zlib/infblock",
|
||||
"function": "$L2587",
|
||||
"owner_function": "_inflate_blocks",
|
||||
"reason": "the exact owning COMDAT and an internal relocation prove this differently numbered jump-table label is the same destination"
|
||||
},
|
||||
{
|
||||
"unit": "source/rasterizer/xbox/rasterizer_xbox_vertex_shaders_runtime",
|
||||
"function": "_rasterizer_set_vertex_shader_permutation",
|
||||
"reason": "hardened COFF comparison proves all 1376 padded bytes and all 133 semantic relocations exact; objdiff reports a switch-table/local-label encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/networking/telnet_console",
|
||||
"function": "_process_telnet_client_buffer",
|
||||
"reason": "hardened COFF comparison proves all 496 padded bytes and all 30 semantic relocations exact; objdiff reports a switch-table/local-label encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_set_game_engine",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_change_ctf_rules",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_change_koth_rules",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_change_slayer_rules",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_change_oddball_rules",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_change_racing_rules",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_change_player_options",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_change_item_options",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_initialize_game_engine",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_initialize_ctf_rules",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_initialize_koth_rules",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_initialize_slayer_rules",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_initialize_oddball_rules",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_initialize_racing_rules",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_initialize_player_options",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_playlist_profile_initialize_item_options",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_player_profile_initialize_controller_settings",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_event_handler_functions",
|
||||
"function": "_player_profile_change_controller_settings",
|
||||
"reason": "hardened COFF comparison proves exact bytes and relocation destinations; objdiff reports a local-symbol ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/render/render_contrails",
|
||||
"function": "_render_contrail",
|
||||
"reason": "hardened COFF comparison proves all 1952 padded bytes and all 57 semantic relocations exact (SHA-256 70d28d083222f55ac171cb1aa9676d018fb2bcae9ee54f09facee54755cef5e8); objdiff reports a switch-table/local-label encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/items/weapons",
|
||||
"function": "_weapon_set_state",
|
||||
"reason": "hardened COFF comparison proves all 432 padded bytes and all 21 semantic relocations exact (SHA-256 667efc085661d6b50a6fb3c778be5f3b44e05acfca0132acf3aa527b21f20b74); objdiff reports a switch-table/local-label encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/ai/path_smoothing",
|
||||
"function": "_surface_is_walkable",
|
||||
"reason": "hardened COFF comparison proves all 128 padded bytes and all 5 semantic relocations exact (SHA-256 a58fa4f6cf9598874c2a0d1fb60f226f65dea7f5cbc7182a682b2faefc62580f); the private name is recovered from the source-backed path-smoothing helper cluster"
|
||||
},
|
||||
{
|
||||
"unit": "source/rasterizer/rasterizer_debug",
|
||||
"function": "_rasterizer_debug_line",
|
||||
"reason": "hardened COFF comparison proves all 32 padded bytes and the REL32 relocation to _rasterizer_debug_line_shaded exact (SHA-256 60f8ba4857cfb47aa739f77d4df9844fae5d61fb4292d7d92b25c28166a7a0d7)"
|
||||
},
|
||||
{
|
||||
"unit": "source/rasterizer/rasterizer_debug",
|
||||
"function": "_rasterizer_debug_triangle",
|
||||
"reason": "hardened COFF comparison proves all 32 padded bytes and the REL32 relocation to _rasterizer_debug_triangle_shaded exact (SHA-256 1b0df8cc752bec5820c858223f553d6f62fc7e39bac45bbb9b209d0f980a148a)"
|
||||
},
|
||||
{
|
||||
"unit": "source/cutscene/recorded_animation_playback",
|
||||
"function": "_recorded_animation_apply_event_stream",
|
||||
"reason": "hardened COFF comparison proves all 496 padded bytes and all 34 semantic relocations exact (SHA-256 4e8a5bd6f5b73b358df9e82beed6a1a08aa23ee6f84b353aa3026df37f1b441b); objdiff reports a switch-table/local-label encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/camera/camera_scripting",
|
||||
"function": "_scripted_camera_update",
|
||||
"reason": "hardened COFF comparison proves all 1664 padded bytes and all 82 semantic relocations exact (SHA-256 cb504e5b44213920854f97d593ab2361bda073fcb0ffef531347b0c4b8565e06); objdiff reports a switch-table/local-label encoding false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/game/game_engine_ctf",
|
||||
"function": "_ctf_engine_display_score",
|
||||
"reason": "hardened COFF comparison proves all 928 padded bytes and all 78 semantic relocations exact (SHA-256 df4518d31867315a05039fdcf8679ba2476011eeb70122ac00c6b6efef13f148); objdiff reports a switch-table/local-label ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/game/game_engine_oddball",
|
||||
"function": "_oddball_engine_display_score",
|
||||
"reason": "hardened COFF comparison proves all 736 padded bytes and all 56 semantic relocations exact (SHA-256 6ad4051ea66ca25449fb855b7cb0076efef3e056e80fa1a6566d7dc5fc2a2e38); objdiff reports pooled-string COMDAT ownership as a false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/first_person_weapons",
|
||||
"function": "_first_person_weapon_state_from_weapon_message",
|
||||
"reason": "hardened COFF comparison proves all 192 padded bytes and all 19 semantic relocations exact (SHA-256 f551efe027b59b504571439a15088c0065c23383298acbcdb85aeb04f10d3947); objdiff reports a private switch-table/local-label ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/first_person_weapons",
|
||||
"function": "_first_person_animation_type_from_weapon_state",
|
||||
"reason": "hardened COFF comparison proves all 272 padded bytes and all 25 semantic relocations exact (SHA-256 ea1838b37d9d2a3d39b80a5118d966f264e0daecbff3a47c9f41a6968006b499); objdiff reports a private switch-table/local-label ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/first_person_weapons",
|
||||
"function": "_first_person_weapon_set_state",
|
||||
"reason": "hardened COFF comparison proves all 688 padded bytes and all 26 semantic relocations exact (SHA-256 965964af9115913e36fa06e152828b2e857e7ac59e2cc0e6fdcff29ddebcb91f); objdiff reports a private switch-table/local-label ownership false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_game_data_input_functions",
|
||||
"function": "_mutliplayer_settings_select_list_update_displayed_items",
|
||||
"reason": "hardened COFF comparison proves all 1424 padded bytes and all 73 semantic relocations exact (SHA-256 adce7f9ab32aee72ec9d542efc297df9295a839a27406848eb8467ffea97594f); objdiff reports compiler-local switch-table labels as a false negative; January's original misspelling of multiplayer in the owner name is preserved"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget_game_data_input_functions",
|
||||
"function": "_server_list_menu_update",
|
||||
"reason": "hardened COFF comparison proves all 2016 padded bytes and all 115 semantic relocations exact (SHA-256 f7a5f8c39ab8f6200fa4dfe798c533c40d76e0f8acd06935cea2d5a696c73334); objdiff reports this complete typed server-list graph as a false negative"
|
||||
},
|
||||
{
|
||||
"unit": "source/interface/ui_widget",
|
||||
"function": "_remap_sticks_for_local_player",
|
||||
"reason": "hardened COFF comparison proves all 304 padded bytes and all 31 semantic relocations exact (SHA-256 963b6756ac2f3b70faf18955bad37bac6ed40bbe366baa697feccc61e7050ce8); objdiff reports a control-flow pairing false negative after the natural switch assigns the remapped icon and reaches the shared return"
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,68 @@
|
||||
[
|
||||
{ "file_offset": 1536, "name" : ".text" },
|
||||
{ "file_offset": 1926336, "name" : "D3D" },
|
||||
{ "file_offset": 2005192, "name" : "D3D_RD" },
|
||||
{ "file_offset": 2011016, "name" : "D3D_RW" },
|
||||
{ "file_offset": 2011136, "name" : "D3D_URW" },
|
||||
{ "file_offset": 2024576, "name" : "D3DX" },
|
||||
{ "file_offset": 2044112, "name" : "D3DX_RD" },
|
||||
{ "file_offset": 2044320, "name" : "DSOUND" },
|
||||
{ "file_offset": 2092088, "name" : "DSOUND_RD" },
|
||||
{ "file_offset": 2171408, "name" : "DSOUND_RW" },
|
||||
{ "file_offset": 2173056, "name" : "DSOUND_URW" },
|
||||
{ "file_offset": 2173248, "name" : "XNET" },
|
||||
{ "file_offset": 2218120, "name" : "XNET_RD" },
|
||||
{ "file_offset": 2218496, "name" : "BINK" },
|
||||
{ "file_offset": 2308672, "name" : "BINK32" },
|
||||
{ "file_offset": 2313408, "name" : "BINK32A" },
|
||||
{ "file_offset": 2318912, "name" : "BINK16" },
|
||||
{ "file_offset": 2323808, "name" : "BINK4444" },
|
||||
{ "file_offset": 2329344, "name" : "BINK5551" },
|
||||
{ "file_offset": 2333760, "name" : "BINK16MX" },
|
||||
{ "file_offset": 2334080, "name" : "BINK16X2" },
|
||||
{ "file_offset": 2335456, "name" : "BINK16M" },
|
||||
{ "file_offset": 2335968, "name" : "BINK32MX" },
|
||||
{ "file_offset": 2336416, "name" : "BINK32X2" },
|
||||
{ "file_offset": 2337856, "name" : "BINK32M" },
|
||||
{ "file_offset": 2338208, "name" : ".XPP$ClassA" },
|
||||
{ "file_offset": 2338212, "name" : ".XPP$ClassHub" },
|
||||
{ "file_offset": 2338216, "name" : ".XPP$ClassMU" },
|
||||
{ "file_offset": 2338220, "name" : ".XPP$ClassXID" },
|
||||
{ "file_offset": 2338228, "name" : ".XPP$ClassZ" },
|
||||
{ "file_offset": 2338232, "name" : ".XPP$Data" },
|
||||
{ "file_offset": 2338948, "name" : ".XPPCINIT" },
|
||||
{ "file_offset": 2342115, "name" : ".XPPCODE" },
|
||||
{ "file_offset": 2370500, "name" : ".XPPRDATA" },
|
||||
{ "file_offset": 2370592, "name" : ".idata$5" },
|
||||
{ "file_offset": 2371276, "name" : ".rdata" },
|
||||
{ "file_offset": 2845216, "name" : ".rdata$debug" },
|
||||
{ "file_offset": 2845312, "name" : ".CRT$RIA" },
|
||||
{ "file_offset": 2845316, "name" : ".CRT$RII10" },
|
||||
{ "file_offset": 2845320, "name" : ".CRT$RII20" },
|
||||
{ "file_offset": 2845324, "name" : ".CRT$RIZ" },
|
||||
{ "file_offset": 2845328, "name" : ".CRT$XCA" },
|
||||
{ "file_offset": 2845332, "name" : ".CRT$XCU" },
|
||||
{ "file_offset": 2845340, "name" : ".CRT$XCZ" },
|
||||
{ "file_offset": 2845344, "name" : ".CRT$XIA" },
|
||||
{ "file_offset": 2845348, "name" : ".CRT$XIC" },
|
||||
{ "file_offset": 2845356, "name" : ".CRT$XIZ" },
|
||||
{ "file_offset": 2845360, "name" : ".CRT$XPA" },
|
||||
{ "file_offset": 2845364, "name" : ".CRT$XPX" },
|
||||
{ "file_offset": 2845368, "name" : ".CRT$XPZ" },
|
||||
{ "file_offset": 2845372, "name" : ".CRT$XTA" },
|
||||
{ "file_offset": 2845376, "name" : ".CRT$XTZ" },
|
||||
{ "file_offset": 2845392, "name" : ".data" },
|
||||
{ "file_offset": 3251360, "name" : ".bss" },
|
||||
{ "file_offset": 6401024, "name" : "DOLBY" },
|
||||
{ "file_offset": 6429088, "name" : "BINKDATA" },
|
||||
{ "file_offset": 6446080, "name" : ".idata$2" },
|
||||
{ "file_offset": 6446120, "name" : ".idata$3" },
|
||||
{ "file_offset": 6446140, "name" : ".idata$4" },
|
||||
{ "file_offset": 6446824, "name" : ".idata$6" },
|
||||
{ "file_offset": 6446848, "name" : ".tls" },
|
||||
{ "file_offset": 6446852, "name" : ".tls$" },
|
||||
{ "file_offset": 6446860, "name" : ".tls$ZZZ" },
|
||||
{ "file_offset": 6446880, "name" : ".XBLD" },
|
||||
{ "file_offset": 6446896, "name" : ".XBLD$A" },
|
||||
{ "file_offset": 6446912, "name" : ".XBLD$V" }
|
||||
]
|
||||
@@ -0,0 +1,39 @@
|
||||
[
|
||||
{
|
||||
"unit": "source/objects/objects",
|
||||
"section": ".bss",
|
||||
"reason": "January layout, PDB-public evidence, and module-local references prove three source-private object globals followed by the externally visible debug byte",
|
||||
"snapshot": {
|
||||
"size": 13,
|
||||
"flags": 3224371328,
|
||||
"relocation_count": 0,
|
||||
"normalized_sha256": "dd46c3eebb1884ff3b5258c0a2fc9398e560a29e0780d4b53869b6254aa46a96",
|
||||
"symbols": [
|
||||
{
|
||||
"name": "_object_name_list",
|
||||
"value": 0,
|
||||
"type": 0,
|
||||
"storage": 3
|
||||
},
|
||||
{
|
||||
"name": "_object_memory_pool",
|
||||
"value": 4,
|
||||
"type": 0,
|
||||
"storage": 3
|
||||
},
|
||||
{
|
||||
"name": "_object_globals",
|
||||
"value": 8,
|
||||
"type": 0,
|
||||
"storage": 3
|
||||
},
|
||||
{
|
||||
"name": "_debug_objects_position_velocity",
|
||||
"value": 12,
|
||||
"type": 0,
|
||||
"storage": 2
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
+23861
File diff suppressed because it is too large.
Load diff
+164
-137
@@ -1,28 +1,70 @@
|
||||
#!/usr/bin/env python3
|
||||
|
||||
# root build script: writes build.ninja for the native ports (Linux, Windows,
|
||||
# Android) and the web port
|
||||
# root build script
|
||||
|
||||
import argparse
|
||||
import io
|
||||
import os
|
||||
import sys
|
||||
import json
|
||||
from pathlib import Path
|
||||
from types import SimpleNamespace
|
||||
|
||||
from tools import ninja_syntax
|
||||
from tools.android_build import android_configure_inputs, generate_android_build
|
||||
from tools.linux_build import check_profile_options, generate_linux_build, linux_configure_inputs
|
||||
from tools.web_build import generate_web_build, web_configure_inputs
|
||||
from tools.windows_build import generate_windows_build, windows_configure_inputs
|
||||
|
||||
|
||||
def is_windows() -> bool:
|
||||
return os.name == "nt"
|
||||
|
||||
from typing import (
|
||||
IO,
|
||||
Any,
|
||||
Callable,
|
||||
Dict,
|
||||
Iterable,
|
||||
List,
|
||||
Optional,
|
||||
Set,
|
||||
Tuple,
|
||||
TypedDict,
|
||||
Union,
|
||||
cast,
|
||||
)
|
||||
|
||||
from tools.project_x86 import (
|
||||
Object,
|
||||
ObjectStatus,
|
||||
ProjectConfig,
|
||||
SolutionConfig,
|
||||
calculate_progress,
|
||||
generate_build,
|
||||
is_windows,
|
||||
)
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
# arguments
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument(
|
||||
"mode",
|
||||
choices=["configure", "progress"],
|
||||
default="configure",
|
||||
help="script mode (default: configure)",
|
||||
nargs="?",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--objdiff",
|
||||
metavar="BINARY",
|
||||
type=Path,
|
||||
help="path to objdiff-cli binary (optional)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--csplit",
|
||||
metavar="BINARY",
|
||||
type=Path,
|
||||
help="path to csplit binary (optional)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--ninja",
|
||||
metavar="BINARY",
|
||||
type=Path,
|
||||
help="path to ninja binary (optional)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--ml",
|
||||
metavar="BINARY",
|
||||
type=Path,
|
||||
help="path to Microsoft Macro Assembler for authentic CRT .asm units",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--linux-cc",
|
||||
metavar="BINARY",
|
||||
@@ -31,36 +73,26 @@ parser.add_argument(
|
||||
parser.add_argument(
|
||||
"--compiler-launcher",
|
||||
metavar="BINARY",
|
||||
help="a program that runs each compile, such as ccache "
|
||||
help="native ports: a program that runs each compile, such as ccache "
|
||||
"(links and the Android host's few units run the compiler directly)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--release",
|
||||
action="store_true",
|
||||
help="release builds (Linux, Windows, Android, web): assertions are not checked",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--profile",
|
||||
action="store_true",
|
||||
help="profiling builds (Linux, Windows, Android): CPU scopes recorded on a "
|
||||
"console command or launch setting (README, \"Profiling builds\"); not with --pgo=train",
|
||||
help="release builds of the native ports (Linux, Windows, Android): assertions are not checked",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--lto",
|
||||
choices=["full", "thin", "off"],
|
||||
default="full",
|
||||
help="link-time optimisation (Linux, Windows): full (the default: the whole game "
|
||||
help="link-time optimisation of the native ports (Linux, Windows): full (the default: the whole game "
|
||||
"optimised as one module, the fastest code and the slowest links), thin (parallel and incremental) or off",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--portable",
|
||||
action="store_true",
|
||||
help="x86 builds (Linux, Windows): code for any x86-64 processor (SSE2) rather than for this "
|
||||
"machine's (-march=native, the default); use it for builds that run on other computers. On Linux it also "
|
||||
"builds against Debian 11's glibc 2.31 rather than this machine's, and brings its own SDL 3 (libSDL3.so.0, "
|
||||
"beside the executable), so that it starts on SteamOS and older distributions: the first build downloads "
|
||||
"the Debian packages and SDL's source (build/linux/third_party, tools/linux_sysroot.py), and needs CMake, "
|
||||
"pkgconf and wayland-scanner, not the 32-bit SDL 3",
|
||||
help="native x86 ports (Linux, Windows): code for any x86-64 processor (SSE2) rather than for this "
|
||||
"machine's (-march=native, the default); use it for builds that run on other computers",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--pgo",
|
||||
@@ -68,7 +100,7 @@ parser.add_argument(
|
||||
const="train",
|
||||
default="use",
|
||||
choices=["use", "train", "off"],
|
||||
help="profile-guided optimisation: use (the default) optimises with the profiles in pgo/, "
|
||||
help="profile-guided optimisation of the native ports: use (the default) optimises with the profiles in pgo/, "
|
||||
"train (or plain --pgo) first records this platform's profile if it is missing, by letting an instrumented "
|
||||
"build play every campaign level (needs the game data in assets/ and a display; Linux and Windows), off does "
|
||||
"without",
|
||||
@@ -77,7 +109,7 @@ parser.add_argument(
|
||||
"--pgo-profile",
|
||||
metavar="PROFDATA",
|
||||
type=Path,
|
||||
help="profile-guided optimisation from this profile instead",
|
||||
help="native ports: profile-guided optimisation from this profile instead",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--android-ndk",
|
||||
@@ -89,119 +121,114 @@ parser.add_argument(
|
||||
type=str,
|
||||
help="clang with the arm64_32 target for the Android guest (default: clang)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--web-emcc",
|
||||
type=str,
|
||||
help="Emscripten's emcc for `ninja web` (default: emcc on the PATH, then EMSDK's or ~/emsdk's)",
|
||||
)
|
||||
|
||||
# no need to spam those extra flags when running on Windows
|
||||
if not is_windows():
|
||||
parser.add_argument(
|
||||
"--windows-cross",
|
||||
action="store_true",
|
||||
help="generate the Windows build (`ninja windows`) on Linux, cross-compiling "
|
||||
"with clang against an MSVC toolchain (--windows-vctools-dir and --windows-sdk-dir), "
|
||||
"and make it the default target",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--windows-cc",
|
||||
"--wrapper",
|
||||
metavar="BINARY",
|
||||
help="compiler for the Windows cross build, `ninja windows` (default: clang). "
|
||||
"Only clang is supported for now.",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--windows-vctools-dir",
|
||||
metavar="DIR",
|
||||
type=Path,
|
||||
help="the Visual C++ tools of the MSVC toolchain a --windows-cross build compiles "
|
||||
"and links against: the versioned folder under VC/Tools/MSVC, the one with `include` "
|
||||
"and `lib` (default: VCToolsInstallDir)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--windows-sdk-dir",
|
||||
metavar="DIR",
|
||||
type=Path,
|
||||
help="the Windows SDK a --windows-cross build compiles and links against: the "
|
||||
"folder with `Include` and `Lib`, each with a versioned folder (default: WindowsSdkDir)",
|
||||
help="path to wibo or wine (optional)",
|
||||
)
|
||||
|
||||
args = parser.parse_args()
|
||||
try:
|
||||
check_profile_options(args.profile, args.pgo)
|
||||
except ValueError as error:
|
||||
parser.error(str(error))
|
||||
|
||||
# the settings the builds read
|
||||
sln = SimpleNamespace(
|
||||
build_dir=Path("build"),
|
||||
linux_cc=args.linux_cc,
|
||||
compiler_launcher=args.compiler_launcher,
|
||||
port_release=args.release,
|
||||
port_profile=args.profile,
|
||||
port_lto=args.lto,
|
||||
port_portable=args.portable,
|
||||
port_pgo=args.pgo,
|
||||
port_pgo_profile=args.pgo_profile,
|
||||
android_ndk=args.android_ndk,
|
||||
android_guest_cc=args.android_guest_cc,
|
||||
web_emcc=args.web_emcc,
|
||||
)
|
||||
# path setup
|
||||
|
||||
build_dir = Path("build")
|
||||
config_dir = Path("config")
|
||||
config_json_path = config_dir / "config.json"
|
||||
project_dir = Path("projects")
|
||||
tools_dir = Path("tools")
|
||||
|
||||
# build config json
|
||||
|
||||
class BuildConfigObject(TypedDict):
|
||||
name: str
|
||||
index: int
|
||||
status: str
|
||||
options: Dict[str, Any]
|
||||
|
||||
class BuildConfigProject(TypedDict):
|
||||
name: str
|
||||
guid: str
|
||||
objects: List[BuildConfigObject]
|
||||
options: Dict[str, Any]
|
||||
|
||||
class BuildConfig(TypedDict):
|
||||
name: str
|
||||
guid: str
|
||||
baserom: str
|
||||
projects: List[BuildConfigProject]
|
||||
|
||||
build_config: BuildConfig = json.load(open(config_json_path, "r", encoding="utf-8"))
|
||||
|
||||
# solution configuration
|
||||
|
||||
sln = SolutionConfig()
|
||||
sln.build_dir = build_dir
|
||||
sln.config_dir = config_dir
|
||||
sln.project_dir = project_dir
|
||||
sln.tools_dir = tools_dir
|
||||
|
||||
sln.name = build_config["name"]
|
||||
sln.guid = build_config["guid"]
|
||||
sln.baserom = build_config["baserom"]
|
||||
|
||||
# Apply arguments
|
||||
sln.objdiff_path = args.objdiff
|
||||
sln.csplit_path = args.csplit
|
||||
sln.ninja_path = args.ninja
|
||||
sln.ml_path = args.ml
|
||||
sln.linux_cc = args.linux_cc
|
||||
sln.compiler_launcher = args.compiler_launcher
|
||||
sln.port_release = args.release
|
||||
sln.port_lto = args.lto
|
||||
sln.port_portable = args.portable
|
||||
sln.port_pgo = args.pgo
|
||||
sln.port_pgo_profile = args.pgo_profile
|
||||
sln.android_ndk = args.android_ndk
|
||||
sln.android_guest_cc = args.android_guest_cc
|
||||
if not is_windows():
|
||||
sln.windows_cc = args.windows_cc
|
||||
sln.windows_cross = args.windows_cross
|
||||
sln.windows_vctools_dir = args.windows_vctools_dir
|
||||
sln.windows_sdk_dir = args.windows_sdk_dir
|
||||
sln.wrapper = args.wrapper
|
||||
|
||||
# Tool versions
|
||||
sln.objdiff_tag = "v3.6.0"
|
||||
sln.csplit_tag = "v0.0.2"
|
||||
# v0.0.2 plus upstream's "Fix uninit phony section"; built from source on Linux
|
||||
sln.csplit_source_commit = "db510e7ef9f60bb09b13a3df88c7419e9b215cde"
|
||||
sln.wibo_tag = "1.0.0"
|
||||
sln.uasm_tag = "v2.57r"
|
||||
|
||||
# build.ninja
|
||||
out = io.StringIO()
|
||||
n = ninja_syntax.Writer(out)
|
||||
n.variable("ninja_required_version", "1.3")
|
||||
n.newline()
|
||||
sln.projects = []
|
||||
for build_project in build_config["projects"]:
|
||||
project = ProjectConfig(**build_project.get("options", {}))
|
||||
project.name = build_project["name"]
|
||||
project.guid = build_project["guid"]
|
||||
project.objects = []
|
||||
for build_object in build_project["objects"]:
|
||||
def get_object_completed(status: str) -> ObjectStatus:
|
||||
if status == "MISSING":
|
||||
return ObjectStatus.Missing
|
||||
elif status == "Matching":
|
||||
return ObjectStatus.Matching
|
||||
elif status == "NonMatching":
|
||||
return ObjectStatus.NonMatching
|
||||
assert False, f"Invalid object status {status}"
|
||||
project.objects.append(Object(get_object_completed(build_object["status"]), Path(build_object["name"]), **build_object.get("options", {})))
|
||||
sln.projects.append(project)
|
||||
|
||||
configure_script = Path(os.path.relpath(os.path.abspath(sys.argv[0])))
|
||||
n.comment("The arguments passed to configure.py, for rerunning it.")
|
||||
n.variable(
|
||||
"configure_args",
|
||||
[f'"{arg}"' if any(ch.isspace() for ch in arg) else arg for arg in sys.argv[1:]],
|
||||
)
|
||||
n.variable("python", f'"{sys.executable}"')
|
||||
n.newline()
|
||||
# build file generation
|
||||
|
||||
generate_linux_build(n, sln)
|
||||
generate_android_build(n, sln)
|
||||
generate_windows_build(n, sln)
|
||||
generate_web_build(n, sln)
|
||||
|
||||
n.comment("Reconfigure on change")
|
||||
n.rule(
|
||||
name="configure",
|
||||
command=f"$python {configure_script} $configure_args",
|
||||
generator=True,
|
||||
description=f"RUN {configure_script}",
|
||||
)
|
||||
n.build(
|
||||
outputs="build.ninja",
|
||||
rule="configure",
|
||||
implicit=[
|
||||
configure_script,
|
||||
Path("tools/ninja_syntax.py"),
|
||||
*linux_configure_inputs(),
|
||||
*android_configure_inputs(),
|
||||
*windows_configure_inputs(),
|
||||
*web_configure_inputs(),
|
||||
],
|
||||
)
|
||||
n.newline()
|
||||
|
||||
# the build for this computer, where it could be generated (the Windows
|
||||
# build is left out when SDL cannot be fetched, for instance)
|
||||
default = "windows" if is_windows() or sln.windows_cross else "linux"
|
||||
if f"\nbuild {default}: " in out.getvalue():
|
||||
n.comment("Default rule: the build for this computer")
|
||||
n.default(default)
|
||||
|
||||
with open("build.ninja", "w", encoding="utf-8") as f:
|
||||
f.write(out.getvalue())
|
||||
out.close()
|
||||
if args.mode == "configure":
|
||||
if sln.matching and any(
|
||||
obj["status"] != "MISSING" and obj["name"].startswith("libs/d3d8/")
|
||||
for project in build_config["projects"]
|
||||
for obj in project["objects"]
|
||||
):
|
||||
subprocess.run([sys.executable, "libs/d3d8/generate_sdk_overlay.py"], check=True)
|
||||
# Write build.ninja and objdiff.json
|
||||
generate_build(sln)
|
||||
elif args.mode == "progress":
|
||||
# Print progress information
|
||||
calculate_progress(sln)
|
||||
else:
|
||||
sys.exit("Unknown mode: " + args.mode)
|
||||
@@ -1,3 +0,0 @@
|
||||
*
|
||||
!healthz.sh
|
||||
!*.zip
|
||||
@@ -1,2 +0,0 @@
|
||||
# a release zip copied here to build the image from (README.md, "Building it")
|
||||
*.zip
|
||||
@@ -1,60 +0,0 @@
|
||||
# syntax=docker/dockerfile:1
|
||||
#
|
||||
# The dedicated server (docs/dedicated_server.md) as a container image, made
|
||||
# from a release's halo-linux-release.zip (the portable build: halo, its
|
||||
# libSDL3.so.0, brokers.txt, masters.txt):
|
||||
#
|
||||
# docker build -t opence-server deploy/docker
|
||||
# docker build -t opence-server --build-arg RELEASE=https://github.com/OpenCommunityEdition/OpenCE/releases/download/build-206/halo-linux-release.zip deploy/docker
|
||||
# docker build -t opence-server --build-arg RELEASE=halo-linux-release.zip deploy/docker (a zip in deploy/docker)
|
||||
#
|
||||
# The game data is never in the image: mount the folder that holds maps/ at
|
||||
# /data, read-only. /state is the only folder the server writes (config.toml,
|
||||
# the save root with its map cache, the logs), so the root can be read-only.
|
||||
# deploy/docker/README.md says how to run it.
|
||||
|
||||
FROM debian:bookworm-slim AS release
|
||||
RUN apt-get update \
|
||||
&& apt-get install -y --no-install-recommends unzip \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
# a URL, or a file beside this Dockerfile
|
||||
ARG RELEASE=https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-linux-release.zip
|
||||
ADD ${RELEASE} /tmp/halo-linux-release.zip
|
||||
COPY healthz.sh /opt/opence/healthz.sh
|
||||
RUN unzip -q /tmp/halo-linux-release.zip -d /opt/opence \
|
||||
&& test -f /opt/opence/halo \
|
||||
&& chmod 0755 /opt/opence/halo /opt/opence/healthz.sh \
|
||||
&& if [ -f /opt/opence/halo-server ]; then chmod 0755 /opt/opence/halo-server; fi
|
||||
|
||||
FROM debian:bookworm-slim
|
||||
# The 32-bit C runtime; the release's own libSDL3.so.0 needs nothing more for
|
||||
# a server, which opens no window or sound device. ca-certificates: the
|
||||
# master servers and the update check are HTTPS.
|
||||
RUN dpkg --add-architecture i386 \
|
||||
&& apt-get update \
|
||||
&& apt-get install -y --no-install-recommends libc6:i386 libgcc-s1:i386 ca-certificates \
|
||||
&& rm -rf /var/lib/apt/lists/* \
|
||||
&& groupadd -g 10001 opence \
|
||||
&& useradd -u 10001 -g 10001 -d /state -M -s /usr/sbin/nologin opence \
|
||||
&& mkdir -p /data /state \
|
||||
&& chown 10001:10001 /state
|
||||
COPY --from=release /opt/opence /opt/opence
|
||||
ENV HALO_SERVER=1 \
|
||||
HALO_CONFIG_FILE=/state/config.toml \
|
||||
HALO_DATA_ROOT=/data \
|
||||
HALO_SAVE_ROOT=/state/saves \
|
||||
HALO_LOG_ROOT=/state/logs \
|
||||
HALO_NET_TUNNEL_PORT=2302 \
|
||||
HALO_SERVER_WEB_BIND=0.0.0.0 \
|
||||
HALO_SERVER_WEB_PORT=8080 \
|
||||
HOME=/state
|
||||
VOLUME ["/state"]
|
||||
# Internet play's tunnel, and the web page, API and RCON (publish it on the
|
||||
# host's loopback, or behind a proxy with TLS). System link's 5150, 5151 and
|
||||
# 5153 are for a local network only.
|
||||
EXPOSE 2302/udp 8080/tcp
|
||||
USER 10001:10001
|
||||
WORKDIR /state
|
||||
HEALTHCHECK --interval=15s --timeout=3s --start-period=60s --retries=3 CMD ["/opt/opence/healthz.sh"]
|
||||
STOPSIGNAL SIGTERM
|
||||
ENTRYPOINT ["/opt/opence/halo", "--server"]
|
||||
@@ -1,134 +0,0 @@
|
||||
# The dedicated server in a container
|
||||
|
||||
`ghcr.io/opencommunityedition/opence-server` is the dedicated server
|
||||
(`docs/dedicated_server.md`) as a container image: a release's
|
||||
`halo-linux-release.zip` on Debian 12 with the 32-bit C runtime, run as
|
||||
`halo --server` by the user 10001. CI builds it from each release
|
||||
(`.github/workflows/server-image.yml`) and signs it with cosign; the tags are
|
||||
`latest`, the release's (`build-206`) and `sha-<commit>`.
|
||||
|
||||
The game data is never in the image. Mount the folder that holds `maps/`
|
||||
(from your own copy of the game: port/linux/README.md, "Game data") at
|
||||
`/data`, read-only. Without it the server exits with code 2 and says which
|
||||
maps it looked for.
|
||||
|
||||
## Running it
|
||||
|
||||
```sh
|
||||
docker run -d --name halo --restart unless-stopped \
|
||||
--read-only --cap-drop ALL --security-opt no-new-privileges --tmpfs /tmp \
|
||||
-p 2302:2302/udp -p 127.0.0.1:8080:8080 \
|
||||
-v /srv/halo/data:/data:ro -v halo-state:/state \
|
||||
-e HALO_SERVER_NAME="My server" \
|
||||
-e HALO_SERVER_ROTATION="bloodgulch:ctf, sidewinder:team_slayer" \
|
||||
-e HALO_SERVER_WEB_PASSWORD=changeme-please \
|
||||
ghcr.io/opencommunityedition/opence-server:latest
|
||||
docker logs -f halo
|
||||
```
|
||||
|
||||
Or with Compose: `compose.yaml` beside this file runs the same, with the
|
||||
settings taken from the shell or a `.env` file
|
||||
(`HALO_DATA=/srv/halo/data`, `HALO_SERVER_NAME=...`). Its `https` profile
|
||||
adds Caddy in front of the web port, with a certificate for
|
||||
`HALO_WEB_DOMAIN`:
|
||||
|
||||
```sh
|
||||
HALO_DATA=/srv/halo/data docker compose -f deploy/docker/compose.yaml up -d
|
||||
HALO_WEB_DOMAIN=halo.example.org docker compose -f deploy/docker/compose.yaml --profile https up -d
|
||||
```
|
||||
|
||||
The Compose file puts both on a network of its own, `172.30.80.0/24`, with
|
||||
Caddy at the fixed address `172.30.80.10` and the server's
|
||||
`HALO_SERVER_WEB_TRUSTED_PROXY` set to it: the server believes Caddy's
|
||||
`X-Forwarded-For`, `-Host` and `-Proto`, so its rate limits and log name the
|
||||
visitor rather than Caddy, and the session cookie is `Secure`. If that
|
||||
subnet overlaps one of the host's, change the subnet, Caddy's
|
||||
`ipv4_address` and the variable together.
|
||||
|
||||
`docker stop` sends SIGTERM: the game in progress goes to its postgame,
|
||||
the players are told, the listing is withdrawn, and the server exits 0
|
||||
within the 15 seconds Compose waits (`docker stop -t 15` otherwise).
|
||||
|
||||
## Folders
|
||||
|
||||
| Path | What |
|
||||
| --- | --- |
|
||||
| `/opt/opence` | The release: `halo`, `libSDL3.so.0`, `brokers.txt`, `masters.txt`, `healthz.sh`, the licences (read-only) |
|
||||
| `/data` | The game data: `maps/`, and if you have them `custom_maps/`, `gametypes/` and `init.txt` (yours, read-only) |
|
||||
| `/state` | The only folder written: `config.toml` (`HALO_CONFIG_FILE`), `publisher.key` beside it, the save root `saves/` with the map cache (about 115 MB), `logs/` (`debug.txt`, `bans.txt`, `cheaters.txt`) |
|
||||
|
||||
The image sets `HALO_CONFIG_FILE=/state/config.toml` rather than linking
|
||||
`config.toml` beside the executable into the volume: the settings file is
|
||||
then in the volume from the first start, and nothing in `/opt/opence` is
|
||||
written. The server writes every setting there at the first start, with
|
||||
the generated web password if none was given.
|
||||
|
||||
## Settings
|
||||
|
||||
Every setting is an environment variable (port/linux/README.md, "Dedicated
|
||||
server", and docs/dedicated_server.md). A variable that is set wins over
|
||||
`config.toml`, and the web page's settings cannot change it. The image sets:
|
||||
|
||||
| Variable | Value |
|
||||
| --- | --- |
|
||||
| `HALO_SERVER` | `1` |
|
||||
| `HALO_CONFIG_FILE` | `/state/config.toml` |
|
||||
| `HALO_DATA_ROOT` | `/data` |
|
||||
| `HALO_SAVE_ROOT` | `/state/saves` |
|
||||
| `HALO_LOG_ROOT` | `/state/logs` |
|
||||
| `HALO_NET_TUNNEL_PORT` | `2302` |
|
||||
| `HALO_SERVER_WEB_BIND` | `0.0.0.0` (within the container; publish the port on `127.0.0.1` or behind TLS) |
|
||||
| `HALO_SERVER_WEB_PORT` | `8080` |
|
||||
|
||||
The ones most often given: `HALO_SERVER_NAME`, `HALO_SERVER_ROTATION`,
|
||||
`HALO_SERVER_MAX_PLAYERS`, `HALO_SERVER_PASSWORD`, `HALO_SERVER_PUBLIC`,
|
||||
`HALO_SERVER_MOTD`, `HALO_SERVER_WEB_PASSWORD`, `HALO_NET_PUBLIC_ADDRESS`,
|
||||
`HALO_SERVER_PUBLISHER_KEY` (the master servers' key, as 64 hex
|
||||
characters; `docker run --rm -v halo-state:/state <image> --keygen` makes one
|
||||
into the volume instead), `HALO_SERVER_INSTANCE`, `HALO_SERVER_REGION`,
|
||||
`HALO_SERVER_LOG_FORMAT=json`.
|
||||
|
||||
A tunnel port other than 2302 is published as the same number on both sides
|
||||
(`-e HALO_NET_TUNNEL_PORT=2303 -p 2303:2303/udp`), as the server offers its
|
||||
own port to joiners. Behind a NAT that STUN cannot see through, give the
|
||||
public address and port in `HALO_NET_PUBLIC_ADDRESS`.
|
||||
|
||||
## Health
|
||||
|
||||
`HEALTHCHECK` runs `/opt/opence/healthz.sh`, which asks `GET /healthz` on
|
||||
the web port (bash's `/dev/tcp`: the image has no curl) and is healthy on a
|
||||
200: the server is hosting (lobby, loading, playing or postgame) and its
|
||||
frames run. With `HALO_SERVER_WEB_PORT=0` it always passes.
|
||||
|
||||
## Building it
|
||||
|
||||
```sh
|
||||
docker build -t opence-server deploy/docker # the latest release
|
||||
docker build -t opence-server --build-arg RELEASE=https://github.com/OpenCommunityEdition/OpenCE/releases/download/build-206/halo-linux-release.zip deploy/docker
|
||||
```
|
||||
|
||||
A build of your own (`python tools/ci_build.py linux release` leaves
|
||||
`dist/halo-linux-release/`) goes in as a zip beside the Dockerfile:
|
||||
|
||||
```sh
|
||||
(cd dist/halo-linux-release && zip -qr ../../deploy/docker/halo-linux-release.zip .)
|
||||
docker build -t opence-server --build-arg RELEASE=halo-linux-release.zip deploy/docker
|
||||
```
|
||||
|
||||
`RELEASE` is a URL or a file beside the Dockerfile. The image is 32-bit
|
||||
x86 and runs on amd64 hosts only.
|
||||
|
||||
## Networking
|
||||
|
||||
Bridge networking works for internet play: the tunnel port is published one
|
||||
to one, and the server needs no hole punching of its own. System link
|
||||
(UDP 5150 and 5151, TCP 5150 and 5153) finds other machines only with
|
||||
`--network host`.
|
||||
|
||||
Verify an image's signature:
|
||||
|
||||
```sh
|
||||
cosign verify ghcr.io/opencommunityedition/opence-server:latest \
|
||||
--certificate-identity-regexp '^https://github\.com/OpenCommunityEdition/OpenCE/\.github/workflows/server-image\.yml@' \
|
||||
--certificate-oidc-issuer https://token.actions.githubusercontent.com
|
||||
```
|
||||
@@ -1,92 +0,0 @@
|
||||
# The dedicated server with Docker Compose (deploy/docker/README.md):
|
||||
#
|
||||
# docker compose -f deploy/docker/compose.yaml up -d
|
||||
# docker compose -f deploy/docker/compose.yaml --profile https up -d (with Caddy in front of the web port)
|
||||
#
|
||||
# HALO_DATA is the folder that holds maps/ (and custom_maps/, gametypes/),
|
||||
# mounted read-only; settings come from the environment below or from a
|
||||
# .env file beside this one.
|
||||
name: opence
|
||||
|
||||
services:
|
||||
server:
|
||||
image: ${OPENCE_IMAGE:-ghcr.io/opencommunityedition/opence-server:latest}
|
||||
restart: unless-stopped
|
||||
read_only: true
|
||||
cap_drop: [ALL]
|
||||
security_opt: ["no-new-privileges:true"]
|
||||
tmpfs:
|
||||
- /tmp
|
||||
ports:
|
||||
- "${HALO_NET_TUNNEL_PORT:-2302}:${HALO_NET_TUNNEL_PORT:-2302}/udp"
|
||||
# (the web page on the host's loopback only; Caddy reaches it on the
|
||||
# compose network)
|
||||
- "127.0.0.1:${HALO_SERVER_WEB_PORT:-8080}:${HALO_SERVER_WEB_PORT:-8080}/tcp"
|
||||
volumes:
|
||||
- ${HALO_DATA:-./data}:/data:ro
|
||||
- state:/state
|
||||
# A variable named without a value is passed only when it is set (in the
|
||||
# shell or .env): one that is set wins over config.toml, and sv_set
|
||||
# cannot change it.
|
||||
environment:
|
||||
- HALO_NET_TUNNEL_PORT=${HALO_NET_TUNNEL_PORT:-2302}
|
||||
- HALO_SERVER_WEB_PORT=${HALO_SERVER_WEB_PORT:-8080}
|
||||
- HALO_SERVER_NAME
|
||||
- HALO_SERVER_ROTATION
|
||||
- HALO_SERVER_MAX_PLAYERS
|
||||
- HALO_SERVER_PASSWORD
|
||||
- HALO_SERVER_PUBLIC
|
||||
- HALO_SERVER_MOTD
|
||||
# (8 characters or more; unset: one is made at the first start, printed
|
||||
# in the log and kept in the state volume's config.toml)
|
||||
- HALO_SERVER_WEB_PASSWORD
|
||||
- HALO_NET_PUBLIC_ADDRESS
|
||||
- HALO_SERVER_PUBLISHER_KEY
|
||||
- HALO_SERVER_INSTANCE
|
||||
- HALO_SERVER_REGION
|
||||
- HALO_SERVER_LOG_FORMAT
|
||||
# Caddy's address on the network below (the https profile): its
|
||||
# X-Forwarded-For, -Host and -Proto are believed, so the page's rate
|
||||
# limits and log name the visitor, and its session cookie is Secure.
|
||||
# Nothing else has this address.
|
||||
- HALO_SERVER_WEB_TRUSTED_PROXY=172.30.80.10
|
||||
networks:
|
||||
- opence
|
||||
stop_grace_period: 15s
|
||||
|
||||
# HTTPS for the web page, with a certificate from Let's Encrypt for
|
||||
# HALO_WEB_DOMAIN (which must resolve to this host, ports 80 and 443 open).
|
||||
caddy:
|
||||
image: caddy:2
|
||||
profiles: [https]
|
||||
restart: unless-stopped
|
||||
depends_on: [server]
|
||||
ports:
|
||||
- "80:80/tcp"
|
||||
- "443:443/tcp"
|
||||
- "443:443/udp"
|
||||
command: ["caddy", "reverse-proxy", "--from", "${HALO_WEB_DOMAIN:-halo.example.org}", "--to", "server:${HALO_SERVER_WEB_PORT:-8080}"]
|
||||
volumes:
|
||||
- caddy-data:/data
|
||||
- caddy-config:/config
|
||||
networks:
|
||||
opence:
|
||||
# (server.web_trusted_proxy above; outside the range Docker hands
|
||||
# out, so no other container takes it)
|
||||
ipv4_address: 172.30.80.10
|
||||
|
||||
# A fixed subnet, so that Caddy's address is known in advance. Containers
|
||||
# other than Caddy get addresses from ip_range only. Change it (and the two
|
||||
# addresses above) if it overlaps a network of the host's.
|
||||
networks:
|
||||
opence:
|
||||
ipam:
|
||||
config:
|
||||
- subnet: 172.30.80.0/24
|
||||
ip_range: 172.30.80.128/25
|
||||
gateway: 172.30.80.1
|
||||
|
||||
volumes:
|
||||
state:
|
||||
caddy-data:
|
||||
caddy-config:
|
||||
@@ -1,18 +0,0 @@
|
||||
#!/bin/bash
|
||||
# The image's health check: GET /healthz on the web port, healthy on a 200
|
||||
# (the server answers 200 while it hosts and its frames run, 503 otherwise).
|
||||
# Bash's /dev/tcp, as the image has no curl.
|
||||
port="${HALO_SERVER_WEB_PORT:-8080}"
|
||||
# (no web port: nothing to ask)
|
||||
if [ -z "$port" ] || [ "$port" = 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
{ exec 3<>"/dev/tcp/127.0.0.1/$port"; } 2>/dev/null || exit 1
|
||||
printf 'GET /healthz HTTP/1.1\r\nHost: 127.0.0.1:%s\r\nConnection: close\r\n\r\n' "$port" >&3 || exit 1
|
||||
IFS=' ' read -r -t 3 version status _ <&3 || exit 1
|
||||
exec 3<&-
|
||||
case "$version" in
|
||||
HTTP/1.*) ;;
|
||||
*) exit 1 ;;
|
||||
esac
|
||||
[ "$status" = 200 ]
|
||||
@@ -1,29 +0,0 @@
|
||||
# Big team slayer: first team to 50 kills, vehicles as Halo PC places them.
|
||||
# Play it with server.rotation entries such as bloodgulch:btb_slayer.
|
||||
base = "team_slayer"
|
||||
name = "BTB Slayer"
|
||||
|
||||
[universal]
|
||||
teams = true
|
||||
score_to_win = 50
|
||||
lives = 0
|
||||
respawn_time = 5
|
||||
health = 100
|
||||
weapon_set = "normal"
|
||||
vehicle_set = "default"
|
||||
radar = true
|
||||
friend_indicators = true
|
||||
|
||||
[options]
|
||||
time_limit = 20
|
||||
friendly_fire = "shields_only"
|
||||
friendly_fire_penalty = 5
|
||||
vehicle_respawn_time = 60
|
||||
auto_team_balance = true
|
||||
radar_players = "friends"
|
||||
team_vehicles = "pc"
|
||||
|
||||
[slayer]
|
||||
no_death_bonus = false
|
||||
no_kill_penalty = false
|
||||
kill_in_order = false
|
||||
@@ -1,27 +0,0 @@
|
||||
# Capture the flag as players remember it: three captures, the flag must be
|
||||
# at home to score.
|
||||
base = "ctf"
|
||||
name = "Classic CTF"
|
||||
|
||||
[universal]
|
||||
teams = true
|
||||
score_to_win = 3
|
||||
respawn_time = 5
|
||||
weapon_set = "normal"
|
||||
vehicle_set = "default"
|
||||
radar = true
|
||||
|
||||
[options]
|
||||
time_limit = 25
|
||||
friendly_fire = "off"
|
||||
vehicle_respawn_time = 90
|
||||
auto_team_balance = true
|
||||
radar_players = "friends"
|
||||
team_vehicles = "pc"
|
||||
|
||||
[ctf]
|
||||
assault = false
|
||||
reset_on_capture = false
|
||||
flag_must_reset = false
|
||||
flag_at_home_to_score = true
|
||||
single_flag_time = 0
|
||||
@@ -1,17 +0,0 @@
|
||||
# King of the hill whose hill moves about the map, for teams.
|
||||
base = "team_king"
|
||||
name = "Moving Hill"
|
||||
|
||||
[universal]
|
||||
teams = true
|
||||
score_to_win = 3
|
||||
respawn_time = 5
|
||||
radar = true
|
||||
|
||||
[options]
|
||||
time_limit = 15
|
||||
friendly_fire = "off"
|
||||
auto_team_balance = true
|
||||
|
||||
[king]
|
||||
moving_hill = true
|
||||
@@ -1,23 +0,0 @@
|
||||
# Free for all slayer to 25 kills, starting with a pistol and an assault rifle.
|
||||
base = "slayer"
|
||||
name = "Lone Wolves"
|
||||
|
||||
[universal]
|
||||
teams = false
|
||||
score_to_win = 25
|
||||
respawn_time = 3
|
||||
health = 100
|
||||
radar = false
|
||||
|
||||
[options]
|
||||
time_limit = 15
|
||||
radar_players = "none"
|
||||
loadout = "custom"
|
||||
primary_weapon = "pistol"
|
||||
secondary_weapon = "assault_rifle"
|
||||
team_vehicles = "pc"
|
||||
|
||||
[slayer]
|
||||
no_death_bonus = false
|
||||
no_kill_penalty = false
|
||||
kill_in_order = false
|
||||
@@ -1,2 +0,0 @@
|
||||
#!/bin/sh
|
||||
exec "$(dirname "$0")/halo" --server "$@"
|
||||
@@ -1,3 +0,0 @@
|
||||
# Not part of the packaged chart: unit tests and CI values files.
|
||||
tests/
|
||||
ci/
|
||||
@@ -1,17 +0,0 @@
|
||||
apiVersion: v2
|
||||
name: opence-server
|
||||
description: >-
|
||||
The OpenCE dedicated server: a headless Halo: Combat Evolved host that plays games one after
|
||||
another, with no window, sound or player of its own. The game data (maps) is mounted from a
|
||||
volume you provide.
|
||||
type: application
|
||||
version: 0.1.0
|
||||
kubeVersion: ">=1.29.0-0"
|
||||
# Informational only: which image runs is set by image.repository, image.tag and image.digest.
|
||||
appVersion: "latest"
|
||||
home: https://github.com/OpenCommunityEdition/OpenCE
|
||||
sources:
|
||||
- https://github.com/OpenCommunityEdition/OpenCE/tree/main/deploy/helm/opence-server
|
||||
keywords:
|
||||
- halo
|
||||
- game-server
|
||||
@@ -1,111 +0,0 @@
|
||||
# opence-server
|
||||
|
||||
The OpenCE dedicated server (`docs/dedicated_server.md`) on Kubernetes: one
|
||||
pod of the image `ghcr.io/opencommunityedition/opence-server`
|
||||
(`deploy/docker`), its tunnel port behind a UDP Service, its web page behind
|
||||
a ClusterIP Service, probes on `GET /healthz`, and a NetworkPolicy.
|
||||
|
||||
The game data is never in the image or the chart: give a volume that holds
|
||||
`maps/` from your own copy of the game.
|
||||
|
||||
## Quick start
|
||||
|
||||
```sh
|
||||
kubectl create namespace halo
|
||||
# a claim (or an NFS export) holding maps/, read-only is enough
|
||||
helm install halo deploy/helm/opence-server -n halo \
|
||||
--set gameData.existingClaim=halo-maps \
|
||||
--set server.name="My server" \
|
||||
--set persistence.enabled=true
|
||||
kubectl -n halo logs -f deploy/halo-opence-server
|
||||
```
|
||||
|
||||
The admin password of the web page is made at the first install and kept in
|
||||
the release's Secret (NOTES.txt prints the command that shows it), unless
|
||||
`web.password` or `web.existingSecret` gives one. Reach the page with
|
||||
`kubectl -n halo port-forward deploy/halo-opence-server 8080`, or put an
|
||||
Ingress with TLS in front of the `-web` Service (and allow its namespace
|
||||
in `networkPolicy.webFrom`).
|
||||
|
||||
## Values
|
||||
|
||||
`values.yaml` describes each value. Each one under `server`, `web`,
|
||||
`network` and `publisherKey` is one of the server's `HALO_*` variables:
|
||||
|
||||
| Value | Variable |
|
||||
| --- | --- |
|
||||
| `server.name` | `HALO_SERVER_NAME` (15 characters) |
|
||||
| `server.rotation` (a list) | `HALO_SERVER_ROTATION`, joined with commas |
|
||||
| `server.maxPlayers` | `HALO_SERVER_MAX_PLAYERS` |
|
||||
| `server.public` | `HALO_SERVER_PUBLIC` |
|
||||
| `server.lobbySeconds` | `HALO_SERVER_LOBBY_SECONDS` |
|
||||
| `server.motd` | `HALO_SERVER_MOTD` |
|
||||
| `server.logFormat` | `HALO_SERVER_LOG_FORMAT` |
|
||||
| `server.instance`, `server.region` | `HALO_SERVER_INSTANCE`, `HALO_SERVER_REGION` |
|
||||
| `server.masterPublish` | `HALO_SERVER_MASTER_PUBLISH` |
|
||||
| `server.password` | `HALO_SERVER_PASSWORD` (from a Secret) |
|
||||
| `publisherKey` | `HALO_SERVER_PUBLISHER_KEY` (from a Secret) |
|
||||
| `web.port` | `HALO_SERVER_WEB_PORT` (0: none, and no probes) |
|
||||
| `web.password`, `web.existingSecret` | `HALO_SERVER_WEB_PASSWORD` (from a Secret) |
|
||||
| `web.moderatorPassword` | `HALO_SERVER_WEB_MODERATOR_PASSWORD` (from a Secret) |
|
||||
| `network.tunnelPort` | `HALO_NET_TUNNEL_PORT` |
|
||||
| `network.publicAddress` | `HALO_NET_PUBLIC_ADDRESS` |
|
||||
| `customMaps` | `HALO_CUSTOM_MAPS_ROOT=/custom_maps` |
|
||||
|
||||
The chart also sets `HALO_SERVER=1`, `HALO_CONFIG_FILE=/state/config.toml`,
|
||||
`HALO_DATA_ROOT=/data`, `HALO_SAVE_ROOT=/state/saves`,
|
||||
`HALO_LOG_ROOT=/state/logs`, `HALO_SERVER_CONSOLE=false` (a pod has no
|
||||
standard input) and, with a web port, `HALO_SERVER_WEB_BIND=0.0.0.0` (the
|
||||
kubelet's probes reach the pod's address). Any other setting goes in
|
||||
`extraEnv`, which comes last and so overrides the chart's.
|
||||
|
||||
A variable the chart sets wins over `config.toml`, and neither `sv_set` nor
|
||||
the web page's settings can change it. So the values under `server` are
|
||||
unset by default (empty, `[]` or `null`): the chart then sets no variable,
|
||||
and the setting is `config.toml`'s (or the server's default, which
|
||||
`values.yaml` names), changeable from the web page and kept in the state
|
||||
volume. Give a value only for a setting you want fixed.
|
||||
|
||||
## Web password
|
||||
|
||||
With neither `web.password` nor `web.existingSecret`, the chart makes an
|
||||
admin password at the first install and keeps it in the release's Secret;
|
||||
on an upgrade it finds that Secret again with `lookup`. `helm template`,
|
||||
and GitOps tools that render with it (Argo CD, Flux's dry runs,
|
||||
Kustomize's Helm support), have no cluster to look in: each render makes a
|
||||
new password, and the Secret changes at every sync. There, create the Secret
|
||||
yourself and name it:
|
||||
|
||||
```sh
|
||||
kubectl -n halo create secret generic halo-web \
|
||||
--from-literal=web-password="$(openssl rand -base64 18)" \
|
||||
--from-literal=web-moderator-password="$(openssl rand -base64 18)"
|
||||
helm template halo deploy/helm/opence-server -n halo \
|
||||
--set gameData.existingClaim=halo-maps --set web.existingSecret=halo-web
|
||||
```
|
||||
|
||||
(or a SealedSecret or an External Secrets object of the same name).
|
||||
`web.key` and `web.moderatorKey` name its keys; the moderator's is
|
||||
optional.
|
||||
|
||||
## Networking
|
||||
|
||||
`service.type` is `LoadBalancer` with `externalTrafficPolicy: Local` by
|
||||
default, so that the server sees the players' own addresses (its bans and
|
||||
limits are by address). `NodePort` works too; `ClusterIP` is for tests. The
|
||||
tunnel's Service port and `network.tunnelPort` should be the same number, as
|
||||
the server offers its own port to joiners; behind a NAT that STUN cannot see
|
||||
through, give the forwarded address in `network.publicAddress`.
|
||||
|
||||
The NetworkPolicy lets anyone reach the tunnel port and only `webFrom` the
|
||||
web port, and lets the pod reach DNS, TCP 1883 (the MQTT brokers) and 443
|
||||
(the master servers) and any UDP port on public addresses.
|
||||
|
||||
## Tests
|
||||
|
||||
```sh
|
||||
helm lint deploy/helm/opence-server --strict -f deploy/helm/opence-server/ci/full-values.yaml
|
||||
helm unittest deploy/helm/opence-server
|
||||
```
|
||||
|
||||
`.github/workflows/server-image.yml` runs both.
|
||||
@@ -1,87 +0,0 @@
|
||||
# Every option the chart has, for lint and the schema check (not installed: the NFS server is made
|
||||
# up).
|
||||
image:
|
||||
tag: build-206@sha256:0000000000000000000000000000000000000000000000000000000000000000
|
||||
imagePullSecrets:
|
||||
- name: registry-credentials
|
||||
gameData:
|
||||
nfs:
|
||||
server: nfs.example.com
|
||||
path: /exports/halo
|
||||
subPath: xbox
|
||||
customMaps:
|
||||
existingClaim: halo-custom-maps
|
||||
server:
|
||||
name: Example server
|
||||
rotation: [bloodgulch:ctf_classic, sidewinder:team_slayer+score=50, hangemhigh:king_moving]
|
||||
maxPlayers: 24
|
||||
public: true
|
||||
lobbySeconds: 20
|
||||
motd: Welcome
|
||||
logFormat: json
|
||||
instance: eu-1
|
||||
region: eu
|
||||
masterPublish: true
|
||||
password:
|
||||
existingSecret: halo-join
|
||||
key: password
|
||||
publisherKey:
|
||||
existingSecret: halo-publisher
|
||||
key: seed
|
||||
web:
|
||||
port: 8080
|
||||
existingSecret: halo-web
|
||||
key: admin
|
||||
moderatorKey: moderator
|
||||
network:
|
||||
tunnelPort: 2303
|
||||
publicAddress: halo.example.com:2303
|
||||
extraEnv:
|
||||
- name: HALO_SERVER_EMPTY_SECONDS
|
||||
value: "60"
|
||||
persistence:
|
||||
enabled: true
|
||||
storageClass: standard
|
||||
annotations:
|
||||
example.com/keep: "true"
|
||||
service:
|
||||
type: LoadBalancer
|
||||
port: 2303
|
||||
nodePort: 30703
|
||||
annotations:
|
||||
example.com/address: 192.0.2.10
|
||||
externalTrafficPolicy: Local
|
||||
loadBalancerSourceRanges: [0.0.0.0/0]
|
||||
tolerations:
|
||||
- key: dedicated
|
||||
operator: Equal
|
||||
value: games
|
||||
effect: NoSchedule
|
||||
podAnnotations:
|
||||
example.com/scrape: "true"
|
||||
podLabels:
|
||||
team: games
|
||||
probes:
|
||||
liveness:
|
||||
periodSeconds: 30
|
||||
readiness:
|
||||
enabled: false
|
||||
networkPolicy:
|
||||
webFrom:
|
||||
- namespaceSelector:
|
||||
matchLabels:
|
||||
kubernetes.io/metadata.name: ingress-nginx
|
||||
extraEgress:
|
||||
- to:
|
||||
- ipBlock:
|
||||
cidr: 203.0.113.0/24
|
||||
ports:
|
||||
- protocol: TCP
|
||||
port: 8443
|
||||
extraObjects:
|
||||
- apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: '{{ .Release.Name }}-extra'
|
||||
data:
|
||||
hello: world
|
||||
@@ -1,6 +0,0 @@
|
||||
# The smallest install that renders: no maps (an emptyDir in their place), so the server exits with
|
||||
# code 2 and the pod goes into CrashLoopBackOff. A real install gives gameData.existingClaim or
|
||||
# gameData.nfs instead.
|
||||
gameData:
|
||||
volume:
|
||||
emptyDir: {}
|
||||
@@ -1,33 +0,0 @@
|
||||
OpenCE dedicated server {{ .Chart.Version }}: {{ include "opence-server.fullname" . }} in namespace {{ .Release.Namespace }}.
|
||||
|
||||
Rotation: {{ join ", " .Values.server.rotation | default "the server's default" }}.
|
||||
{{- if kindIs "invalid" .Values.server.public }}
|
||||
Listed in everyone's server browser{{ with .Values.server.name }} as "{{ . }}"{{ end }}, unless config.toml or the web page turns server.public off.
|
||||
{{- else if .Values.server.public }}
|
||||
Listed in everyone's server browser{{ with .Values.server.name }} as "{{ . }}"{{ end }}.
|
||||
{{- else }}
|
||||
Not listed: players join with the invite link from the log, or on the LAN.
|
||||
{{- end }}
|
||||
|
||||
The log (the ready line, players, games):
|
||||
|
||||
kubectl -n {{ .Release.Namespace }} logs -f deploy/{{ include "opence-server.fullname" . }}
|
||||
|
||||
Players reach UDP port {{ .Values.service.port }} through Service {{ include "opence-server.fullname" . }} ({{ .Values.service.type }}).
|
||||
{{- if eq .Values.service.type "ClusterIP" }}
|
||||
A ClusterIP Service is not reachable from outside the cluster: set service.type to LoadBalancer or
|
||||
NodePort for internet play.
|
||||
{{- end }}
|
||||
{{- if gt (int .Values.web.port) 0 }}
|
||||
|
||||
The web page, API and remote console:
|
||||
|
||||
kubectl -n {{ .Release.Namespace }} port-forward deploy/{{ include "opence-server.fullname" . }} {{ .Values.web.port }}
|
||||
open http://127.0.0.1:{{ .Values.web.port }}/
|
||||
{{- if not .Values.web.existingSecret }}
|
||||
|
||||
The admin password:
|
||||
|
||||
kubectl -n {{ .Release.Namespace }} get secret {{ include "opence-server.secretName" . }} -o jsonpath='{.data.{{ .Values.web.key }}}' | base64 -d
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
@@ -1,84 +0,0 @@
|
||||
{{/* The objects' name: fullnameOverride, else the release name if it contains the chart's name,
|
||||
else <release>-<chart>. */}}
|
||||
{{- define "opence-server.fullname" -}}
|
||||
{{- if .Values.fullnameOverride -}}
|
||||
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}
|
||||
{{- else -}}
|
||||
{{- $name := default .Chart.Name .Values.nameOverride -}}
|
||||
{{- if contains $name .Release.Name -}}
|
||||
{{- .Release.Name | trunc 63 | trimSuffix "-" -}}
|
||||
{{- else -}}
|
||||
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end }}
|
||||
|
||||
{{- define "opence-server.name" -}}
|
||||
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
|
||||
{{- end }}
|
||||
|
||||
{{- define "opence-server.labels" -}}
|
||||
{{ include "opence-server.selectorLabels" . }}
|
||||
app.kubernetes.io/managed-by: {{ .Release.Service }}
|
||||
helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
|
||||
{{- end }}
|
||||
|
||||
{{- define "opence-server.selectorLabels" -}}
|
||||
app.kubernetes.io/name: {{ include "opence-server.name" . }}
|
||||
app.kubernetes.io/instance: {{ .Release.Name }}
|
||||
{{- end }}
|
||||
|
||||
{{/* repository:tag, repository:tag@digest, or repository@digest; an empty tag is the appVersion. */}}
|
||||
{{- define "opence-server.image" -}}
|
||||
{{- $image := .Values.image -}}
|
||||
{{- $ref := $image.repository -}}
|
||||
{{- $tag := toString ($image.tag | default .Chart.AppVersion) -}}
|
||||
{{- if $image.digest }}{{ $tag = regexReplaceAll "@.*$" $tag "" }}{{ if hasPrefix "sha256:" $tag }}{{ $tag = "" }}{{ end }}{{ end -}}
|
||||
{{- if hasPrefix "sha256:" $tag }}{{ $ref = printf "%s@%s" $ref $tag }}
|
||||
{{- else if $tag }}{{ $ref = printf "%s:%s" $ref $tag }}{{ end -}}
|
||||
{{- if and $image.digest (not (contains "@" $ref)) }}{{ $ref = printf "%s@%s" $ref $image.digest }}{{ end -}}
|
||||
{{- $ref -}}
|
||||
{{- end }}
|
||||
|
||||
{{- define "opence-server.stateClaim" -}}
|
||||
{{- .Values.persistence.existingClaim | default (printf "%s-state" (include "opence-server.fullname" .)) -}}
|
||||
{{- end }}
|
||||
|
||||
{{/* The chart's Secret: the web passwords it makes or is given, the join password, the publisher
|
||||
key. */}}
|
||||
{{- define "opence-server.secretName" -}}
|
||||
{{- printf "%s-secrets" (include "opence-server.fullname" .) -}}
|
||||
{{- end }}
|
||||
|
||||
{{/* The Secret holding the web password: web.existingSecret, else the chart's. */}}
|
||||
{{- define "opence-server.webSecret" -}}
|
||||
{{- .Values.web.existingSecret | default (include "opence-server.secretName" .) -}}
|
||||
{{- end }}
|
||||
|
||||
{{- define "opence-server.hasGameData" -}}
|
||||
{{- with .Values.gameData -}}
|
||||
{{- if or .existingClaim (and .nfs.server .nfs.path) .volume }}true{{ end -}}
|
||||
{{- end -}}
|
||||
{{- end }}
|
||||
|
||||
{{- define "opence-server.hasCustomMaps" -}}
|
||||
{{- with .Values.customMaps -}}
|
||||
{{- if or .existingClaim (and .nfs.server .nfs.path) .volume }}true{{ end -}}
|
||||
{{- end -}}
|
||||
{{- end }}
|
||||
|
||||
{{/* A volume source of gameData or customMaps (the dict), read-only. */}}
|
||||
{{- define "opence-server.volumeSource" -}}
|
||||
{{- if .existingClaim }}
|
||||
persistentVolumeClaim:
|
||||
claimName: {{ .existingClaim }}
|
||||
readOnly: true
|
||||
{{- else if and .nfs.server .nfs.path }}
|
||||
nfs:
|
||||
server: {{ .nfs.server }}
|
||||
path: {{ .nfs.path }}
|
||||
readOnly: true
|
||||
{{- else }}
|
||||
{{- toYaml .volume }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
@@ -1,198 +0,0 @@
|
||||
{{- if not (include "opence-server.hasGameData" .) }}
|
||||
{{- fail "gameData: set existingClaim, nfs.server and nfs.path, or volume - the server needs the game's maps, which are never in the image" }}
|
||||
{{- end }}
|
||||
{{- $fullname := include "opence-server.fullname" . }}
|
||||
{{- $secret := include "opence-server.secretName" . }}
|
||||
{{- $webPort := int .Values.web.port }}
|
||||
{{- $env := list }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER" "value" "1") }}
|
||||
{{- $env = append $env (dict "name" "HALO_CONFIG_FILE" "value" "/state/config.toml") }}
|
||||
{{- $env = append $env (dict "name" "HALO_DATA_ROOT" "value" "/data") }}
|
||||
{{- $env = append $env (dict "name" "HALO_SAVE_ROOT" "value" "/state/saves") }}
|
||||
{{- $env = append $env (dict "name" "HALO_LOG_ROOT" "value" "/state/logs") }}
|
||||
{{- if include "opence-server.hasCustomMaps" . }}
|
||||
{{- $env = append $env (dict "name" "HALO_CUSTOM_MAPS_ROOT" "value" "/custom_maps") }}
|
||||
{{- end }}
|
||||
{{- /* (a pod has no standard input to read commands from) */}}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_CONSOLE" "value" "false") }}
|
||||
{{- $env = append $env (dict "name" "HALO_NET_TUNNEL_PORT" "value" (toString (int .Values.network.tunnelPort))) }}
|
||||
{{- with .Values.network.publicAddress }}
|
||||
{{- $env = append $env (dict "name" "HALO_NET_PUBLIC_ADDRESS" "value" .) }}
|
||||
{{- end }}
|
||||
{{- with .Values.server.name }}
|
||||
{{- if gt (len .) 15 }}
|
||||
{{- fail "server.name: 15 characters at most" }}
|
||||
{{- end }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_NAME" "value" .) }}
|
||||
{{- end }}
|
||||
{{- with .Values.server.rotation }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_ROTATION" "value" (join ", " .)) }}
|
||||
{{- end }}
|
||||
{{- /* (a value left null is not set, so that config.toml, sv_set and the web page's settings can
|
||||
change it) */}}
|
||||
{{- if not (kindIs "invalid" .Values.server.maxPlayers) }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_MAX_PLAYERS" "value" (toString (int .Values.server.maxPlayers))) }}
|
||||
{{- end }}
|
||||
{{- if not (kindIs "invalid" .Values.server.public) }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_PUBLIC" "value" (toString .Values.server.public)) }}
|
||||
{{- end }}
|
||||
{{- if not (kindIs "invalid" .Values.server.lobbySeconds) }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_LOBBY_SECONDS" "value" (toString (int .Values.server.lobbySeconds))) }}
|
||||
{{- end }}
|
||||
{{- with .Values.server.motd }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_MOTD" "value" .) }}
|
||||
{{- end }}
|
||||
{{- with .Values.server.logFormat }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_LOG_FORMAT" "value" .) }}
|
||||
{{- end }}
|
||||
{{- with .Values.server.instance }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_INSTANCE" "value" .) }}
|
||||
{{- end }}
|
||||
{{- with .Values.server.region }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_REGION" "value" .) }}
|
||||
{{- end }}
|
||||
{{- if not (kindIs "invalid" .Values.server.masterPublish) }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_MASTER_PUBLISH" "value" (toString .Values.server.masterPublish)) }}
|
||||
{{- end }}
|
||||
{{- if .Values.server.password.existingSecret }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_PASSWORD" "valueFrom" (dict "secretKeyRef" (dict "name" .Values.server.password.existingSecret "key" .Values.server.password.key))) }}
|
||||
{{- else if .Values.server.password.value }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_PASSWORD" "valueFrom" (dict "secretKeyRef" (dict "name" $secret "key" .Values.server.password.key))) }}
|
||||
{{- end }}
|
||||
{{- if .Values.publisherKey.existingSecret }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_PUBLISHER_KEY" "valueFrom" (dict "secretKeyRef" (dict "name" .Values.publisherKey.existingSecret "key" .Values.publisherKey.key))) }}
|
||||
{{- else if .Values.publisherKey.value }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_PUBLISHER_KEY" "valueFrom" (dict "secretKeyRef" (dict "name" $secret "key" .Values.publisherKey.key))) }}
|
||||
{{- end }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_WEB_PORT" "value" (toString $webPort)) }}
|
||||
{{- if gt $webPort 0 }}
|
||||
{{- /* (the kubelet's probes reach the pod's own address, not its loopback) */}}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_WEB_BIND" "value" "0.0.0.0") }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_WEB_PASSWORD" "valueFrom" (dict "secretKeyRef" (dict "name" (include "opence-server.webSecret" .) "key" .Values.web.key))) }}
|
||||
{{- if .Values.web.existingSecret }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_WEB_MODERATOR_PASSWORD" "valueFrom" (dict "secretKeyRef" (dict "name" .Values.web.existingSecret "key" .Values.web.moderatorKey "optional" true))) }}
|
||||
{{- else if .Values.web.moderatorPassword }}
|
||||
{{- $env = append $env (dict "name" "HALO_SERVER_WEB_MODERATOR_PASSWORD" "valueFrom" (dict "secretKeyRef" (dict "name" $secret "key" .Values.web.moderatorKey))) }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{- $probe := dict "httpGet" (dict "path" "/healthz" "port" "web") }}
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: {{ $fullname }}
|
||||
labels:
|
||||
{{- include "opence-server.labels" . | nindent 4 }}
|
||||
spec:
|
||||
# One server owns the tunnel port and the address players reach it at.
|
||||
replicas: 1
|
||||
strategy:
|
||||
{{- toYaml .Values.strategy | nindent 4 }}
|
||||
selector:
|
||||
matchLabels:
|
||||
{{- include "opence-server.selectorLabels" . | nindent 6 }}
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
{{- include "opence-server.selectorLabels" . | nindent 8 }}
|
||||
{{- with .Values.podLabels }}
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
{{- with .Values.podAnnotations }}
|
||||
annotations:
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
spec:
|
||||
# The server never calls the Kubernetes API.
|
||||
automountServiceAccountToken: false
|
||||
enableServiceLinks: false
|
||||
{{- with .Values.imagePullSecrets }}
|
||||
imagePullSecrets:
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
{{- with .Values.priorityClassName }}
|
||||
priorityClassName: {{ . }}
|
||||
{{- end }}
|
||||
terminationGracePeriodSeconds: {{ .Values.terminationGracePeriodSeconds }}
|
||||
securityContext:
|
||||
{{- toYaml .Values.podSecurityContext | nindent 8 }}
|
||||
{{- with .Values.nodeSelector }}
|
||||
nodeSelector:
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
{{- with .Values.affinity }}
|
||||
affinity:
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
{{- with .Values.tolerations }}
|
||||
tolerations:
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
containers:
|
||||
- name: opence-server
|
||||
image: {{ include "opence-server.image" . | quote }}
|
||||
imagePullPolicy: {{ .Values.image.pullPolicy }}
|
||||
env:
|
||||
{{- toYaml $env | nindent 12 }}
|
||||
{{- with .Values.extraEnv }}
|
||||
{{- toYaml . | nindent 12 }}
|
||||
{{- end }}
|
||||
ports:
|
||||
- name: tunnel
|
||||
containerPort: {{ .Values.network.tunnelPort }}
|
||||
protocol: UDP
|
||||
{{- if gt $webPort 0 }}
|
||||
- name: web
|
||||
containerPort: {{ $webPort }}
|
||||
protocol: TCP
|
||||
{{- end }}
|
||||
{{- if gt $webPort 0 }}
|
||||
{{- range $name := list "startup" "readiness" "liveness" }}
|
||||
{{- $p := index $.Values.probes $name }}
|
||||
{{- if $p.enabled }}
|
||||
{{ $name }}Probe:
|
||||
{{- toYaml (merge (omit $p "enabled") $probe) | nindent 12 }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
resources:
|
||||
{{- toYaml .Values.resources | nindent 12 }}
|
||||
securityContext:
|
||||
{{- toYaml .Values.securityContext | nindent 12 }}
|
||||
volumeMounts:
|
||||
- name: game-data
|
||||
mountPath: /data
|
||||
readOnly: true
|
||||
{{- with .Values.gameData.subPath }}
|
||||
subPath: {{ . }}
|
||||
{{- end }}
|
||||
# config.toml, publisher.key, the save root and its map cache, the logs
|
||||
- name: state
|
||||
mountPath: /state
|
||||
{{- if include "opence-server.hasCustomMaps" . }}
|
||||
- name: custom-maps
|
||||
mountPath: /custom_maps
|
||||
readOnly: true
|
||||
{{- with .Values.customMaps.subPath }}
|
||||
subPath: {{ . }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
- name: tmp
|
||||
mountPath: /tmp
|
||||
volumes:
|
||||
- name: game-data
|
||||
{{- include "opence-server.volumeSource" .Values.gameData | trim | nindent 10 }}
|
||||
- name: state
|
||||
{{- if .Values.persistence.enabled }}
|
||||
persistentVolumeClaim:
|
||||
claimName: {{ include "opence-server.stateClaim" . }}
|
||||
{{- else }}
|
||||
emptyDir:
|
||||
sizeLimit: {{ .Values.persistence.emptyDirSizeLimit }}
|
||||
{{- end }}
|
||||
- name: tmp
|
||||
emptyDir:
|
||||
sizeLimit: 64Mi
|
||||
{{- if include "opence-server.hasCustomMaps" . }}
|
||||
- name: custom-maps
|
||||
{{- include "opence-server.volumeSource" .Values.customMaps | trim | nindent 10 }}
|
||||
{{- end }}
|
||||
@@ -1,4 +0,0 @@
|
||||
{{- range .Values.extraObjects }}
|
||||
---
|
||||
{{ tpl (toYaml .) $ }}
|
||||
{{- end }}
|
||||
@@ -1,66 +0,0 @@
|
||||
{{- if .Values.networkPolicy.enabled }}
|
||||
{{- $np := .Values.networkPolicy }}
|
||||
# In: the players' UDP on the tunnel port, and the web port from webFrom alone. Out: DNS, TCP to
|
||||
# the MQTT brokers and the master servers, UDP to the internet (STUN, the players' ports); nothing
|
||||
# on the private ranges.
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: NetworkPolicy
|
||||
metadata:
|
||||
name: {{ include "opence-server.fullname" . }}
|
||||
labels:
|
||||
{{- include "opence-server.labels" . | nindent 4 }}
|
||||
spec:
|
||||
podSelector:
|
||||
matchLabels:
|
||||
{{- include "opence-server.selectorLabels" . | nindent 6 }}
|
||||
policyTypes:
|
||||
- Ingress
|
||||
- Egress
|
||||
ingress:
|
||||
- ports:
|
||||
- protocol: UDP
|
||||
port: {{ .Values.network.tunnelPort }}
|
||||
{{- with $np.from }}
|
||||
from:
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
{{- if and $np.webFrom (gt (int .Values.web.port) 0) }}
|
||||
- ports:
|
||||
- protocol: TCP
|
||||
port: {{ .Values.web.port }}
|
||||
from:
|
||||
{{- toYaml $np.webFrom | nindent 8 }}
|
||||
{{- end }}
|
||||
{{- with $np.extraIngress }}
|
||||
{{- toYaml . | nindent 4 }}
|
||||
{{- end }}
|
||||
egress:
|
||||
- to:
|
||||
{{- toYaml $np.dns.to | nindent 8 }}
|
||||
ports:
|
||||
- protocol: UDP
|
||||
port: 53
|
||||
- protocol: TCP
|
||||
port: 53
|
||||
{{- if or $np.internet.tcpPorts $np.internet.udp }}
|
||||
- to:
|
||||
- ipBlock:
|
||||
cidr: {{ $np.internet.cidr }}
|
||||
{{- with $np.internet.except }}
|
||||
except:
|
||||
{{- toYaml . | nindent 14 }}
|
||||
{{- end }}
|
||||
ports:
|
||||
{{- range $np.internet.tcpPorts }}
|
||||
- protocol: TCP
|
||||
port: {{ . }}
|
||||
{{- end }}
|
||||
{{- if $np.internet.udp }}
|
||||
# every UDP port: STUN (19302, 3478) and the players' own
|
||||
- protocol: UDP
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{- with $np.extraEgress }}
|
||||
{{- toYaml . | nindent 4 }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
@@ -1,44 +0,0 @@
|
||||
{{- $data := dict }}
|
||||
{{- if and (gt (int .Values.web.port) 0) (not .Values.web.existingSecret) }}
|
||||
{{- $password := .Values.web.password }}
|
||||
{{- if $password }}
|
||||
{{- if lt (len $password) 8 }}
|
||||
{{- fail "web.password: 8 characters or more (the server refuses a shorter one beyond loopback)" }}
|
||||
{{- end }}
|
||||
{{- else }}
|
||||
{{- /* made once, then kept from the Secret the release already has */}}
|
||||
{{- $existing := lookup "v1" "Secret" .Release.Namespace (include "opence-server.secretName" .) }}
|
||||
{{- if and $existing $existing.data (hasKey $existing.data .Values.web.key) }}
|
||||
{{- $password = index $existing.data .Values.web.key | b64dec }}
|
||||
{{- else }}
|
||||
{{- $password = randAlphaNum 24 }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{- $_ := set $data .Values.web.key ($password | b64enc) }}
|
||||
{{- with .Values.web.moderatorPassword }}
|
||||
{{- if lt (len .) 8 }}
|
||||
{{- fail "web.moderatorPassword: 8 characters or more" }}
|
||||
{{- end }}
|
||||
{{- $_ := set $data $.Values.web.moderatorKey (. | b64enc) }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{- if and .Values.server.password.value (not .Values.server.password.existingSecret) }}
|
||||
{{- $_ := set $data .Values.server.password.key (.Values.server.password.value | b64enc) }}
|
||||
{{- end }}
|
||||
{{- if and .Values.publisherKey.value (not .Values.publisherKey.existingSecret) }}
|
||||
{{- if not (regexMatch "^[0-9a-f]{64}$" .Values.publisherKey.value) }}
|
||||
{{- fail "publisherKey.value: the 64 lower-case hex characters of the seed (halo --server --keygen)" }}
|
||||
{{- end }}
|
||||
{{- $_ := set $data .Values.publisherKey.key (.Values.publisherKey.value | b64enc) }}
|
||||
{{- end }}
|
||||
{{- if $data }}
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: {{ include "opence-server.secretName" . }}
|
||||
labels:
|
||||
{{- include "opence-server.labels" . | nindent 4 }}
|
||||
type: Opaque
|
||||
data:
|
||||
{{- toYaml $data | nindent 2 }}
|
||||
{{- end }}
|
||||
@@ -1,23 +0,0 @@
|
||||
{{- if and .Values.web.service.enabled (gt (int .Values.web.port) 0) }}
|
||||
# The web page, its API and the remote console, inside the cluster only: for an Ingress with TLS,
|
||||
# or kubectl port-forward.
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: {{ include "opence-server.fullname" . }}-web
|
||||
labels:
|
||||
{{- include "opence-server.labels" . | nindent 4 }}
|
||||
{{- with .Values.web.service.annotations }}
|
||||
annotations:
|
||||
{{- toYaml . | nindent 4 }}
|
||||
{{- end }}
|
||||
spec:
|
||||
type: ClusterIP
|
||||
selector:
|
||||
{{- include "opence-server.selectorLabels" . | nindent 4 }}
|
||||
ports:
|
||||
- name: web
|
||||
port: {{ .Values.web.service.port }}
|
||||
targetPort: web
|
||||
protocol: TCP
|
||||
{{- end }}
|
||||
@@ -1,40 +0,0 @@
|
||||
# The tunnel port, UDP: the one port players need.
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: {{ include "opence-server.fullname" . }}
|
||||
labels:
|
||||
{{- include "opence-server.labels" . | nindent 4 }}
|
||||
{{- with .Values.service.labels }}
|
||||
{{- toYaml . | nindent 4 }}
|
||||
{{- end }}
|
||||
{{- with .Values.service.annotations }}
|
||||
annotations:
|
||||
{{- toYaml . | nindent 4 }}
|
||||
{{- end }}
|
||||
spec:
|
||||
type: {{ .Values.service.type }}
|
||||
{{- if ne .Values.service.type "ClusterIP" }}
|
||||
{{- with .Values.service.externalTrafficPolicy }}
|
||||
externalTrafficPolicy: {{ . }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{- if eq .Values.service.type "LoadBalancer" }}
|
||||
{{- with .Values.service.loadBalancerClass }}
|
||||
loadBalancerClass: {{ . }}
|
||||
{{- end }}
|
||||
{{- with .Values.service.loadBalancerSourceRanges }}
|
||||
loadBalancerSourceRanges:
|
||||
{{- toYaml . | nindent 4 }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
selector:
|
||||
{{- include "opence-server.selectorLabels" . | nindent 4 }}
|
||||
ports:
|
||||
- name: tunnel
|
||||
port: {{ .Values.service.port }}
|
||||
targetPort: tunnel
|
||||
protocol: UDP
|
||||
{{- if and (ne .Values.service.type "ClusterIP") .Values.service.nodePort }}
|
||||
nodePort: {{ .Values.service.nodePort }}
|
||||
{{- end }}
|
||||
@@ -1,21 +0,0 @@
|
||||
{{- if and .Values.persistence.enabled (not .Values.persistence.existingClaim) }}
|
||||
apiVersion: v1
|
||||
kind: PersistentVolumeClaim
|
||||
metadata:
|
||||
name: {{ include "opence-server.stateClaim" . }}
|
||||
labels:
|
||||
{{- include "opence-server.labels" . | nindent 4 }}
|
||||
{{- with .Values.persistence.annotations }}
|
||||
annotations:
|
||||
{{- toYaml . | nindent 4 }}
|
||||
{{- end }}
|
||||
spec:
|
||||
accessModes:
|
||||
{{- toYaml .Values.persistence.accessModes | nindent 4 }}
|
||||
{{- with .Values.persistence.storageClass }}
|
||||
storageClassName: {{ . }}
|
||||
{{- end }}
|
||||
resources:
|
||||
requests:
|
||||
storage: {{ .Values.persistence.size }}
|
||||
{{- end }}
|
||||
@@ -1,221 +0,0 @@
|
||||
suite: deployment
|
||||
templates:
|
||||
- templates/deployment.yaml
|
||||
set:
|
||||
gameData.existingClaim: halo-maps
|
||||
tests:
|
||||
- it: refuses to render without game data, which is never in the image
|
||||
set:
|
||||
gameData.existingClaim: ""
|
||||
asserts:
|
||||
- failedTemplate:
|
||||
errorPattern: "gameData: set existingClaim"
|
||||
|
||||
- it: mounts an existing claim read-only at /data
|
||||
asserts:
|
||||
- equal:
|
||||
path: 'spec.template.spec.volumes[0]'
|
||||
value: { name: game-data, persistentVolumeClaim: { claimName: halo-maps, readOnly: true } }
|
||||
- contains:
|
||||
path: 'spec.template.spec.containers[0].volumeMounts'
|
||||
content: { name: game-data, mountPath: /data, readOnly: true }
|
||||
|
||||
- it: mounts an NFS export read-only, with a subPath
|
||||
set:
|
||||
gameData: { existingClaim: "", nfs: { server: nfs.example.com, path: /halo }, subPath: xbox }
|
||||
asserts:
|
||||
- equal:
|
||||
path: 'spec.template.spec.volumes[0]'
|
||||
value: { name: game-data, nfs: { server: nfs.example.com, path: /halo, readOnly: true } }
|
||||
- contains:
|
||||
path: 'spec.template.spec.containers[0].volumeMounts'
|
||||
content: { name: game-data, mountPath: /data, readOnly: true, subPath: xbox }
|
||||
|
||||
- it: takes any other volume source
|
||||
set:
|
||||
gameData: { existingClaim: "", volume: { emptyDir: {} } }
|
||||
asserts:
|
||||
- equal:
|
||||
path: 'spec.template.spec.volumes[0]'
|
||||
value: { name: game-data, emptyDir: {} }
|
||||
|
||||
- it: runs one replica, replaced not rolled, hardened
|
||||
asserts:
|
||||
- equal: { path: spec.replicas, value: 1 }
|
||||
- equal: { path: spec.strategy.type, value: Recreate }
|
||||
- equal: { path: spec.template.spec.automountServiceAccountToken, value: false }
|
||||
- equal: { path: spec.template.spec.securityContext.runAsNonRoot, value: true }
|
||||
- equal: { path: spec.template.spec.securityContext.runAsUser, value: 10001 }
|
||||
- equal: { path: spec.template.spec.securityContext.seccompProfile.type, value: RuntimeDefault }
|
||||
- equal: { path: 'spec.template.spec.containers[0].securityContext.readOnlyRootFilesystem', value: true }
|
||||
- equal: { path: 'spec.template.spec.containers[0].securityContext.allowPrivilegeEscalation', value: false }
|
||||
- equal: { path: 'spec.template.spec.containers[0].securityContext.capabilities.drop', value: [ALL] }
|
||||
- equal: { path: spec.template.spec.nodeSelector, value: { kubernetes.io/os: linux, kubernetes.io/arch: amd64 } }
|
||||
- equal: { path: spec.template.spec.terminationGracePeriodSeconds, value: 15 }
|
||||
- exists: { path: 'spec.template.spec.containers[0].resources.limits.memory' }
|
||||
|
||||
- it: sets the server's paths and mode
|
||||
asserts:
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER, value: "1" } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_CONFIG_FILE, value: /state/config.toml } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_DATA_ROOT, value: /data } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SAVE_ROOT, value: /state/saves } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_LOG_ROOT, value: /state/logs } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_CONSOLE, value: "false" } }
|
||||
|
||||
- it: maps the values to the HALO_ variables
|
||||
set:
|
||||
server:
|
||||
name: Test server
|
||||
rotation: [bloodgulch:ctf, "sidewinder:team_slayer+score=50"]
|
||||
maxPlayers: 24
|
||||
public: false
|
||||
lobbySeconds: 30
|
||||
motd: Hello
|
||||
logFormat: json
|
||||
instance: eu-1
|
||||
region: eu
|
||||
masterPublish: false
|
||||
network: { tunnelPort: 2303, publicAddress: "halo.example.com:2303" }
|
||||
asserts:
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_NAME, value: Test server } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_ROTATION, value: "bloodgulch:ctf, sidewinder:team_slayer+score=50" } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_MAX_PLAYERS, value: "24" } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_PUBLIC, value: "false" } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_LOBBY_SECONDS, value: "30" } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_MOTD, value: Hello } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_LOG_FORMAT, value: json } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_INSTANCE, value: eu-1 } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_REGION, value: eu } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_MASTER_PUBLISH, value: "false" } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_NET_TUNNEL_PORT, value: "2303" } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_NET_PUBLIC_ADDRESS, value: "halo.example.com:2303" } }
|
||||
- equal: { path: 'spec.template.spec.containers[0].ports[0]', value: { name: tunnel, containerPort: 2303, protocol: UDP } }
|
||||
|
||||
- it: leaves empty values to config.toml
|
||||
asserts:
|
||||
- notContains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_NAME, value: "" } }
|
||||
- notContains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_MOTD, value: "" } }
|
||||
- notContains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_NET_PUBLIC_ADDRESS, value: "" } }
|
||||
|
||||
- it: leaves the settings the values do not give to config.toml, sv_set and the web page
|
||||
asserts:
|
||||
- notExists: { path: 'spec.template.spec.containers[0].env[?(@.name == "HALO_SERVER_ROTATION")]' }
|
||||
- notExists: { path: 'spec.template.spec.containers[0].env[?(@.name == "HALO_SERVER_MAX_PLAYERS")]' }
|
||||
- notExists: { path: 'spec.template.spec.containers[0].env[?(@.name == "HALO_SERVER_PUBLIC")]' }
|
||||
- notExists: { path: 'spec.template.spec.containers[0].env[?(@.name == "HALO_SERVER_LOBBY_SECONDS")]' }
|
||||
- notExists: { path: 'spec.template.spec.containers[0].env[?(@.name == "HALO_SERVER_LOG_FORMAT")]' }
|
||||
- notExists: { path: 'spec.template.spec.containers[0].env[?(@.name == "HALO_SERVER_MASTER_PUBLISH")]' }
|
||||
|
||||
- it: sets a false or zero value that is given
|
||||
set:
|
||||
server: { public: false, masterPublish: false, lobbySeconds: 0 }
|
||||
asserts:
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_PUBLIC, value: "false" } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_MASTER_PUBLISH, value: "false" } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_LOBBY_SECONDS, value: "0" } }
|
||||
|
||||
- it: refuses a name longer than the game's 15 characters (the values' schema, or the template)
|
||||
set:
|
||||
server.name: "A name too long!"
|
||||
asserts:
|
||||
- failedTemplate:
|
||||
errorPattern: "server.name|/server/name|15 characters"
|
||||
|
||||
- it: takes the web password from the chart's Secret, bound beyond loopback for the probes
|
||||
release: { name: opence-server }
|
||||
asserts:
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_WEB_PORT, value: "8080" } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_WEB_BIND, value: 0.0.0.0 } }
|
||||
- contains:
|
||||
path: 'spec.template.spec.containers[0].env'
|
||||
content: { name: HALO_SERVER_WEB_PASSWORD, valueFrom: { secretKeyRef: { name: opence-server-secrets, key: web-password } } }
|
||||
- contains: { path: 'spec.template.spec.containers[0].ports', content: { name: web, containerPort: 8080, protocol: TCP } }
|
||||
|
||||
- it: takes the passwords and the publisher key from existing Secrets
|
||||
set:
|
||||
web: { existingSecret: halo-web, key: admin, moderatorKey: moderator }
|
||||
server.password: { existingSecret: halo-join, key: password }
|
||||
publisherKey: { existingSecret: halo-publisher, key: seed }
|
||||
asserts:
|
||||
- contains:
|
||||
path: 'spec.template.spec.containers[0].env'
|
||||
content: { name: HALO_SERVER_WEB_PASSWORD, valueFrom: { secretKeyRef: { name: halo-web, key: admin } } }
|
||||
- contains:
|
||||
path: 'spec.template.spec.containers[0].env'
|
||||
content: { name: HALO_SERVER_WEB_MODERATOR_PASSWORD, valueFrom: { secretKeyRef: { name: halo-web, key: moderator, optional: true } } }
|
||||
- contains:
|
||||
path: 'spec.template.spec.containers[0].env'
|
||||
content: { name: HALO_SERVER_PASSWORD, valueFrom: { secretKeyRef: { name: halo-join, key: password } } }
|
||||
- contains:
|
||||
path: 'spec.template.spec.containers[0].env'
|
||||
content: { name: HALO_SERVER_PUBLISHER_KEY, valueFrom: { secretKeyRef: { name: halo-publisher, key: seed } } }
|
||||
|
||||
- it: probes GET /healthz on the web port
|
||||
asserts:
|
||||
- equal: { path: 'spec.template.spec.containers[0].startupProbe.httpGet', value: { path: /healthz, port: web } }
|
||||
- equal: { path: 'spec.template.spec.containers[0].readinessProbe.httpGet', value: { path: /healthz, port: web } }
|
||||
- equal: { path: 'spec.template.spec.containers[0].livenessProbe.httpGet', value: { path: /healthz, port: web } }
|
||||
- equal: { path: 'spec.template.spec.containers[0].startupProbe.failureThreshold', value: 60 }
|
||||
|
||||
- it: drops a probe that is turned off
|
||||
set:
|
||||
probes.liveness.enabled: false
|
||||
asserts:
|
||||
- notExists: { path: 'spec.template.spec.containers[0].livenessProbe' }
|
||||
- exists: { path: 'spec.template.spec.containers[0].readinessProbe' }
|
||||
|
||||
- it: has no web port, password or probes with web.port 0
|
||||
set:
|
||||
web.port: 0
|
||||
asserts:
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_WEB_PORT, value: "0" } }
|
||||
- notContains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_SERVER_WEB_BIND, value: 0.0.0.0 } }
|
||||
- lengthEqual: { path: 'spec.template.spec.containers[0].ports', count: 1 }
|
||||
- notExists: { path: 'spec.template.spec.containers[0].startupProbe' }
|
||||
- notExists: { path: 'spec.template.spec.containers[0].livenessProbe' }
|
||||
|
||||
- it: puts extraEnv after the chart's variables, so it can override them
|
||||
set:
|
||||
extraEnv: [{ name: HALO_SERVER_LOBBY_SECONDS, value: "5" }]
|
||||
asserts:
|
||||
- equal:
|
||||
path: 'spec.template.spec.containers[0].env[-1:]'
|
||||
value: { name: HALO_SERVER_LOBBY_SECONDS, value: "5" }
|
||||
|
||||
- it: keeps the state in an emptyDir without persistence
|
||||
asserts:
|
||||
- contains: { path: spec.template.spec.volumes, content: { name: state, emptyDir: { sizeLimit: 1Gi } } }
|
||||
- lengthEqual: { path: spec.template.spec.volumes, count: 3 }
|
||||
|
||||
- it: uses the claim with persistence
|
||||
release: { name: opence-server }
|
||||
set:
|
||||
persistence.enabled: true
|
||||
asserts:
|
||||
- contains: { path: spec.template.spec.volumes, content: { name: state, persistentVolumeClaim: { claimName: opence-server-state } } }
|
||||
|
||||
- it: mounts a custom_maps claim read-only, with its variable
|
||||
set:
|
||||
customMaps: { existingClaim: halo-custom-maps, subPath: ce }
|
||||
asserts:
|
||||
- contains: { path: 'spec.template.spec.containers[0].env', content: { name: HALO_CUSTOM_MAPS_ROOT, value: /custom_maps } }
|
||||
- contains:
|
||||
path: spec.template.spec.volumes
|
||||
content: { name: custom-maps, persistentVolumeClaim: { claimName: halo-custom-maps, readOnly: true } }
|
||||
- contains:
|
||||
path: 'spec.template.spec.containers[0].volumeMounts'
|
||||
content: { name: custom-maps, mountPath: /custom_maps, readOnly: true, subPath: ce }
|
||||
|
||||
- it: takes a tag with a digest, and lets digest replace it
|
||||
set:
|
||||
image.tag: build-206@sha256:1111111111111111111111111111111111111111111111111111111111111111
|
||||
image.digest: sha256:2222222222222222222222222222222222222222222222222222222222222222
|
||||
asserts:
|
||||
- equal:
|
||||
path: 'spec.template.spec.containers[0].image'
|
||||
value: ghcr.io/opencommunityedition/opence-server:build-206@sha256:2222222222222222222222222222222222222222222222222222222222222222
|
||||
|
||||
- it: uses the appVersion as the default tag
|
||||
asserts:
|
||||
- equal: { path: 'spec.template.spec.containers[0].image', value: "ghcr.io/opencommunityedition/opence-server:latest" }
|
||||
@@ -1,39 +0,0 @@
|
||||
suite: network policy
|
||||
templates:
|
||||
- templates/networkpolicy.yaml
|
||||
tests:
|
||||
- it: lets anyone reach the tunnel port, and nothing else in
|
||||
asserts:
|
||||
- equal: { path: spec.policyTypes, value: [Ingress, Egress] }
|
||||
- equal: { path: spec.ingress, value: [{ ports: [{ protocol: UDP, port: 2302 }] }] }
|
||||
|
||||
- it: allows DNS, TCP 1883 and 443 and all UDP to public addresses only
|
||||
asserts:
|
||||
- equal: { path: 'spec.egress[0].ports', value: [{ protocol: UDP, port: 53 }, { protocol: TCP, port: 53 }] }
|
||||
- equal: { path: 'spec.egress[1].to[0].ipBlock.cidr', value: 0.0.0.0/0 }
|
||||
- contains: { path: 'spec.egress[1].to[0].ipBlock.except', content: 10.0.0.0/8 }
|
||||
- contains: { path: 'spec.egress[1].to[0].ipBlock.except', content: 192.168.0.0/16 }
|
||||
- equal: { path: 'spec.egress[1].ports', value: [{ protocol: TCP, port: 1883 }, { protocol: TCP, port: 443 }, { protocol: UDP }] }
|
||||
|
||||
- it: lets webFrom reach the web port
|
||||
set:
|
||||
networkPolicy.webFrom: [{ namespaceSelector: { matchLabels: { kubernetes.io/metadata.name: ingress-nginx } } }]
|
||||
asserts:
|
||||
- equal:
|
||||
path: 'spec.ingress[1]'
|
||||
value: { ports: [{ protocol: TCP, port: 8080 }], from: [{ namespaceSelector: { matchLabels: { kubernetes.io/metadata.name: ingress-nginx } } }] }
|
||||
|
||||
- it: narrows the players' sources and follows the tunnel port
|
||||
set:
|
||||
network.tunnelPort: 2303
|
||||
networkPolicy.from: [{ ipBlock: { cidr: 198.51.100.0/24 } }]
|
||||
asserts:
|
||||
- equal:
|
||||
path: spec.ingress
|
||||
value: [{ ports: [{ protocol: UDP, port: 2303 }], from: [{ ipBlock: { cidr: 198.51.100.0/24 } }] }]
|
||||
|
||||
- it: renders nothing when off
|
||||
set:
|
||||
networkPolicy.enabled: false
|
||||
asserts:
|
||||
- hasDocuments: { count: 0 }
|
||||
@@ -1,21 +0,0 @@
|
||||
suite: persistence
|
||||
templates:
|
||||
- templates/state-pvc.yaml
|
||||
release:
|
||||
name: opence-server
|
||||
tests:
|
||||
- it: makes no claim without persistence
|
||||
asserts:
|
||||
- hasDocuments: { count: 0 }
|
||||
- it: makes the state claim with persistence
|
||||
set:
|
||||
persistence: { enabled: true, size: 3Gi, storageClass: fast }
|
||||
asserts:
|
||||
- equal: { path: metadata.name, value: opence-server-state }
|
||||
- equal: { path: spec.resources.requests.storage, value: 3Gi }
|
||||
- equal: { path: spec.storageClassName, value: fast }
|
||||
- it: makes none for an existing claim
|
||||
set:
|
||||
persistence: { enabled: true, existingClaim: mine }
|
||||
asserts:
|
||||
- hasDocuments: { count: 0 }
|
||||
@@ -1,48 +0,0 @@
|
||||
suite: secret
|
||||
templates:
|
||||
- templates/secret.yaml
|
||||
release:
|
||||
name: opence-server
|
||||
tests:
|
||||
- it: makes a web password when none is given
|
||||
asserts:
|
||||
- hasDocuments: { count: 1 }
|
||||
- isKind: { of: Secret }
|
||||
- equal: { path: metadata.name, value: opence-server-secrets }
|
||||
- matchRegex: { path: data.web-password, pattern: "^[A-Za-z0-9+/]{32}$" }
|
||||
|
||||
- it: keeps a given web password, join password and publisher key
|
||||
set:
|
||||
web.password: correct-horse
|
||||
server.password.value: letmein
|
||||
publisherKey.value: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
|
||||
asserts:
|
||||
- equal: { path: data.web-password, value: Y29ycmVjdC1ob3JzZQ== }
|
||||
- equal: { path: data.password, value: bGV0bWVpbg== }
|
||||
- exists: { path: data.publisher-key }
|
||||
|
||||
- it: refuses a short web password
|
||||
set:
|
||||
web.password: short
|
||||
asserts:
|
||||
- failedTemplate:
|
||||
errorPattern: "8 characters or more"
|
||||
|
||||
- it: refuses a publisher key that is not 64 hex characters
|
||||
set:
|
||||
publisherKey.value: not-a-key
|
||||
asserts:
|
||||
- failedTemplate:
|
||||
errorPattern: "64 lower-case hex"
|
||||
|
||||
- it: makes none when every secret comes from elsewhere
|
||||
set:
|
||||
web.existingSecret: halo-web
|
||||
asserts:
|
||||
- hasDocuments: { count: 0 }
|
||||
|
||||
- it: makes none without a web port or secrets
|
||||
set:
|
||||
web.port: 0
|
||||
asserts:
|
||||
- hasDocuments: { count: 0 }
|
||||
@@ -1,43 +0,0 @@
|
||||
suite: service
|
||||
templates:
|
||||
- templates/service.yaml
|
||||
- templates/service-web.yaml
|
||||
release:
|
||||
name: opence-server
|
||||
tests:
|
||||
- it: exposes the tunnel port over UDP on a load balancer that keeps the players' addresses
|
||||
template: templates/service.yaml
|
||||
asserts:
|
||||
- equal: { path: metadata.name, value: opence-server }
|
||||
- equal: { path: spec.type, value: LoadBalancer }
|
||||
- equal: { path: spec.externalTrafficPolicy, value: Local }
|
||||
- equal: { path: 'spec.ports[0]', value: { name: tunnel, port: 2302, targetPort: tunnel, protocol: UDP } }
|
||||
|
||||
- it: ignores externalTrafficPolicy and nodePort on a ClusterIP Service
|
||||
template: templates/service.yaml
|
||||
set:
|
||||
service: { type: ClusterIP, nodePort: 30702 }
|
||||
asserts:
|
||||
- notExists: { path: spec.externalTrafficPolicy }
|
||||
- notExists: { path: 'spec.ports[0].nodePort' }
|
||||
|
||||
- it: sets a fixed node port
|
||||
template: templates/service.yaml
|
||||
set:
|
||||
service: { type: NodePort, nodePort: 30702 }
|
||||
asserts:
|
||||
- equal: { path: 'spec.ports[0].nodePort', value: 30702 }
|
||||
|
||||
- it: keeps the web port inside the cluster
|
||||
template: templates/service-web.yaml
|
||||
asserts:
|
||||
- equal: { path: metadata.name, value: opence-server-web }
|
||||
- equal: { path: spec.type, value: ClusterIP }
|
||||
- equal: { path: 'spec.ports[0]', value: { name: web, port: 8080, targetPort: web, protocol: TCP } }
|
||||
|
||||
- it: has no web Service without a web port
|
||||
template: templates/service-web.yaml
|
||||
set:
|
||||
web.port: 0
|
||||
asserts:
|
||||
- hasDocuments: { count: 0 }
|
||||
@@ -1,445 +0,0 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft-07/schema#",
|
||||
"title": "opence-server values",
|
||||
"description": "Strict where the chart defines the structure; free-form where values pass through to Kubernetes. values.yaml describes each value.",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"definitions": {
|
||||
"port": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 65535
|
||||
},
|
||||
"volume": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"existingClaim": {
|
||||
"type": "string"
|
||||
},
|
||||
"nfs": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"server": {
|
||||
"type": "string"
|
||||
},
|
||||
"path": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"volume": {
|
||||
"type": "object"
|
||||
},
|
||||
"subPath": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"secretValue": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"value": {
|
||||
"type": "string"
|
||||
},
|
||||
"existingSecret": {
|
||||
"type": "string"
|
||||
},
|
||||
"key": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
}
|
||||
}
|
||||
},
|
||||
"probe": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"enabled": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"initialDelaySeconds": {
|
||||
"type": "integer",
|
||||
"minimum": 0
|
||||
},
|
||||
"periodSeconds": {
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
},
|
||||
"timeoutSeconds": {
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
},
|
||||
"failureThreshold": {
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
},
|
||||
"successThreshold": {
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
},
|
||||
"terminationGracePeriodSeconds": {
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"properties": {
|
||||
"global": {
|
||||
"type": "object"
|
||||
},
|
||||
"nameOverride": {
|
||||
"type": "string"
|
||||
},
|
||||
"fullnameOverride": {
|
||||
"type": "string"
|
||||
},
|
||||
"image": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"repository"
|
||||
],
|
||||
"properties": {
|
||||
"repository": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"tag": {
|
||||
"type": [
|
||||
"string",
|
||||
"number"
|
||||
]
|
||||
},
|
||||
"digest": {
|
||||
"type": "string",
|
||||
"pattern": "^(sha256:[0-9a-f]{64})?$"
|
||||
},
|
||||
"pullPolicy": {
|
||||
"enum": [
|
||||
"Always",
|
||||
"IfNotPresent",
|
||||
"Never"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"imagePullSecrets": {
|
||||
"type": "array"
|
||||
},
|
||||
"gameData": {
|
||||
"$ref": "#/definitions/volume"
|
||||
},
|
||||
"customMaps": {
|
||||
"$ref": "#/definitions/volume"
|
||||
},
|
||||
"server": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"maxLength": 15,
|
||||
"pattern": "^[ -~]*$"
|
||||
},
|
||||
"rotation": {
|
||||
"type": "array",
|
||||
"maxItems": 64,
|
||||
"items": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
}
|
||||
},
|
||||
"maxPlayers": {
|
||||
"type": [
|
||||
"integer",
|
||||
"null"
|
||||
],
|
||||
"minimum": 2,
|
||||
"maximum": 127
|
||||
},
|
||||
"public": {
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"lobbySeconds": {
|
||||
"type": [
|
||||
"integer",
|
||||
"null"
|
||||
],
|
||||
"minimum": 0,
|
||||
"maximum": 300
|
||||
},
|
||||
"motd": {
|
||||
"type": "string",
|
||||
"maxLength": 127
|
||||
},
|
||||
"logFormat": {
|
||||
"enum": [
|
||||
"",
|
||||
"text",
|
||||
"json",
|
||||
null
|
||||
]
|
||||
},
|
||||
"instance": {
|
||||
"type": "string",
|
||||
"pattern": "^[A-Za-z0-9_-]{0,32}$"
|
||||
},
|
||||
"region": {
|
||||
"type": "string",
|
||||
"maxLength": 16
|
||||
},
|
||||
"masterPublish": {
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"password": {
|
||||
"$ref": "#/definitions/secretValue"
|
||||
}
|
||||
}
|
||||
},
|
||||
"publisherKey": {
|
||||
"$ref": "#/definitions/secretValue"
|
||||
},
|
||||
"web": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"port": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 65535
|
||||
},
|
||||
"password": {
|
||||
"type": "string"
|
||||
},
|
||||
"existingSecret": {
|
||||
"type": "string"
|
||||
},
|
||||
"key": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"moderatorPassword": {
|
||||
"type": "string"
|
||||
},
|
||||
"moderatorKey": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"service": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"enabled": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"port": {
|
||||
"$ref": "#/definitions/port"
|
||||
},
|
||||
"annotations": {
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"network": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"tunnelPort": {
|
||||
"$ref": "#/definitions/port"
|
||||
},
|
||||
"publicAddress": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"extraEnv": {
|
||||
"type": "array"
|
||||
},
|
||||
"persistence": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"enabled": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"existingClaim": {
|
||||
"type": "string"
|
||||
},
|
||||
"size": {
|
||||
"type": "string"
|
||||
},
|
||||
"storageClass": {
|
||||
"type": "string"
|
||||
},
|
||||
"accessModes": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"annotations": {
|
||||
"type": "object"
|
||||
},
|
||||
"emptyDirSizeLimit": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"service": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"type": {
|
||||
"enum": [
|
||||
"ClusterIP",
|
||||
"NodePort",
|
||||
"LoadBalancer"
|
||||
]
|
||||
},
|
||||
"port": {
|
||||
"$ref": "#/definitions/port"
|
||||
},
|
||||
"nodePort": {
|
||||
"type": [
|
||||
"string",
|
||||
"integer"
|
||||
]
|
||||
},
|
||||
"annotations": {
|
||||
"type": "object"
|
||||
},
|
||||
"labels": {
|
||||
"type": "object"
|
||||
},
|
||||
"externalTrafficPolicy": {
|
||||
"enum": [
|
||||
"",
|
||||
"Cluster",
|
||||
"Local"
|
||||
]
|
||||
},
|
||||
"loadBalancerClass": {
|
||||
"type": "string"
|
||||
},
|
||||
"loadBalancerSourceRanges": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"strategy": {
|
||||
"type": "object"
|
||||
},
|
||||
"resources": {
|
||||
"type": "object"
|
||||
},
|
||||
"nodeSelector": {
|
||||
"type": "object"
|
||||
},
|
||||
"affinity": {
|
||||
"type": "object"
|
||||
},
|
||||
"tolerations": {
|
||||
"type": "array"
|
||||
},
|
||||
"priorityClassName": {
|
||||
"type": "string"
|
||||
},
|
||||
"podAnnotations": {
|
||||
"type": "object"
|
||||
},
|
||||
"podLabels": {
|
||||
"type": "object"
|
||||
},
|
||||
"terminationGracePeriodSeconds": {
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
},
|
||||
"podSecurityContext": {
|
||||
"type": "object"
|
||||
},
|
||||
"securityContext": {
|
||||
"type": "object"
|
||||
},
|
||||
"probes": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"startup": {
|
||||
"$ref": "#/definitions/probe"
|
||||
},
|
||||
"readiness": {
|
||||
"$ref": "#/definitions/probe"
|
||||
},
|
||||
"liveness": {
|
||||
"$ref": "#/definitions/probe"
|
||||
}
|
||||
}
|
||||
},
|
||||
"networkPolicy": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"enabled": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"from": {
|
||||
"type": "array"
|
||||
},
|
||||
"webFrom": {
|
||||
"type": "array"
|
||||
},
|
||||
"dns": {
|
||||
"type": "object"
|
||||
},
|
||||
"internet": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"cidr": {
|
||||
"type": "string"
|
||||
},
|
||||
"except": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"tcpPorts": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/port"
|
||||
}
|
||||
},
|
||||
"udp": {
|
||||
"type": "boolean"
|
||||
}
|
||||
}
|
||||
},
|
||||
"extraIngress": {
|
||||
"type": "array"
|
||||
},
|
||||
"extraEgress": {
|
||||
"type": "array"
|
||||
}
|
||||
}
|
||||
},
|
||||
"extraObjects": {
|
||||
"type": "array"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,239 +0,0 @@
|
||||
# opence-server: the OpenCE dedicated server (docs/dedicated_server.md). One replica: the server
|
||||
# owns its tunnel port and the address players reach it at.
|
||||
|
||||
nameOverride: ""
|
||||
fullnameOverride: ""
|
||||
|
||||
image:
|
||||
repository: ghcr.io/opencommunityedition/opence-server
|
||||
# Empty: the chart's appVersion (latest). A release's tag (build-206) or sha-<commit> pins it;
|
||||
# <tag>@sha256:... as Argo CD Image Updater writes it works too.
|
||||
tag: ""
|
||||
# sha256:... ; replaces any digest in tag.
|
||||
digest: ""
|
||||
pullPolicy: IfNotPresent
|
||||
|
||||
imagePullSecrets: []
|
||||
|
||||
# The game data: the folder that holds maps/ (and custom_maps/, gametypes/ and init.txt if you have
|
||||
# them), from your own copy of the game. It is never in the image. Mounted read-only at /data
|
||||
# (HALO_DATA_ROOT). One source is required.
|
||||
gameData:
|
||||
# An existing PersistentVolumeClaim.
|
||||
existingClaim: ""
|
||||
# Or an NFS export.
|
||||
nfs:
|
||||
server: ""
|
||||
path: ""
|
||||
# Or any other volume source, as in a pod's volumes (without the name), e.g.
|
||||
# {hostPath: {path: /srv/halo, type: Directory}}. Without maps/ui.map and the rotation's maps the
|
||||
# server exits with code 2 and says which maps it looked for, and the pod goes into
|
||||
# CrashLoopBackOff.
|
||||
volume: {}
|
||||
# The folder within the volume that holds maps/. Empty: the volume's root.
|
||||
subPath: ""
|
||||
|
||||
# A custom_maps folder of its own (Custom Edition maps with bitmaps.map, sounds.map and loc.map),
|
||||
# mounted read-only at /custom_maps (HALO_CUSTOM_MAPS_ROOT). Optional: without one the server uses
|
||||
# gameData's custom_maps/.
|
||||
customMaps:
|
||||
existingClaim: ""
|
||||
nfs:
|
||||
server: ""
|
||||
path: ""
|
||||
volume: {}
|
||||
subPath: ""
|
||||
|
||||
# The server's settings, as its HALO_* environment variables (docs/dedicated_server.md and
|
||||
# port/linux/README.md, "Dedicated server"). A value given here wins over config.toml, and sv_set
|
||||
# and the web page's settings cannot change it. Each is unset by default (empty, or null): the
|
||||
# setting is then config.toml's, or the server's default (named below), and can be changed from
|
||||
# the web page.
|
||||
server:
|
||||
# server.name: 15 characters of printable ASCII (default "OpenCE Server").
|
||||
name: ""
|
||||
# server.rotation: map[:gametype[+rule=value...]] entries, played in turn, e.g.
|
||||
# [bloodgulch:ctf, sidewinder:team_slayer, prisoner:slayer] (the default).
|
||||
rotation: []
|
||||
# server.max_players: 2 to 127 (default 16).
|
||||
maxPlayers: null
|
||||
# server.public: list the server in everyone's server browser (default true).
|
||||
public: null
|
||||
# server.lobby_seconds (default 15).
|
||||
lobbySeconds: null
|
||||
# server.motd: a notice each player is shown on joining.
|
||||
motd: ""
|
||||
# server.log_format: text or json (default text).
|
||||
logFormat: ""
|
||||
# server.instance and server.region, as the master servers list them.
|
||||
instance: ""
|
||||
region: ""
|
||||
# server.master_publish: publish the server to the official master servers (needs a publisher
|
||||
# key, below; default true).
|
||||
masterPublish: null
|
||||
# server.password: the password the server browser asks for. value, or a key of an existing
|
||||
# Secret; empty for none.
|
||||
password:
|
||||
value: ""
|
||||
existingSecret: ""
|
||||
key: password
|
||||
|
||||
# The master servers' publisher key (HALO_SERVER_PUBLISHER_KEY): the 64 hex characters of the seed
|
||||
# halo --server --keygen writes. value, or a key of an existing Secret; empty: the state volume's
|
||||
# publisher.key, if there is one.
|
||||
publisherKey:
|
||||
value: ""
|
||||
existingSecret: ""
|
||||
key: publisher-key
|
||||
|
||||
# The web page, its API and the remote console (server.web_port), on which the probes ask
|
||||
# GET /healthz. 0 turns them off, and the probes with them.
|
||||
web:
|
||||
port: 8080
|
||||
# The admin password (server.web_password, 8 characters or more), from existingSecret's key, else
|
||||
# from password, else made at the first install and kept in the chart's Secret. The made one is
|
||||
# found again with lookup on upgrades, which helm template and GitOps tools (Argo CD, Flux's
|
||||
# dry runs) cannot do: they make a new one at each render. Give password or existingSecret
|
||||
# there (README.md, "Web password").
|
||||
password: ""
|
||||
existingSecret: ""
|
||||
key: web-password
|
||||
# server.web_moderator_password, from the same Secret's moderatorKey when it has one.
|
||||
moderatorPassword: ""
|
||||
moderatorKey: web-moderator-password
|
||||
# A ClusterIP Service for the web port, for an Ingress (with TLS) or kubectl port-forward.
|
||||
service:
|
||||
enabled: true
|
||||
port: 8080
|
||||
annotations: {}
|
||||
|
||||
network:
|
||||
# network.tunnel_port: the UDP port of internet play, which the Service exposes.
|
||||
tunnelPort: 2302
|
||||
# network.public_address: host[:port] players reach the tunnel port at, when the cluster is behind
|
||||
# a NAT that STUN cannot see through. Empty: what STUN finds.
|
||||
publicAddress: ""
|
||||
|
||||
# More environment variables, as in a pod spec ({name, value} or {name, valueFrom}); they come after
|
||||
# the chart's, so the same name overrides it.
|
||||
extraEnv: []
|
||||
|
||||
# /state: config.toml (HALO_CONFIG_FILE), publisher.key, the save root with its map cache (about
|
||||
# 115 MB for the multiplayer maps), the logs. Without persistence an emptyDir: the cache is built
|
||||
# again at each start, and settings changed from the web page are lost.
|
||||
persistence:
|
||||
enabled: false
|
||||
existingClaim: ""
|
||||
size: 2Gi
|
||||
storageClass: ""
|
||||
accessModes:
|
||||
- ReadWriteOnce
|
||||
annotations: {}
|
||||
emptyDirSizeLimit: 1Gi
|
||||
|
||||
# The tunnel port's Service. Players reach it from outside the cluster, so a real deployment needs
|
||||
# LoadBalancer or NodePort.
|
||||
service:
|
||||
type: LoadBalancer
|
||||
port: 2302
|
||||
nodePort: ""
|
||||
annotations: {}
|
||||
labels: {}
|
||||
# Local keeps the players' own addresses (no SNAT to a node), which bans and the server's limits
|
||||
# rely on.
|
||||
externalTrafficPolicy: Local
|
||||
loadBalancerClass: ""
|
||||
loadBalancerSourceRanges: []
|
||||
|
||||
strategy:
|
||||
type: Recreate
|
||||
|
||||
resources:
|
||||
requests:
|
||||
cpu: 100m
|
||||
memory: 192Mi
|
||||
limits:
|
||||
memory: 600Mi
|
||||
|
||||
# The image is 32-bit x86 Linux code, which runs on amd64 nodes only.
|
||||
nodeSelector:
|
||||
kubernetes.io/os: linux
|
||||
kubernetes.io/arch: amd64
|
||||
affinity: {}
|
||||
tolerations: []
|
||||
priorityClassName: ""
|
||||
|
||||
podAnnotations: {}
|
||||
podLabels: {}
|
||||
|
||||
# SIGTERM ends the game in progress, tells the players and exits 0; a second signal, or 5 seconds
|
||||
# on, exits at once.
|
||||
terminationGracePeriodSeconds: 15
|
||||
|
||||
podSecurityContext:
|
||||
runAsNonRoot: true
|
||||
runAsUser: 10001
|
||||
runAsGroup: 10001
|
||||
fsGroup: 10001
|
||||
seccompProfile:
|
||||
type: RuntimeDefault
|
||||
|
||||
securityContext:
|
||||
allowPrivilegeEscalation: false
|
||||
readOnlyRootFilesystem: true
|
||||
capabilities:
|
||||
drop: ["ALL"]
|
||||
|
||||
# GET /healthz on the web port: 200 while the server hosts (lobby, loading, playing, postgame) and
|
||||
# its frames run. Each probe's fields override these; enabled: false drops it.
|
||||
probes:
|
||||
startup:
|
||||
enabled: true
|
||||
periodSeconds: 2
|
||||
failureThreshold: 60
|
||||
timeoutSeconds: 2
|
||||
readiness:
|
||||
enabled: true
|
||||
periodSeconds: 10
|
||||
failureThreshold: 3
|
||||
timeoutSeconds: 2
|
||||
liveness:
|
||||
enabled: true
|
||||
periodSeconds: 20
|
||||
failureThreshold: 3
|
||||
timeoutSeconds: 3
|
||||
|
||||
networkPolicy:
|
||||
enabled: true
|
||||
# Who may reach the tunnel port. Empty: anyone (players are on the internet).
|
||||
from: []
|
||||
# Who may reach the web port, as NetworkPolicy peers (an Ingress controller's namespace, say).
|
||||
# Empty: no pod; kubectl port-forward and the kubelet's probes still reach it.
|
||||
webFrom: []
|
||||
dns:
|
||||
to:
|
||||
- namespaceSelector:
|
||||
matchLabels:
|
||||
kubernetes.io/metadata.name: kube-system
|
||||
podSelector:
|
||||
matchLabels:
|
||||
k8s-app: kube-dns
|
||||
# The internet: TCP to the MQTT brokers (1883) and the master servers (443), and UDP to anywhere
|
||||
# (STUN, and the players' own ports). The private ranges are excepted.
|
||||
internet:
|
||||
cidr: 0.0.0.0/0
|
||||
except:
|
||||
- 10.0.0.0/8
|
||||
- 172.16.0.0/12
|
||||
- 192.168.0.0/16
|
||||
- 100.64.0.0/10
|
||||
- 169.254.0.0/16
|
||||
tcpPorts:
|
||||
- 1883
|
||||
- 443
|
||||
udp: true
|
||||
extraIngress: []
|
||||
extraEgress: []
|
||||
|
||||
# More objects to render with the release (templated).
|
||||
extraObjects: []
|
||||
@@ -1,31 +0,0 @@
|
||||
# init.txt: commands a dedicated server runs once at its start, one a line,
|
||||
# as if typed at its console (docs/dedicated_server.md, "Commands"). Copy
|
||||
# this file to init.txt in the data folder (server.init_file), and take the
|
||||
# "# " off the lines you want. Lines starting with # or ; are comments.
|
||||
#
|
||||
# Settings are better given in config.toml or as HALO_* variables; these are
|
||||
# for what changes from one start to the next.
|
||||
|
||||
# The rotation, replacing server.rotation (and written to it):
|
||||
# sv_rotation_set bloodgulch:ctf, sidewinder:team_slayer+score=50, hangemhigh:king_moving
|
||||
# sv_rotation_add prisoner:slayer+time=10
|
||||
# sv_rotation_begin 2
|
||||
|
||||
# The game's name, players and notice (sv_set of the server.* settings):
|
||||
# sv_name My server
|
||||
# sv_maxplayers 12
|
||||
# sv_motd Welcome. Be nice; admins are watching.
|
||||
# sv_public 1
|
||||
# sv_password secret
|
||||
|
||||
# Any setting the server lists in sv_settings:
|
||||
# sv_set server.lobby_seconds 20
|
||||
# sv_set server.empty_seconds 60
|
||||
|
||||
# A first game other than the rotation's, which goes on after it:
|
||||
# sv_map bloodgulch ctf_classic
|
||||
|
||||
# The state of the server, in the log:
|
||||
# sv_status
|
||||
|
||||
# The game's own console commands run too, with the owner's role.
|
||||
@@ -1,40 +0,0 @@
|
||||
# The dedicated server on MCSManager
|
||||
|
||||
`mcsmanager-config.json` holds two MCSManager quick-install entries for the
|
||||
dedicated server (`docs/dedicated_server.md`). Each unzips a release's
|
||||
`halo-linux-release.zip` into the instance's folder and runs
|
||||
`./halo --server` there, stopped with `quit`.
|
||||
|
||||
| Entry | How it runs |
|
||||
| --- | --- |
|
||||
| Host | On the node itself, which needs the 32-bit C runtime (Debian and Ubuntu: `dpkg --add-architecture i386 && apt install libc6:i386`) |
|
||||
| Docker | In a container of `ghcr.io/ptero-eggs/games:source` (Debian 12 with the 32-bit libraries), the instance's folder mounted at `/workspace` |
|
||||
|
||||
## Using it
|
||||
|
||||
1. Add the entries to the node's quick-install list, and create an
|
||||
instance from one.
|
||||
2. Upload the `maps/` folder of your own copy of the game into the
|
||||
instance's folder. Without `maps/ui.map` and the rotation's maps the
|
||||
server exits with code 2 and says which maps it looked for.
|
||||
3. Start it.
|
||||
|
||||
## Folders
|
||||
|
||||
The Docker entry's container is made again at each start, so it sets
|
||||
`HALO_SAVE_ROOT=/workspace/saves` and `HALO_LOG_ROOT=/workspace/logs`: the
|
||||
save root with the map cache (about 115 MB, built at the first start) and
|
||||
the logs stay in the instance's folder rather than in the container. The
|
||||
host entry keeps the save root in the home folder of the daemon's user
|
||||
(`~/.local/share/halo-linux`), which every host instance of that user
|
||||
shares; give each its own with
|
||||
`HALO_SAVE_ROOT=saves` (in the instance's environment, or as
|
||||
`env HALO_SAVE_ROOT=saves ./halo --server` for its start command).
|
||||
`config.toml` is written beside `halo` at the first start.
|
||||
|
||||
## Ports
|
||||
|
||||
UDP 2302 is the tunnel port, the one players need; the web page, its API
|
||||
and the remote console are on 127.0.0.1:8080. A second instance on the node
|
||||
needs ports of its own: `HALO_NET_TUNNEL_PORT` and `HALO_SERVER_WEB_PORT`,
|
||||
and for the Docker entry its published ports to match.
|
||||
@@ -1,139 +0,0 @@
|
||||
{
|
||||
"_comment": "MCSManager quick-install entries for the OpenCE dedicated server (docs/dedicated_server.md). Each package unzips the release into the instance's folder; put the maps/ folder of your own copy of the game beside halo before the first start. Settings: config.toml beside halo, written at the first start, or HALO_* variables.",
|
||||
"languages": [
|
||||
{
|
||||
"label": "English",
|
||||
"value": "en_us"
|
||||
}
|
||||
],
|
||||
"packages": [
|
||||
{
|
||||
"language": "en_us",
|
||||
"platform": "Linux",
|
||||
"title": "OpenCE Dedicated Server",
|
||||
"category": "Halo: Combat Evolved",
|
||||
"runtime": "Linux x86-64 with 32-bit libraries",
|
||||
"hardware": "1 CPU core, 600 MB of memory",
|
||||
"size": "45 MB, and the game data you upload",
|
||||
"author": "OpenCE",
|
||||
"targetLink": "https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-linux-release.zip",
|
||||
"description": "The dedicated server run on the node itself, which needs the 32-bit C runtime (Debian and Ubuntu: dpkg --add-architecture i386 && apt install libc6:i386). Open UDP 2302; the web page is on http://127.0.0.1:8080/.",
|
||||
"remark": "Host",
|
||||
"setupInfo": {
|
||||
"nickname": "OpenCE Dedicated Server",
|
||||
"startCommand": "./halo --server",
|
||||
"stopCommand": "quit",
|
||||
"ie": "utf-8",
|
||||
"oe": "utf-8",
|
||||
"type": "universal",
|
||||
"tag": [
|
||||
"halo",
|
||||
"opence"
|
||||
],
|
||||
"processType": "general",
|
||||
"updateCommand": "",
|
||||
"crlf": 1,
|
||||
"actionCommandList": [
|
||||
{
|
||||
"name": "Status",
|
||||
"command": "sv_status"
|
||||
},
|
||||
{
|
||||
"name": "Players",
|
||||
"command": "sv_players"
|
||||
},
|
||||
{
|
||||
"name": "Next map",
|
||||
"command": "sv_map_next"
|
||||
},
|
||||
{
|
||||
"name": "Reload settings",
|
||||
"command": "sv_reload"
|
||||
}
|
||||
],
|
||||
"eventTask": {
|
||||
"autoStart": false,
|
||||
"autoRestart": true,
|
||||
"ignore": false
|
||||
},
|
||||
"terminalOption": {
|
||||
"haveColor": false,
|
||||
"pty": false
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"language": "en_us",
|
||||
"platform": "Linux",
|
||||
"title": "OpenCE Dedicated Server",
|
||||
"category": "Halo: Combat Evolved",
|
||||
"runtime": "Linux x86-64 with 32-bit libraries",
|
||||
"hardware": "1 CPU core, 600 MB of memory",
|
||||
"size": "45 MB, and the game data you upload",
|
||||
"author": "OpenCE",
|
||||
"targetLink": "https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-linux-release.zip",
|
||||
"description": "The dedicated server in a container of ghcr.io/ptero-eggs/games:source (Debian 12 with the 32-bit libraries), the instance's folder mounted as its working folder; the save root (with the map cache) and the logs are kept in it, as the container is made again at each start. Publishes UDP 2302 and the web page on the node's 127.0.0.1:8080 (each instance on a node needs ports of its own).",
|
||||
"remark": "Docker",
|
||||
"setupInfo": {
|
||||
"nickname": "OpenCE Dedicated Server",
|
||||
"startCommand": "./halo --server",
|
||||
"stopCommand": "quit",
|
||||
"ie": "utf-8",
|
||||
"oe": "utf-8",
|
||||
"type": "universal",
|
||||
"tag": [
|
||||
"halo",
|
||||
"opence"
|
||||
],
|
||||
"processType": "docker",
|
||||
"updateCommand": "",
|
||||
"crlf": 1,
|
||||
"actionCommandList": [
|
||||
{
|
||||
"name": "Status",
|
||||
"command": "sv_status"
|
||||
},
|
||||
{
|
||||
"name": "Players",
|
||||
"command": "sv_players"
|
||||
},
|
||||
{
|
||||
"name": "Next map",
|
||||
"command": "sv_map_next"
|
||||
},
|
||||
{
|
||||
"name": "Reload settings",
|
||||
"command": "sv_reload"
|
||||
}
|
||||
],
|
||||
"eventTask": {
|
||||
"autoStart": false,
|
||||
"autoRestart": true,
|
||||
"ignore": false
|
||||
},
|
||||
"terminalOption": {
|
||||
"haveColor": false,
|
||||
"pty": false
|
||||
},
|
||||
"docker": {
|
||||
"image": "ghcr.io/ptero-eggs/games:source",
|
||||
"ports": [
|
||||
"2302:2302/udp",
|
||||
"127.0.0.1:8080:8080/tcp"
|
||||
],
|
||||
"extraVolumes": [],
|
||||
"networkMode": "bridge",
|
||||
"networkAliases": [],
|
||||
"env": [
|
||||
"HALO_SERVER_WEB_BIND=0.0.0.0",
|
||||
"HALO_SAVE_ROOT=/workspace/saves",
|
||||
"HALO_LOG_ROOT=/workspace/logs"
|
||||
],
|
||||
"memory": 600,
|
||||
"workingDir": "/workspace/",
|
||||
"changeWorkdir": true
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,94 +0,0 @@
|
||||
# The dedicated server on Pterodactyl and Pelican
|
||||
|
||||
`egg-opence-dedicated-server.json` is an egg (`PTDL_v2`) that installs a
|
||||
release of OpenCE from GitHub and runs it as a dedicated server
|
||||
(`docs/dedicated_server.md`). Pelican imports the same file.
|
||||
|
||||
## Importing it
|
||||
|
||||
1. Admin > Nests (Pelican: Eggs) > Import Egg, and choose the file.
|
||||
2. Create a server with the egg. Its primary allocation is the tunnel port
|
||||
(`network.tunnel_port`, UDP): the one port players need, from 1025 up
|
||||
(the container cannot bind lower ports).
|
||||
3. Upload the game data: the `maps/` folder of your own copy of the game
|
||||
(port/linux/README.md, "Game data"), into the server's folder over SFTP
|
||||
(the panel's SFTP details, on the Settings tab). Without `maps/ui.map`
|
||||
and the rotation's maps the server stops at once with exit code 2 and
|
||||
says which maps it looked for.
|
||||
4. Start it. The panel shows it running once it prints its ready line
|
||||
(`server: ready`, or `"msg":"ready (` with `server.log_format = "json"`).
|
||||
|
||||
## Files
|
||||
|
||||
| Path (in `/home/container`) | What |
|
||||
| --- | --- |
|
||||
| `halo`, `halo-server`, `libSDL3.so.0`, `brokers.txt`, `masters.txt`, the licences | The release (replaced on Reinstall) |
|
||||
| `maps/` | The game data (yours) |
|
||||
| `custom_maps/` | Custom Edition maps, with `bitmaps.map`, `sounds.map` and `loc.map` (shared with players who join) |
|
||||
| `gametypes/*.toml` | Gametypes of your own (the release adds examples, never replacing yours) |
|
||||
| `init.txt` | Commands run at each start (`init.txt.example` has examples) |
|
||||
| `config.toml` | Every setting, written at the first start |
|
||||
| `publisher.key` | The master servers' key: made by `./halo --server --keygen` on any machine with the release and uploaded, or given as the Publisher key variable instead |
|
||||
| `logs/` | `debug.txt`, `bans.txt`, `cheaters.txt` |
|
||||
|
||||
Reinstall (Settings tab) downloads the release again, the one the Release
|
||||
variable names, and keeps `config.toml`, `init.txt`, `publisher.key`,
|
||||
`gametypes/`, `custom_maps/`, `maps/` and `logs/`.
|
||||
|
||||
## Variables
|
||||
|
||||
Every variable is one of the server's settings, by its environment name
|
||||
(docs/dedicated_server.md and port/linux/README.md, "Dedicated server"). A
|
||||
variable wins over `config.toml`, and the web page's settings cannot
|
||||
change it.
|
||||
|
||||
| Variable | Setting |
|
||||
| --- | --- |
|
||||
| Release (`OPENCE_RELEASE`) | `latest` or a tag (`build-206`); used by Reinstall |
|
||||
| Server name (`HALO_SERVER_NAME`) | `server.name`, 15 characters |
|
||||
| Rotation (`HALO_SERVER_ROTATION`) | `server.rotation` |
|
||||
| Max players (`HALO_SERVER_MAX_PLAYERS`) | `server.max_players` |
|
||||
| Join password (`HALO_SERVER_PASSWORD`) | `server.password` |
|
||||
| Public (`HALO_SERVER_PUBLIC`) | `server.public` |
|
||||
| Message of the day (`HALO_SERVER_MOTD`) | `server.motd` |
|
||||
| Lobby seconds (`HALO_SERVER_LOBBY_SECONDS`) | `server.lobby_seconds` |
|
||||
| Web UI port (`HALO_SERVER_WEB_PORT`) | `server.web_port`; 0 for none |
|
||||
| Web UI password (`HALO_SERVER_WEB_PASSWORD`) | `server.web_password` |
|
||||
| Public address (`HALO_NET_PUBLIC_ADDRESS`) | `network.public_address` |
|
||||
| Publisher key (`HALO_SERVER_PUBLISHER_KEY`) | The master servers' key itself, in place of `publisher.key` |
|
||||
| Instance name (`HALO_SERVER_INSTANCE`) | `server.instance` |
|
||||
| Region (`HALO_SERVER_REGION`) | `server.region` |
|
||||
| Log format (`HALO_SERVER_LOG_FORMAT`) | `server.log_format` |
|
||||
|
||||
The startup command sets `HALO_NET_TUNNEL_PORT` to the primary allocation's
|
||||
port and `HALO_LOG_ROOT` to `logs/`. Two variables are the administrator's
|
||||
only: Web UI bind (`0.0.0.0`, as the allocation's address is the node's,
|
||||
not the container's) and GitHub repository (`OpenCommunityEdition/OpenCE`).
|
||||
|
||||
## The web page
|
||||
|
||||
The admin page, its API and the remote console need a second allocation:
|
||||
the node's administrator adds one to the server (or raises its allocation
|
||||
limit so the owner can, on the Network tab). Give its port as Web UI port
|
||||
and a password of 8 characters or more as Web UI password, restart, and
|
||||
open `http://<allocation address>:<port>/`. The page has no TLS of its own:
|
||||
put it behind a reverse proxy with HTTPS for anything but a private network.
|
||||
|
||||
## Stopping and restarting
|
||||
|
||||
The panel's Stop sends SIGINT, which the server takes as SIGTERM: the game
|
||||
in progress goes to its postgame, the players are told, the listing is
|
||||
withdrawn, and it exits 0. The console's `quit` command does the same, but
|
||||
Wings counts an exit it did not ask for as a crash and starts the server
|
||||
again; use Stop. `sv_restart` exits with code 5, which Wings also takes as a
|
||||
crash and restarts, which is what it asks for.
|
||||
|
||||
Updates: `server.auto_update` is for servers that own their files; on a
|
||||
panel, change the Release variable (or keep `latest`) and Reinstall, by hand
|
||||
or as a schedule.
|
||||
|
||||
## Checking the egg
|
||||
|
||||
`python tools/egg_build.py` copies `install.sh` into the egg and checks it;
|
||||
`python -m pytest -q tools/test_egg.py` checks the egg and runs `install.sh`
|
||||
in a `debian:bookworm-slim` container against a release served locally.
|
||||
@@ -1,203 +0,0 @@
|
||||
{
|
||||
"_comment": "DO NOT EDIT: FILE GENERATED AUTOMATICALLY BY PTERODACTYL PANEL - PTERODACTYL.IO",
|
||||
"meta": {
|
||||
"version": "PTDL_v2",
|
||||
"update_url": null
|
||||
},
|
||||
"exported_at": "2026-10-24T00:00:00+00:00",
|
||||
"name": "OpenCE Dedicated Server",
|
||||
"author": "opence@halocombatevolved.com",
|
||||
"description": "A dedicated server of OpenCE, the port of Halo: Combat Evolved: hosts multiplayer games one after another, with no window, sound or player of its own. Installs a release from GitHub. The game data is yours to upload: put the maps/ folder of your own copy of the game in the server's folder over SFTP; the server does not start without it.",
|
||||
"features": [],
|
||||
"docker_images": {
|
||||
"Debian 12 with 32-bit libraries (Pterodactyl)": "ghcr.io/ptero-eggs/games:source",
|
||||
"Debian 12 with 32-bit libraries (Pelican)": "ghcr.io/pelican-eggs/games:source"
|
||||
},
|
||||
"file_denylist": [],
|
||||
"startup": "HALO_NET_TUNNEL_PORT={{SERVER_PORT}} HALO_LOG_ROOT=/home/container/logs ./halo --server",
|
||||
"config": {
|
||||
"files": "{}",
|
||||
"startup": "{\r\n \"done\": [\r\n \"server: ready\",\r\n \"\\\"msg\\\":\\\"ready (\"\r\n ]\r\n}",
|
||||
"logs": "{}",
|
||||
"stop": "^C"
|
||||
},
|
||||
"scripts": {
|
||||
"installation": {
|
||||
"script": "#!/bin/bash\n# The OpenCE dedicated server egg's installation script (Pterodactyl and\n# Pelican), run as root in ghcr.io/ptero-eggs/installers:debian with the\n# server's folder at /mnt/server. tools/egg_build.py copies it into\n# egg-opence-dedicated-server.json.\n#\n# OPENCE_RELEASE: \"latest\" or a release tag (build-206).\n# OPENCE_REPOSITORY: the GitHub repository (owner/name) to download from.\n#\n# A reinstall replaces the release's files and keeps the owner's:\n# config.toml, init.txt, publisher.key, gametypes/, custom_maps/, maps/ and\n# logs/. The panel ignores this script's exit code, so each failure says\n# what went wrong.\n\nset -u\n\nSERVER_DIR=\"${SERVER_DIR:-/mnt/server}\"\nRELEASE=\"${OPENCE_RELEASE:-latest}\"\nREPOSITORY=\"${OPENCE_REPOSITORY:-OpenCommunityEdition/OpenCE}\"\nGITHUB_URL=\"${OPENCE_GITHUB_URL:-https://github.com}\"\nGITHUB_API=\"${OPENCE_GITHUB_API:-https://api.github.com}\"\nASSET=halo-linux-release.zip\n\nfail() {\n\techo \"INSTALL FAILED: $*\"\n\texit 1\n}\n\nif ! [[ \"$REPOSITORY\" =~ ^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$ ]]; then\n\tfail \"the repository \\\"$REPOSITORY\\\" is not owner/name\"\nfi\nif [ -z \"$RELEASE\" ] || [ \"$RELEASE\" = latest ]; then\n\t# (no API call, so no rate limit)\n\turl=\"$GITHUB_URL/$REPOSITORY/releases/latest/download/$ASSET\"\nelse\n\tif ! [[ \"$RELEASE\" =~ ^[A-Za-z0-9._-]+$ ]]; then\n\t\tfail \"the release \\\"$RELEASE\\\" is not a tag name (build-206) or latest\"\n\tfi\n\techo \"Looking up release $RELEASE of $REPOSITORY\"\n\trelease_json=\"$(curl -fsSL --retry 3 -H 'Accept: application/vnd.github+json' \\\n\t\t\"$GITHUB_API/repos/$REPOSITORY/releases/tags/$RELEASE\")\" \\\n\t\t|| fail \"no release $RELEASE in $REPOSITORY (or GitHub's API did not answer)\"\n\turl=\"$(printf '%s' \"$release_json\" | jq -r --arg name \"$ASSET\" \\\n\t\t'[.assets[]? | select(.name == $name) | .browser_download_url][0] // empty')\"\n\t[ -n \"$url\" ] || fail \"release $RELEASE has no $ASSET\"\nfi\n\nmkdir -p \"$SERVER_DIR\" || fail \"cannot make $SERVER_DIR\"\ncd \"$SERVER_DIR\" || fail \"cannot enter $SERVER_DIR\"\n\nwork=\"$(mktemp -d)\" || fail \"cannot make a temporary folder\"\ntrap 'rm -rf \"$work\"' EXIT\n\necho \"Downloading $url\"\ncurl -fL --retry 3 --progress-bar -o \"$work/$ASSET\" \"$url\" || fail \"the download of $url failed\"\nunzip -tq \"$work/$ASSET\" > /dev/null || fail \"$ASSET is not a zip file\"\nmkdir \"$work/release\"\nunzip -q \"$work/$ASSET\" -d \"$work/release\" || fail \"cannot unzip $ASSET\"\n[ -f \"$work/release/halo\" ] || fail \"$ASSET has no halo executable\"\n\n# the release's files, over the old release's; the owner's are never in it,\n# and gametypes/ only adds the examples not already there\nfor entry in \"$work/release\"/* \"$work/release\"/.[!.]*; do\n\t[ -e \"$entry\" ] || continue\n\tname=\"$(basename \"$entry\")\"\n\tcase \"$name\" in\n\tconfig.toml | init.txt | publisher.key | custom_maps | maps | logs)\n\t\tcontinue\n\t\t;;\n\tgametypes)\n\t\tmkdir -p gametypes\n\t\tcp -rn \"$entry\"/. gametypes/\n\t\tcontinue\n\t\t;;\n\tesac\n\trm -rf \"./$name\"\n\tcp -a \"$entry\" \"./$name\" || fail \"cannot copy $name\"\ndone\n\nchmod 0755 halo\nif [ ! -f halo-server ]; then\n\tprintf '#!/bin/sh\\nexec \"$(dirname \"$0\")/halo\" --server \"$@\"\\n' > halo-server\nfi\nchmod 0755 halo-server\nmkdir -p maps custom_maps gametypes logs\n\necho \"Checking that the server runs\"\nif version=\"$(HOME=\"$work\" HALO_SAVE_ROOT=\"$work/saves\" timeout 30 ./halo --version 2>&1)\"; then\n\techo \"$version\"\nelse\n\techo \"WARNING: ./halo --version did not run. The server needs the 32-bit C runtime\"\n\techo \"WARNING: (the egg's ghcr.io/ptero-eggs/games:source image has it):\"\n\techo \"$version\"\nfi\n\nif [ ! -f maps/ui.map ]; then\n\techo \"No game data yet: upload your maps/ folder (ui.map and the multiplayer maps)\"\n\techo \"over SFTP into the server's folder before starting it.\"\nfi\necho \"Installation completed\"\n",
|
||||
"container": "ghcr.io/ptero-eggs/installers:debian",
|
||||
"entrypoint": "bash"
|
||||
}
|
||||
},
|
||||
"variables": [
|
||||
{
|
||||
"name": "Release",
|
||||
"description": "A release tag (build-206) or latest. A change takes effect on Reinstall (Settings tab), which keeps config.toml, init.txt, gametypes/, custom_maps/ and maps/.",
|
||||
"env_variable": "OPENCE_RELEASE",
|
||||
"default_value": "latest",
|
||||
"user_viewable": true,
|
||||
"user_editable": true,
|
||||
"rules": "required|string|max:40|regex:/^[A-Za-z0-9._-]+$/",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "Server name",
|
||||
"description": "The game's name in the lobby and the server browser: 15 characters of printable ASCII.",
|
||||
"env_variable": "HALO_SERVER_NAME",
|
||||
"default_value": "OpenCE Server",
|
||||
"user_viewable": true,
|
||||
"user_editable": true,
|
||||
"rules": "required|string|max:15|regex:/^[\\x20-\\x7E]+$/",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "Rotation",
|
||||
"description": "The games played one after another, separated by commas: map:gametype, with +rule=value after a gametype (bloodgulch:ctf, sidewinder:team_slayer+score=50). A gametype is a built-in's name or a gametypes/<name>.toml of yours.",
|
||||
"env_variable": "HALO_SERVER_ROTATION",
|
||||
"default_value": "bloodgulch:ctf, sidewinder:team_slayer, prisoner:slayer",
|
||||
"user_viewable": true,
|
||||
"user_editable": true,
|
||||
"rules": "required|string|max:4096",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "Max players",
|
||||
"description": "2 to 127.",
|
||||
"env_variable": "HALO_SERVER_MAX_PLAYERS",
|
||||
"default_value": "16",
|
||||
"user_viewable": true,
|
||||
"user_editable": true,
|
||||
"rules": "required|integer|between:2,127",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "Join password",
|
||||
"description": "The password the server browser asks for; empty for none. The invite link joins without it.",
|
||||
"env_variable": "HALO_SERVER_PASSWORD",
|
||||
"default_value": "",
|
||||
"user_viewable": true,
|
||||
"user_editable": true,
|
||||
"rules": "nullable|string|max:64",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "Public",
|
||||
"description": "List the server in everyone's server browser.",
|
||||
"env_variable": "HALO_SERVER_PUBLIC",
|
||||
"default_value": "true",
|
||||
"user_viewable": true,
|
||||
"user_editable": true,
|
||||
"rules": "required|string|in:true,false",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "Message of the day",
|
||||
"description": "A notice each player is shown on joining (127 characters); empty for none.",
|
||||
"env_variable": "HALO_SERVER_MOTD",
|
||||
"default_value": "",
|
||||
"user_viewable": true,
|
||||
"user_editable": true,
|
||||
"rules": "nullable|string|max:127",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "Lobby seconds",
|
||||
"description": "Seconds the lobby counts down before each game (0 to 300).",
|
||||
"env_variable": "HALO_SERVER_LOBBY_SECONDS",
|
||||
"default_value": "15",
|
||||
"user_viewable": true,
|
||||
"user_editable": true,
|
||||
"rules": "required|integer|between:0,300",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "Web UI port",
|
||||
"description": "0: no web page. Else the port of an additional allocation (Network tab) for the admin page, its API and the remote console, at http://<allocation address>:<port>/; it needs a web UI password.",
|
||||
"env_variable": "HALO_SERVER_WEB_PORT",
|
||||
"default_value": "0",
|
||||
"user_viewable": true,
|
||||
"user_editable": true,
|
||||
"rules": "required|integer|between:0,65535",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "Web UI password",
|
||||
"description": "The admin password of the web page, 8 characters or more.",
|
||||
"env_variable": "HALO_SERVER_WEB_PASSWORD",
|
||||
"default_value": "",
|
||||
"user_viewable": true,
|
||||
"user_editable": true,
|
||||
"rules": "nullable|string|min:8|max:64",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "Public address",
|
||||
"description": "host[:port] offered to joiners first, for a node behind a NAT that STUN cannot see through; usually empty.",
|
||||
"env_variable": "HALO_NET_PUBLIC_ADDRESS",
|
||||
"default_value": "",
|
||||
"user_viewable": true,
|
||||
"user_editable": true,
|
||||
"rules": "nullable|string|max:253",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "Publisher key",
|
||||
"description": "Your approved key for the master servers that list dedicated servers: the 64 hex characters of the seed ./halo --server --keygen writes to publisher.key. Empty: the key file, if there is one; the server is not listed on the masters without one.",
|
||||
"env_variable": "HALO_SERVER_PUBLISHER_KEY",
|
||||
"default_value": "",
|
||||
"user_viewable": true,
|
||||
"user_editable": true,
|
||||
"rules": "nullable|string|regex:/^[0-9a-f]{64}$/",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "Instance name",
|
||||
"description": "Tells this server from your others on the master servers: letters, digits, dashes.",
|
||||
"env_variable": "HALO_SERVER_INSTANCE",
|
||||
"default_value": "main",
|
||||
"user_viewable": true,
|
||||
"user_editable": true,
|
||||
"rules": "required|string|alpha_dash|max:32",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "Region",
|
||||
"description": "A label in the server browser (eu, na-east); empty for none.",
|
||||
"env_variable": "HALO_SERVER_REGION",
|
||||
"default_value": "",
|
||||
"user_viewable": true,
|
||||
"user_editable": true,
|
||||
"rules": "nullable|string|alpha_dash|max:16",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "Log format",
|
||||
"description": "The console's lines: text, or json for a log collector.",
|
||||
"env_variable": "HALO_SERVER_LOG_FORMAT",
|
||||
"default_value": "text",
|
||||
"user_viewable": true,
|
||||
"user_editable": true,
|
||||
"rules": "required|string|in:text,json",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "Web UI bind",
|
||||
"description": "The container's address the web port listens on: all of them, as the allocation's address is the node's.",
|
||||
"env_variable": "HALO_SERVER_WEB_BIND",
|
||||
"default_value": "0.0.0.0",
|
||||
"user_viewable": false,
|
||||
"user_editable": false,
|
||||
"rules": "required|string|in:0.0.0.0",
|
||||
"field_type": "text"
|
||||
},
|
||||
{
|
||||
"name": "GitHub repository",
|
||||
"description": "owner/name the installation downloads the release from.",
|
||||
"env_variable": "OPENCE_REPOSITORY",
|
||||
"default_value": "OpenCommunityEdition/OpenCE",
|
||||
"user_viewable": false,
|
||||
"user_editable": false,
|
||||
"rules": "required|string|max:100|regex:/^[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+$/",
|
||||
"field_type": "text"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,100 +0,0 @@
|
||||
#!/bin/bash
|
||||
# The OpenCE dedicated server egg's installation script (Pterodactyl and
|
||||
# Pelican), run as root in ghcr.io/ptero-eggs/installers:debian with the
|
||||
# server's folder at /mnt/server. tools/egg_build.py copies it into
|
||||
# egg-opence-dedicated-server.json.
|
||||
#
|
||||
# OPENCE_RELEASE: "latest" or a release tag (build-206).
|
||||
# OPENCE_REPOSITORY: the GitHub repository (owner/name) to download from.
|
||||
#
|
||||
# A reinstall replaces the release's files and keeps the owner's:
|
||||
# config.toml, init.txt, publisher.key, gametypes/, custom_maps/, maps/ and
|
||||
# logs/. The panel ignores this script's exit code, so each failure says
|
||||
# what went wrong.
|
||||
|
||||
set -u
|
||||
|
||||
SERVER_DIR="${SERVER_DIR:-/mnt/server}"
|
||||
RELEASE="${OPENCE_RELEASE:-latest}"
|
||||
REPOSITORY="${OPENCE_REPOSITORY:-OpenCommunityEdition/OpenCE}"
|
||||
GITHUB_URL="${OPENCE_GITHUB_URL:-https://github.com}"
|
||||
GITHUB_API="${OPENCE_GITHUB_API:-https://api.github.com}"
|
||||
ASSET=halo-linux-release.zip
|
||||
|
||||
fail() {
|
||||
echo "INSTALL FAILED: $*"
|
||||
exit 1
|
||||
}
|
||||
|
||||
if ! [[ "$REPOSITORY" =~ ^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$ ]]; then
|
||||
fail "the repository \"$REPOSITORY\" is not owner/name"
|
||||
fi
|
||||
if [ -z "$RELEASE" ] || [ "$RELEASE" = latest ]; then
|
||||
# (no API call, so no rate limit)
|
||||
url="$GITHUB_URL/$REPOSITORY/releases/latest/download/$ASSET"
|
||||
else
|
||||
if ! [[ "$RELEASE" =~ ^[A-Za-z0-9._-]+$ ]]; then
|
||||
fail "the release \"$RELEASE\" is not a tag name (build-206) or latest"
|
||||
fi
|
||||
echo "Looking up release $RELEASE of $REPOSITORY"
|
||||
release_json="$(curl -fsSL --retry 3 -H 'Accept: application/vnd.github+json' \
|
||||
"$GITHUB_API/repos/$REPOSITORY/releases/tags/$RELEASE")" \
|
||||
|| fail "no release $RELEASE in $REPOSITORY (or GitHub's API did not answer)"
|
||||
url="$(printf '%s' "$release_json" | jq -r --arg name "$ASSET" \
|
||||
'[.assets[]? | select(.name == $name) | .browser_download_url][0] // empty')"
|
||||
[ -n "$url" ] || fail "release $RELEASE has no $ASSET"
|
||||
fi
|
||||
|
||||
mkdir -p "$SERVER_DIR" || fail "cannot make $SERVER_DIR"
|
||||
cd "$SERVER_DIR" || fail "cannot enter $SERVER_DIR"
|
||||
|
||||
work="$(mktemp -d)" || fail "cannot make a temporary folder"
|
||||
trap 'rm -rf "$work"' EXIT
|
||||
|
||||
echo "Downloading $url"
|
||||
curl -fL --retry 3 --progress-bar -o "$work/$ASSET" "$url" || fail "the download of $url failed"
|
||||
unzip -tq "$work/$ASSET" > /dev/null || fail "$ASSET is not a zip file"
|
||||
mkdir "$work/release"
|
||||
unzip -q "$work/$ASSET" -d "$work/release" || fail "cannot unzip $ASSET"
|
||||
[ -f "$work/release/halo" ] || fail "$ASSET has no halo executable"
|
||||
|
||||
# the release's files, over the old release's; the owner's are never in it,
|
||||
# and gametypes/ only adds the examples not already there
|
||||
for entry in "$work/release"/* "$work/release"/.[!.]*; do
|
||||
[ -e "$entry" ] || continue
|
||||
name="$(basename "$entry")"
|
||||
case "$name" in
|
||||
config.toml | init.txt | publisher.key | custom_maps | maps | logs)
|
||||
continue
|
||||
;;
|
||||
gametypes)
|
||||
mkdir -p gametypes
|
||||
cp -rn "$entry"/. gametypes/
|
||||
continue
|
||||
;;
|
||||
esac
|
||||
rm -rf "./$name"
|
||||
cp -a "$entry" "./$name" || fail "cannot copy $name"
|
||||
done
|
||||
|
||||
chmod 0755 halo
|
||||
if [ ! -f halo-server ]; then
|
||||
printf '#!/bin/sh\nexec "$(dirname "$0")/halo" --server "$@"\n' > halo-server
|
||||
fi
|
||||
chmod 0755 halo-server
|
||||
mkdir -p maps custom_maps gametypes logs
|
||||
|
||||
echo "Checking that the server runs"
|
||||
if version="$(HOME="$work" HALO_SAVE_ROOT="$work/saves" timeout 30 ./halo --version 2>&1)"; then
|
||||
echo "$version"
|
||||
else
|
||||
echo "WARNING: ./halo --version did not run. The server needs the 32-bit C runtime"
|
||||
echo "WARNING: (the egg's ghcr.io/ptero-eggs/games:source image has it):"
|
||||
echo "$version"
|
||||
fi
|
||||
|
||||
if [ ! -f maps/ui.map ]; then
|
||||
echo "No game data yet: upload your maps/ folder (ui.map and the multiplayer maps)"
|
||||
echo "over SFTP into the server's folder before starting it."
|
||||
fi
|
||||
echo "Installation completed"
|
||||
@@ -1,49 +0,0 @@
|
||||
# The dedicated server on PufferPanel
|
||||
|
||||
`template.json` is a PufferPanel template for the dedicated server
|
||||
(`docs/dedicated_server.md`), run in PufferPanel's host environment: it
|
||||
downloads a release's `halo-linux-release.zip` into the server's folder,
|
||||
runs `./halo --server` there, and stops it by writing `quit` to its
|
||||
standard input.
|
||||
|
||||
## Using it
|
||||
|
||||
1. The node needs the 32-bit C runtime (Debian and Ubuntu:
|
||||
`dpkg --add-architecture i386 && apt install libc6:i386`). The template
|
||||
mounts `/lib32` and `/usr/lib32` into PufferPanel's sandbox, which does
|
||||
not otherwise; without them the 32-bit `halo` cannot start.
|
||||
2. Add the template (Templates, New, and paste the file), and create a
|
||||
server from it.
|
||||
3. Upload the `maps/` folder of your own copy of the game into the
|
||||
server's folder. Without `maps/ui.map` and the rotation's maps the server
|
||||
exits with code 2 and says which maps it looked for.
|
||||
4. Start it.
|
||||
|
||||
## Ports
|
||||
|
||||
The **Tunnel port** (UDP, 2302 by default) is the one port players need.
|
||||
The **Web UI port** is the web page, its API and the remote console, on
|
||||
127.0.0.1 only. Its default is 8090, because PufferPanel itself listens on
|
||||
8080. Each server on a node needs a tunnel port and a web port of its own
|
||||
(or a web port of 0, for none).
|
||||
|
||||
## Files
|
||||
|
||||
Everything the server writes stays in its folder: `config.toml` (every
|
||||
setting, written at the first start, with the web page's admin password if
|
||||
none was given), `saves/` (`HALO_SAVE_ROOT`: the profiles and the map cache,
|
||||
about 115 MB, built at the first start), `logs/` (`HALO_LOG_ROOT`:
|
||||
`debug.txt`, `bans.txt`, `cheaters.txt`) and `status.json`
|
||||
(`server.status_file`, the status every 2 seconds).
|
||||
|
||||
The template's variables are passed as `HALO_*` variables, which win over
|
||||
`config.toml`: `sv_set` and the web page cannot change those settings.
|
||||
|
||||
## PufferPanel versions
|
||||
|
||||
The template is in the format of PufferPanel 2's templates (`run.command`
|
||||
as a string, `run.stop` as the command written to standard input). We have
|
||||
not confirmed how PufferPanel 3 imports it, nor the form of its standard
|
||||
input settings; if a server made from it on PufferPanel 3 does not stop
|
||||
with `quit`, set its stop to send `quit` to standard input (or SIGTERM,
|
||||
which the server takes as well) in the server's settings.
|
||||
@@ -1,140 +0,0 @@
|
||||
{
|
||||
"type": "opence",
|
||||
"display": "OpenCE Dedicated Server",
|
||||
"install": [
|
||||
{
|
||||
"type": "download",
|
||||
"files": [
|
||||
"${release_url}"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "command",
|
||||
"commands": [
|
||||
"unzip -o halo-linux-release.zip",
|
||||
"rm -f halo-linux-release.zip",
|
||||
"chmod 0755 halo halo-server",
|
||||
"mkdir -p maps custom_maps gametypes saves logs",
|
||||
"./halo --version"
|
||||
]
|
||||
}
|
||||
],
|
||||
"run": {
|
||||
"command": "./halo --server",
|
||||
"stop": "quit",
|
||||
"workingDirectory": "",
|
||||
"pre": [],
|
||||
"post": [],
|
||||
"environmentVars": {
|
||||
"HALO_NET_TUNNEL_PORT": "${port}",
|
||||
"HALO_SERVER_NAME": "${name}",
|
||||
"HALO_SERVER_ROTATION": "${rotation}",
|
||||
"HALO_SERVER_MAX_PLAYERS": "${max_players}",
|
||||
"HALO_SERVER_PUBLIC": "${public}",
|
||||
"HALO_SERVER_WEB_PORT": "${web_port}",
|
||||
"HALO_SERVER_LOG_FORMAT": "${log_format}",
|
||||
"HALO_SERVER_STATUS_FILE": "status.json",
|
||||
"HALO_SAVE_ROOT": "saves",
|
||||
"HALO_LOG_ROOT": "logs"
|
||||
},
|
||||
"autostart": false,
|
||||
"autorecover": true,
|
||||
"autorestart": false
|
||||
},
|
||||
"data": {
|
||||
"release_url": {
|
||||
"type": "string",
|
||||
"display": "Release",
|
||||
"desc": "The release's halo-linux-release.zip: .../releases/latest/download/halo-linux-release.zip, or .../releases/download/<tag>/halo-linux-release.zip. Used when the server is installed again.",
|
||||
"required": true,
|
||||
"value": "https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-linux-release.zip",
|
||||
"userEdit": true
|
||||
},
|
||||
"port": {
|
||||
"type": "integer",
|
||||
"display": "Tunnel port",
|
||||
"desc": "The UDP port of internet play (network.tunnel_port), the one port players need.",
|
||||
"required": true,
|
||||
"value": 2302,
|
||||
"userEdit": true
|
||||
},
|
||||
"name": {
|
||||
"type": "string",
|
||||
"display": "Server name",
|
||||
"desc": "The game's name in the server browser: 15 characters of printable ASCII.",
|
||||
"required": true,
|
||||
"value": "OpenCE Server",
|
||||
"userEdit": true
|
||||
},
|
||||
"rotation": {
|
||||
"type": "string",
|
||||
"display": "Rotation",
|
||||
"desc": "The games played one after another: map:gametype entries separated by commas.",
|
||||
"required": true,
|
||||
"value": "bloodgulch:ctf, sidewinder:team_slayer, prisoner:slayer",
|
||||
"userEdit": true
|
||||
},
|
||||
"max_players": {
|
||||
"type": "integer",
|
||||
"display": "Max players",
|
||||
"desc": "2 to 127.",
|
||||
"required": true,
|
||||
"value": 16,
|
||||
"userEdit": true
|
||||
},
|
||||
"public": {
|
||||
"type": "boolean",
|
||||
"display": "Public",
|
||||
"desc": "List the server in everyone's server browser.",
|
||||
"required": true,
|
||||
"value": true,
|
||||
"userEdit": true
|
||||
},
|
||||
"web_port": {
|
||||
"type": "integer",
|
||||
"display": "Web UI port",
|
||||
"desc": "The web page, its API and the remote console, on 127.0.0.1 (server.web_port); 0 for none. Each server on a node needs a port of its own, and not PufferPanel's own (8080). The admin password is printed at the first start and kept in config.toml.",
|
||||
"required": true,
|
||||
"value": 8090,
|
||||
"userEdit": true
|
||||
},
|
||||
"log_format": {
|
||||
"type": "option",
|
||||
"display": "Log format",
|
||||
"desc": "The console's lines.",
|
||||
"required": true,
|
||||
"value": "text",
|
||||
"userEdit": true,
|
||||
"options": [
|
||||
{
|
||||
"value": "text",
|
||||
"display": "Text"
|
||||
},
|
||||
{
|
||||
"value": "json",
|
||||
"display": "JSON"
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"environment": {
|
||||
"type": "host",
|
||||
"mounts": [
|
||||
"/lib32",
|
||||
"/usr/lib32"
|
||||
]
|
||||
},
|
||||
"supportedEnvironments": [
|
||||
{
|
||||
"type": "host",
|
||||
"mounts": [
|
||||
"/lib32",
|
||||
"/usr/lib32"
|
||||
]
|
||||
}
|
||||
],
|
||||
"requirements": {
|
||||
"os": "linux",
|
||||
"arch": "amd64"
|
||||
}
|
||||
}
|
||||
@@ -1 +0,0 @@
|
||||
d04e8b101007d1641cace8b95fcca76f7f44709f6885c3d031b52394dbdf9376
|
||||
@@ -1,52 +0,0 @@
|
||||
# The dedicated server under systemd
|
||||
|
||||
`halo-server@.service` runs the dedicated server (`docs/dedicated_server.md`)
|
||||
as a templated unit: one instance for each folder
|
||||
`/opt/opence/servers/<name>`, all sharing one release in `/opt/opence/bin`
|
||||
and one read-only copy of the game data in `/opt/opence/data`.
|
||||
|
||||
| Path | What |
|
||||
| --- | --- |
|
||||
| `/opt/opence/bin/` | The release (`halo-linux-release.zip`, unzipped) |
|
||||
| `/opt/opence/data/` | The game data, only read: `maps/`, `custom_maps/`, `gametypes/` |
|
||||
| `/opt/opence/servers/<name>/` | The instance's own, the only folder it may write: `config.toml`, `init.txt`, `publisher.key`, `server.env`, `saves/` (the map cache), `logs/` |
|
||||
|
||||
## Installing
|
||||
|
||||
```sh
|
||||
sudo useradd --system --home-dir /opt/opence --shell /usr/sbin/nologin halo
|
||||
sudo install -d -o halo -g halo -m 0750 /opt/opence/servers/main
|
||||
sudo cp deploy/systemd/halo-server@.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now halo-server@main
|
||||
journalctl -u halo-server@main -f
|
||||
```
|
||||
|
||||
Open UDP 2302 (the instance's `network.tunnel_port`) in the firewall.
|
||||
|
||||
## Settings
|
||||
|
||||
`server.env` in the instance's folder holds its settings as `HALO_*`
|
||||
variables, one a line (port/linux/README.md, "Dedicated server"). A
|
||||
variable set there wins over `config.toml`, and `sv_set` and the web page
|
||||
cannot change it; leave out what you want to change from the web page.
|
||||
|
||||
A second instance on the machine needs ports of its own, and its own
|
||||
loopback address for system link:
|
||||
|
||||
```sh
|
||||
HALO_NET_TUNNEL_PORT=2303
|
||||
HALO_SERVER_WEB_PORT=8081
|
||||
HALO_NET_ADDRESS=127.0.0.2
|
||||
HALO_NET_BROADCAST=127.0.0.1
|
||||
```
|
||||
|
||||
The web port stays on 127.0.0.1 unless `server.env` says otherwise (and
|
||||
then it needs a password, and TLS in front of it).
|
||||
|
||||
## Exit codes
|
||||
|
||||
Exit code 5 (`sv_restart`, or an update installed) restarts the server; 2
|
||||
(no usable maps) and 3 (bad configuration) do not, as a restart would fail
|
||||
the same way. The unit has no console (`StandardInput=null`): commands come
|
||||
from `init.txt` and the web port.
|
||||
@@ -1,96 +0,0 @@
|
||||
# A dedicated server under systemd (docs/dedicated_server.md), one instance
|
||||
# for each folder /opt/opence/servers/<name>:
|
||||
#
|
||||
# /opt/opence/bin/ the release (halo-linux-release.zip, unzipped)
|
||||
# /opt/opence/data/ the game data, shared by every instance and
|
||||
# only read: maps/, custom_maps/, gametypes/
|
||||
# /opt/opence/servers/<name>/ the instance's own: config.toml, init.txt,
|
||||
# publisher.key, server.env, logs/, saves/
|
||||
#
|
||||
# server.env holds the instance's settings as HALO_* variables, one a line.
|
||||
# A second instance on the machine needs its own ports, and its own loopback
|
||||
# address for system link:
|
||||
#
|
||||
# HALO_NET_TUNNEL_PORT=2303
|
||||
# HALO_SERVER_WEB_PORT=8081
|
||||
# HALO_NET_ADDRESS=127.0.0.2
|
||||
# HALO_NET_BROADCAST=127.0.0.1
|
||||
#
|
||||
# Install:
|
||||
# sudo useradd --system --home-dir /opt/opence --shell /usr/sbin/nologin halo
|
||||
# sudo install -d -o halo -g halo -m 0750 /opt/opence/servers/main
|
||||
# sudo cp deploy/systemd/halo-server@.service /etc/systemd/system/
|
||||
# sudo systemctl daemon-reload
|
||||
# sudo systemctl enable --now halo-server@main
|
||||
# journalctl -u halo-server@main -f
|
||||
#
|
||||
# Open UDP 2302 (each instance's network.tunnel_port) in the firewall. The
|
||||
# web port stays on 127.0.0.1 unless server.env says otherwise.
|
||||
#
|
||||
# Exit code 5 (sv_restart, or an update installed) restarts the server;
|
||||
# 2 (no usable maps) and 3 (bad configuration) do not, as a restart would
|
||||
# fail the same way.
|
||||
[Unit]
|
||||
Description=OpenCE dedicated server %i
|
||||
Documentation=https://github.com/OpenCommunityEdition/OpenCE/blob/main/docs/dedicated_server.md
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=exec
|
||||
User=halo
|
||||
Group=halo
|
||||
WorkingDirectory=/opt/opence/servers/%i
|
||||
Environment=HOME=/opt/opence/servers/%i
|
||||
Environment=HALO_CONFIG_FILE=/opt/opence/servers/%i/config.toml
|
||||
Environment=HALO_DATA_ROOT=/opt/opence/data
|
||||
Environment=HALO_SAVE_ROOT=/opt/opence/servers/%i/saves
|
||||
Environment=HALO_LOG_ROOT=/opt/opence/servers/%i/logs
|
||||
Environment=HALO_SERVER_INIT_FILE=/opt/opence/servers/%i/init.txt
|
||||
Environment=HALO_NET_TUNNEL_PORT=2302
|
||||
EnvironmentFile=-/opt/opence/servers/%i/server.env
|
||||
ExecStartPre=/bin/mkdir -p /opt/opence/servers/%i/logs /opt/opence/servers/%i/saves
|
||||
ExecStart=/opt/opence/bin/halo --server
|
||||
# (no console: commands come from init.txt and the web port)
|
||||
StandardInput=null
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
KillSignal=SIGTERM
|
||||
TimeoutStopSec=15
|
||||
Restart=on-failure
|
||||
RestartSec=10
|
||||
RestartForceExitStatus=5
|
||||
RestartPreventExitStatus=2 3
|
||||
# (no privileges, nothing writable but the instance's folder)
|
||||
NoNewPrivileges=yes
|
||||
CapabilityBoundingSet=
|
||||
AmbientCapabilities=
|
||||
ProtectSystem=strict
|
||||
ReadWritePaths=/opt/opence/servers/%i
|
||||
ProtectHome=yes
|
||||
PrivateTmp=yes
|
||||
PrivateDevices=yes
|
||||
ProtectKernelTunables=yes
|
||||
ProtectKernelModules=yes
|
||||
ProtectKernelLogs=yes
|
||||
ProtectControlGroups=yes
|
||||
ProtectClock=yes
|
||||
ProtectHostname=yes
|
||||
ProtectProc=invisible
|
||||
RestrictAddressFamilies=AF_INET AF_UNIX AF_NETLINK
|
||||
RestrictNamespaces=yes
|
||||
RestrictRealtime=yes
|
||||
RestrictSUIDSGID=yes
|
||||
LockPersonality=yes
|
||||
MemoryDenyWriteExecute=yes
|
||||
# (a 32-bit x86 program)
|
||||
SystemCallArchitectures=native x86
|
||||
SystemCallFilter=@system-service
|
||||
SystemCallFilter=~@privileged
|
||||
SystemCallErrorNumber=EPERM
|
||||
UMask=0027
|
||||
MemoryMax=600M
|
||||
TasksMax=64
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
@@ -1,240 +0,0 @@
|
||||
> This is the README of [OpenCE](https://github.com/OpenCommunityEdition/OpenCE),
|
||||
> the port Mjolnir VR is built on, kept for its build and
|
||||
> development notes. Its download links are OpenCE's. For the VR mod, see
|
||||
> the [main README](../README.md).
|
||||
|
||||
# Halo: Combat Evolved for Linux, Windows, Android and the web
|
||||
|
||||
[](https://discord.gg/9gqcHyr5km)
|
||||
|
||||
This project is a port of the Halo: Combat Evolved decompilation to Linux,
|
||||
Windows, Android and web browsers. The decompilation is of the Xbox build 2342
|
||||
(`cachebeta.exe`, SHA-256
|
||||
`4cc87b45f721270392a96f1674ed2b5cd4a7bb4355faeab4531d1cf1884d9520`).
|
||||
|
||||
<img width="1289" height="995" alt="The game on Linux" src="https://github.com/user-attachments/assets/0d3ad50f-f8b8-46cf-aef8-e3661da2a7d7" />
|
||||
|
||||
The port starts from the decompilation of [bnunu/halo-1](https://github.com/bnunu/halo-1).
|
||||
That project is a fork of [punpckhdq/halo](https://github.com/punpckhdq/halo).
|
||||
|
||||
## Download
|
||||
|
||||
GitHub Actions builds the game for each commit. These links download the
|
||||
builds of the latest release:
|
||||
|
||||
| Platform | Release | Debug |
|
||||
| --- | --- | --- |
|
||||
| Linux | [halo-linux-release.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-linux-release.zip) | [halo-linux-debug.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-linux-debug.zip) |
|
||||
| Windows | [halo-windows-release.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-windows-release.zip) | [halo-windows-debug.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-windows-debug.zip) |
|
||||
| Android | [halo-android-release.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-android-release.zip) | [halo-android-debug.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-android-debug.zip) |
|
||||
| Web | [halocombatevolved.com](https://halocombatevolved.com/) (or [halo-web-release.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-web-release.zip) for your own server) | [halo-web-debug.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-web-debug.zip) |
|
||||
|
||||
Use the release build to play. The debug build stops at the first failed
|
||||
assertion and writes it to the log. Use the debug build to find and report
|
||||
problems.
|
||||
|
||||
The game updates itself. At start-up it looks for a newer release, and asks
|
||||
if you want to install it. Refer to "Updates" in
|
||||
[port/linux/README.md](port/linux/README.md#updates). The web site offers
|
||||
each new build when it is out.
|
||||
|
||||
Each build of the `main` branch that passes on all four platforms is a new
|
||||
release, and the web site then plays it. The [Releases](https://github.com/OpenCommunityEdition/OpenCE/releases)
|
||||
page keeps the last five releases. If the latest build has a problem, get
|
||||
an older build from that page.
|
||||
|
||||
### Arch-based Linux Distributions
|
||||
|
||||
The above Linux binary release is available on the [AUR](https://aur.archlinux.org/packages/opence-bin).
|
||||
|
||||
## Game data
|
||||
|
||||
The port does not include the game data. Download an Xbox disc image
|
||||
(`.xiso` or `.iso`) of Halo: Combat Evolved. All versions of the game
|
||||
operate. The maps of the European (PAL) version were made for a slower
|
||||
console. The port changes them to play as the North American (NTSC) maps do,
|
||||
so players of the two versions can play together.
|
||||
|
||||
1. Start the game.
|
||||
2. At the first start, the game asks for the disc image. Select it.
|
||||
3. The game extracts the `maps/` folder. Then the game starts.
|
||||
|
||||
On Linux and Windows, the game puts `maps/` next to the executable. On
|
||||
Android, copy the disc image to the phone first. The app puts `maps/` in its
|
||||
data folder. Refer to [port/android/README.md](port/android/README.md). On
|
||||
the web, the page copies `maps/` out of the disc image into the browser's
|
||||
storage for the site; nothing is uploaded. Refer to
|
||||
[port/web/README.md](port/web/README.md).
|
||||
|
||||
## Mods
|
||||
|
||||
Mods are folders of Halo PC tag files, as the Halo Editing Kit and Invader
|
||||
write them, in `mods/` next to `maps/`: texture, sound, text and model packs
|
||||
that play over the maps' on your machine only, in any game. Each has a
|
||||
`mod.toml`. Every mod in the folder is on; the main menu's Mods turns them
|
||||
off and on and sets the order they load in.
|
||||
Refer to [docs/mods.md](docs/mods.md).
|
||||
|
||||
## Platforms
|
||||
|
||||
Each platform has its own instructions:
|
||||
|
||||
| Platform | Instructions |
|
||||
| --- | --- |
|
||||
| Linux (32-bit x86 executable, OpenGL 4.5, SDL3) | [port/linux/README.md](port/linux/README.md) |
|
||||
| Windows (32-bit x86 executable, OpenGL 4.5, SDL3) | [port/windows/README.md](port/windows/README.md) |
|
||||
| Android (arm64 app, OpenGL ES 3, SDL3) | [port/android/README.md](port/android/README.md) |
|
||||
| Web (WebAssembly, WebGL 2, SDL3; desktop Chrome, Edge and Firefox) | [port/web/README.md](port/web/README.md) |
|
||||
|
||||
The Linux README also gives the controls, the settings and the multiplayer
|
||||
functions. These are almost the same on all platforms.
|
||||
|
||||
## Multiplayer
|
||||
|
||||
The game can play system link games on a local network and on the internet:
|
||||
|
||||
- A system link game can have up to 128 players on up to 128 machines.
|
||||
- Linux, Windows and Android machines and browsers can play in the same
|
||||
game. On a local network, the native builds play system link; browsers
|
||||
play each other in rooms, over WebRTC
|
||||
([port/web/README.md](port/web/README.md)).
|
||||
- An invite link, or the server browser, lets a machine join a game on the
|
||||
internet, browsers too: a native build takes a browser's WebRTC
|
||||
([port/linux/README.md](port/linux/README.md), "Browsers"). No server of
|
||||
this project is necessary.
|
||||
- The netcode is new. Each machine moves its own player at once,
|
||||
and the host makes the decisions for the game. Refer to
|
||||
[port/linux/NETCODE.md](port/linux/NETCODE.md).
|
||||
|
||||
## Build the game
|
||||
|
||||
You do not need the Xbox SDK. The port supplies the SDK declarations that
|
||||
the game uses. Refer to [port/include/xdk](port/include/xdk/README.md).
|
||||
|
||||
To build the game:
|
||||
|
||||
1. Install Python and [ninja](https://ninja-build.org/).
|
||||
2. Install the tools for your platform. Refer to the README for the
|
||||
platform.
|
||||
3. In the root folder of the repository, enter `python configure.py`.
|
||||
4. Enter `ninja` with the target for the platform:
|
||||
|
||||
| Target | Result |
|
||||
| --- | --- |
|
||||
| `ninja linux` | `build/linux/halo` |
|
||||
| `ninja windows` (on Windows) | `build/windows/halo.exe` and `SDL3.dll` |
|
||||
| `ninja android_apk` | `port/android/app/build/outputs/apk/debug/app-debug.apk` |
|
||||
| `ninja web` | `build/web/site/`, the web site (`python tools/web_serve.py` serves it) |
|
||||
|
||||
If you enter `ninja` without a target, ninja builds the game for the
|
||||
computer that you use.
|
||||
|
||||
`tools/ci_build.py` makes the same builds as GitHub Actions. For example,
|
||||
enter `python tools/ci_build.py linux release`.
|
||||
|
||||
### Build options
|
||||
|
||||
Give these options to `configure.py`:
|
||||
|
||||
| Option | Result |
|
||||
| --- | --- |
|
||||
| (none) | A debug build. A failed assertion stops the game. |
|
||||
| `--release` | A release build. The game does not examine assertions, as in the retail game. |
|
||||
| `--portable` | The Linux and Windows builds operate on all x86-64 processors. The Linux build also operates on older distributions and on SteamOS: refer to "Portable build" in [port/linux/README.md](port/linux/README.md#portable-build). Use this option for builds that you give to other persons. |
|
||||
| `--lto=thin`, `--lto=off` | Less link-time optimization. The link is faster. |
|
||||
| `--pgo=off` | No profile-guided optimization. |
|
||||
| `--pgo=train` | Records a new optimization profile. Refer to "Optimization profiles". |
|
||||
| `--profile` | A profiling build. It records CPU times. Refer to "Profiling builds". |
|
||||
| `--web-emcc PATH` | The Emscripten `emcc` for `ninja web` (else the one on the PATH, or `~/emsdk`'s). |
|
||||
|
||||
Without `--portable`, the Linux and Windows builds use all the instructions
|
||||
of the processor that builds them (`-march=native`). Such a build does not
|
||||
always start on a different computer.
|
||||
|
||||
### Optimization profiles
|
||||
|
||||
The builds use profiles of the game to optimize the code:
|
||||
|
||||
- `pgo/halo_linux.profdata` for Linux and Android.
|
||||
- `pgo/halo_windows.profdata` for Windows.
|
||||
|
||||
The profiles need clang 22 or later. With an older clang, the builds do not
|
||||
use the profiles.
|
||||
|
||||
To record a new profile:
|
||||
|
||||
1. Delete the profile.
|
||||
2. Enter `python configure.py --pgo=train`.
|
||||
3. Enter `ninja linux` or `ninja windows`.
|
||||
|
||||
The build then plays the main menu and the first minute of each campaign
|
||||
level. This procedure continues for approximately 15 minutes. The game
|
||||
data must be in `assets/`.
|
||||
|
||||
### Profiling builds
|
||||
|
||||
A profiling build records where the game spends its time.
|
||||
|
||||
1. Enter `python configure.py --profile`, then build as usual.
|
||||
2. Start a recording. Enter `profile_record` in the console (or the telnet
|
||||
console), or set `debug.profile_record = true` in `config.toml`. To
|
||||
record each game of a session, also set
|
||||
`debug.profile_record_when = "game"`.
|
||||
3. Stop the recording. Enter `profile_stop`, load another map, or quit.
|
||||
|
||||
The game writes numbered `.part<n>.json` files under `profiles/` in its data root
|
||||
and logs their paths. Parts are retained after the recording stops. Logs go to
|
||||
standard error; a Windows release build without standard error writes them to
|
||||
`halo.log` next to `halo.exe`.
|
||||
|
||||
`tools/net_report.py` is a helper for developers. Enter
|
||||
`python tools/net_report.py <recording.part1.json>` to read a recording
|
||||
as tables. The command also writes `<recording>.summary.txt`, a short text
|
||||
file.
|
||||
|
||||
| Command | Result |
|
||||
| --- | --- |
|
||||
| `profile_record [seconds]` | Starts a recording. With a number of seconds, the recording stops after that time. |
|
||||
| `profile_stop` | Stops the recording. |
|
||||
|
||||
`debug.profile_memory` sets the memory of a recording in MB (default 256,
|
||||
from 4 to 1024). A recording has no length limit:
|
||||
the game writes a part each time the memory is full. Refer to "Settings" in
|
||||
[port/linux/README.md](port/linux/README.md).
|
||||
|
||||
On Android, the files are in `/sdcard/Android/data/com.halo.decomp/files/profiles/`.
|
||||
Enter `adb pull` to copy the recording parts to a computer.
|
||||
|
||||
A profiling build plays with normal builds. It does not use
|
||||
`--pgo=train`.
|
||||
|
||||
## Licence
|
||||
|
||||
OpenCE is free software: you can give it to others and change it under the
|
||||
terms of the GNU Affero General Public License as published by the Free
|
||||
Software Foundation, version 3 of the License or (at your option) any later
|
||||
version (`AGPL-3.0-or-later`). It comes with no warranty. The full text is in
|
||||
[LICENSE](LICENSE).
|
||||
|
||||
- **From the change.** The AGPL applies from the commit that made the change,
|
||||
and to each release built from that commit or a later one. Earlier
|
||||
releases, and the source at every earlier commit, were released under
|
||||
[CC0 1.0](LICENSES/CC0-1.0.txt) and stay that way.
|
||||
- **What OpenCE builds on.** The decompilation of
|
||||
[punpckhdq/halo](https://github.com/punpckhdq/halo) is under the AGPL 3.0
|
||||
from 17 October 2026, and under CC0 1.0 before that date.
|
||||
[bnunu/halo-1](https://github.com/bnunu/halo-1) is under CC0 1.0.
|
||||
- **Contributions** are under `AGPL-3.0-or-later`. A change taken from a
|
||||
project under GPL 3.0 keeps that licence and its notices; the GPL 3.0 and
|
||||
the AGPL 3.0 let the two be combined (section 13 of each).
|
||||
- **Hosts and servers.** If you change the game and let other persons play
|
||||
with your version over a network (for example, as the host of an internet
|
||||
game, or on a web site), the AGPL asks you to offer them the source of
|
||||
your version (section 13). The game as released has its source here, and
|
||||
each release's source is its tag (`build-<n>`).
|
||||
- **Third-party code, fonts and art** keep their own licences, which are
|
||||
next to them (`port/third_party`, `port/assets/fonts`,
|
||||
`port/assets/icons`, `port/assets/text_filter`). The release downloads and
|
||||
the web site's `licenses.txt` carry their notices.
|
||||
- **Halo is not covered.** The licence covers the work of OpenCE's authors.
|
||||
It gives no rights in Halo, its maps or anything else that Microsoft owns.
|
||||
@@ -0,0 +1,106 @@
|
||||
# Assertions, warnings, and halts: shared API and January matching
|
||||
|
||||
The owner is [source/cseries/cseries.h](../source/cseries/cseries.h).
|
||||
All assertions express a condition that **must be true**. A false condition
|
||||
reports the diagnostic with `display_assert(..., TRUE)` and then calls
|
||||
`system_exit(-1)`. Evaluate diagnostic expressions only on the failure path.
|
||||
|
||||
Warnings likewise report only when their condition is false, but use
|
||||
`display_assert(..., FALSE)` and **continue**. Halts are unconditional: they
|
||||
report with `TRUE` and call the existing `halt_and_catch_fire()` owner.
|
||||
They do not take an assertion condition.
|
||||
|
||||
| Intent | Current supported API | Diagnostic |
|
||||
| --- | --- | --- |
|
||||
| Plain assertion | `assert(expression)` | Stringified expression |
|
||||
| Diagnostic assertion | `dassert(expression, diagnostic)` | Supplied string expression |
|
||||
| Formatted assertion | `vassert(expression, csprintf(temporary, format, ...))` | Formatted string, produced only on failure |
|
||||
| Preserve original source location | `match_assert(file, line, expression)` | Stringified expression |
|
||||
| Preserve location and diagnostic | `match_dassert(file, line, expression, diagnostic)` | Supplied string expression |
|
||||
| Preserve location and formatted diagnostic | `match_vassert(file, line, expression, csprintf(temporary, format, ...))` | Formatted string |
|
||||
| Plain warning | `warn(expression)` | Stringified expression; nonfatal |
|
||||
| Diagnostic warning | `dwarn(expression, diagnostic)` | Supplied string; nonfatal |
|
||||
| Formatted warning | `vwarn(expression, csprintf(temporary, format, ...))` | Failure-only formatting; nonfatal |
|
||||
| Plain halt | `halt()` | No message; unconditional fatal report |
|
||||
| Diagnostic halt | `dhalt(diagnostic)` | Supplied string; unconditional |
|
||||
| Formatted halt | `vhalt(csprintf(temporary, format, ...))` | Formatted string; unconditional |
|
||||
|
||||
Warnings and halts also have `match_warn`, `match_dwarn`, `match_vwarn`,
|
||||
`match_halt`, `match_dhalt`, and `match_vhalt` counterparts. Their first two
|
||||
arguments are the original `file` and `line`, followed by the ordinary API's
|
||||
arguments.
|
||||
|
||||
`vassert`/`match_vassert` already accepted a message expression before this
|
||||
cleanup. The `dassert`/`dwarn`/`dhalt` names and matching counterparts are
|
||||
statement-safe diagnostic convenience wrappers for the existing behavior,
|
||||
not a claim that these exact wrappers were in Bungie's January source.
|
||||
Existing callers remain compatible.
|
||||
|
||||
The pinned XDK 3911 compiler is VC7 13.00.9254.1. Its preprocessor rejects
|
||||
`#define vassert(expression, format, ...)` with C2010, and does not implement
|
||||
`__VA_ARGS__`. Variadic **functions** such as `csprintf` are supported. Do not
|
||||
change compiler versions, add a function-call wrapper, or force inline code
|
||||
merely to obtain the newer comma-separated macro syntax.
|
||||
|
||||
The supplied CE reference files themselves use two-argument
|
||||
`vassert(expression, message)` calls: `random_math.c`'s random-seed lock
|
||||
checks, server line 1248, and client line 521. These calls corroborate the
|
||||
older API, but the attachments do not include its defining `cseries.h`.
|
||||
See [the source reconstruction map](user_source_reconstruction_map_20260906.md).
|
||||
|
||||
## Units example: assert the invariant, not the error condition
|
||||
|
||||
The invariant is that an inventory weapon being dropped is **not** connected
|
||||
to the map:
|
||||
|
||||
```c
|
||||
match_vassert(
|
||||
"c:\\halo\\SOURCE\\units\\units.c",
|
||||
8505,
|
||||
!TEST_FLAG(weapon->object.flags, _object_connected_to_map_bit),
|
||||
csprintf(
|
||||
temporary,
|
||||
"a %s tried to drop a %s which was connected to the map.",
|
||||
tag_get_name(unit->definition_index),
|
||||
tag_get_name(weapon->definition_index)));
|
||||
```
|
||||
|
||||
Omitting `!` reverses the behavior: it would assert for a disconnected weapon
|
||||
and accept the connected weapon. Keep the two `tag_get_name` calls and the
|
||||
formatting inside the assertion message expression, so successful execution
|
||||
does not evaluate them.
|
||||
|
||||
The matching form retains January's original filename and line number. In a
|
||||
`NON_MATCHING` build, `MATCH_FILE`/`MATCH_LINE` deliberately use the actual
|
||||
current source location instead. For new code with no original location to
|
||||
preserve, use the ordinary `assert`/`dassert`/`vassert` form.
|
||||
|
||||
## Limits and adoption
|
||||
|
||||
- Use braces around surrounding `if`/`else` branches. Some inherited macros
|
||||
expand to an `if` statement; an unbraced outer `else` can bind incorrectly.
|
||||
- Keep expressions free of unnecessary side effects. The condition is
|
||||
evaluated once, and the diagnostic only on failure, but argument evaluation
|
||||
order inside a formatted call remains the C compiler's responsibility.
|
||||
- `temporary` is the existing shared 256-byte buffer and `csprintf` uses
|
||||
unbounded `vsprintf`. Preserve authenticated legacy call sites; this is not
|
||||
a thread-safe or size-safe general logging facility. Do not pass arbitrary
|
||||
unbounded input or preformat into this buffer on the success path.
|
||||
- Do not add `NDEBUG`-based removal: the current project macros do not have
|
||||
that contract. Both debug and `NDEBUG` fixture builds are tested.
|
||||
- Migrate one coherent owner at a time and run its strict gate plus consumer
|
||||
regression checks. Do not bulk-rewrite active lanes or lose original
|
||||
diagnostic text, argument types, failure polarity, or source locations.
|
||||
|
||||
The executable macro tests are
|
||||
[tools/test_cseries_assertions.py](../tools/test_cseries_assertions.py), using
|
||||
[C fixtures](../tools/fixtures/cseries_assertions.c) compiled by the actual VC7
|
||||
toolchain. They check success/failure, lazy formatting, single evaluation,
|
||||
exact matching/nonmatching locations, fatal flag and `system_exit(-1)` or
|
||||
`halt_and_catch_fire()` dispatch, nonfatal warning continuation, and
|
||||
connected-weapon polarity. They use bounded diagnostic API doubles; they do
|
||||
not validate the termination implementation, `vsprintf` buffer safety, or the
|
||||
game's complete error-reporting subsystem.
|
||||
|
||||
See also [common constants](common_constants.md) and the
|
||||
[Units cleanup ledger](object_matching_logs/units_obj_assertion_cleanup_20260906.md).
|
||||
@@ -0,0 +1,81 @@
|
||||
# Campaign house rules and working cadence
|
||||
|
||||
User-confirmed 2026-09-07. Apply these to reconciliation and new reconstruction.
|
||||
|
||||
1. Put a no-argument `void` on its own line inside the parameter list.
|
||||
2. Put each parameter on its own line.
|
||||
3. Use explicit returns: `return;` for void functions, an appropriate returned
|
||||
value for non-void functions. Do not add an invalid bare return to non-void C.
|
||||
4. Use subsystem typed macros wrapping `tag_get`.
|
||||
5. Use typed object-access macros instead of repeated raw-access casts.
|
||||
6. Preserve January's inline schedule; do not emit a `point_from_line3d` COMDAT.
|
||||
7. Give private functions authentic or descriptive project-style names, never
|
||||
`code` plus an address.
|
||||
8. Likewise name globals; do not add `bss` plus address identifiers.
|
||||
9. Put prototypes in their genuine owners, not unrelated consumer C files.
|
||||
10. Helper/math functions may use inline assembly sparingly, with evidence.
|
||||
11. If easy exactness fails, retain credible fuzzy code, document it and park.
|
||||
12. Prioritize small objects in substantially reconstructed families.
|
||||
13. Avoid manual/forced inlining; retain ordinary helpers and natural scheduling.
|
||||
14. Use open-source Marathon as a style/semantic reference, not January byte proof.
|
||||
15. When no dedicated header exists, use the closest genuine associated header.
|
||||
16. Use correct enum constants in switch tables.
|
||||
17. Combine declaration and initialization when practical.
|
||||
18. Prefer suitable `cseries.h` macros over manual bit manipulation.
|
||||
19. Use project types, e.g. `real`, rather than generic replacements.
|
||||
20. Reject fake matching and source implausible for the original program.
|
||||
21. Reject nonsensical logic even when bytes happen to match.
|
||||
22. Use `/QIfist` where required by the target/compiler evidence. It is a
|
||||
per-TU option, not a blanket default or license to change unrelated flags.
|
||||
Check the complete TU and affected callers; conversion instructions and
|
||||
widths must agree. Existing usage is recorded in `config/config.json`.
|
||||
|
||||
Rule 6 has a later, narrow owner-approved exception for folded header-inline
|
||||
helpers (see `docs/object_matching_logs/claude_lane_b_HANDOFF_20260920.md`,
|
||||
section 3). A translation unit may emit a shared-header `__inline` COMDAT,
|
||||
including `_point_from_line3d`, only when the emitted copy is byte-identical
|
||||
to January's selected copy, its caller is strictly exact, the full ownership
|
||||
and build sweep has zero regressions, and the selected-provider link passes.
|
||||
January's per-object folded survivor is not an absolute emission boundary.
|
||||
Do not hand-expand or hand-copy the helper to evade this check.
|
||||
|
||||
## Batch workflow
|
||||
|
||||
Reconcile coherent multi-object or owner/family packets, normally several
|
||||
thousand bytes when available. Review source quality, headers, ABI and emitted
|
||||
ownership together; run one full build, tools suite and stable regression sweep
|
||||
per batch. Use existing strict gates for ordinary exact leaves. Reserve new
|
||||
bespoke runtime harnesses for ambiguous behavior/ABIs, not every tiny function.
|
||||
Isolate blockers without holding unrelated admissible work. Preserve donor trees.
|
||||
|
||||
Publish only verified source/tooling gains to canonical and the authorized
|
||||
GitHub branches. Donor-relative headline totals are not additive canonical
|
||||
credit. Keep meaningful exact bytes distinct from padded and fuzzy counts.
|
||||
|
||||
User clarification, 2026-09-07: preserve the best available house-rule-compliant
|
||||
Claude implementations in canonical and GitHub even when non-exact. Document
|
||||
the donor, fresh measurements, remaining differences and research pointers;
|
||||
do not leave useful fuzzy work stranded in donor trees. Closeness never
|
||||
justifies undefined/nonsensical logic or inappropriate Matching credit.
|
||||
Any accepted loss of exactness must be explicitly recorded and subtracted,
|
||||
not hidden behind the batch's gross gains or a semantic-match override.
|
||||
|
||||
Refresh the canonical treemap after each **10,000 additional verified reconciled
|
||||
meaningful code bytes**. Starting checkpoint for this cadence is **930,828**;
|
||||
the first threshold is **940,828**. Record the next threshold in the queue.
|
||||
Do not start a timer or unrelated recurring automation for this work threshold.
|
||||
|
||||
## Quick references
|
||||
|
||||
- [Constants, types, flags and representations](common_constants.md)
|
||||
- [Assertions, warnings and halts](assertions.md): predicates express required
|
||||
invariants; diagnostics are lazy. The weapon example needs `!TEST_FLAG(...)`.
|
||||
VC7 uses a formatted message expression, not modern variadic macros.
|
||||
- [Supplied-source reconstruction map](user_source_reconstruction_map_20260906.md)
|
||||
- [Matching methodology](matching_methodology.md)
|
||||
- [Reconciliation queue](reconciliation_queue_20260907.md)
|
||||
|
||||
Cross-build symbols/types are evidence, not interchangeable January layouts.
|
||||
Analyze supplied executables as data; do not execute them. Preserve binaries
|
||||
and private symbol assets locally, outside published source batches. Inlined
|
||||
source and absent debug assets cannot be recovered automatically with certainty.
|
||||
@@ -0,0 +1,631 @@
|
||||
# CLAUDE LANE A — AI Core Exact-Match Closeout (79,657 Remaining Halo Bytes)
|
||||
|
||||
You are continuing the Halo January 14, 2002 Xbox exact-match campaign. Your job is to maximize verified, source-authentic strict matches within one isolated AI-core portfolio while producing house-rule-clean fuzzy reconstructions for genuinely unresolved functions.
|
||||
|
||||
## 1. Frozen baseline and isolation
|
||||
|
||||
Use exactly this baseline:
|
||||
|
||||
- Commit: `6130661c9585fdb2785b3ff6bdb2ad0cfef0520c`
|
||||
- Branch represented by the baseline: `jonas/exact-pilots`
|
||||
|
||||
Create a new isolated Git worktree and branch from that exact commit, for example:
|
||||
|
||||
- Worktree: `C:\halo-worktrees\claude-lane-a-ai-core-20260920`
|
||||
- Branch: `claude/lane-a-ai-core-20260920`
|
||||
|
||||
Before doing any work:
|
||||
|
||||
1. Verify `git rev-parse HEAD` equals the full baseline hash.
|
||||
2. Verify `git status --short` is empty.
|
||||
3. Do not use a newer or older canonical checkout as the source of truth.
|
||||
4. Do not mutate the canonical checkout.
|
||||
5. Do not push anything.
|
||||
6. Do not rebase, merge, pull, or incorporate another active lane.
|
||||
7. Do not copy complete files from stale worktrees. Historical worktrees and branches are evidence sources only.
|
||||
8. Keep every experiment in this lane or under `scratch/`.
|
||||
9. At completion, leave the lane committed and clean.
|
||||
|
||||
Expected baseline sanity figures are approximately:
|
||||
|
||||
- Halo accepted: `7,291 / 7,574` functions
|
||||
- Halo accepted meaningful bytes: `1,443,979 / 1,770,166`
|
||||
- Overall accepted: `7,558` functions / `1,465,211` meaningful bytes
|
||||
- Parks: `184 active / 0 stale / 0 invalid`
|
||||
|
||||
Recompute these figures from the baseline rather than blindly trusting them. Stop and diagnose if the baseline materially differs.
|
||||
|
||||
## 2. Exclusive production scope
|
||||
|
||||
You may edit only these 11 production C translation units:
|
||||
|
||||
1. `source/ai/actor_firing_position.c` — 1,113 remaining meaningful bytes
|
||||
2. `source/ai/actor_looking.c` — 5,316
|
||||
3. `source/ai/actor_moving.c` — 10,402
|
||||
4. `source/ai/actor_perception.c` — 17,272
|
||||
5. `source/ai/actors.c` — 4,308
|
||||
6. `source/ai/ai.c` — 2,253
|
||||
7. `source/ai/ai_communication.c` — 11,377
|
||||
8. `source/ai/ai_debug.c` — 26,513
|
||||
9. `source/ai/ai_script.c` — 214
|
||||
10. `source/ai/encounters.c` — 745
|
||||
11. `source/ai/props.c` — 144
|
||||
|
||||
Frozen portfolio total: **79,657 remaining Halo meaningful bytes**.
|
||||
|
||||
This number is the starting residual portfolio, not earned credit. Re-measure it on the frozen baseline and disclose any difference.
|
||||
|
||||
Do not edit any other `.c`, `.cpp`, `.h`, `.hpp`, `.inl`, or assembly source file. In particular:
|
||||
|
||||
- No Xbox library or vendor-library work.
|
||||
- No unrelated Halo unit.
|
||||
- No shared-header edits.
|
||||
- No generated-source edits.
|
||||
- No compiler, comparator, split-target, object, or build-tool modification.
|
||||
|
||||
Documentation under `docs/object_matching_logs/`, evidence under `scratch/`, and narrowly justified configuration edits described below are allowed.
|
||||
|
||||
If a candidate requires a header correction, do not put a surrogate prototype in the consumer C file and do not edit the header in this lane. Record:
|
||||
|
||||
- the genuine owner header;
|
||||
- every consumer;
|
||||
- the proposed declaration;
|
||||
- the exact function expected to benefit;
|
||||
- the baseline controls;
|
||||
- a minimal deferred patch or edit description;
|
||||
- the evidence needed for a later header-owner lane.
|
||||
|
||||
Then continue elsewhere. A header prerequisite must not stall the portfolio.
|
||||
|
||||
## 3. Goal and work order
|
||||
|
||||
The goal is not “try a few promising functions.” Work the entire allowed portfolio in descending leverage until every remaining owner has one of these dispositions:
|
||||
|
||||
- strict exact and admitted;
|
||||
- credible improved fuzzy source retained at zero credit;
|
||||
- unchanged because the current source remains best;
|
||||
- blocked with a concrete, evidence-specific reopening condition.
|
||||
|
||||
Start with the small units to bank inexpensive closures and validate your workflow:
|
||||
|
||||
1. `props`
|
||||
2. `ai_script`
|
||||
3. `encounters`
|
||||
4. `actor_firing_position`
|
||||
5. `ai`
|
||||
6. `actors`
|
||||
|
||||
Then work:
|
||||
|
||||
7. `actor_looking`
|
||||
8. `actor_moving`
|
||||
9. `ai_communication`
|
||||
10. `actor_perception`
|
||||
11. `ai_debug`
|
||||
|
||||
You may reorder the last five when primary evidence makes another sequence more efficient. Do not spend an entire campaign fighting one allocator/x87 tie while untouched structural or unwritten work remains.
|
||||
|
||||
An old park or rejection is not proof of impossibility. It is binding evidence about hypotheses already tested. Reopen only when you have a genuinely new witness, mechanism, compiler-context fact, source graph, type, owner, ABI, call graph, constant, or cross-build correspondence. Do not repeat rejected spelling searches under new filenames.
|
||||
|
||||
## 4. Required reading before editing
|
||||
|
||||
Read these completely before production edits:
|
||||
|
||||
- `docs/campaign_house_rules.md`
|
||||
- `docs/common_constants.md`
|
||||
- `docs/assertions.md`
|
||||
- `docs/matching_methodology.md`
|
||||
- `docs/campaign_throughput_lessons.md`
|
||||
- `docs/user_source_reconstruction_map_20260906.md`
|
||||
- `tools/campaign/README.md`
|
||||
- `docs/object_matching_logs/astra_90pct_HANDOFF_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_admission_manifest_20260920.json`
|
||||
- `docs/object_matching_logs/astra_90pct_research_atlas_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_rejected_hypotheses_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_context_packet_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_debug_packet_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_canonical_reconciliation_20260920.md`
|
||||
|
||||
Read the relevant unit-specific evidence before assigning each unit:
|
||||
|
||||
### Actor looking
|
||||
|
||||
- `docs/object_matching_logs/actor_looking_obj_evidence_closeout_20260919.md`
|
||||
- `docs/object_matching_logs/astra_90pct_actor_looking_packet_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research10_actor_looking_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research10_actor_looking_independent_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research14_aiming_blockage_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research14_aiming_blockage_independent_20260920.md`
|
||||
|
||||
### Actor moving
|
||||
|
||||
- `docs/object_matching_logs/astra_90pct_actor_moving_avoidance_packet_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research8_actor_moving_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research11_actor_move_update_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research11_biped_moving_20260920.md`
|
||||
|
||||
### Actor perception
|
||||
|
||||
- `docs/object_matching_logs/astra_90pct_actor_perception_packet_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research10_perception_refresh_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research12_perception_update_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_wave2_perception_independent_review_20260920.md`
|
||||
|
||||
### AI communication
|
||||
|
||||
- `docs/object_matching_logs/astra_90pct_research10_communication_event_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research10_communication_independent_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research18_communication_probe_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research18_communication_private_owner_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_communication_independent_review_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_wave4_communication_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_wave4_communication_independent_review_20260920.md`
|
||||
|
||||
### AI debug
|
||||
|
||||
- `docs/object_matching_logs/astra_90pct_wave2_ai_debug_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_wave2_ai_debug_independent_review_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research12_ai_debug_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research12_ai_debug_color_independent_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research12_ai_debug_length_independent_20260920.md`
|
||||
|
||||
Also search `docs/object_matching_logs/` for every allowed object and read its newest reports plus any report named by their “read first,” “prior work,” or “reopening” sections.
|
||||
|
||||
## 5. Evidence sources and authority
|
||||
|
||||
Evidence priority is:
|
||||
|
||||
1. January split object code, padding, relocations, owner topology, target data, and actual executable instructions.
|
||||
2. Authenticated January PDB publics, MAP/public names, strings, and image identities.
|
||||
3. Original Bungie source, symbols, headers, or same-era builds when provenance is established.
|
||||
4. Ghidra and DIA evidence from authenticated supplied builds.
|
||||
5. Earlier/later Halo cross-builds, HCEA, the supplied 2020 symbol executable, and open-source Marathon as corroboration.
|
||||
6. Historical branches and old candidates as hypotheses only.
|
||||
|
||||
Useful local assets include:
|
||||
|
||||
- `C:\Users\isabe\Downloads\Halo Combat Evolved (Jan 14, 2002 prototype)\cachebeta.xbe`
|
||||
- `C:\Users\isabe\Downloads\Halo Combat Evolved (Jan 14, 2002 prototype)\cachebeta.exe`
|
||||
- `C:\Users\isabe\Downloads\Halo Combat Evolved (Jan 14, 2002 prototype)\cachebeta.pdb`
|
||||
- `C:\Users\isabe\Downloads\haloleak2024\halo1\h1_tags\halo_cache_symbols.exe`
|
||||
- `C:\Users\isabe\Downloads\Halo - Combat Evolved (Oct 12, 2001 prototype)\Halo 2276`
|
||||
- `C:\Users\isabe\Documents\Codex\2026-09-20\files-pasted-by-the-user-halo\outputs`
|
||||
- the local Marathon research tree referenced by the campaign documentation.
|
||||
|
||||
Known evidence limits:
|
||||
|
||||
- The January PDB has publics/compiland information but no useful Halo locals, lexical blocks, source lines, or original headers.
|
||||
- The supplied 2020 executable was built with a different compiler and contains confirmed source differences. Its RTC locals, call graphs, assertions, and structural correspondences are corroborating evidence, not automatic January source proof.
|
||||
- HCEA supplies useful types, names, and line information, but it is a different platform/build.
|
||||
- IDA Free 9.4 has no callable automation endpoint here. Do not stall or ask again for one.
|
||||
- Ghidra and DIA are available and authorized.
|
||||
- No additional local full-symbol January build or original Halo source/header archive exists. Do not waste time repeatedly searching for byte-identical copies or asking for nonexistent artifacts.
|
||||
- Decompiler output is reconstructed pseudocode, never original source text.
|
||||
|
||||
Use multiple independent lenses whenever possible: target disassembly, relocation identity, call graph, PDB/MAP identity, cross-build raw instructions, HCEA types, historical compiler behavior, and exact sibling controls.
|
||||
|
||||
## 6. Evidence-backed mechanisms to prioritize
|
||||
|
||||
Astra already established useful, bounded source mechanisms. Use them precisely; do not generalize them beyond their evidence.
|
||||
|
||||
### Actor looking
|
||||
|
||||
The authenticated fuzzy reconstruction establishes:
|
||||
|
||||
- `real look_delta_deviations[2]` and the corresponding private parameter type;
|
||||
- two independently evaluated priority equalities rather than copying the first Boolean result;
|
||||
- the initial `succeeded = FALSE`;
|
||||
- clearing free/optional facing states before installing primary facing.
|
||||
|
||||
The remaining barrier is a concrete stack/register lifetime cascade involving `facing_locked`, `aiming_cosine`, `primary_priority`, the secondary aim-valid result, and desired-facing pointer lifetime. Research authentic owner types, scopes, call-return use, or natural same-compiler donor patterns for this boundary. Do not repeat the already exhausted generic scope/order, stationary-copy, representation-cast, or spelling permutations.
|
||||
|
||||
### Actor moving
|
||||
|
||||
The avoidance packet authenticates array widths, typed aggregate identities, ray/fraction/point families, the transform operation, and several real control facts. The unresolved issue is the genuine January helper/include/inlining mechanism and remaining register lifetime, not a license to emit an unauthorized `point_from_line3d` owner. Seek authentic macro/helper definitions, same-compiler donor call sites, or owner/include evidence. Do not repeat the historical helper-storage-class, force-inline, short-local, clear-first, PIN/MAX, cross-product, or generic flag searches without new evidence.
|
||||
|
||||
### Actor perception
|
||||
|
||||
The authenticated fuzzy patch establishes:
|
||||
|
||||
- one `interesting_orphan_index`;
|
||||
- repeated inner danger predicates that are redundant semantically but supported by original control-flow evidence.
|
||||
|
||||
It fixes the timer and tail structural regions while retaining zero credit. Remaining barriers are a precise call-return scheduling boundary and x87 ordering around squared 2D distance. Seek an authentic helper definition, call-site type context, or natural same-compiler donor. Do not repeat declaration splits, generic scope changes, header-COMDAT distance helpers, or scalar spelling searches already shown inert.
|
||||
|
||||
### AI communication
|
||||
|
||||
The existing packets authenticate much of the possibility-array structure, narrow private types, conversation ownership, and several call relationships. Reconcile the new original private-owner evidence before trying new body shapes. The event residual still has concrete relocation-count differences in actor data, datum access, race lookup, team communication, and low-priority rating paths. Use those relocation multiplicities and January call order as a semantic source-graph diagnostic. Do not count frame equality or later-build store order as exact progress.
|
||||
|
||||
### AI debug
|
||||
|
||||
The best authenticated fuzzy body restores:
|
||||
|
||||
- the fifth activation-marker point;
|
||||
- the vision-cone zero-vector/accumulation graph;
|
||||
- January’s target extent and relocation count.
|
||||
|
||||
Its remaining differences are allocation/scheduling and possibly still-unrecovered scalar lifetimes. Use the 94 protected-local records and direct January references as lower-bound lifetime evidence only. Do not infer complete lifetimes, lexical scopes, or 72/80-byte buffer extents from RTC records alone. Preserve the inherited genuine `point_from_line3d` ownership exactly; do not add, remove, or duplicate it casually.
|
||||
|
||||
### Small AI units
|
||||
|
||||
For the six small units, prioritize:
|
||||
|
||||
- unwritten or placeholder bodies;
|
||||
- authentic private names from January/HCEA/MAP evidence;
|
||||
- wrong scalar widths or enum types;
|
||||
- missing calls and relocation multiplicity;
|
||||
- genuine control-flow topology;
|
||||
- incorrect owner/linkage;
|
||||
- wrong constants already catalogued in `docs/common_constants.md`;
|
||||
- historical best source that was never reconciled onto this baseline.
|
||||
|
||||
Do not assume “small residual” means an allocator tie. Inspect the raw function and relocations first.
|
||||
|
||||
## 7. Complete house rules
|
||||
|
||||
Apply all of these to every retained source change:
|
||||
|
||||
1. Format a no-argument parameter list with `void` on its own line inside the parentheses.
|
||||
2. Put every parameter on its own line.
|
||||
3. End every function, including `void` functions, with an explicit valid `return;`; non-void functions must return an appropriate value.
|
||||
4. Use subsystem typed macros wrapping `tag_get` for typed tag access.
|
||||
5. Use typed object-access macros rather than repeated casts after raw `object_get`.
|
||||
6. Preserve January’s inline schedule. Do not introduce an unauthorized `point_from_line3d` COMDAT or alter its selected owner.
|
||||
7. Name private functions authentically when evidence exists; otherwise use a credible project-style descriptive name. Never add `code_XXXXXXXX` or address-based names.
|
||||
8. Name globals authentically or descriptively according to project conventions. Never add `bss_XXXXXXXX` names.
|
||||
9. Put function prototypes in their genuine owner. Never hide a missing owner declaration in an unrelated consumer C file.
|
||||
10. Helper and math functions may use inline assembly only sparingly and only with function-specific machine-code evidence that C cannot reproduce naturally.
|
||||
11. If exact matching is not readily achievable, retain only credible source-authentic fuzzy progress, document it, give it zero exact credit, and park it with a concrete reopening condition.
|
||||
12. Prefer small objects and high-confidence closures before prolonged allocator fights.
|
||||
13. Avoid manual or forced inlining. Preserve ordinary helpers and natural compiler scheduling.
|
||||
14. Use open-source Marathon only as a semantic/style reference, never as January byte proof.
|
||||
15. If a C file lacks a dedicated header, use the closest genuine associated owner header. Since headers are outside this lane’s write scope, document the needed owner change rather than creating a local facade.
|
||||
16. Use correct named enum constants in switch tables and comparisons.
|
||||
17. Declare and initialize variables together when natural and consistent with genuine source lifetime.
|
||||
18. Prefer established `cseries.h` macros over manual flag and bit manipulation.
|
||||
19. Use project-defined types such as `real`, `boolean`, `byte`, `short`, and `long`, not generic substitutes such as `float`, `bool`, or fixed-width types unless the project itself requires them.
|
||||
20. Reject fake matching and source forms that almost certainly were not present in the original.
|
||||
21. Reject nonsensical logic even if it happens to byte-match.
|
||||
22. Use `/QIfist` only when target/compiler evidence requires it, only for the relevant TU, and only after checking every function and caller affected by that option.
|
||||
23. Use the correct `assert`, `dassert`, `vassert`, `warn`, `dwarn`, `vwarn`, `halt`, `dhalt`, and `vhalt` family contracts. Assertion predicates describe the required true invariant. Diagnostics must remain lazy. Do not manually expand one into `display_assert`/`system_exit` merely to shape bytes.
|
||||
24. Preserve authentic January bugs only when direct evidence proves them. Mark them with a precise `BUG:` comment where project policy requires it. Do not invent undefined behavior, uninitialized reads, overflows, invalid aliasing, or out-of-bounds access to steer code generation.
|
||||
25. A strict match does not excuse implausible source. Equality is necessary but not sufficient for admission.
|
||||
26. Do not add dead locals, redundant stores, duplicate calls, empty branches, goto-next-label constructs, self-assignments, volatile reinterpretation, arbitrary union punning, raw-byte emission, linker tricks, or code-generation pragmas unless independent evidence authenticates that exact construct.
|
||||
27. Do not use manual machine bytes or edit target objects.
|
||||
28. Do not change the comparator, normalization rules, semantic-credit policy, or acceptance thresholds.
|
||||
29. Do not trade away an inherited exact function for a larger gross gain.
|
||||
30. Preserve code, data, BSS/COMMON, relocation, linkage, COMDAT, and selected-owner topology.
|
||||
31. Correct fuzzy code gets zero exact credit. Never call 100% diagnostic similarity strict exact unless the strict comparator and ownership checks agree.
|
||||
32. Function exactness and whole-object completion are separate claims. Do not mark an object complete until all target owners, data, selected providers, extra owners, and veto conditions have been audited.
|
||||
33. Do not count external Xbox/vendor code toward this Halo lane.
|
||||
34. Do not count already-exact baseline work, embedded labels, alias duplicates, documentation, configuration edits, or repeated historical work as new bytes.
|
||||
35. Do not fabricate original names. A unique byte match from `namegap.py` is a proposal, not name provenance.
|
||||
|
||||
## 8. Parallel worker architecture
|
||||
|
||||
Use subagents aggressively, but keep their responsibilities disjoint.
|
||||
|
||||
Recommended structure:
|
||||
|
||||
- One worker per C file, or one worker for each small-file group with no overlapping file.
|
||||
- Dedicated research workers may inspect evidence for actor looking, moving, perception, communication, and debug.
|
||||
- Workers may read anything but may write only scratch candidates and reports.
|
||||
- Workers must not run Ninja, edit shared configuration, commit, push, or land directly in production.
|
||||
- Workers compile with `tools/campaign/gate.py` into PID-specific scratch objects.
|
||||
- The orchestrator independently reviews and lands minimal patches.
|
||||
- Every landed function receives a separate adversarial review by a worker that did not author it.
|
||||
- Do not let multiple workers edit the same production file.
|
||||
- Do not let workers change build outputs used by another worker.
|
||||
|
||||
Each worker brief must include:
|
||||
|
||||
- exact baseline commit;
|
||||
- exact owned C file;
|
||||
- current exact/residual/unwritten census;
|
||||
- existing parks and prior rejected hypotheses;
|
||||
- mandatory evidence files;
|
||||
- house rules;
|
||||
- required before/after gate;
|
||||
- owner/data/COMMON/point guard;
|
||||
- prohibition on production/config/header edits;
|
||||
- exact/fuzzy accounting rules.
|
||||
|
||||
## 9. Baseline workflow
|
||||
|
||||
Before production edits:
|
||||
|
||||
1. Run the full baseline build:
|
||||
|
||||
`ninja -j4 all_source progress semantic_progress`
|
||||
|
||||
2. Save a stable snapshot:
|
||||
|
||||
`python -m tools.campaign.stable_verdicts snapshot scratch/lane-a-before.json`
|
||||
|
||||
3. Save copies of:
|
||||
|
||||
- `build/semantic_report.json`
|
||||
- the progress report;
|
||||
- parked-function validation output;
|
||||
- object-admission audit output;
|
||||
- fake-match scan output;
|
||||
- per-unit `board.py` and `gate.py --all` results;
|
||||
- owner/data/COMMON/point inventories for all 11 units.
|
||||
|
||||
4. Validate parks:
|
||||
|
||||
`python -m tools.parked_functions`
|
||||
|
||||
5. Run object-admission audit:
|
||||
|
||||
`python tools/audit_object_admission.py`
|
||||
|
||||
6. Run tests:
|
||||
|
||||
`python -m pytest -q tools`
|
||||
|
||||
7. Run a fake-match baseline scan:
|
||||
|
||||
`python tools/fake_match_scan.py --format json source/ai`
|
||||
|
||||
8. Record the exact compiler flags for all 11 TUs from `build.ninja`.
|
||||
|
||||
9. For each unit, inventory:
|
||||
|
||||
- January function owners;
|
||||
- current candidate owners;
|
||||
- exact/residual/unwritten status;
|
||||
- meaningful and padded size;
|
||||
- normalized hashes;
|
||||
- relocation count and identities;
|
||||
- linkage/storage class;
|
||||
- parks and reopening criteria;
|
||||
- target and candidate data sections;
|
||||
- COMMON/BSS;
|
||||
- point-helper definitions;
|
||||
- target-absent candidate owners.
|
||||
|
||||
## 10. Function-level workflow
|
||||
|
||||
For each candidate:
|
||||
|
||||
1. Read current source and all prior reports first.
|
||||
2. Confirm it is not already exact or already accepted under another identity.
|
||||
3. Use `git log --all -- <file>` and `tools/campaign/branch_sweep.py` to census distinct historical source, but do not treat historical code as admitted.
|
||||
4. Inspect target and candidate using:
|
||||
|
||||
- `tools/campaign/gate.py`
|
||||
- `tools/campaign/alndiff.py`
|
||||
- `tools/campaign/tinfo.py`
|
||||
- `tools/campaign/relocdiff.py`
|
||||
- `tools/bijection_walk.py` where allocation bijection matters
|
||||
- `tools/campaign/namegap.py` only for identity proposals
|
||||
- Ghidra/DIA/raw PDB or MAP evidence as relevant.
|
||||
|
||||
5. Diagnose semantic structure before editing:
|
||||
|
||||
- missing or extra calls;
|
||||
- relocation multiplicity;
|
||||
- parameter width;
|
||||
- return type;
|
||||
- enum width/value;
|
||||
- aggregate identity/layout;
|
||||
- branch topology;
|
||||
- loop shape;
|
||||
- expression order;
|
||||
- source-owned repeated predicates or stores;
|
||||
- helper ownership and inlining;
|
||||
- local lifetime and scope;
|
||||
- declaration initialization;
|
||||
- frame extent;
|
||||
- x87 stack order;
|
||||
- calling convention and linkage.
|
||||
|
||||
6. Test bounded evidence-backed shapes with in-memory edits or scratch copies. Do not perform combinatorial permutation searches or random spelling sweeps.
|
||||
|
||||
7. Require a strict function gate for exact claims.
|
||||
|
||||
8. For changed units, compare the complete unit and preserve every inherited exact sibling.
|
||||
|
||||
9. Run the emitted-symbol point guard wherever January does not own the helper. For `ai_debug`, preserve its inherited genuine owner byte-for-byte and prevent any duplicate owner.
|
||||
|
||||
10. Run the fake-match scanner on every changed file and manually adjudicate every new lead.
|
||||
|
||||
11. Compare all codeowners, data, COMMON, runtime sections, relocations, linkage, COMDAT selection, and target-absent owners.
|
||||
|
||||
12. If still fuzzy, compare it against baseline. Retain it only if it is semantically more authentic and materially improves a documented structural defect. Similarity percentage alone is not enough.
|
||||
|
||||
13. For every rejected shape, save a concise negative result so later workers do not repeat it.
|
||||
|
||||
## 11. Config policy
|
||||
|
||||
No header changes are permitted.
|
||||
|
||||
Narrow configuration changes are allowed only as follows:
|
||||
|
||||
### `config/parked.json`
|
||||
|
||||
You may change entries only for functions in the 11 allowed TUs.
|
||||
|
||||
- Remove a park only when the function is independently verified strict exact.
|
||||
- Re-baseline an improved fuzzy function only when the retained source is house-rule compliant, genuinely better supported, and its new measurements and evidence are documented.
|
||||
- Do not change unrelated parks.
|
||||
- Do not use a park edit to hide a regression.
|
||||
- Keep fuzzy bytes at zero credit.
|
||||
|
||||
### `config/symbols.json`
|
||||
|
||||
You may edit only an entry belonging to an allowed TU and only when an original or independently authenticated name is established through January PDB/MAP, original source, or sufficiently strong private-symbol/call-graph evidence.
|
||||
|
||||
- A byte-equal alias or `namegap.py` proposal alone is insufficient.
|
||||
- Do not rename target symbols merely to make the comparator agree.
|
||||
- Land the name and corresponding source owner atomically.
|
||||
- Preserve old/new file offset, evidence source, and identity reasoning in the manifest.
|
||||
|
||||
### `config/config.json`
|
||||
|
||||
A per-TU `/QIfist` or whole-object status change is allowed only with direct target/compiler evidence and complete unit validation.
|
||||
|
||||
- No blanket compiler-option changes.
|
||||
- No unrelated object changes.
|
||||
- No “Matching” status until complete owner/data/extra-owner audit passes.
|
||||
- Do not add a semantic-match exception for a nonexact function.
|
||||
|
||||
No other configuration or policy file may change.
|
||||
|
||||
## 12. Wave cadence and commits
|
||||
|
||||
Work in coherent waves. Do not wait for exactly 10,000 bytes if a clean smaller wave is ready, but avoid one tiny commit per leaf unless isolation is necessary.
|
||||
|
||||
Suggested waves:
|
||||
|
||||
- Wave A1: small-unit closures.
|
||||
- Wave A2: actor looking and moving.
|
||||
- Wave A3: communication and perception.
|
||||
- Wave A4: AI debug and portfolio closeout.
|
||||
- Additional waves are allowed when evidence supports them.
|
||||
|
||||
For each wave:
|
||||
|
||||
1. Land minimal production/config patches.
|
||||
2. Independently review every changed function.
|
||||
3. Run all per-function and complete-TU gates.
|
||||
4. Run full Ninja once for the coherent batch.
|
||||
5. Take a stable after snapshot and diff against the frozen baseline, not merely the previous wave.
|
||||
6. Recompute semantic accepted bytes.
|
||||
7. Validate parks and admissions.
|
||||
8. Run changed-file fake scans and owner/data/COMMON/point checks.
|
||||
9. Run `git diff --check`.
|
||||
10. Commit code, config, and its evidence report together.
|
||||
|
||||
At each cumulative 10,000 newly verified meaningful-byte checkpoint, also run the full tools test suite and record the refreshed treemap/progress inputs. Do not claim the checkpoint until the semantic accepted ledger proves it.
|
||||
|
||||
Never squash away the evidence boundaries. Keep an ordered, cherry-pickable commit series.
|
||||
|
||||
## 13. Verification and accounting
|
||||
|
||||
Maintain these totals separately:
|
||||
|
||||
1. **New strict meaningful Halo bytes** — authoritative campaign credit from the accepted semantic ledger.
|
||||
2. **New strict padded bytes** — physical function-section gain from stable comparison.
|
||||
3. **New strict functions**.
|
||||
4. **Fuzzy meaningful bytes changed or improved** — always zero exact credit.
|
||||
5. **Whole-object completions** — separate status, never duplicate function credit.
|
||||
6. **Regressions** — must remain zero.
|
||||
|
||||
Do not report:
|
||||
|
||||
- diagnostic similarity as byte credit;
|
||||
- target-size totals for nonexact bodies as “progress”;
|
||||
- already exact functions as new;
|
||||
- config-only identity changes without admission proof;
|
||||
- external/vendor bytes;
|
||||
- duplicate aliases or embedded labels;
|
||||
- gross gains that conceal losses.
|
||||
|
||||
Every exact row in the final manifest must include:
|
||||
|
||||
- unit;
|
||||
- function;
|
||||
- meaningful bytes;
|
||||
- padded bytes;
|
||||
- target section/index;
|
||||
- target and candidate normalized SHA-256;
|
||||
- relocation count and identity result;
|
||||
- before/after verdict;
|
||||
- evidence basis;
|
||||
- reviewer;
|
||||
- source commit;
|
||||
- owner/data/COMMON/point result.
|
||||
|
||||
Every fuzzy row must include:
|
||||
|
||||
- zero credit explicitly;
|
||||
- baseline and final measurements;
|
||||
- what source defect was corrected;
|
||||
- why the retained code is more authentic;
|
||||
- remaining differing regions;
|
||||
- rejected alternatives;
|
||||
- precise reopening evidence.
|
||||
|
||||
## 14. Final verification
|
||||
|
||||
On final tip:
|
||||
|
||||
1. Confirm `git status --short` is empty.
|
||||
2. Run:
|
||||
|
||||
`ninja -j4 all_source progress semantic_progress`
|
||||
|
||||
3. Save:
|
||||
|
||||
`python -m tools.campaign.stable_verdicts snapshot scratch/lane-a-after.json`
|
||||
|
||||
4. Diff against the frozen baseline snapshot:
|
||||
|
||||
`python -m tools.campaign.stable_verdicts diff scratch/lane-a-before.json scratch/lane-a-after.json`
|
||||
|
||||
5. Run:
|
||||
|
||||
- `python -m tools.parked_functions`
|
||||
- `python tools/audit_object_admission.py`
|
||||
- `python tools/fake_match_scan.py --format json source/ai`
|
||||
- `python -m pytest -q tools`
|
||||
- `git diff --check 6130661c9585fdb2785b3ff6bdb2ad0cfef0520c..HEAD`
|
||||
|
||||
6. Verify all inherited exact functions remain exact.
|
||||
7. Verify no production C/H file outside the 11-file allowlist changed.
|
||||
8. Verify no Xbox/vendor source changed.
|
||||
9. Verify no target object, build tool, compiler, comparator, or acceptance policy changed.
|
||||
10. Verify all data, COMMON/BSS, owner, linkage, COMDAT, and point-helper inventories.
|
||||
11. Verify every retained fake-scan lead is inherited or individually evidence-approved.
|
||||
12. Recompute exact meaningful and padded gains from final production, not worker self-reports.
|
||||
13. List the ordered commit range from baseline to tip.
|
||||
14. Do not push and do not touch canonical.
|
||||
|
||||
## 15. Required deliverables
|
||||
|
||||
Create:
|
||||
|
||||
- `docs/object_matching_logs/claude_lane_a_ai_core_HANDOFF_20260920.md`
|
||||
- `docs/object_matching_logs/claude_lane_a_ai_core_admission_manifest_20260920.json`
|
||||
- `docs/object_matching_logs/claude_lane_a_ai_core_rejected_hypotheses_20260920.md`
|
||||
|
||||
The handoff must contain:
|
||||
|
||||
- worktree, branch, baseline, and final tip;
|
||||
- exact ordered commits;
|
||||
- complete changed-file list;
|
||||
- baseline and final accepted totals;
|
||||
- strict meaningful, padded, and function gains;
|
||||
- fuzzy extent at zero credit;
|
||||
- zero-regression proof;
|
||||
- per-wave results;
|
||||
- per-function evidence;
|
||||
- config changes and why;
|
||||
- all header prerequisites deferred;
|
||||
- every remaining owner and reopening condition;
|
||||
- verification commands and actual outputs;
|
||||
- whether the tree is clean;
|
||||
- explicit statement: nothing pushed and canonical untouched.
|
||||
|
||||
The JSON manifest must be machine-readable and include hashes, measurements, relocations, evidence, reviewer decisions, exact/fuzzy disposition, and credit for every retained change.
|
||||
|
||||
Preserve compact reproducible scratch evidence locally, but do not commit huge generated disassemblies, copied binaries, object files, or private symbol assets. Record their paths and hashes in the handoff.
|
||||
|
||||
## 16. Completion standard
|
||||
|
||||
Do not stop because one large function reaches an allocator tie. Move to the next function and continue the portfolio.
|
||||
|
||||
Do not declare the lane “exhausted” unless:
|
||||
|
||||
- every residual/unwritten owner in all 11 units was inventoried;
|
||||
- previous work was checked for duplication;
|
||||
- all existing high-confidence Astra mechanisms were either integrated, rejected with current evidence, or superseded;
|
||||
- every new evidence-backed structural hypothesis was tested in bounded form;
|
||||
- every retained change follows the house rules;
|
||||
- every exact claim passed strict production verification;
|
||||
- every nonexact improvement is explicitly zero credit;
|
||||
- every untouched blocker has a concrete reopening condition rather than a generic “compiler tie” label.
|
||||
|
||||
The desired outcome is the largest defensible strict gain possible from these 79,657 remaining Halo-owned bytes, plus a materially better research boundary for everything not yet exact. Source authenticity, semantics, ownership, and zero regressions take precedence over a large but artificial headline number.
|
||||
@@ -0,0 +1,444 @@
|
||||
HALO JANUARY EXACT-MATCH CAMPAIGN — CLAUDE LANE B
|
||||
AI ACTIONS, PATHFINDING, GAMEPLAY, PHYSICS/COLLISION, BIPEDS/UNITS/VEHICLES
|
||||
|
||||
MISSION
|
||||
|
||||
Work only from canonical commit:
|
||||
|
||||
6130661c9585fdb2785b3ff6bdb2ad0cfef0520c
|
||||
branch: jonas/exact-pilots
|
||||
|
||||
Your lane contains exactly 75,377 currently non-exact meaningful Halo-owned code bytes. Reconstruct as much of this entire allocation as possible, aiming for at least +50,000 newly proven strict meaningful bytes and ultimately all 75,377. Do not manufacture matches to meet the number. If evidence is insufficient, do more research; do not declare human-written Halo code inherently unmatchable.
|
||||
|
||||
This is one of four concurrent, disjoint Claude lanes. Stay inside the source-unit allowlist below. Do not touch Xbox/XDK libraries, Bink/vendor code, libcmt, or any source unit assigned to another lane.
|
||||
|
||||
Administrative “reserved,” “do not spend,” and old lane-scope holds are lifted inside this allowlist. Scientific rejections are not automatically erased: do not repeat an exhausted spelling unless new evidence refutes its premise. Parked functions in this lane may be reopened when new evidence satisfies or invalidates their recorded criteria.
|
||||
|
||||
Do not push. Do not modify the canonical checkout or canonical branch. Work in a new local worktree and branch created directly from 6130661c.
|
||||
|
||||
REQUIRED WORKTREE
|
||||
|
||||
Create a clean worktree such as:
|
||||
|
||||
C:\halo-worktrees\claude-lane-b-ai-physics-units-20260920
|
||||
branch: claude/lane-b-ai-physics-units-20260920
|
||||
|
||||
If either name already exists, use a unique suffixed name. Never reset, delete, clean, or repurpose an existing worktree.
|
||||
|
||||
Before editing, prove:
|
||||
|
||||
- `git rev-parse HEAD` is exactly `6130661c9585fdb2785b3ff6bdb2ad0cfef0520c`.
|
||||
- `git status --short` is empty.
|
||||
- The configured full build passes.
|
||||
- A complete stable-verdict snapshot has been saved.
|
||||
- Baseline meaningful, padded, function, object, park, and test totals have been recorded.
|
||||
|
||||
ALLOWED SOURCE UNITS — NO OTHERS
|
||||
|
||||
The values are the current meaningful residual-byte ceilings at the frozen baseline.
|
||||
|
||||
AI/action/path family — 20,507 bytes:
|
||||
|
||||
- `source/ai/action_charge.c` — 3,246
|
||||
- `source/ai/action_converse.c` — 248
|
||||
- `source/ai/action_obey.c` — 984
|
||||
- `source/ai/action_vehicle.c` — 1,679
|
||||
- `source/ai/actions.c` — 1,981
|
||||
- `source/ai/actor_combat.c` — 1,529
|
||||
- `source/ai/actor_type_flood.c` — 1,295
|
||||
- `source/ai/actor_type_infection.c` — 3,609
|
||||
- `source/ai/path.c` — 2,783
|
||||
- `source/ai/path_obstacle_avoidance.c` — 1,569
|
||||
- `source/ai/path_obstacles.c` — 160
|
||||
- `source/ai/path_smoothing.c` — 326
|
||||
- `source/ai/path_structure_bsp.c` — 1,098
|
||||
|
||||
Game family — 5,186 bytes:
|
||||
|
||||
- `source/game/aim_assist.c` — 1,173
|
||||
- `source/game/game.c` — 92
|
||||
- `source/game/game_engine_king.c` — 444
|
||||
- `source/game/game_engine_race.c` — 215
|
||||
- `source/game/player_control.c` — 1,577
|
||||
- `source/game/players.c` — 1,685
|
||||
|
||||
Memory family — 821 bytes:
|
||||
|
||||
- `source/memory/stack_memory_pool.c` — 821
|
||||
|
||||
Physics/collision family — 25,691 bytes:
|
||||
|
||||
- `source/physics/breakable_surfaces.c` — 4,020
|
||||
- `source/physics/collision_bsp.c` — 3,158
|
||||
- `source/physics/collision_debug.c` — 4,182
|
||||
- `source/physics/collisions.c` — 4,744
|
||||
- `source/physics/physics.c` — 9,587
|
||||
|
||||
Scenario family — 380 bytes:
|
||||
|
||||
- `source/scenario/wind.c` — 380
|
||||
|
||||
Units family — 22,792 bytes:
|
||||
|
||||
- `source/units/biped_limp_noodle.c` — 3,443
|
||||
- `source/units/bipeds.c` — 13,147
|
||||
- `source/units/unit_dialogue.c` — 1,041
|
||||
- `source/units/units.c` — 48
|
||||
- `source/units/vehicles.c` — 5,113
|
||||
|
||||
The corresponding genuine owner headers may be changed only when required for one of these units and only under the header protocol below. Do not edit generic shared headers such as `cseries.h`, `real_math.h`, object/tag core headers, bitmap headers, weapon headers, or unrelated subsystem headers. If a correct reconstruction requires an out-of-lane shared-header change, preserve the source candidate in scratch, document the exact required header packet and blast radius, and continue elsewhere.
|
||||
|
||||
The only permitted non-source edits are:
|
||||
|
||||
- lane-specific entries in `config/parked.json`;
|
||||
- independently authenticated lane-specific names in `config/symbols.json`;
|
||||
- lane documentation under `docs/object_matching_logs/`.
|
||||
|
||||
Do not edit build flags, tools, `semantic_matches.json`, semantic overrides, object-admission overrides, or unrelated configuration to make a candidate appear accepted.
|
||||
|
||||
READ THESE BEFORE EDITING
|
||||
|
||||
Read these files completely:
|
||||
|
||||
- `docs/campaign_house_rules.md`
|
||||
- `docs/campaign_throughput_lessons.md`
|
||||
- `docs/common_constants.md`
|
||||
- `docs/assertions.md`
|
||||
- `docs/matching_methodology.md`
|
||||
- `docs/exact_match_acceleration_playbook.md`
|
||||
- `docs/object_matching_logs/opus5_next150_compiler_laws_20260916.md`
|
||||
- `docs/object_matching_logs/opus5_next150_compiler_laws_round2_20260916.md`
|
||||
- `docs/object_matching_logs/astra_90pct_canonical_reconciliation_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_HANDOFF_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_research_atlas_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_rejected_hypotheses_20260920.md`
|
||||
- `docs/object_matching_logs/astra_90pct_admission_manifest_20260920.json`
|
||||
|
||||
Then read the relevant Astra evidence before touching its corresponding family:
|
||||
|
||||
- action charge:
|
||||
- `astra_90pct_wave13_action_charge_setup_20260920.md`
|
||||
- `astra_90pct_wave13_action_charge_primary_independent_20260920.md`
|
||||
- `astra_90pct_wave13_action_charge_independent_20260920.md`
|
||||
- `astra_90pct_wave13_call_sequence_census_20260920.md`
|
||||
- `astra_90pct_research8_action_charge_20260920.md`
|
||||
- `astra_90pct_research8_action_charge_independent_20260920.md`
|
||||
- aim assist:
|
||||
- `astra_90pct_research8_aim_assist_20260920.md`
|
||||
- `astra_90pct_research8_aim_assist_independent_20260920.md`
|
||||
- infection:
|
||||
- `astra_90pct_research7_infection_20260920.md`
|
||||
- collisions:
|
||||
- `astra_90pct_wave2_collisions_20260920.md`
|
||||
- physics:
|
||||
- `astra_90pct_wave4_physics_20260920.md`
|
||||
- `astra_90pct_wave4_physics_independent_review_20260920.md`
|
||||
- `astra_90pct_wave4_frame_statistics_20260920.md`
|
||||
- collision debug:
|
||||
- `astra_90pct_wave6_collision_debug_20260920.md`
|
||||
- bipeds:
|
||||
- `astra_90pct_wave3_bipeds_packet_20260920.md`
|
||||
- `astra_90pct_wave3_bipeds_independent_review_20260920.md`
|
||||
- `astra_90pct_research18_bipeds_probe_20260920.md`
|
||||
- `astra_90pct_research18_biped_private_owner_20260920.md`
|
||||
- `astra_90pct_research11_biped_moving_20260920.md`
|
||||
- vehicles:
|
||||
- `astra_90pct_research7_vehicles_20260920.md`
|
||||
- `astra_90pct_vehicle_independent_review_20260920.md`
|
||||
- path/obstacles:
|
||||
- `astra_90pct_wave17_obstacle_owner_20260920.md`
|
||||
- players:
|
||||
- `astra_90pct_wave17_player_probe_20260920.md`
|
||||
- `astra_90pct_wave17_player_private_owner_20260920.md`
|
||||
- `astra_90pct_wave17_player_independent_20260920.md`
|
||||
- `astra_90pct_research16_player_context_20260920.md`
|
||||
|
||||
The complete immutable Astra evidence package is here:
|
||||
|
||||
`C:\Users\isabe\Documents\Codex\2026-09-20\files-pasted-by-the-user-halo\outputs`
|
||||
|
||||
Its `SHA256SUMS.json` and package README define its integrity and contents. The large function atlas is research evidence, not current accounting authority. The current build at 6130661c is authoritative.
|
||||
|
||||
IMPORTANT ASTRA BOUNDARY
|
||||
|
||||
Astra already made `_action_charge_setup` and `_player_examine_nearby_unit` strict exact. They and every other exact baseline function are immutable. Do not “improve,” restyle, or rewrite an exact function.
|
||||
|
||||
Use Astra’s rejected-hypothesis ledger to avoid rerunning identical failed spellings. A negative result is not a permanent ban when you have genuinely new evidence, but state what new evidence invalidates the old premise before spending on it. “Try it again” is not new evidence.
|
||||
|
||||
EVIDENCE SOURCES
|
||||
|
||||
January is the byte authority:
|
||||
|
||||
`C:\Users\isabe\Downloads\Halo Combat Evolved (Jan 14, 2002 prototype)`
|
||||
|
||||
This directory contains the January `cachebeta` XBE variants, `cachebeta.exe`, and `cachebeta.pdb`. The PDB has useful public symbols but lacks Halo local-variable and line records. Do not claim those missing records exist.
|
||||
|
||||
Additional evidence, never interchangeable byte targets:
|
||||
|
||||
- October 2001 prototype:
|
||||
`C:\Users\isabe\Downloads\Halo - Combat Evolved (Oct 12, 2001 prototype)\Halo 2276`
|
||||
- supplied later symbol executables and three original Bungie source files:
|
||||
`C:\Users\isabe\Downloads\haloleak2024\halo1`
|
||||
- open-source Marathon reference:
|
||||
`C:\Users\isabe\Documents\Codex\2026-07-13\i-w\_research-marathon-source-agent-20260904`
|
||||
- locally mirrored public Halo research:
|
||||
- `C:\Users\isabe\Documents\Codex\2026-07-13\i-w\_research-punpck-halo`
|
||||
- `C:\Users\isabe\Documents\Codex\2026-07-13\i-w\_research-stian-halo`
|
||||
- the other `_research-*` trees beside them.
|
||||
|
||||
The supplied 2020 executables have confirmed source differences. They may establish names, types, broad control-flow topology, ownership, and semantic intent, but their instructions are not January byte proof.
|
||||
|
||||
Use Ghidra and DIA where useful. Use the installed IDA Free interactively for ambiguous high-value functions when available, but it has no working callable scripting/RPC interface; do not waste the campaign repeatedly probing for one or declare the lane blocked because IDA cannot be automated. Analyze supplied binaries as data only—never execute them.
|
||||
|
||||
HOUSE RULES — ALL ARE BINDING
|
||||
|
||||
1. Format a no-argument function with `void` on its own line inside the parameter list.
|
||||
2. Put every parameter on its own line.
|
||||
3. End every function with an explicit return: `return;` for `void`, an appropriate value for non-void functions.
|
||||
4. Use subsystem typed macros wrapping `tag_get`; do not scatter raw typed casts.
|
||||
5. Use typed object-access macros instead of repeated casts after raw `object_get`.
|
||||
6. Preserve January’s inline schedule and do not emit a `point_from_line3d` COMDAT.
|
||||
7. Give private functions authentic or descriptive project-style names; never use `code_XXXXXXXX` or address names.
|
||||
8. Give globals authentic or descriptive project-style names; never use `bss_XXXXXXXX` or address names.
|
||||
9. Put prototypes in their genuine owner locations, not unrelated consumer `.c` files.
|
||||
10. Inline assembly is exceptional. It may be used sparingly in a genuine helper/math routine only when target evidence proves ordinary VC7 C cannot emit the required instructions. Earlier asm rulings are function-specific and do not create blanket permission.
|
||||
11. If easy exactness fails, preserve credible, useful fuzzy source, document it, and park it at zero credit.
|
||||
12. Prioritize small objects and small unwritten functions within these substantially reconstructed families.
|
||||
13. Avoid manual or forced inlining. Reproduce the natural helper boundary and January schedule.
|
||||
14. Use Marathon as a style/semantic reference, not as January byte proof.
|
||||
15. If a `.c` file has no dedicated header, use the closest genuine associated header.
|
||||
16. Use correct enum constants in switch tables; do not replace missing research with raw magic case numbers.
|
||||
17. Combine declaration and initialization when practical and source-authentic.
|
||||
18. Prefer appropriate `cseries.h` macros over manual bitwise logic.
|
||||
19. Use project-defined types such as `real`, not generic substitutes such as `float`.
|
||||
20. Reject fake matching and source Bungie almost certainly would not have written.
|
||||
21. Reject nonsensical logic even when it coincidentally byte-matches.
|
||||
22. Use `/QIfist` only where target/compiler evidence requires it. It is a per-TU property, not a blanket flag. Audit the complete TU and callers before changing it.
|
||||
23. Assertions/warnings/halts must follow `docs/assertions.md`. Predicates state required invariants, diagnostics remain lazy, and the weapon-connected example requires `!TEST_FLAG(...)`. Do not hand-expand `display_assert` when the genuine `assert`/`dassert`/`vassert` family is appropriate.
|
||||
24. Never invent undefined behavior, uninitialized reads, out-of-bounds access, representation punning, volatile steering, dummy locals, redundant assignments, self-assignments, impossible conditions, raw-byte emission, pragmas, compiler barriers, fake globals, or arbitrary struct offsets to force bytes.
|
||||
25. If January conclusively proves an original bug that cannot be expressed in defined natural C, preserve the evidence and candidate at zero credit and request a narrow owner ruling. Do not silently land UB.
|
||||
26. Correct semantics, ABI, linkage, symbol ownership, data ownership, and source authenticity are required in addition to byte equality.
|
||||
|
||||
STRICT CREDIT
|
||||
|
||||
A function receives exact credit only when the current strict comparator proves the January and candidate sections identical, including size, normalized bytes, relocation layout and identities, and the required section/owner metadata.
|
||||
|
||||
Do not count:
|
||||
|
||||
- fuzzy or parked functions;
|
||||
- “100%” fuzzy similarity;
|
||||
- same-size functions;
|
||||
- matching relocation counts without matching instructions;
|
||||
- semantic overrides;
|
||||
- asm-implemented or externally supplied rows;
|
||||
- padded alignment bytes as meaningful bytes;
|
||||
- pre-existing exact functions;
|
||||
- worker estimates;
|
||||
- renamed functions without independent name provenance;
|
||||
- whole objects whose data/BSS/linkage/extra-owner state has not been audited.
|
||||
|
||||
Keep these totals separate in every report:
|
||||
|
||||
1. newly strict exact functions;
|
||||
2. newly strict meaningful code bytes from the accepted ledger;
|
||||
3. newly strict padded bytes from stable-verdict diff;
|
||||
4. credible fuzzy bytes retained at zero credit;
|
||||
5. object-level completions after complete code/data/ownership audit.
|
||||
|
||||
Do not mark an object green/Matching merely because all visible functions look exact.
|
||||
|
||||
ANTI-DUPLICATION AND CURRENT-STATE INVENTORY
|
||||
|
||||
Before source work:
|
||||
|
||||
1. Run the current board on every allowed unit.
|
||||
2. Record each target function’s target-section identity, baseline status, meaningful/padded size, relocation count, frame size, and current owner.
|
||||
3. Query the Astra function atlas, handoff, and rejection ledger by function.
|
||||
4. Run `tools/campaign/branch_sweep.py` for each allowed source file to locate better historical bodies without blindly cherry-picking them.
|
||||
5. Map promising blobs back to commits and read their ledgers/reviews.
|
||||
6. Treat historical code only as a donor hypothesis. Recompile against 6130661c and re-audit it under current house rules.
|
||||
7. Never assign two workers the same `.c` file.
|
||||
8. Never count a function already exact at baseline as a lane gain.
|
||||
|
||||
Use the current source/config trees, not an old patch, old all-lanes treemap union, or a prior worker’s headline total.
|
||||
|
||||
THROUGHPUT STRATEGY
|
||||
|
||||
Do not spend the campaign fighting one register-allocation tie while unwritten or structurally wrong functions remain.
|
||||
|
||||
Start with a closeout wave over the smallest residual objects:
|
||||
|
||||
- `units` — 48
|
||||
- `game` — 92
|
||||
- `path_obstacles` — 160
|
||||
- `game_engine_race` — 215
|
||||
- `action_converse` — 248
|
||||
- `path_smoothing` — 326
|
||||
- `wind` — 380
|
||||
- `game_engine_king` — 444
|
||||
- `stack_memory_pool` — 821
|
||||
- `action_obey` — 984
|
||||
|
||||
Within every unit, prioritize:
|
||||
|
||||
1. unwritten bodies;
|
||||
2. proven missing calls/helper boundaries/incorrect signatures or types;
|
||||
3. structural control-flow and frame-layout defects;
|
||||
4. exact historical donors that pass current authenticity review;
|
||||
5. only then near-tie scheduling/x87/register residuals.
|
||||
|
||||
After a few bounded source-shape attempts without new evidence, move to another function. Do not create a bespoke Python tester for every 200–500 byte function. Use the universal gate, relocation diff, aligned disassembly, and stable sweep. Add a runtime harness only when behavior or ABI is genuinely ambiguous.
|
||||
|
||||
Return to hard functions after a research pass across:
|
||||
|
||||
- public/private symbol provenance;
|
||||
- caller and callee graphs;
|
||||
- strings/assert paths/line-number evidence;
|
||||
- target relocation identities;
|
||||
- cross-build topology;
|
||||
- analogous exact functions in January;
|
||||
- C2 compiler probes;
|
||||
- Ghidra/IDA/DIA evidence;
|
||||
- original Bungie/Marathon coding idioms.
|
||||
|
||||
A historical park is a research index, not an excuse to stop. Test its explicit reopen criterion. If the criterion is stale or contradicted, reopen it honestly and update only that lane-specific park entry.
|
||||
|
||||
PARALLEL AGENT ARCHITECTURE
|
||||
|
||||
Use an orchestrator plus workers and independent adversarial reviewers.
|
||||
|
||||
- One worker per `.c` file; files must remain strictly disjoint.
|
||||
- Workers use `tools/campaign/gate.py` and scratch objects only.
|
||||
- Workers do not run `ninja`, `configure.py`, full pytest, or shared-build commands.
|
||||
- Workers do not edit headers, config, tools, or commit.
|
||||
- Workers report exact baseline counts and only newly gained functions.
|
||||
- The orchestrator reviews and applies candidates to the real source.
|
||||
- A different agent independently reviews every proposed landing for semantics, house rules, ownership, and exactness.
|
||||
- The orchestrator alone performs full builds, config updates, and commits.
|
||||
|
||||
`gate.py` is safe for concurrent TU work because it writes PID-isolated scratch objects. Useful forms include:
|
||||
|
||||
- `python tools/campaign/gate.py <unit>`
|
||||
- `python tools/campaign/gate.py <unit> --fn <function>`
|
||||
- `python tools/campaign/gate.py <unit> --source <scratch-source>`
|
||||
- `python tools/campaign/gate.py <unit> --edits <json>`
|
||||
- `python tools/campaign/gate.py <unit> --out <scratch-object>`
|
||||
- `python tools/campaign/gate.py <unit> --forbid-emitted-symbol _point_from_line3d --all`
|
||||
|
||||
Do not rely on `gate.py --disas` after instruction counts diverge; it is index-zipped. Use:
|
||||
|
||||
- `python tools/campaign/alndiff.py <unit> <function>`
|
||||
- `python tools/campaign/relocdiff.py <unit> <function>`
|
||||
- `python tools/campaign/tinfo.py <unit> --fn <function>`
|
||||
- `python tools/bijection_walk.py --unit <unit> <function> -v`
|
||||
|
||||
Use spelling sweeps only to test evidence-backed hypotheses. A successful brute-force spelling is not authenticity evidence by itself.
|
||||
|
||||
HEADER PROTOCOL
|
||||
|
||||
Header edits are high risk because VC7 allocation can change in unrelated includers based only on declaration position.
|
||||
|
||||
Before touching a header:
|
||||
|
||||
1. Enumerate every including `.c` with `rg`.
|
||||
2. Prove the declaration belongs in that header.
|
||||
3. Confirm it cannot correctly remain TU-private in the owner `.c`.
|
||||
4. Save a pristine baseline snapshot.
|
||||
5. Make the header change as a separate prerequisite commit.
|
||||
6. Rebuild and compare every dependent TU against pristine.
|
||||
7. Run the whole-tree stable sweep.
|
||||
8. Reject the header change if it loses any inherited exact function, even if the lane’s net total rises.
|
||||
9. Never compensate for a header regression with unrelated source steering.
|
||||
|
||||
Private structs, enums, helpers, and prototypes should remain in their genuine owner TU when historically and semantically appropriate. Public prototypes belong in the real subsystem header, never copied into whichever `.c` happens to call them.
|
||||
|
||||
CONFIG AND NAMING POLICY
|
||||
|
||||
`config/parked.json` may change only for functions in this allowlist:
|
||||
|
||||
- remove an entry after current strict proof;
|
||||
- remeasure it when an admitted source/header change legitimately changes the residual;
|
||||
- add a credible fuzzy landing with measured remaining differences and a concrete reopen criterion.
|
||||
|
||||
`config/symbols.json` may change only when the name has independent evidence from a January public, PDB, source/map artifact, unambiguous cross-build identity plus caller graph, or similarly strong provenance. A unique byte alias is a proposal, not name proof.
|
||||
|
||||
Do not retain `code + address` or `bss + address` identifiers in finished source. If the original private name is unrecoverable, use a descriptive project-convention name, label it as descriptive rather than proven, and document the evidence.
|
||||
|
||||
FULL VERIFICATION
|
||||
|
||||
At baseline:
|
||||
|
||||
- full configured `ninja -j4 all_source progress semantic_progress`;
|
||||
- `python -m tools.campaign.stable_verdicts snapshot scratch/lane_b_before.json`;
|
||||
- `python -m tools.campaign.board`;
|
||||
- park validation;
|
||||
- object-admission audit;
|
||||
- test suite;
|
||||
- changed-scope fake-scan baseline.
|
||||
|
||||
After each coherent wave—and at least every +10,000 newly proven meaningful bytes—the orchestrator must:
|
||||
|
||||
1. run all affected per-function strict gates;
|
||||
2. run the `_point_from_line3d` emitted-symbol guard on every changed TU;
|
||||
3. run a full `ninja -j4 all_source progress semantic_progress`;
|
||||
4. capture a new stable-verdict snapshot;
|
||||
5. diff it against the frozen lane baseline and prove zero exact regressions;
|
||||
6. inspect accepted meaningful totals from the semantic report;
|
||||
7. validate parks with zero stale/invalid entries;
|
||||
8. run the object-admission audit;
|
||||
9. run `tools/fake_match_scan.py` over every changed source file and adjudicate every new finding;
|
||||
10. audit emitted code/data/COMMON owners;
|
||||
11. run relevant runtime/ABI tests and the full pytest suite at final;
|
||||
12. run `git diff --check`;
|
||||
13. review the complete diff against the source allowlist.
|
||||
|
||||
No inherited exact regression is permitted. Net gain does not excuse one lost exact function.
|
||||
|
||||
COMMITS
|
||||
|
||||
Commit in coherent, reviewable waves, preferably family/file packets. Keep prerequisite header changes separate. Keep zero-credit fuzzy preservation separate from strict admissions. Do not create a giant opaque final commit.
|
||||
|
||||
Every commit message and wave record must identify:
|
||||
|
||||
- affected units/functions;
|
||||
- new strict meaningful and padded bytes;
|
||||
- fuzzy bytes, separately;
|
||||
- stable regression result;
|
||||
- config/header changes;
|
||||
- evidence used;
|
||||
- independent reviewer result.
|
||||
|
||||
Do not push. Do not merge into `jonas/exact-pilots`. Leave a clean local lane.
|
||||
|
||||
FINAL DELIVERABLES
|
||||
|
||||
Create:
|
||||
|
||||
- `docs/object_matching_logs/claude_lane_b_HANDOFF_20260920.md`
|
||||
- `docs/object_matching_logs/claude_lane_b_admission_manifest_20260920.json`
|
||||
- `docs/object_matching_logs/claude_lane_b_rejected_hypotheses_20260920.md`
|
||||
|
||||
The handoff must include:
|
||||
|
||||
- worktree, branch, frozen base, and final tip;
|
||||
- ordered commit list;
|
||||
- exact changed-file list;
|
||||
- baseline and final accepted ledgers;
|
||||
- newly strict functions with unit, target section, meaningful bytes, padded bytes, relocation counts, and commit;
|
||||
- fuzzy functions retained at zero credit with fresh measurements;
|
||||
- all header/config edits and their blast-radius proofs;
|
||||
- exact-regression proof;
|
||||
- test/build/park/admission/fake-scan results;
|
||||
- remaining function-by-function inventory;
|
||||
- concrete next evidence required for every remaining substantial function;
|
||||
- any candidates held for a narrow owner ruling;
|
||||
- confirmation that no out-of-lane source, vendor library, canonical checkout, or remote branch was touched.
|
||||
|
||||
The JSON manifest must be machine-readable and include baseline/final hashes, per-function evidence, source provenance, strict verdict, semantic-credit status, reviewer decision, and commit hash.
|
||||
|
||||
If context or token budget becomes low, stop launching new probes. Finish the current coherent packet, run the complete verification, commit it, write the handoff/manifest, and leave the tree clean. Do not leave valuable work uncommitted or source claims unsupported.
|
||||
|
||||
Do not stop merely because the headline +50,000 target looks difficult. Continue broad, evidence-driven work across the full 75,377-byte allocation. The valid stopping conditions are:
|
||||
|
||||
- every allocated byte is strict exact; or
|
||||
- every remaining row has received a fresh evidence pass, all admissible improvements are committed, and each unresolved function has a specific documented blocker/reopen criterion rather than a generic “compiler tie” claim.
|
||||
@@ -0,0 +1,564 @@
|
||||
You are Claude Opus 5 running Lane C of the Halo: Combat Evolved January 14, 2002 exact-match campaign.
|
||||
|
||||
Your task is to reconstruct and strictly verify the remaining Halo-owned graphics/UI code assigned below. Work for maximum durable progress, not a brief sampling pass.
|
||||
|
||||
## 1. Frozen baseline and isolation
|
||||
|
||||
The immutable starting point is:
|
||||
|
||||
- Branch: `jonas/exact-pilots`
|
||||
- Commit: `6130661c9585fdb2785b3ff6bdb2ad0cfef0520c`
|
||||
- Canonical checkout, READ ONLY:
|
||||
`C:\Users\isabe\Documents\Codex\2026-07-13\i-w\worktrees\astra-reconcile-20260920`
|
||||
|
||||
Use a dedicated worktree and branch, for example:
|
||||
|
||||
- Worktree: `C:\halo-worktrees\claude-lane-c-graphics-ui-20260920`
|
||||
- Branch: `claude/lane-c-graphics-ui-20260920`
|
||||
|
||||
If that worktree or branch already exists, inspect it instead of blindly recreating it. Before doing any work, prove:
|
||||
|
||||
```text
|
||||
git status --short
|
||||
git rev-parse HEAD
|
||||
```
|
||||
|
||||
The tree must be clean and HEAD must be exactly `6130661c9585fdb2785b3ff6bdb2ad0cfef0520c`.
|
||||
|
||||
Never edit the canonical checkout, never move or reset `jonas/exact-pilots`, and never push. Make local commits only in your dedicated lane. Do not cherry-pick another lane wholesale.
|
||||
|
||||
## 2. Objective
|
||||
|
||||
This lane begins with approximately **83,898 meaningful non-exact Halo code bytes** in its assigned units.
|
||||
|
||||
Campaign target:
|
||||
|
||||
- Primary target: at least **50,000 newly proven strict meaningful exact bytes**.
|
||||
- Stretch target: close the entire **83,898-byte** assigned residual pool.
|
||||
- Also maximize genuinely complete, whole-object `Matching` closures.
|
||||
- Preserve credible, house-rule-compliant fuzzy improvements at zero matching credit when exactness is not yet attainable.
|
||||
|
||||
Do not stop after one or two low-yield waves. Do not declare the target impossible merely by summing current park entries. Parks are prior evidence and hypotheses, not eternal prohibitions; reopen them only when their recorded criteria or genuinely new evidence justify it.
|
||||
|
||||
A lower result is acceptable only after every in-scope residual has received a current-baseline classification and all high-confidence structural opportunities have been pursued. “Register allocation tie” or “compiler noise” requires evidence from the existing classifiers or controlled experiments, not intuition.
|
||||
|
||||
Count only gains relative to commit `6130661c`. Pre-existing exact functions, donor-relative gains, fuzzy bodies, helper COMDATs, and already-integrated Astra work are not new credit.
|
||||
|
||||
## 3. Exclusive source scope
|
||||
|
||||
Only the following Halo translation units are assigned to this lane. The byte figures are starting estimates and must be remeasured at the frozen baseline.
|
||||
|
||||
### Bitmaps — 8,790 bytes
|
||||
|
||||
```text
|
||||
source/bitmaps/bitmap_group.c 995
|
||||
source/bitmaps/bitmap_utilities.c 2,362
|
||||
source/bitmaps/bitmaps.c 1,287
|
||||
source/bitmaps/s3tc/s3tc.c 4,146
|
||||
```
|
||||
|
||||
### Interface/UI — 32,470 bytes
|
||||
|
||||
```text
|
||||
source/interface/first_person_weapons.c 1,533
|
||||
source/interface/hud.c 1,744
|
||||
source/interface/hud_draw.c 364
|
||||
source/interface/hud_messaging.c 2,922
|
||||
source/interface/hud_nav_points.c 1,618
|
||||
source/interface/hud_weapon.c 7,696
|
||||
source/interface/interface.c 2,981
|
||||
source/interface/motion_sensor.c 3,144
|
||||
source/interface/progress_bar.c 349
|
||||
source/interface/ui_widget.c 6,425
|
||||
source/interface/ui_widget_game_data_input_functions.c 1,008
|
||||
source/interface/virtual_keyboard.c 2,686
|
||||
```
|
||||
|
||||
### Rasterizer — 34,352 bytes
|
||||
|
||||
```text
|
||||
source/rasterizer/rasterizer_frame_statistics.c 4,236
|
||||
source/rasterizer/rasterizer_geometry.c 1,179
|
||||
source/rasterizer/rasterizer_lights.c 3,049
|
||||
source/rasterizer/xbox/rasterizer_xbox_active_camouflage.c 2,014
|
||||
source/rasterizer/xbox/rasterizer_xbox_environment.c 4,957
|
||||
source/rasterizer/xbox/rasterizer_xbox_environment_fog.c 4,685
|
||||
source/rasterizer/xbox/rasterizer_xbox_hardware_bitmaps.c 388
|
||||
source/rasterizer/xbox/rasterizer_xbox_hardware_geometry.c 337
|
||||
source/rasterizer/xbox/rasterizer_xbox_lights.c 2,338
|
||||
source/rasterizer/xbox/rasterizer_xbox_models.c 9,553
|
||||
source/rasterizer/xbox/rasterizer_xbox_shadows.c 1,616
|
||||
```
|
||||
|
||||
### Render — 8,286 bytes
|
||||
|
||||
```text
|
||||
source/render/render_cameras.c 4,649
|
||||
source/render/render_particles.c 1,154
|
||||
source/render/render_sprite.c 2,483
|
||||
```
|
||||
|
||||
The arithmetic total for the complete allowlist is **83,898 meaningful residual bytes**.
|
||||
|
||||
The files under `source/rasterizer/xbox/` listed above are Halo-owned Xbox renderer code and are explicitly in scope. Do not classify them as external merely because `xbox` appears in the path.
|
||||
|
||||
Everything else is out of scope:
|
||||
|
||||
- No Xbox SDK/XDK library objects.
|
||||
- No Bink, Direct3D, XAPI, libcmt, zlib, libtiff, or other vendor-library campaign work.
|
||||
- No AI, units, vehicles, networking, physics, effects, sound, game-state, or unrelated renderer files.
|
||||
- Do not modify another lane’s `.c` file to make one of your objects match.
|
||||
|
||||
Related genuine headers and narrowly necessary configuration entries may be changed only under the header/configuration policy below.
|
||||
|
||||
## 4. Required reading before assigning work
|
||||
|
||||
Read these files completely before editing:
|
||||
|
||||
```text
|
||||
docs/campaign_house_rules.md
|
||||
docs/matching_methodology.md
|
||||
docs/exact_match_acceleration_playbook.md
|
||||
docs/campaign_throughput_lessons.md
|
||||
docs/common_constants.md
|
||||
docs/assertions.md
|
||||
docs/user_source_reconstruction_map_20260906.md
|
||||
docs/fake_match_review.md
|
||||
tools/campaign/README.md
|
||||
docs/object_matching_logs/opus5_next150_compiler_laws_20260916.md
|
||||
docs/object_matching_logs/opus5_next150_compiler_laws_round2_20260916.md
|
||||
docs/object_matching_logs/opus5_next150_research_campaign_20260916.md
|
||||
```
|
||||
|
||||
Then search and read every relevant current ledger before touching a function:
|
||||
|
||||
```text
|
||||
docs/object_matching_logs/astra_90pct_*
|
||||
docs/object_matching_logs/*bitmap*
|
||||
docs/object_matching_logs/*hud*
|
||||
docs/object_matching_logs/*interface*
|
||||
docs/object_matching_logs/*widget*
|
||||
docs/object_matching_logs/*motion_sensor*
|
||||
docs/object_matching_logs/*rasterizer*
|
||||
docs/object_matching_logs/*render_camera*
|
||||
docs/object_matching_logs/*render_particle*
|
||||
docs/object_matching_logs/*render_sprite*
|
||||
config/parked.json
|
||||
config/symbols.json
|
||||
```
|
||||
|
||||
Use `rg` by exact unit and function name. Do not rely on filenames alone. Newer Astra ledgers supersede older guesses when they contain fresh measurements, but every candidate must still be remeasured against commit `6130661c`.
|
||||
|
||||
Before assigning a function to a worker, run the existing unclassified/ledger cross-reference workflow described in the compiler-law documents. Determine:
|
||||
|
||||
1. Is it already exact at this baseline?
|
||||
2. Is the same source already integrated under another name?
|
||||
3. Was the proposed shape already tried?
|
||||
4. Is it parked, and what is the explicit reopen criterion?
|
||||
5. Is there a historical branch with a stronger body?
|
||||
6. Is the mismatch structural, relocation/ownership, frame/type, helper-boundary, x87 ordinal, or a proven allocator/scheduling tie?
|
||||
|
||||
Do not duplicate prior work merely because an old handoff started from a lower byte total.
|
||||
|
||||
## 5. Evidence hierarchy and research assets
|
||||
|
||||
Use evidence in this order:
|
||||
|
||||
1. January target object bytes, relocations, section ownership, public symbols, strings, callers, and callees.
|
||||
2. Authentic Bungie source or authenticated same-function cross-build source.
|
||||
3. Earlier/later Halo builds for semantics, names, types, and control-flow hypotheses.
|
||||
4. Open-source Marathon for Bungie style and likely abstractions.
|
||||
5. Compiler micro-labs and corpus-wide laws for source-shape discrimination.
|
||||
6. Pure visual similarity or decompiler output only as a hypothesis.
|
||||
|
||||
Relevant local evidence includes:
|
||||
|
||||
```text
|
||||
C:\Users\isabe\Downloads\Halo Combat Evolved (Jan 14, 2002 prototype)
|
||||
C:\Users\isabe\Downloads\Halo - Combat Evolved (Oct 12, 2001 prototype)\Halo 2276
|
||||
C:\Users\isabe\Downloads\haloleak2024\halo1
|
||||
C:\Users\isabe\Downloads\haloleak2024\halo1\h1_tags
|
||||
C:\Users\isabe\Documents\Codex\2026-07-13\i-w\_research-marathon-source-agent-20260904
|
||||
C:\Users\isabe\Documents\Codex\2026-07-13\i-w\_research-punpck-halo
|
||||
C:\Users\isabe\Documents\Codex\2026-07-13\i-w\_research-stian-halo
|
||||
C:\Users\isabe\Documents\Codex\2026-07-13\i-w\_research-halopc-restored
|
||||
C:\Users\isabe\Documents\Codex\2026-07-13\i-w\_research-demon
|
||||
C:\Users\isabe\Documents\Codex\2026-07-13\i-w\halocea-review
|
||||
C:\Users\isabe\Documents\Codex\2026-07-13\i-w\research
|
||||
C:\Users\isabe\Documents\Codex\2026-07-13\i-w\research-cache
|
||||
C:\Users\isabe\Documents\Codex\2026-07-13\i-w\_research_cache
|
||||
```
|
||||
|
||||
Known limitations:
|
||||
|
||||
- The January `cachebeta.pdb` has useful public symbols but lacks Halo locals and line records.
|
||||
- The supplied 2020 symbol executables have confirmed source differences. Use them for names, types, and semantic hypotheses—not January byte proof.
|
||||
- Use both IDA and Ghidra evidence where available. IDA Free on this machine has no usable headless scripting/RPC interface; do not burn a wave repeatedly trying to automate it. Use an existing interactive IDA database/export if available, and use Ghidra headless plus DIA/public-symbol tooling for repeatable extraction.
|
||||
- Never execute supplied game/tool binaries merely to inspect them.
|
||||
- Decompiler pseudocode is not original source.
|
||||
|
||||
When existing evidence is insufficient, research the target rather than declaring human-written code impossible. Build caller/callee graphs, inspect data and relocation ownership, compare cross-build implementations, search authentic source idioms, and construct narrowly controlled compiler labs. Validate any new “compiler law” against exact controls before applying it.
|
||||
|
||||
## 6. House rules — mandatory
|
||||
|
||||
1. Format a no-argument parameter list with `void` on its own line inside the parentheses.
|
||||
2. Put every parameter on its own line.
|
||||
3. End every function—including `void` functions—with an explicit `return;`. Non-void functions must return an appropriate value, never a bare `return;`.
|
||||
4. Use subsystem macros wrapping `tag_get` for typed tag access.
|
||||
5. Use typed object-access macros rather than repeated casts after raw `object_get` calls.
|
||||
6. Preserve the January inline schedule without emitting a `point_from_line3d` COMDAT.
|
||||
7. Name private functions correctly. Never introduce `code_XXXXXXXX`, `sub_XXXXXXXX`, or address-based private names.
|
||||
8. Name globals correctly. Never introduce `bss_XXXXXXXX` or address-based names. When the original name is unavailable, use a descriptive name consistent with project conventions and label it as inferred.
|
||||
9. Put function prototypes in their genuine owner headers or genuine TU-private location, never in an unrelated consumer `.c` file.
|
||||
10. Helper and math functions may use inline assembly only sparingly and with direct evidence. Existing admitted asm is not blanket precedent for new asm.
|
||||
11. If easy exactness is not achievable, retain the best credible fuzzy reconstruction, document and park it, and grant it zero exact credit.
|
||||
12. Prioritize small functions and near-complete objects within this assigned family, while still researching the larger structural functions.
|
||||
13. Avoid forced/manual inlining. Preserve natural helpers and January’s observed inline schedule.
|
||||
14. Use open-source Marathon as a style and semantic reference, not proof of January bytes.
|
||||
15. If a `.c` file has no dedicated header, use the closest genuine associated header.
|
||||
16. Use proper enum constants in switch tables, not unexplained raw case numbers.
|
||||
17. Declare and initialize variables together when practical and natural.
|
||||
18. Prefer established `cseries.h` macros over manual bit manipulation.
|
||||
19. Use project-defined types such as `real`, `boolean`, `byte`, `word`, and `dword` rather than generic substitutes such as `float`, C++ `bool`, or platform-dependent integers.
|
||||
20. Reject fake matching and source that Bungie almost certainly would not have written.
|
||||
21. Reject nonsensical function logic even if it coincidentally byte-matches.
|
||||
22. Use `/QIfist` only where target/compiler evidence requires it. It is a per-TU option, not a blanket setting.
|
||||
|
||||
Additional fidelity requirements:
|
||||
|
||||
- Use `assert(expression)`, `dassert(expression, diagnostic)`, and `vassert(expression, format, ...)` through the established `cseries.h` owner. Likewise use the established `warn`/`dwarn`/`vwarn` and `halt`/`dhalt`/`vhalt` families. Do not hand-expand them into `display_assert`, formatting buffers, and `system_exit`.
|
||||
- Assertion predicates state the required invariant. Do not accidentally invert them.
|
||||
- Preserve evaluation count, evaluation order, and lazy diagnostics.
|
||||
- No `volatile`, `register`, dummy statements, dead locals, arbitrary buffer inflation, invented globals, compiler barriers, pragmas, raw byte emission, self-assignments, empty branches, goto-next-label tricks, or duplicated equivalent branches merely to steer code generation.
|
||||
- No undefined behavior, uninitialized reads, out-of-bounds accesses, inactive-union-member tricks, representation-punning casts, raw numeric struct offsets, or stack overruns for a match. If January appears to contain a genuine bug, document the evidence and hold it for an owner ruling; do not silently land it.
|
||||
- Do not extend function-specific prior rulings to other functions.
|
||||
- Correct semantics and credible source are admission requirements even when bytes match.
|
||||
|
||||
## 7. Strict exactness, fuzzy work, and accounting
|
||||
|
||||
A function is strict exact only when the established comparator proves:
|
||||
|
||||
- exact function size,
|
||||
- exact normalized code bytes,
|
||||
- exact relocation count,
|
||||
- exact relocation addresses/types,
|
||||
- exact relocation target identities,
|
||||
- and the correct target-function owner.
|
||||
|
||||
Do not call a size/relocation near-tie exact. Do not use semantic overrides or matching allowlists to manufacture credit.
|
||||
|
||||
Maintain three separate totals:
|
||||
|
||||
1. Newly strict **meaningful** code bytes from `build/semantic_report.json`.
|
||||
2. Newly strict padded/function-section bytes from the stable verdict diff.
|
||||
3. Credible fuzzy bytes retained at **zero credit**.
|
||||
|
||||
Also report:
|
||||
|
||||
- strict functions gained,
|
||||
- strict functions lost,
|
||||
- newly complete function-only objects,
|
||||
- newly admitted whole `Matching` objects,
|
||||
- data/BSS/linkage/extra-owner changes,
|
||||
- parks removed, remeasured, stale, or invalid.
|
||||
|
||||
A function-only 100% object is not automatically a whole matching object. Before marking an object `Matching`, prove:
|
||||
|
||||
- every required Halo function is strict exact,
|
||||
- data, rdata, BSS, and COMMON ownership agree,
|
||||
- linkage/storage classes agree,
|
||||
- no extra code or data owner is emitted,
|
||||
- helper/COMDAT ownership agrees with January,
|
||||
- the object is source-authentic,
|
||||
- and the object-admission audit accepts it.
|
||||
|
||||
A blue “100%” result is not green whole-object proof. Halo-owned Xbox rasterizer objects must not be hidden as `external`.
|
||||
|
||||
Never trade away an inherited exact function. Gross gain does not conceal a regression. If an intentional exactness loss is ever proposed, do not land it without an explicit owner ruling and explicit subtraction from the totals.
|
||||
|
||||
## 8. Anti-duplication procedure
|
||||
|
||||
Before editing each unit:
|
||||
|
||||
```text
|
||||
git log --all -- <unit.c>
|
||||
python tools/campaign/branch_sweep.py <unit-without-.c>
|
||||
python tools/campaign/gate.py <unit-without-.c> --all
|
||||
python -m tools.campaign.unparked <unit-without-.c>
|
||||
```
|
||||
|
||||
Search the function and unit name across all ledgers and handoffs. Map any promising historical blob back to its commits and provenance. A historical exact body still needs current-baseline source, owner, ABI, house-rule, and regression review.
|
||||
|
||||
Never count:
|
||||
|
||||
- code already exact at `6130661c`,
|
||||
- code newly exact only because of a symbol alias without authenticated naming evidence,
|
||||
- a donor’s claimed total,
|
||||
- a function that another worker landed earlier in this lane,
|
||||
- helper code not owned by the January object,
|
||||
- or fuzzy code.
|
||||
|
||||
Keep a central assignment ledger so two workers never attack the same TU or function.
|
||||
|
||||
Historical leads such as `_bitmap_2d_sharpen`, `_bitmap_group_add_bitmap`, `_EncodeBlockRGBColorKey`, `_first_person_weapon_update`, `_hud_render_unit_interface`, `_hud_update_weapon`, motion-sensor updates, environment/lightmap/fog functions, and render-camera frustum functions must be remeasured. Their old labels are hypotheses, not instructions. Do not repeat a recorded negative shape unless new evidence directly refutes the old premise.
|
||||
|
||||
## 9. Parallel campaign architecture
|
||||
|
||||
Use agents aggressively, but safely:
|
||||
|
||||
- One implementation worker per `.c` file.
|
||||
- Files must be strictly disjoint.
|
||||
- No worker edits headers, config, shared docs, or another worker’s file.
|
||||
- Workers use `tools/campaign/gate.py`, which writes PID-isolated scratch objects.
|
||||
- Workers do not run `ninja`, `configure.py`, or any command that writes the shared `build/` tree.
|
||||
- Workers do not commit.
|
||||
- Workers record the exact current unit census before editing.
|
||||
- Workers retain only source-authentic improvements and fully revert reductions in strict exactness.
|
||||
- Each landed file receives an independent adversarial review by an agent other than its author.
|
||||
- Only the orchestrator edits genuine shared headers/config, runs full builds, updates parks, and commits.
|
||||
|
||||
Use waves of disjoint TUs. Start with:
|
||||
|
||||
1. Unwritten functions.
|
||||
2. Small functions capable of closing near-complete objects.
|
||||
3. Structural mismatches with a named source-level defect.
|
||||
4. Larger functions where call graph, frame, type width, relocation, or helper-boundary evidence gives a concrete route.
|
||||
5. Pure allocation/x87/scheduling ties only when a new evidenced compiler law supplies a legitimate source lever.
|
||||
|
||||
Eight small closures are preferable to one speculative rewrite. However, do not abandon large objects forever: give their biggest functions dedicated research packets after the easy structural pool is harvested.
|
||||
|
||||
If a wave yields little, preserve its durable negative evidence and immediately pivot to a different mechanism. Do not spend multiple waves permuting declarations or random spellings.
|
||||
|
||||
## 10. Existing tools — use universal gates
|
||||
|
||||
Prefer the committed campaign tools over writing a bespoke Python test for every function:
|
||||
|
||||
```text
|
||||
python tools/campaign/board.py
|
||||
python tools/campaign/board.py <unit>
|
||||
python tools/campaign/gate.py <unit> --fn <function>
|
||||
python tools/campaign/gate.py <unit> --all
|
||||
python tools/campaign/alndiff.py <unit> <function>
|
||||
python tools/campaign/relocdiff.py <unit> <function> --count-by-target
|
||||
python tools/campaign/tinfo.py <unit> --fn <function>
|
||||
python tools/campaign/tinfo.py <unit> --data
|
||||
python tools/campaign/branch_sweep.py <unit>
|
||||
python tools/bijection_walk.py --unit <unit> <function> -v
|
||||
python tools/fake_match_scan.py <changed paths>
|
||||
python -m tools.campaign.unparked <unit>
|
||||
python -m tools.campaign.stable_verdicts snapshot <file>
|
||||
python -m tools.campaign.stable_verdicts diff <before> <after>
|
||||
python -m tools.parked_functions
|
||||
python -m tools.audit_semantic_matches
|
||||
python tools/audit_object_admission.py
|
||||
```
|
||||
|
||||
Use `alndiff.py`, not `gate.py --disas`, when instruction counts diverge; the latter is an index-aligned zip and hides insert/delete boundaries.
|
||||
|
||||
Use the existing frame-slot, x87-mod8, inline-boundary, cross-jump, scheduling-selection, and unclassified-triage detectors described in the compiler-law ledgers. Run their required ordering before inventing source shapes.
|
||||
|
||||
Spelling sweeps and compiler probes are diagnostic only. A winning spelling is not source-authenticity evidence by itself.
|
||||
|
||||
Do not add general tooling unless it solves a genuinely recurring gap. Any committed tool must be tested and documented; otherwise keep research scripts under untracked scratch evidence.
|
||||
|
||||
## 11. Headers and configuration
|
||||
|
||||
Header changes are high-risk because VC7 code generation is definition-position sensitive.
|
||||
|
||||
To keep the four concurrent lanes mechanically reconcilable, do not commit
|
||||
changes to broad cross-lane headers such as `cseries.h`, `real_math.h`, core
|
||||
object/tag headers, or a header genuinely owned by another lane. Preserve any
|
||||
such requirement as a minimal proposed patch with consumer census and strict
|
||||
before/after evidence, then continue elsewhere. Lane C may commit only genuine
|
||||
bitmap, interface, rasterizer, or render owner-header changes whose complete
|
||||
consumer set has been audited under the protocol below.
|
||||
|
||||
Before changing any header:
|
||||
|
||||
1. Identify every `.c` includer with `rg`.
|
||||
2. Prove the declaration belongs in that header.
|
||||
3. Determine whether a TU-private declaration is more authentic.
|
||||
4. Compile pristine and patched header trees for every dependent TU.
|
||||
5. Compare every dependent function’s size, relocations, normalized hash, emitted owners, and data ownership.
|
||||
6. Run a full stable whole-tree diff.
|
||||
7. Obtain an independent reviewer’s approval.
|
||||
8. Commit the header prerequisite in an independently buildable packet.
|
||||
|
||||
Do not keep a header change that gains your object by regressing an unrelated object. Do not “repair” a regression with coincidental declaration ordering.
|
||||
|
||||
Configuration policy:
|
||||
|
||||
- `config/symbols.json`: edit only with authenticated January/PDB/source/caller evidence. Keep a symbol rename and the corresponding source identifiers in the same coherent commit.
|
||||
- `config/parked.json`: orchestrator only. Remove a park when the function is newly exact. Rebaseline a credible fuzzy function only with fresh measurements and dated evidence. Never rebaseline a park to conceal a regression.
|
||||
- `config/config.json` or object `Matching` status: change only after whole-object admission proves code, data, BSS, linkage, extra-owner, and source credibility.
|
||||
- Never add a semantic-match override.
|
||||
- Never broadly change compiler flags. `/QIfist` requires per-TU proof and full consumer/caller verification.
|
||||
|
||||
If a required owner header is shared with an out-of-scope unit, you may make the minimal genuine header change but may not edit the out-of-scope `.c` file. Every consumer must remain exact or unchanged.
|
||||
|
||||
## 12. COMDAT, owner, and inline safeguards
|
||||
|
||||
For every changed TU:
|
||||
|
||||
```text
|
||||
python tools/campaign/gate.py <unit> --forbid-emitted-symbol _point_from_line3d --all
|
||||
```
|
||||
|
||||
This must explicitly pass. Undefined references do not fail the guard; a candidate code definition does.
|
||||
|
||||
Also inspect:
|
||||
|
||||
- target and candidate code-symbol owner sets,
|
||||
- COMDAT selection and storage class,
|
||||
- helper bodies emitted only by the candidate,
|
||||
- missing target helper owners,
|
||||
- data/rdata/BSS/COMMON owners,
|
||||
- relocation target identity and addends,
|
||||
- private versus external linkage.
|
||||
|
||||
Do not gain a caller by changing the wrong helper owner. Preserve January’s observed inline schedule. Do not make shared `real_math.h` inline bodies `static` or otherwise globally change helper emission to fix one object.
|
||||
|
||||
Existing admitted asm such as `fast_ftol` or the already-reviewed color helper is function-specific evidence. It is not permission to hand-write arbitrary renderer bodies in assembly.
|
||||
|
||||
## 13. Baseline, checkpoint, and final verification
|
||||
|
||||
Before editing:
|
||||
|
||||
1. Run the full build.
|
||||
2. Save a stable verdict snapshot.
|
||||
3. Save `build/semantic_report.json`.
|
||||
4. Record board totals and all in-scope per-unit gates.
|
||||
5. Validate parks and object admission.
|
||||
6. Record the baseline owner/data census for every assigned object.
|
||||
|
||||
At each coherent admission batch:
|
||||
|
||||
1. Review the source diff for house-rule compliance.
|
||||
2. Run each changed unit’s full `gate.py --all`.
|
||||
3. Run the `_point_from_line3d` emitted-symbol guard.
|
||||
4. Review every target/candidate owner and relocation change.
|
||||
5. Run the fake-match scanner over all changed source.
|
||||
6. Run `ninja`.
|
||||
7. Take a fresh stable snapshot and diff it from the frozen baseline and the previous checkpoint.
|
||||
8. Require zero inherited exact regressions.
|
||||
9. Validate parks.
|
||||
10. Run semantic-match and whole-object admission audits.
|
||||
11. Run the repository’s full pytest suite.
|
||||
12. Run `git diff --check`.
|
||||
13. Commit only when the tree is fully verified.
|
||||
|
||||
At final tip, require:
|
||||
|
||||
```text
|
||||
ninja
|
||||
python -m tools.campaign.stable_verdicts snapshot scratch/lane-c-after.json
|
||||
python -m tools.campaign.stable_verdicts diff scratch/lane-c-before.json scratch/lane-c-after.json
|
||||
python -m tools.parked_functions
|
||||
python -m tools.audit_semantic_matches
|
||||
python tools/audit_object_admission.py
|
||||
python tools/fake_match_scan.py <all changed source/header paths>
|
||||
python -m pytest -q
|
||||
git diff --check
|
||||
git status --short
|
||||
```
|
||||
|
||||
If scratch content interferes with pytest discovery, move evidence outside the worktree rather than excluding real tests.
|
||||
|
||||
The final tracked tree must be clean. Keep bulky scratch objects and experimental variants outside Git.
|
||||
|
||||
## 14. Fuzzy preservation
|
||||
|
||||
If a credible reconstruction is the best current implementation but does not become strict exact:
|
||||
|
||||
- Keep it only if semantics, ABI, ownership, and house rules are sound.
|
||||
- Measure size, normalized divergence, relocations, and first differing regions.
|
||||
- Compare it with the baseline and every known donor.
|
||||
- Document why it is better.
|
||||
- Record remaining blockers and exact reopen criteria.
|
||||
- Update its park evidence honestly.
|
||||
- Give it zero strict credit.
|
||||
- Do not sacrifice an exact sibling or whole-object owner to retain it.
|
||||
|
||||
A fuzzy implementation is useful future research, but it must never inflate the strict total.
|
||||
|
||||
## 15. Campaign behavior
|
||||
|
||||
Work autonomously. Do not pause for ordinary implementation questions. If one function needs an owner ruling, park that question, continue unrelated work, and present rulings in a compact batch.
|
||||
|
||||
Do not terminate because:
|
||||
|
||||
- the first wave was low yield,
|
||||
- a previous ledger called something difficult,
|
||||
- a function is parked,
|
||||
- a header is shared,
|
||||
- or the PDB lacks locals.
|
||||
|
||||
Instead, determine whether new evidence can satisfy the reopen condition. Conversely, do not repeatedly attack a proven allocator tie without a new source-level lever.
|
||||
|
||||
Every one of the 83,898 starting residual bytes must finish in one of these categories:
|
||||
|
||||
1. Strict exact and landed.
|
||||
2. Credible fuzzy improvement landed at zero credit.
|
||||
3. Evidence-backed structural blocker with a concrete reopen criterion.
|
||||
4. Demonstrated compiler allocation/scheduling tie with the validating detector.
|
||||
5. Owner/policy ruling required, with a minimal ready candidate.
|
||||
6. Previously solved/duplicate at the frozen baseline and therefore excluded from new credit.
|
||||
|
||||
“Unexamined” is not an acceptable final category.
|
||||
|
||||
## 16. Commit and handoff requirements
|
||||
|
||||
Make small, independently buildable commits organized by coherent TU or owner packet. Avoid a tangled final megacommit. Header/config prerequisites and their affected source must remain in a clear, ordered series.
|
||||
|
||||
Do not push.
|
||||
|
||||
Create:
|
||||
|
||||
```text
|
||||
docs/object_matching_logs/claude_lane_c_graphics_ui_HANDOFF_20260920.md
|
||||
docs/object_matching_logs/claude_lane_c_graphics_ui_admission_manifest_20260920.json
|
||||
```
|
||||
|
||||
The handoff must include:
|
||||
|
||||
- frozen base and final commit IDs,
|
||||
- exact reverse-order cherry-pick range,
|
||||
- every commit and changed file,
|
||||
- baseline and final strict functions,
|
||||
- baseline and final meaningful exact bytes,
|
||||
- new meaningful bytes,
|
||||
- new padded bytes,
|
||||
- fuzzy bytes at zero credit,
|
||||
- exact regressions, which must be zero,
|
||||
- objects moved to function-only 100%,
|
||||
- objects admitted as whole `Matching`,
|
||||
- data/BSS/linkage/COMDAT owner changes,
|
||||
- header/config changes and their full blast-radius evidence,
|
||||
- parks removed or remeasured,
|
||||
- tests and audits with exact counts,
|
||||
- fake-scan findings and disposition,
|
||||
- per-function sizes, hashes, relocation counts, and source evidence,
|
||||
- rejected experiments and do-not-repeat findings,
|
||||
- unresolved candidates and precise reopen criteria,
|
||||
- confirmation that canonical was untouched and nothing was pushed.
|
||||
|
||||
The JSON manifest must be machine-readable and contain per-function before/after evidence, not merely headline totals.
|
||||
|
||||
Finish with a clean local branch and report:
|
||||
|
||||
```text
|
||||
branch
|
||||
base
|
||||
tip
|
||||
commit count
|
||||
strict meaningful gain
|
||||
strict padded gain
|
||||
strict function gain
|
||||
whole-object Matching gain
|
||||
fuzzy bytes retained at zero credit
|
||||
regressions
|
||||
test/audit results
|
||||
git status
|
||||
nothing pushed
|
||||
canonical untouched
|
||||
```
|
||||
@@ -0,0 +1,77 @@
|
||||
# Claude Lane D — refreshed after A/B/C reconciliation
|
||||
|
||||
Work on Halo January 2342 **Halo-owned** code, not Xbox/vendor libraries. Start
|
||||
an isolated local worktree and branch at the **latest fetched tip** of
|
||||
`jonas/exact-pilots` (`https://github.com/bnunu/halo`). Verify that this tip
|
||||
contains the audited A/B/C reconciliation commit
|
||||
`4f4c85021db48dae61252d8e1301c60e1c2cc138`, record its full hash in
|
||||
your handoff, and confirm a clean tree before editing. Do not start from the
|
||||
stale `6130661c` base in the old Lane D brief. Never modify canonical or
|
||||
push your lane.
|
||||
|
||||
Read these complete before selecting work:
|
||||
|
||||
- `docs/campaign_prompts/CLAUDE_REMAINING_LANE_D_SYSTEMS_EFFECTS_20260920.md`
|
||||
for the full 49-TU Lane D allowlist, reference paths, workflow and house rules;
|
||||
**this refresh overrides its baseline, numeric portfolio, cross-lane header
|
||||
reservations, and absolute COMDAT rule**.
|
||||
- `docs/campaign_house_rules.md`, `docs/matching_methodology.md`,
|
||||
`docs/common_constants.md`, `docs/assertions.md`,
|
||||
`docs/campaign_throughput_lessons.md`.
|
||||
- `docs/object_matching_logs/claude_lane_a_ai_core_HANDOFF_20260920.md`,
|
||||
`docs/object_matching_logs/claude_lane_a_HANDOFF_TO_LANE_B_20260921.md`,
|
||||
`docs/object_matching_logs/claude_lane_b_HANDOFF_20260920.md`,
|
||||
`docs/object_matching_logs/claude_lane_b_rejected_hypotheses_20260920.md`,
|
||||
`docs/object_matching_logs/claude_lane_c_canonical_reconciliation_20260922.md`,
|
||||
and `docs/common_pool_ordering_20260922.md`.
|
||||
|
||||
Re-measure the allowlist against **this** baseline. A/B/C already changed some
|
||||
Lane D files, so no old residual size, park count, donor gain, or archived lane
|
||||
report is current authority. Freeze a stable-verdict snapshot, per-object
|
||||
function/data/owner census, parks, admission audit, build and tests before any
|
||||
edit. Prioritize still-unwritten and structural gaps in projectiles/weapons,
|
||||
decals/effects, HS compile/runtime, sound, geometry, and the smaller systems
|
||||
objects; do not redo already exact rows. Aim for 40K new meaningful exact code
|
||||
bytes while evidence supports it, but report the actual verified delta only.
|
||||
|
||||
Lessons that bind this lane:
|
||||
|
||||
1. Exact function credit requires a strict stable row, full build, unchanged
|
||||
inherited exact rows, sound semantics, and an ownership audit. A fuzzy body
|
||||
is useful source but earns zero exact bytes. Data scoring changed with
|
||||
objdiff v3.6.0; separate scorer/accounting gains from newly reconstructed
|
||||
source and keep `linker_common` at zero credit while incomplete.
|
||||
2. Header definition position can alter unrelated TUs. Put each genuine owner
|
||||
header change in a prerequisite commit, enumerate all consumers, and run a
|
||||
board-wide per-row sweep. Do not hide a needed declaration in a consumer
|
||||
`.c`. The A/B/C work has landed, so prior cross-lane reservations are lifted;
|
||||
the blast-radius rule is not.
|
||||
3. COMMON pool adjacency is only a negative constraint, **never** proof of a
|
||||
global's owning TU. Do not add unreferenced or address-named globals to
|
||||
complete `.data`/`.bss`. Require an independent original owner/type oracle.
|
||||
4. A real shared-header inline COMDAT may be emitted under the documented
|
||||
A/B/C narrow exception only when January's folded copy is byte-identical,
|
||||
the caller is strict exact, the full owner census is reviewed, and no exact
|
||||
sibling regresses. Do not hand-expand helpers to evade ownership. In
|
||||
particular, preserve the January `_point_from_line3d` schedule.
|
||||
5. Previously held UB, artificial duplicate work, pragmas, two-pass asm, and
|
||||
source-shape steering do **not** become acceptable merely because they
|
||||
byte-match. Reopen only on new primary evidence and an explicit owner
|
||||
ruling. The rejected Lane C COMMON, null-write, HUD asm/pragma, and
|
||||
lens-flare-overrun packets are examples, not backlog to re-land.
|
||||
6. Use first-party January bytes/relocations, January MAP/PDB, the supplied
|
||||
Bungie C files, HCEA/2020, Ghidra/DIA and Marathon with their correct
|
||||
evidentiary limits. The later builds are not interchangeable with January.
|
||||
Do not spend a wave on known pure register/x87 ties without a falsifiable
|
||||
source, type or header hypothesis.
|
||||
|
||||
Use one worker per disjoint `.c`; workers use PID-isolated `gate.py` scratch
|
||||
objects, never shared build/config. Orchestrator alone edits headers/config,
|
||||
runs Ninja, performs the stable diff, commits, and updates parks. In each
|
||||
5K–15K wave reject exact losses, invalid parks, invented owners, surplus
|
||||
COMDATs, fake-scan leads, and nonsensical logic before banking. Keep a
|
||||
machine-readable per-function manifest and an evidence-backed list of rejected
|
||||
trials. End with local commits, a clean worktree, final tests/build/sweep and
|
||||
handoff; **do not push**. Report strict meaningful code, padded code, fuzzy
|
||||
zero-credit extent, data-only/scorer gains and whole-object completions
|
||||
separately.
|
||||
@@ -0,0 +1,311 @@
|
||||
# Claude prompt — Lane D: effects, items, world data, sound, scripting, and systems
|
||||
|
||||
You are running one of four strictly disjoint Halo 1 January 2342 exact-match
|
||||
lanes. Work aggressively and persistently, but never purchase byte equality
|
||||
with fake source, undefined behavior, invented ownership, target rewriting, or
|
||||
nonsensical logic.
|
||||
|
||||
## Fixed baseline and isolation
|
||||
|
||||
- Repository: https://github.com/bnunu/halo
|
||||
- Baseline branch: jonas/exact-pilots
|
||||
- Exact baseline commit: `6130661c9585fdb2785b3ff6bdb2ad0cfef0520c`
|
||||
(Reconcile final Astra campaign, +4,073 bytes)
|
||||
- Create an isolated worktree and branch from that exact commit, for example
|
||||
C:\\halo-worktrees\\claude-remaining-lane-d-20260920 on
|
||||
claude/remaining-lane-d-20260920.
|
||||
- Confirm `git rev-parse HEAD` equals the full baseline hash and the tree is
|
||||
clean.
|
||||
- Never edit the canonical checkout. Never push. Do not merge or rebase another
|
||||
campaign. Finish with local commits and a clean worktree.
|
||||
- Read the whole repository and evidence corpus, but modify only Lane D files,
|
||||
genuine Lane D owner headers after the header protocol below, uniquely named
|
||||
Lane D documentation, and a final isolated bookkeeping commit.
|
||||
|
||||
The reconciled baseline has 1,443,979 / 1,770,166 accepted Halo meaningful
|
||||
bytes (81.573084%), 7,291 / 7,574 accepted Halo functions, and 184 valid active
|
||||
parks. All four lanes together cover 326,187 remaining Halo-owned bytes.
|
||||
|
||||
Lane D owns 87,255 meaningful residual bytes across 49 translation units:
|
||||
32,593 written-unparked, 54,651 parked, and 11 unwritten. Target at least
|
||||
40,000 new strict meaningful bytes, with a stretch goal of closing the full
|
||||
portfolio. If 40K is not reached, continue until every unit has a verified
|
||||
landing or a precise evidence-backed blocker. Do not declare the lane
|
||||
unreachable from aggregate park counts.
|
||||
|
||||
## Exclusive Lane D allowlist
|
||||
|
||||
Only these translation units are in scope:
|
||||
|
||||
~~~text
|
||||
source/bink/bink_playback 979
|
||||
source/bungie_net/common/prime_numbers 340
|
||||
source/bungie_net/network/transport_endpoint_set_winsock 1344
|
||||
source/bungie_net/network/transport_endpoint_winsock 294
|
||||
source/cache/cache_files_decompress_windows 2117
|
||||
source/cache/cache_files_windows 746
|
||||
source/cache/xbox_sound_cache 368
|
||||
source/cache/xbox_texture_cache 209
|
||||
source/camera/dead_camera 1512
|
||||
source/camera/editor_flying_camera 2563
|
||||
source/camera/observer 1561
|
||||
source/cseries/profile 276
|
||||
source/cseries/stack_walk_windows 1167
|
||||
source/cutscene/cinematics 1272
|
||||
source/effects/contrails 945
|
||||
source/effects/decals 7930
|
||||
source/effects/effects 3003
|
||||
source/effects/particle_systems 2103
|
||||
source/effects/player_effects 2355
|
||||
source/effects/weather_particle_systems 2346
|
||||
source/hs/hs 81
|
||||
source/hs/hs_compile 2632
|
||||
source/hs/hs_runtime 3404
|
||||
source/items/items 2352
|
||||
source/items/projectiles 7905
|
||||
source/items/weapons 2224
|
||||
source/main/main 2542
|
||||
source/math/geometry 4775
|
||||
source/math/periodic_functions 244
|
||||
source/networking/network_connection 588
|
||||
source/objects/damage 2663
|
||||
source/objects/widgets/flags 1170
|
||||
source/objects/widgets/glow 1729
|
||||
source/objects/widgets/light_volumes 905
|
||||
source/objects/widgets/lightning 2571
|
||||
source/saved games/player_profile 1148
|
||||
source/saved games/saved_game_files 359
|
||||
source/sound/game_sound 1570
|
||||
source/sound/ima_adpcm 404
|
||||
source/sound/sound_dsound_xbox 630
|
||||
source/sound/sound_manager 3966
|
||||
source/structures/leaf_map 1950
|
||||
source/structures/structure_detail_objects 66
|
||||
source/structures/structure_lens_flares 4331
|
||||
source/structures/structure_visibility 468
|
||||
source/structures/structures 1210
|
||||
source/tag_files/files_windows 209
|
||||
source/text/draw_string 920
|
||||
source/tool/connected_geometry 809
|
||||
~~~
|
||||
|
||||
Numbers are current residual bytes, not promised gains. Do not work in libs/**,
|
||||
xbox/**, vendor Bink objects, libcmt, d3d8, d3dx8, dsound, xapi, xnet, xkbd, or
|
||||
any translation unit absent from the allowlist.
|
||||
|
||||
## Read before editing
|
||||
|
||||
Read these files completely:
|
||||
|
||||
~~~text
|
||||
README.md
|
||||
docs/campaign_house_rules.md
|
||||
docs/matching_methodology.md
|
||||
docs/common_constants.md
|
||||
docs/assertions.md
|
||||
docs/campaign_throughput_lessons.md
|
||||
tools/campaign/README.md
|
||||
docs/object_matching_logs/astra_90pct_HANDOFF_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_research_atlas_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_rejected_hypotheses_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_admission_manifest_20260920.json
|
||||
docs/object_matching_logs/astra_90pct_research5_shared_context_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_research5_shared_schedule_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_research5_projectiles_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_research5_structure_lens_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_research5_sound_type_rejected_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_research8_damage_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_research8_damage_independent_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_research8_sound_listener_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_research10_weapon_projectiles_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_research10_weapon_projectiles_independent_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_research12_weapons_tail_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_research12_weapons_owner_independent_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_wave4_decals_20260920.md
|
||||
docs/object_matching_logs/astra_90pct_wave4_decals_independent_review_20260920.md
|
||||
~~~
|
||||
|
||||
Search current per-object logs before reopening any park. Useful read-only
|
||||
primary and cross-build material:
|
||||
|
||||
~~~text
|
||||
C:\\Users\\isabe\\Downloads\\Halo Combat Evolved (Jan 14, 2002 prototype)
|
||||
C:\\Users\\isabe\\Downloads\\Halo - Combat Evolved (Oct 12, 2001 prototype)\\Halo 2276
|
||||
C:\\Users\\isabe\\Downloads\\haloleak2024\\halo1\\network_client_manager.c
|
||||
C:\\Users\\isabe\\Downloads\\haloleak2024\\halo1\\network_server_manager.c
|
||||
C:\\Users\\isabe\\Downloads\\haloleak2024\\halo1\\random_math.c
|
||||
C:\\Users\\isabe\\Downloads\\haloleak2024\\halo1\\h1_tags
|
||||
C:\\Users\\isabe\\Documents\\Codex\\2026-07-13\\i-w\\_research-marathon-source-agent-20260904
|
||||
C:\\Users\\isabe\\Documents\\Codex\\2026-09-20\\files-pasted-by-the-user-halo\\outputs\\astra_90pct_function_atlas.csv
|
||||
~~~
|
||||
|
||||
January's PDB has publics but no useful Halo locals or line records. The
|
||||
2020/debug executables have confirmed source differences. Use them as
|
||||
typed/control-flow evidence, not interchangeable source. IDA Free has no
|
||||
callable automation endpoint. Use Ghidra headless, DIA/PDB tools, January raw
|
||||
bytes and relocations, original MAP names, the supplied Bungie source, and
|
||||
authenticated cross-build windows.
|
||||
|
||||
## Mandatory house rules
|
||||
|
||||
1. Put void on its own line in every no-argument parameter list.
|
||||
2. Put every parameter on its own line.
|
||||
3. End every function with an explicit valid return.
|
||||
4. Use subsystem typed macros wrapping tag_get.
|
||||
5. Use typed object macros instead of raw object_get plus casts.
|
||||
6. Preserve January's inline schedule; emit no new point_from_line3d COMDAT.
|
||||
7. Give private functions authentic/descriptive names, never code plus address.
|
||||
8. Give globals authentic/descriptive names, never bss plus address.
|
||||
9. Put prototypes in genuine owners, not unrelated consumers.
|
||||
10. Use inline assembly only for evidenced low-level/helper/math instructions
|
||||
with no faithful VC7 C spelling.
|
||||
11. Retain and document credible fuzzy code at zero credit when easy exactness
|
||||
fails; park it for later.
|
||||
12. Prefer small closable functions before one giant residual.
|
||||
13. Do not force-inline or duplicate helper bodies to steer code generation.
|
||||
14. Marathon is style/semantic reference, not January byte proof.
|
||||
15. With no dedicated header, use the closest genuine associated header.
|
||||
16. Use named correct enum constants in switches.
|
||||
17. Declare and initialize variables together when practical.
|
||||
18. Prefer cseries.h macros over manual bit operations.
|
||||
19. Use project types such as real, boolean, byte, short, and long.
|
||||
20. Reject fake matching and implausible original source.
|
||||
21. Reject nonsensical logic even when bytes match.
|
||||
22. Use /QIfist only when target/compiler evidence requires it per TU and all
|
||||
affected callers/conversions have been audited.
|
||||
|
||||
Use the repository's verified assert/dassert/vassert, warn/dwarn/vwarn, and
|
||||
halt/dhalt/vhalt contracts from docs/assertions.md. Do not manually expand them.
|
||||
Preserve a target-proven original bug only when primary evidence is decisive,
|
||||
the semantics are documented with a BUG comment, and independent review agrees.
|
||||
Never introduce undefined behavior merely to shape bytes.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Establish the full baseline:
|
||||
|
||||
~~~text
|
||||
ninja -j4 all_source progress semantic_progress
|
||||
python -m pytest -q tools
|
||||
python -m tools.campaign.stable_verdicts snapshot scratch/lane-d-before.json
|
||||
python -m tools.parked_functions
|
||||
python tools/audit_object_admission.py --output scratch/lane-d-admission-before.json
|
||||
~~~
|
||||
|
||||
2. Build a Lane D ledger. For every row record meaningful and padded target
|
||||
size, candidate size, relocation count, normalized hash, objdiff percent,
|
||||
park class, reopen criterion, and prior experiments. Re-measure locally; the
|
||||
Astra CSV is routing evidence, not authority.
|
||||
|
||||
3. Attack in this order:
|
||||
- genuinely unwritten functions and missing coherent source graphs;
|
||||
- written-unparked structural differences involving calls, branches, fields,
|
||||
locals, types, or ownership;
|
||||
- small near-complete functions with new primary evidence;
|
||||
- parks only when evidence satisfies or refutes their reopen criteria.
|
||||
|
||||
Do not spend a wave on pure register allocation, independent-load ordering,
|
||||
or x87 stack ties without a falsifiable source/type/header hypothesis.
|
||||
|
||||
4. Highest leverage: projectiles and weapons; decals, structure lens flares,
|
||||
effects, particles and weather; HS compile/runtime; sound manager/game sound;
|
||||
geometry/math with natural helpers; then small cache, camera, object-widget,
|
||||
save, text and tool units. Use the three Bungie C files as style and semantic
|
||||
maps where applicable, not January byte authority.
|
||||
|
||||
5. Use PID-isolated scratch objects:
|
||||
|
||||
~~~text
|
||||
python tools/campaign/gate.py <unit> --fn <function> --out scratch/<unique>.obj
|
||||
python tools/campaign/alndiff.py <unit> <function> --ours-object scratch/<unique>.obj
|
||||
python tools/campaign/relocdiff.py <unit> <function> scratch/<unique>.obj --count-by-target
|
||||
python tools/campaign/tinfo.py --object scratch/<unique>.obj --data
|
||||
~~~
|
||||
|
||||
Use gate --edits or scratch source copies for bounded experiments. A gate hit is
|
||||
necessary but not sufficient: independently review semantics, source
|
||||
plausibility, relocations, owners, non-code sections, and siblings.
|
||||
|
||||
6. If using subagents, assign exactly one C file per worker. Workers use only
|
||||
gate.py and unique scratch objects; they do not run Ninja, edit headers or
|
||||
config, commit, or push. The orchestrator reproduces every hit.
|
||||
|
||||
7. Header protocol: edit only a genuine owner; enumerate every C consumer with
|
||||
rg first; freeze exact controls and owner/data/COMMON/COMDAT state; compile
|
||||
every consumer; put a header prerequisite in its own commit; reject any
|
||||
inherited exact loss or unsupported owner. If a required shared header is
|
||||
owned by another lane, preserve a proposed patch and evidence but do not
|
||||
edit it.
|
||||
|
||||
To minimize four-lane reconciliation, do not commit changes to broad
|
||||
cross-lane headers such as cseries.h, real_math.h, or core object/tag
|
||||
headers. Preserve those as separately reviewable proposed patches with a
|
||||
complete consumer census and strict before/after evidence. Commit only
|
||||
narrow genuine Lane D subsystem owner headers after the protocol above.
|
||||
|
||||
8. Shared config protocol: never change comparators, target objects, build
|
||||
metadata, global optimizer defaults, or semantic-credit rules. symbols.json
|
||||
requires original identity evidence. Matching requires full code, data, BSS,
|
||||
relocation, COMDAT, linkage, surplus-owner and source-authenticity audits.
|
||||
Keep source commits separate. Put minimal park changes in a final bookkeeping
|
||||
commit and duplicate the exact delta in the manifest for conflict-free
|
||||
integration.
|
||||
|
||||
9. Run the hard point_from_line3d emitted-symbol guard on every changed TU
|
||||
unless January genuinely owns it there. For inherited genuine owners, compare
|
||||
the complete before/after owner census. Reject surplus fast_ftol, pixel,
|
||||
math, or XDK helper owners unless authentic topology and link selection are
|
||||
proved. Equal bytes in another object are not ownership proof.
|
||||
|
||||
10. Preserve best credible fuzzy bodies only at zero credit. Do not count fuzzy
|
||||
target extent, objdiff percentage, or padded envelope as exact progress.
|
||||
|
||||
## Wave gates and accounting
|
||||
|
||||
Use coherent 5K–15K candidate waves. Before and after each landing, run full
|
||||
build and stable snapshots. At minimum:
|
||||
|
||||
~~~text
|
||||
ninja -j4 all_source progress semantic_progress
|
||||
python -m tools.campaign.stable_verdicts snapshot scratch/lane-d-after-N.json
|
||||
python -m tools.campaign.stable_verdicts diff scratch/lane-d-before-N.json scratch/lane-d-after-N.json
|
||||
python -m tools.parked_functions
|
||||
python tools/audit_object_admission.py --output scratch/lane-d-admission-N.json
|
||||
python tools/fake_match_scan.py --format json <changed files>
|
||||
git diff --check
|
||||
~~~
|
||||
|
||||
At each cumulative 10K meaningful checkpoint and final closeout also run the
|
||||
full tools tests and global fake scan. Audit exact bytes, ordered relocation
|
||||
identities, inherited matches, code/data/BSS/COMMON owners, COMDAT copies,
|
||||
externals, names/linkage, and non-code sections.
|
||||
|
||||
Report separately: strict meaningful bytes, strict padded bytes, and fuzzy
|
||||
target extent at zero credit. Never derive canonical gain from donor headlines.
|
||||
|
||||
## Commits and handoff
|
||||
|
||||
- Commit only independently verified packets, one coherent source/owner packet
|
||||
per commit. Header prerequisites precede source; park/config bookkeeping is
|
||||
last.
|
||||
- Do not add scratch, build outputs, binaries, PDB/MAP/EXE files, generated
|
||||
atlases, or large probe reports.
|
||||
- Use uniquely named Lane D records. End clean and do not push.
|
||||
|
||||
Create:
|
||||
|
||||
~~~text
|
||||
docs/object_matching_logs/claude_remaining_lane_d_HANDOFF_20260920.md
|
||||
docs/object_matching_logs/claude_remaining_lane_d_admission_manifest_20260920.json
|
||||
~~~
|
||||
|
||||
The handoff must state base/tip, ordered commits, changed files, per-function
|
||||
meaningful/padded bytes and fingerprints, strict gains, zero-credit fuzzy work,
|
||||
rejected trials, parks/config/header changes, owner/COMDAT/data results, exact
|
||||
commands/results, and blockers with concrete reopen criteria. The manifest must
|
||||
contain machine-readable measurements and exact proposed shared-config deltas.
|
||||
|
||||
Do not stop after a few easy leaves. Continue through the allowlist while
|
||||
tokens remain, switching quickly from exhausted scheduling ties to a different
|
||||
unit with structural evidence. Authenticity and zero regressions remain
|
||||
absolute under the 40K goal.
|
||||
@@ -0,0 +1,25 @@
|
||||
# Four-lane remaining-Halo campaign (2026-09-20)
|
||||
|
||||
These four self-contained Claude prompts partition every Halo-owned meaningful
|
||||
residual byte measured at canonical commit
|
||||
`6130661c9585fdb2785b3ff6bdb2ad0cfef0520c`. They deliberately exclude Xbox
|
||||
SDK/XDK and other vendor-library objects.
|
||||
|
||||
| Lane | Scope | Units | Residual bytes | Prompt |
|
||||
| --- | --- | ---: | ---: | --- |
|
||||
| A | AI core, actors, perception, communication, encounters | 11 | 79,657 | `CLAUDE_REMAINING_LANE_A_AI_CORE_20260920.md` |
|
||||
| B | AI actions/pathfinding, gameplay, physics/collision, units/vehicles | 31 | 75,377 | `CLAUDE_REMAINING_LANE_B_SIMULATION_PHYSICS_20260920.md` |
|
||||
| C | Bitmaps, UI/HUD, Halo-owned Xbox rasterizer, rendering | 30 | 83,898 | `CLAUDE_REMAINING_LANE_C_GRAPHICS_UI_20260920.md` |
|
||||
| D | Effects, items, scripting, sound, structures, systems | 49 | 87,255 | `CLAUDE_REMAINING_LANE_D_SYSTEMS_EFFECTS_20260920.md` |
|
||||
| **Total** | **All remaining Halo-owned code** | **121** | **326,187** | |
|
||||
|
||||
The translation-unit allowlists are mutually exclusive. Each prompt requires a
|
||||
dedicated worktree at the exact baseline, forbids pushes and canonical edits,
|
||||
requires current-state anti-duplication checks, applies all house rules, keeps
|
||||
fuzzy work at zero credit, and demands a clean machine-readable handoff for
|
||||
later reconciliation.
|
||||
|
||||
Run all four lanes in parallel only when each Claude session has its own
|
||||
worktree. Give each session exactly one prompt; do not combine the prompts or
|
||||
allow a lane to cross its allowlist. Canonical accounting remains authoritative
|
||||
over worker headline totals.
|
||||
@@ -0,0 +1,218 @@
|
||||
# Campaign throughput lessons (2026-08-30 / 2026-08-31)
|
||||
|
||||
Operational lessons from a run that took the board from **669,879 to 714,807
|
||||
matched bytes (+44,928)** and **4,829 to 4,973 credited functions (+144)** with
|
||||
**zero regressions**, verified by a full build plus a per-function sweep of all
|
||||
569 built units.
|
||||
|
||||
This document is about *throughput and hazards* - how to close many functions
|
||||
in parallel without breaking what already works. For per-function matching
|
||||
technique see `matching_methodology.md` and
|
||||
`exact_match_acceleration_playbook.md`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Write unwritten functions before fighting residuals
|
||||
|
||||
This is the single highest-leverage finding. Measured across four waves:
|
||||
|
||||
| wave | scope | approach | bytes gained | yield |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | 71,112 B residual | close residuals | 11,040 | 16% |
|
||||
| 3 | 27,920 B "sha-only" residual | close residuals | 3,168 | 11% |
|
||||
| 4 | ~160,000 B unwritten | write missing functions | **30,720** | far larger scope |
|
||||
|
||||
Wave 3 deliberately picked the *closest* residuals on the board - functions
|
||||
whose padded size **and** relocation count already matched, so only instruction
|
||||
selection differed - and still returned only 11%. Those residuals are typically
|
||||
a single register-allocation or x87 stack-discipline decision, and they resist
|
||||
source-level control.
|
||||
|
||||
An **unwritten** function has no wrong prior to undo. You read the target
|
||||
disassembly and write natural C89. That is a fundamentally easier problem.
|
||||
|
||||
The board currently holds roughly **1,000,000 bytes of unwritten functions**
|
||||
against **100,000 bytes of residual**. Work the unwritten pool first.
|
||||
|
||||
Within a unit, start with the **small** functions. Eight 300-byte closures beat
|
||||
one failed heroic attempt at a 3,000-byte function.
|
||||
|
||||
## 2. Parallel fan-out architecture
|
||||
|
||||
`tools/campaign/gate.py <unit>` compiles **one** translation unit to a
|
||||
PID-named object under `scratch/` and never writes to `build/`. That makes it
|
||||
safe to run from many workers simultaneously.
|
||||
|
||||
The architecture that worked:
|
||||
|
||||
- **One worker per `.c` file, files strictly disjoint.** Never two workers in
|
||||
one file.
|
||||
- Every worker measures **only** with `gate.py`. Useful flags: `--fn <FUNC>`,
|
||||
`--disas <FUNC>`, `--source <FILE>` (compile a variant without touching the
|
||||
real file), `--edits <json>`.
|
||||
- **No worker runs `ninja` or `configure.py`.** A shared build directory cannot
|
||||
take concurrent writers.
|
||||
- **No worker commits.** The orchestrator does one full build, one board
|
||||
measurement, and one commit at the end.
|
||||
- Workers record `gate.py`'s exact count *before* starting and revert anything
|
||||
that lowers it.
|
||||
|
||||
### `--disas` hides insert/delete holes
|
||||
|
||||
`gate.py --disas` is an **index-aligned zip**, not an alignment diff. Once
|
||||
instruction counts diverge, every later row reads as different and a genuinely
|
||||
inserted or deleted block is invisible. Use `scratch/alndiff.py` (difflib
|
||||
SequenceMatcher over normalized capstone streams, branch targets normalized):
|
||||
|
||||
python scratch/build1.py <unit>.c scratch/cur.obj
|
||||
python scratch/alndiff.py <unit> <FUNC> scratch/cur.obj
|
||||
|
||||
A 48-instruction hole in `_ai_debug_render_actor` was only visible this way.
|
||||
|
||||
Ignore `.rdata` / `__real@...` annotation mismatches in that output - those are
|
||||
symbol-naming artifacts, not code differences.
|
||||
|
||||
## 3. Header edits perturb objects that never name the added types
|
||||
|
||||
**"Edit only your own object's header" is not a safe rule.**
|
||||
|
||||
`source/items/weapons.h` is included by ten other `.c` files. Adding two
|
||||
interface-state structs to it silently dropped `units.obj` from **189/189 to
|
||||
188/189**, breaking `_unit_preprocess_node_orientations` - a function that
|
||||
names none of those types and calls none of the new functions.
|
||||
|
||||
Bisecting the three added blocks:
|
||||
|
||||
| added to weapons.h | units.obj |
|
||||
| --- | --- |
|
||||
| enum only | 189 ok |
|
||||
| structs only | **188 BREAKS** |
|
||||
| protos only | 189 ok |
|
||||
| enum + structs | 189 ok |
|
||||
| structs + protos | **188 BREAKS** |
|
||||
| all three | **188 BREAKS** |
|
||||
|
||||
Adding the enum *in front of* the structs repairs it. The effect is not
|
||||
semantic - it is the C2 allocator's **definition-position** sensitivity. What
|
||||
perturbs codegen is where declarations sit, not what they mean.
|
||||
|
||||
### Rules that follow
|
||||
|
||||
1. Before touching any `.h`, run
|
||||
`grep -rl "<header filename>" source/ --include=*.c`. If anything else
|
||||
includes it, default to putting the declaration in the `.c`.
|
||||
2. Definitions private to one TU belong in that TU. The weapons fix: structs
|
||||
moved into `weapons.c`; the header kept the enum, the prototypes, and a
|
||||
forward declaration so the prototype's struct tag has file scope. `units`
|
||||
returned to 189/189 with all 50 of weapons' exact functions intact.
|
||||
3. **Never** "fix" this by relying on a coincidental ordering that happens to
|
||||
restore the victim.
|
||||
4. If a header edit is genuinely required, prove it: build **shadow header
|
||||
trees** (patched and pristine), compile every dependent unit against both,
|
||||
and compare per-function size, relocation count and normalized hash. This
|
||||
was done to drop `__declspec(align(4))` from `struct guard_state_data` in
|
||||
`actions.h` (24 includers) and it held up under independent re-check.
|
||||
|
||||
### Some cases have no local remedy
|
||||
|
||||
Adding two trailing fields to `struct _projectile_datum` in `projectiles.h` -
|
||||
fields January demonstrably uses at composite offsets 0x1FC and 0x200 - drops
|
||||
`units.obj` to 188/189. The type is public, so internalising it in the `.c`
|
||||
does not apply. About 1,152 bytes of projectile work is gated on this. That is
|
||||
an owner decision; do not trade away a complete object for it quietly.
|
||||
|
||||
## 4. Verification discipline
|
||||
|
||||
**Worker self-reports are systematically optimistic.** One wave's rolled-up
|
||||
"confirmed bytes" read 18,544 against 3,168 actually closed, because verifiers
|
||||
counted pre-existing exact functions alongside new ones.
|
||||
|
||||
The only numbers that count:
|
||||
|
||||
1. A full `ninja` build. Its semantic gate fails closed if any previously exact
|
||||
function stops matching.
|
||||
2. `python tools/campaign/board.py` for the byte and function totals.
|
||||
3. A **per-function regression sweep**: snapshot the exact set of every unit
|
||||
from `build/split` vs `build/base` before the run, and re-compare after.
|
||||
Object-level counts hide one object lost against another gained.
|
||||
|
||||
`board.py`'s per-object listing is **truncated** - an object appearing in or
|
||||
disappearing from it is not evidence of a change. Use the sweep.
|
||||
|
||||
## 5. Cross-cutting codegen facts confirmed this run
|
||||
|
||||
- **Frame size is structural.** A differing `sub esp, N` means a local's scope
|
||||
or type is wrong. It is never scheduling noise. This is what reopened
|
||||
`_generate_prime_numbers` after a prior session had declared evidence
|
||||
exhaustion on it (81.61% -> 91.15%).
|
||||
- **Local declaration order is inert** for stack-slot assignment - proven
|
||||
byte-identical across four permutations. Do not spend waves permuting
|
||||
declarations.
|
||||
- **The zero-register pin.** January frequently keeps a zero live in a register
|
||||
and spends it repeatedly (`mov [mem],reg`, `push reg`, `cmp reg,zeroreg`)
|
||||
where our build rematerialises immediates. Pinning a zero consumes a
|
||||
callee-saved register, so this surfaces *downstream* as stack-slot
|
||||
permutations and duplicated or merged blocks rather than as a local byte
|
||||
difference. It is not a compiler flag: on `_lra_allocate`, `/O1`, `/O2 /Os`
|
||||
and `/O1 /Ob2` all shrink the function to 319 bytes and `/Ox /Os` explodes it
|
||||
to 1255, while the campaign flags give the closest result at 368.
|
||||
- **Shared-header inlines must stay non-`static`.** Converting the 89
|
||||
`__inline` definitions in `real_math.h` (plus 6 elsewhere) to
|
||||
`static __inline` costs **21 objects and 119 functions**: `static` lets VC7
|
||||
dead-code the out-of-line copy and inline more aggressively, changing call
|
||||
sites. This also kills the theory that our ~20-28 surplus COMDATs per object
|
||||
come from storage class - non-static is what reproduces January's bytes, so
|
||||
the surplus-COMDAT question remains open and is a whole-tree property, not
|
||||
something an individual object's reconstruction introduced.
|
||||
|
||||
## 6. Guards against fake matching
|
||||
|
||||
A byte match bought with source Bungie would not have written is worth less
|
||||
than an honest residual. Rejected on sight: `volatile`, `register`, `#pragma`,
|
||||
barriers, compiler-flag changes, raw numeric struct offsets, type punning or
|
||||
representation casts, undefined behaviour, byte forcing, and logic that is
|
||||
nonsensical for the function's stated job and only coincidentally matches.
|
||||
|
||||
Three live examples from this run, all correctly refused:
|
||||
|
||||
- The only shape that narrowed `_ai_debug_render_actor` required
|
||||
`real_vector3d *` to `real_point3d *` casts to reach `point_from_line3d`.
|
||||
That is representation punning, so it was reverted - and re-reading the
|
||||
numbers, it only reached 24,864 of 24,976 bytes anyway. It was never a
|
||||
closure, just a 16-byte improvement on a 128-byte gap.
|
||||
- Writing an early return as `*num_primes = i` to deliberately spend a live
|
||||
zero is a coincidence generator, not a reconstruction. XDK 3911 folds it to
|
||||
identical code and it was already on a do-not-repeat list.
|
||||
- A `vehicle_update` shape that forced an increment into both arms of a clamp
|
||||
using two invented file statics measured the right size only because the
|
||||
shortfall was cancelled downstream by alignment padding. The real shape is
|
||||
the `cseries.h` `MIN` macro with the constant on the left and no local
|
||||
increment at all.
|
||||
|
||||
Inline assembly is allowed **sparingly** and **unit-locally** in small helper
|
||||
and math functions. The admitted case is `fast_ftol` (`fld` / `fistp`), because
|
||||
`/QIfist` lowers every C float-to-int conversion through a 64-bit `fistp qword`
|
||||
and a 32-bit inline `fistp` is never compiler output. Keep it `static __inline`
|
||||
in the `.c` that needs it - never in a shared header.
|
||||
|
||||
## 7. Reusable scratch tooling
|
||||
|
||||
Left in `scratch/` by this run (note that `scratch/` is per-worktree and is not
|
||||
committed, so these exist only in the worktree that produced them):
|
||||
|
||||
| file | purpose |
|
||||
| --- | --- |
|
||||
| `alndiff.py` | true alignment diff over normalized capstone streams |
|
||||
| `build1.py` | compile one unit with the real build flags to a chosen `.obj` |
|
||||
| `cs_build.py`, `cs_gate.py`, `cs_blast2.py` | shadow-header-tree blast-radius harness |
|
||||
| `pn_score.py` | score source variants by byte divergence and first-diff offset |
|
||||
| `pn_try.py` | batch-apply source variants through `gate.py` and report |
|
||||
|
||||
Use the committed `tools/fake_match_scan.py` for fake-match review; unlike the
|
||||
scratch helpers above, it is available in every checkout.
|
||||
|
||||
A caution learned twice the hard way: **Python heredocs in this environment eat
|
||||
one level of backslashes.** Build Windows path separators with `chr(92)` rather
|
||||
than writing them literally, or you will silently emit a single-backslash
|
||||
`__FILE__` string where the source needs a doubled one and break relocation
|
||||
identity against the target's string literal.
|
||||
@@ -0,0 +1,355 @@
|
||||
# Common constants and representation reference
|
||||
|
||||
Verified against canonical on 2026-09-08. Start here before guessing literals.
|
||||
|
||||
This is a lookup guide, not a new constants owner. Most rows record high-use
|
||||
names that already have canonical owners; the supplied-source crosswalk is
|
||||
explicitly separate. Future reconstructions should include the
|
||||
owning header and use the existing symbol or macro; they should not duplicate
|
||||
these declarations in a translation unit merely to obtain a desired code
|
||||
shape.
|
||||
|
||||
`Confirmed` below means the value and spelling are present in the named
|
||||
canonical owner. Float bits show the rounded binary32 representation; tag
|
||||
immediates use the pinned MSVC convention. January corroboration is called out
|
||||
explicitly below. A recognizable bit pattern is a lookup clue, not proof of
|
||||
which source expression produced it. `Context-specific` means a value belongs
|
||||
to the stated enum, storage type, or algorithm, not an unrelated global owner.
|
||||
|
||||
## Core values and representations (confirmed)
|
||||
|
||||
| Purpose | Canonical symbol / type | Value or representation | Owning source | Important boundary |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Boolean true/false | `TRUE`, `FALSE` | `1`, `0` | [source/cseries/cseries.h](../source/cseries/cseries.h) | Use these for the project's one-byte `boolean` APIs. A `boolean` i386 return may define only `AL`; a `void` return promises no value. Do not require unrelated upper `EAX` bits. |
|
||||
| Invalid signed index/handle | `NONE` | `-1` (`0xFFFFFFFF` as a 32-bit `long`) | [source/cseries/cseries.h](../source/cseries/cseries.h) | This is not `NULL`. Confirm the destination width: a byte or word sentinel has the narrowed all-ones representation, and some APIs use zero as a distinct valid or invalid value. |
|
||||
| Simulation rate | `TICKS_PER_SECOND`, `ACTUAL_TICKS_PER_SECOND` | `30`, `30` | [source/cseries/cseries.h](../source/cseries/cseries.h) | Express seconds-to-ticks as `seconds * TICKS_PER_SECOND`; express per-tick scale as `1.0f / TICKS_PER_SECOND`. Do not invent a `SECONDS_PER_TICK` owner. The latter folds to float bits `0x3D088889`. |
|
||||
| Wall-clock unit | `MILLISECONDS_PER_SECOND` | `1000` | [source/cseries/cseries.h](../source/cseries/cseries.h) | Do not mix millisecond tag fields with 30 Hz game ticks. Existing code explicitly converts when needed. |
|
||||
| Display cadence | `VBLANKS_PER_SECOND` | `60` | [source/cseries/cseries.h](../source/cseries/cseries.h) | Vblanks are not simulation ticks even though both are integer rates. |
|
||||
| Integer widths | `LONG_BITS`, `SHORT_BITS`, `CHAR_BITS` | `32`, `16`, `8` | [source/cseries/cseries.h](../source/cseries/cseries.h) | These describe the January/Win32 ABI. Preserve signedness as well as width. |
|
||||
| Integer extrema | `LONG_MAX`, `LONG_MIN`, `UNSIGNED_LONG_MAX`, `SHORT_MAX`, `SHORT_MIN`, `UNSIGNED_SHORT_MAX` | `2147483647`, `-2147483648`, `0xFFFFFFFF`, `32767`, `-32768`, `0xFFFF` | [source/cseries/cseries.h](../source/cseries/cseries.h) | Prefer the named bound. `UNSIGNED_LONG_MAX` is also the canonical all-object mask, but that does not make it a universal sentinel. |
|
||||
| Scalar real | `real` | `typedef float real` (4-byte IEEE-754 binary32 in target ABI) | [source/cseries/cseries.h](../source/cseries/cseries.h) | Use `f` suffixes for ordinary `real` constants. Use `double` only where the genuine API or default vararg promotion requires it. |
|
||||
| Engine boolean | `boolean` | `typedef byte boolean`; `byte` is `unsigned char` | [source/cseries/cseries.h](../source/cseries/cseries.h) | It is one byte, not C/C++ `bool` and not a four-byte `long`. This affects fields, parameters, stack snapshots, and return checks. |
|
||||
| Tag word | `tag` | `typedef unsigned long tag` (32 bits in target ABI) | [source/cseries/cseries.h](../source/cseries/cseries.h) | Preserve the four-character group token and the unsigned 32-bit type. |
|
||||
| Coordinate axes | `_x`, `_y`, `_z` | `0`, `1`, `2` | [source/cseries/cseries.h](../source/cseries/cseries.h) | Use these only as component/projection indices. They are not vector values or bit masks. |
|
||||
| Geometric tolerance | `_real_epsilon` | `0.0001f`, binary32 bits `0x38D1B717` | [source/math/real_math.h](../source/math/real_math.h) | This is not a universal replacement for exact-zero tests. January functions use both epsilon and exact `0.0f`; preserve the observed predicate and NaN behavior. |
|
||||
| Pi | `_pi` | `(real)M_PI`, binary32 bits `0x40490FDB` | [source/math/real_math.h](../source/math/real_math.h) | Use the project cast rather than a hand-rounded decimal when the source works in `real`. |
|
||||
| Angle conversion | `DEGREES_TO_RADIANS`, `RADIANS_TO_DEGREES` | `((real)angle) * _pi / 180.f` or `((real)angle) * 180.f / _pi` | [source/math/real_math.h](../source/math/real_math.h) | Angles stored in tags are not uniformly degrees or radians. First authenticate the field's unit; then use the owner macro. Expression order can affect exact float bytes. |
|
||||
| Finite real envelope | `REAL_MIN`, `REAL_MAX` | `-3.4028235e38f`, `3.4028235e38f` | [source/math/real_math.h](../source/math/real_math.h) | `REAL_MIN` here is the most-negative finite bound, not the C-library meaning “smallest positive normal.” |
|
||||
|
||||
January examples that corroborate the float rows are the
|
||||
`__real@38d1b717`, `__real@41f00000`, and `__real@3d088889` relocations in
|
||||
`build/split/source/objects/damage.obj`. They represent `_real_epsilon`,
|
||||
`(real)TICKS_PER_SECOND`, and `1.0f / TICKS_PER_SECOND`; they do not justify
|
||||
replacing the source-level owners with hexadecimal literals.
|
||||
|
||||
## Canonical macros whose semantics matter
|
||||
|
||||
| Macro | Definition owner | Correct use | Pitfall |
|
||||
| --- | --- | --- | --- |
|
||||
| `MIN(a,b)`, `MAX(a,b)` | [source/cseries/cseries.h](../source/cseries/cseries.h) | Ordinary project min/max spelling when January establishes the same comparison and argument order. | Each expression can be evaluated more than once. Argument order controls signed-zero and NaN outcomes: do not normalize or swap operands merely because finite results look equivalent. |
|
||||
| `FLOOR`, `CEILING`, `PIN` | [source/cseries/cseries.h](../source/cseries/cseries.h) | Named lower/upper/clamp operations. | `PIN` is a macro composition, not an IEEE `fminf`/`fmaxf` substitute. It may evaluate the value repeatedly and lets a NaN value pass through under its current ordering. |
|
||||
| `FLAG(bit)` | [source/cseries/cseries.h](../source/cseries/cseries.h) | Convert an enum *bit index* to a mask. | Most `_..._bit` enum members are indices, not masks. Do not apply `FLAG` again to an existing `_..._mask_*` value. Preserve the owning integer width, especially near bit 31. |
|
||||
| `TEST_FLAG`, `SET_FLAG` | [source/cseries/cseries.h](../source/cseries/cseries.h) | Test or mutate a named bit in the authenticated field. | Do not replace an enum bit with a raw hex mask. Avoid side-effecting lvalues/expressions because these are macros. |
|
||||
| `VALID_FLAGS(flags,bits)` | [source/cseries/cseries.h](../source/cseries/cseries.h) | Validate that no bit at or above the declared count is set. | `bits` is a count, not a mask; signedness and shift width matter. |
|
||||
| `BIT_VECTOR_SIZE_IN_LONGS`, `BIT_VECTOR_TEST_FLAG`, `BIT_VECTOR_SET_FLAG` | [source/cseries/cseries.h](../source/cseries/cseries.h) | Long-word-packed bit vectors, 32 flags per `long`. | The macros index a `long` array. Do not silently cast an original `byte *` API to this representation. A byte-buffer use needs independent owner/caller evidence, as documented for the collision BSP boundary in [docs/object_matching_logs/collision_bsp_obj_sphere_cluster_20260904.md](object_matching_logs/collision_bsp_obj_sphere_cluster_20260904.md). |
|
||||
| `NUMBEROF(array)` | [source/cseries/cseries.h](../source/cseries/cseries.h) | Compile-time count of an actual array in the same scope. | On a pointer it returns a pointer-size ratio, not the pointee count. |
|
||||
| `VALID_INDEX(index,count)` | [source/cseries/cseries.h](../source/cseries/cseries.h) | Signed lower-bound and upper-bound check. | Preserve the signed type. Replacing it with an unsigned comparison can alter code shape and invalid-negative behavior. |
|
||||
| `DATUM_INDEX_NEW`, `DATUM_INDEX_TO_ABSOLUTE_INDEX`, `DATUM_INDEX_TO_IDENTIFIER` | [source/cseries/cseries.h](../source/cseries/cseries.h) | Construct or split the 16-bit absolute index / 16-bit identifier handle representation. | A datum handle is not a plain array index. Mask before indexing; do not discard the identifier except at a proven boundary. |
|
||||
| `TAG_BLOCK_GET_ELEMENT` | [source/tag_files/tag_groups.h](../source/tag_files/tag_groups.h) | Typed access through `tag_block_get_element_with_size(..., sizeof(type))`. | The type and element size are part of the runtime contract. Avoid a raw `address + index*stride` replacement. |
|
||||
|
||||
## Tag strings and common group IDs (confirmed)
|
||||
|
||||
`TAG_STRING_LENGTH` is **31** ([source/tag_files/tag_files.h](../source/tag_files/tag_files.h)). A
|
||||
canonical fixed tag string buffer that includes its terminator is therefore
|
||||
usually `char name[TAG_STRING_LENGTH + 1]`, or 32 bytes. The constant is a
|
||||
payload limit, not permission to omit the final NUL.
|
||||
|
||||
MSVC packs the following four-character constants into the shown immediate
|
||||
value. Always write the named owner; the hex form is provided only to read
|
||||
disassembly and relocations. On little-endian x86 the bytes in memory appear
|
||||
least-significant byte first.
|
||||
|
||||
| Domain | Symbol | Source token / i386 immediate | Owner |
|
||||
| --- | --- | --- | --- |
|
||||
| Game globals | `GAME_GLOBALS_TAG` | `'matg'` / `0x6D617467` | [source/game/game_globals.h](../source/game/game_globals.h) |
|
||||
| Scenario | `SCENARIO_TAG` | `'scnr'` / `0x73636E72` | [source/scenario/scenario_definitions.h](../source/scenario/scenario_definitions.h) |
|
||||
| Structure BSP | `STRUCTURE_BSP_TAG` | `'sbsp'` / `0x73627370` | [source/structures/structure_bsp_definitions.h](../source/structures/structure_bsp_definitions.h) |
|
||||
| Base object definition | `OBJECT_DEFINITION_TAG` | `'obje'` / `0x6F626A65` | [source/objects/object_definitions.h](../source/objects/object_definitions.h) |
|
||||
| Damage effect | `DAMAGE_EFFECT_DEFINITION_TAG` | `'jpt!'` / `0x6A707421` | [source/objects/damage_effect_definitions.h](../source/objects/damage_effect_definitions.h) |
|
||||
| Bitmap | `BITMAP_GROUP_TAG` | `'bitm'` / `0x6269746D` | [source/bitmaps/bitmap_group.h](../source/bitmaps/bitmap_group.h) |
|
||||
| Sound | `SOUND_DEFINITION_TAG` | `'snd!'` / `0x736E6421` | [source/sound/sound_definitions.h](../source/sound/sound_definitions.h) |
|
||||
|
||||
Four-character C constants are implementation-defined outside this compiler
|
||||
context. Do not byte-swap them manually or replace a typed getter such as
|
||||
`object_definition_get` with a raw `tag_get` call only to expose the numeric
|
||||
immediate.
|
||||
|
||||
## Common engine enums and limits (confirmed, domain-specific)
|
||||
|
||||
| Domain | Symbol(s) | Value | Owner and boundary |
|
||||
| --- | --- | --- | --- |
|
||||
| Local rendering/input players | `MAXIMUM_LOCAL_PLAYERS` | `4` | [source/game/players.h](../source/game/players.h). This is not the network/player-datum capacity. |
|
||||
| Network join token | `NETWORK_JOIN_GAME_TOKEN_SIZE` | `16` | [source/networking/network_messages.h](../source/networking/network_messages.h). Protocol byte count, corroborated by the supplied source and January's generator/callers; restored in the canonical protocol owner, not a claim about the absent original header. |
|
||||
| Network header direction | `_byte_order_host`, `_byte_order_network` | `0`, `1` | [source/bungie_net/common/message_header.h](../source/bungie_net/common/message_header.h). January inbound reads pass 0; outbound connection/key/rejection writes pass 1. The former inferred host/network labels were reversed; the corrected names preserve every caller's immediate and emitted code. |
|
||||
| Connection creation flags | `_connection_create_server_bit`, `_connection_create_clientside_client_bit`, `_connection_create_serverside_client_bit` | Bit indices `0`, `1`, `2`; masks `1`, `2`, `4` | [source/networking/network_connection.h](../source/networking/network_connection.h). Use `FLAG` at creation calls; these are not the separate closed/stale state bits. |
|
||||
| Network game ports | `NETWORK_GAME_SERVER_PORT`, `NETWORK_GAME_CLIENT_PORT` | `0x141E`, `0x141F` / `5150`, `5151` | [source/networking/network_game_protocol.h](../source/networking/network_game_protocol.h). Shared only by actual protocol consumers; values are not transport-type ordinals. |
|
||||
| Server rejection reasons | `_rejection_code_version_too_old` through `_rejection_code_blacklisted_machine`; `NUMBER_OF_SERVER_REJECTION_CODES` | Reasons `0..6`, count `7`; game full `4` | [source/networking/network_game_protocol.h](../source/networking/network_game_protocol.h). Serialized rejection field is a `word`; count is an exclusive bound, not a valid reason. |
|
||||
| Connection timeout disabled | `_connection_dont_timeout` | `0` | [source/networking/network_connection.h](../source/networking/network_connection.h). The idle API tests a nonzero timeout before enforcing it. This literal is not the separate `global_connection_dont_timeout` debug boolean. Name from supplied source, value from January, header placement reconstructed. |
|
||||
| Public-endpoint datagram capacity | `DATAGRAM_MAXIMUM_SIZE` | `400` / `0x190` bytes | [source/networking/network_connection.h](../source/networking/network_connection.h). Shared connection/provider limit, distinct from the reliable-message receive capacity below. `network_connection_read` takes a `word *` size; a DWORD stack-slot initialization does not make this a 32-bit API. |
|
||||
| IPv4 loopback address | `IPV4_LOOPBACK_ADDRESS` | `0x7F000001` | [source/bungie_net/network/transport_address_constants.h](../source/bungie_net/network/transport_address_constants.h). Source-attested spelling and January compare immediate. Use in the transport address's host-order IPv4 field, not as four already serialized network bytes. This narrow shared header is included by the actual client/server consumers. |
|
||||
| Client/server receive buffer | `MAXIMUM_NETWORK_MESSAGE_SIZE` | `0x800` / `2048` bytes | Local manager enums in [server](../source/networking/network_server_manager.c) and [client](../source/networking/network_client_manager.c). January proves the buffer and word-sized capacity reset. This is not `MAXIMUM_MESSAGE_SIZE=0xFFF` in the separate Bungie-net message header. A word-aligned array preserves the receiving handler's genuine word-pointer contract. |
|
||||
| Difficulty | `_game_difficulty_level_easy`, `_game_difficulty_level_normal`, `_game_difficulty_level_hard`, `_game_difficulty_level_impossible` | `0`, `1`, `2`, `3` | [source/game/game.h](../source/game/game.h). Use the enum; a raw ordinal is ambiguous at a call site. |
|
||||
| Campaign team | `_game_team_default`, `_game_team_player`, `_game_team_human`, `_game_team_covenant`, `_game_team_flood`, `_game_team_sentinel` | `0` through `5` | [source/game/game.h](../source/game/game.h). Multiplayer `_team_red=0`, `_team_blue=1` intentionally overlaps numerically; the field/API determines the namespace. |
|
||||
| Object types | `_object_type_biped` through `_object_type_sound_scenery` | `0` through `11`; `NUMBER_OF_OBJECT_TYPES=12` | [source/objects/object_types.h](../source/objects/object_types.h). Values are ordinals used by object headers and switch statements. |
|
||||
| Object masks | `_object_mask_unit`, `_object_mask_item`, `_object_mask_device`, `_object_mask_all` | `0x3`, `0x1C`, `0x380`, `0xFFFFFFFF` | [source/objects/object_types.h](../source/objects/object_types.h). These are already masks; test them against an object type with the established `TEST_FLAG(mask, type)` convention. |
|
||||
| Object capacity | `MAXIMUM_OBJECTS_PER_MAP` | `2048` | [source/objects/objects.h](../source/objects/objects.h). Capacity is not the current datum count. |
|
||||
| Rendered-object capacity | `MAXIMUM_RENDERED_OBJECTS` | `256` | [source/objects/objects.h](../source/objects/objects.h). Do not use it to size the master object datum array. |
|
||||
| UI deletion input-inhibit mask | `WIDGET_DELETED_PLAYER_CONTROL_INHIBIT_FLAGS` | `0x0FFF` | TU-local owner in [source/interface/ui_widget.c](../source/interface/ui_widget.c). Passed as a `word` to `player_control_inhibit_buttons` when a root widget with a non-`NONE` local-player index is deleted. It fences the evidenced low twelve discrete action buttons until each held button is released; it does not cover analog movement/look, and it is not `UNSIGNED_SHORT_MAX`, a universal all-buttons mask, or a bit index for `FLAG`. |
|
||||
| Markers/regions/attachments | `MAXIMUM_MARKERS_PER_OBJECT`, `MAXIMUM_REGIONS_PER_OBJECT`, `MAXIMUM_NUMBER_OF_ATTACHMENTS_PER_OBJECT` | `64`, `8`, `8` | [source/objects/objects.h](../source/objects/objects.h) and [source/objects/object_definitions.h](../source/objects/object_definitions.h). These belong to different arrays despite sharing an object definition. |
|
||||
| Damage material modifier capacity | `MAXIMUM_NUMBER_OF_MATERIAL_TYPES` | `40` | [source/game/game_globals.h](../source/game/game_globals.h); used by `damage_definition.material_modifiers` at [source/objects/damage_effect_definitions.h](../source/objects/damage_effect_definitions.h). It is storage capacity, not the current named-material count. |
|
||||
|
||||
## Xbox shader encodings (confirmed SDK owners, context-specific)
|
||||
|
||||
The existing [Xbox D3D8 types header](../xbox/include/D3D8Types.h) owns the
|
||||
register-combiner macros and enums. Prefer them to packed hexadecimal shader
|
||||
words; this documents the actual inputs and outputs without creating new
|
||||
engine constants. They are hardware encodings, not Bungie identifier recovery.
|
||||
|
||||
| Encoding | Existing owner / interpretation | Example |
|
||||
| --- | --- | --- |
|
||||
| Four combiner inputs | `PS_COMBINERINPUTS(a,b,c,d)` packs four input bytes | `PS_COMBINERINPUTS(PS_REGISTER_T0, PS_REGISTER_T0, PS_REGISTER_ZERO, PS_REGISTER_ZERO)` is `0x08080000`. |
|
||||
| Input register/mapping/channel | `PS_REGISTER_*`, `PS_INPUTMAPPING_*`, `PS_CHANNEL_*` | `PS_REGISTER_V0 \| PS_INPUTMAPPING_UNSIGNED_INVERT` is `0x24`; `PS_REGISTER_V1 \| PS_CHANNEL_ALPHA` is `0x15`. These are already encoded masks, not bit indices for `FLAG`. |
|
||||
| Constant one input | `PS_REGISTER_ONE` | `0x20`, zero register with unsigned-invert mapping; not a literal register number 32. |
|
||||
| Combiner destinations | `PS_COMBINEROUTPUTS(ab,cd,mux_sum,flags)` | R0/discard/discard/identity is `0xC0`; R1/discard/discard/identity is `0xD0`. |
|
||||
| Stage count | `PS_COMBINERCOUNT(count,flags)` | Counts 1 and 3 with zero flags encode as 1 and 3. Flags zero select the SDK defaults; count is not a bit index. |
|
||||
| Texture addressing modes | `PS_TEXTUREMODES(t0,t1,t2,t3)` with `PS_TEXTUREMODES_*` | PROJECT2D/NONE/NONE/NONE encodes as 1. |
|
||||
|
||||
The Widgets reconciliation replaces these packed words using the existing
|
||||
macros; all generated code and non-debug sections remain unchanged. Do not
|
||||
assign a fixed-function `D3DVSDE_*` semantic name to an arbitrary custom vertex
|
||||
shader register just because its number agrees: Widgets sends color through
|
||||
register 9 and texture coordinates through register 4. The custom shader's
|
||||
input contract, not the fixed-function spelling, determines their meaning.
|
||||
|
||||
## Damage flags relevant to the current caller/helper packet
|
||||
|
||||
These are confirmed but context-specific. The enum values are **bit indices**;
|
||||
use `TEST_FLAG`/`SET_FLAG` rather than the numeric masks shown for audit
|
||||
convenience.
|
||||
|
||||
| Storage | Symbol | Bit / mask | Owner |
|
||||
| --- | --- | --- | --- |
|
||||
| `being_damaged_flags` | `_object_being_damaged_body_depleted_bit` | `0` / `0x01` | [source/objects/damage.h](../source/objects/damage.h) |
|
||||
| `being_damaged_flags` | `_object_being_damaged_shield_depleted_bit` | `3` / `0x08` | [source/objects/damage.h](../source/objects/damage.h) |
|
||||
| `being_damaged_flags` | `_object_being_damaged_by_friendly_bit` | `4` / `0x10` | [source/objects/damage.h](../source/objects/damage.h) |
|
||||
| `being_damaged_flags` | `_object_being_damaged_multiplied_by_difficulty_bit` | `5` / `0x20` | [source/objects/damage.h](../source/objects/damage.h) |
|
||||
| `damage_data.flags` | `_damage_no_statistics_bit` | `7` / `0x80` | [source/objects/damage.h](../source/objects/damage.h) |
|
||||
| `object.damage_flags` | `_object_passed_shield_damage_threshold_bit` | `1` / `0x0002` | [source/objects/objects.h](../source/objects/objects.h) |
|
||||
| `object.damage_flags` | `_object_shield_depleted_bit` | `3` / `0x0008` | [source/objects/objects.h](../source/objects/objects.h) |
|
||||
| `object.damage_flags` | `_object_shield_over_charging_bit` | `4` / `0x0010` | [source/objects/objects.h](../source/objects/objects.h) |
|
||||
| `object.damage_flags` | `_object_cannot_take_damage_bit` | `11` / `0x0800` | [source/objects/objects.h](../source/objects/objects.h) |
|
||||
|
||||
Do not merge the two “shield depleted” names: one is an event/result bit in a
|
||||
32-bit accumulator and the other is persistent object state in a 16-bit
|
||||
field. Their current numeric bit happens to be the same.
|
||||
|
||||
January-specific category, side-effect, material-response, and private-helper
|
||||
values should remain in the owning Damage enum unless a genuine shared owner
|
||||
is found. A comparison against `1`, `2`, or `3` in disassembly is not enough
|
||||
to infer which enum namespace it belongs to. Likewise, the Damage aftermath
|
||||
upward bias and similar algorithm coefficients are not general math
|
||||
constants; retain a semantic local expression and document its function-level
|
||||
provenance instead of exporting a global name.
|
||||
|
||||
## Assertions and object-access macros
|
||||
|
||||
See [the shared assertion API and Units example](assertions.md). Assertions test
|
||||
an invariant that must be true; a diagnostic error condition usually needs
|
||||
negating. `_object_connected_to_map_bit` is bit 11 in `object.flags`, whereas
|
||||
`_object_header_connected_to_map_bit` is bit 5 in a separate header flags byte.
|
||||
Do not substitute one for the other.
|
||||
|
||||
Use typed accessors such as `unit_get`, `weapon_get`, `object_definition_get`,
|
||||
`bitmap_group_get`, and `sound_definition_get` from their existing subsystem
|
||||
headers. Keep raw `tag_get` and object-access casts encapsulated there rather
|
||||
than repeating casts at each call site.
|
||||
|
||||
## Supplied-source crosswalk (evidence, not yet canonical declarations)
|
||||
|
||||
The user supplied three CE source files on 2026-09-06. Their hashes, local
|
||||
locations, target fingerprints, and integration caveats are recorded in the
|
||||
[source reconstruction map](user_source_reconstruction_map_20260906.md).
|
||||
The following names occur there; do not assume they are already available
|
||||
from canonical headers or export TU-private coefficients globally.
|
||||
|
||||
| Supplied name / expression | Value | Canonical correspondence and scope |
|
||||
| --- | --- | --- |
|
||||
| `RANDOM_A` | `1664525L` / `0x0019660D` | Literal in [source/math/random_math.c](../source/math/random_math.c); LCG multiplier, not a general math constant. |
|
||||
| `RANDOM_C` | `1013904223L` / `0x3C6EF35F` | Same owner; LCG increment. Seed arithmetic is unsigned 32-bit modulo arithmetic. |
|
||||
| `RANDOM(seed)` | Update seed, then take its upper 16 bits | Source macro uses a 16-bit right shift; do not substitute low bits or mutate the seed twice. |
|
||||
| `REAL_RANDOM(seed)` | `(1.f / (real)0xffff) * RANDOM(seed)` | Divisor is `65535`, not `65536`; the source real result can reach both 0 and 1. Integer range scaling instead uses a right shift by 16 and is upper-exclusive for its valid range. Preserve expression order and promotions. |
|
||||
| `RANDOM_DIRECTION_TABLE_GEOSPHERE_SEGMENT_COUNT` | `16` | RandomMath's geosphere construction argument, not a player capacity or direction-table length. |
|
||||
| `COUNTDOWN_TIMER_CANNOT_ACCLERATE_AMOUNT` | `MILLISECONDS_PER_SECOND - 1` = `999` | Source spelling includes `ACCLERATE`; canonical server calls it `NETWORK_GAME_MINIMUM_COUNTDOWN_TIME`. |
|
||||
| `CLIENT_COUNTDOWN_TIMER_MODIFICATION_AMOUNT` | `5 * MILLISECONDS_PER_SECOND` = `5000` | Canonical server `NETWORK_GAME_COUNTDOWN_ADJUSTMENT`. |
|
||||
| `LAN_INITIAL_SERVER_GAME_COUNTDOWN` | `31 * MILLISECONDS_PER_SECOND - 1` = `30999` | Canonical server `NETWORK_GAME_COUNTDOWN_TIME`. |
|
||||
| `LOCAL_INITIAL_SERVER_GAME_COUNTDOWN` | `11 * MILLISECONDS_PER_SECOND - 1` = `10999` | Canonical server `NETWORK_GAME_SPLITSCREEN_COUNTDOWN_TIME`. |
|
||||
| `MAXIMUM_SERVER_GAME_COUNTDOWN` | `31 * MILLISECONDS_PER_SECOND - 1` = `30999` | Separate semantic role from the LAN initial time, despite equal values. |
|
||||
| `NETWORK_GAME_CLIENT_CONNECTION_PROCESS_TIMEOUT_MILLISECONDS` | Debug `120000`; release `15000` | Supplied client enum selects `120` or `15` times `MILLISECONDS_PER_SECOND` under `DEBUG`; do not use one build's timeout in the other. |
|
||||
| `NETWORK_GAME_CLIENT_GAME_SEARCH_INTERVAL_MILLISECONDS` | `2000` | Supplied client search cadence, `2 * MILLISECONDS_PER_SECOND`. |
|
||||
| `NETWORK_GAME_CLIENT_GAME_ADVERTISED_GAME_TIMEOUT` | `6000` | Supplied client: twice the search interval plus `2 * MILLISECONDS_PER_SECOND`; not the connection timeout. |
|
||||
| `NETWORK_GAME_CLIENT_GAME_PING_INTERVAL_MILLISECONDS` | `1000` | Supplied client ping cadence, `1 * MILLISECONDS_PER_SECOND`. |
|
||||
| `NETWORK_GAME_CLIENT_INITIAL_PACKET_SEQUENCE_NUMBER` | `1` | Supplied client protocol sequence origin; not a universal first array index. |
|
||||
|
||||
Countdown correspondences are in
|
||||
[source/networking/network_server_manager.c](../source/networking/network_server_manager.c).
|
||||
The supplied server's client-machine flag indices are connected `0`,
|
||||
validated `1`, level-loaded `2`, and precached `3`. Canonical currently uses
|
||||
joined/loaded names for indices 1/2; numeric agreement alone does not authorize
|
||||
a global semantic rename. These flags are not object-datum flags.
|
||||
|
||||
The supplied RandomMath also references `_full_circle`, `_half_circle`, and
|
||||
`_quarter_circle`, but their defining header was not supplied and they are not
|
||||
present in the current canonical math headers. Do not invent a declaration
|
||||
or infer exact expression ordering solely from those names.
|
||||
|
||||
The supplied client names its two flag indices
|
||||
`_network_game_client_connected_to_server_bit = 0` and
|
||||
`_network_game_client_sent_join_request_to_server_bit = 1`. Canonical uses
|
||||
shorter inferred names and literal timing values; restore names only with
|
||||
ordinary strict-object and consumer checks, not by unreviewed bulk replacement.
|
||||
|
||||
## AI profile meter layout
|
||||
|
||||
January's shared AI profiling state is declared in
|
||||
`source/ai/ai_profile.h`. Include that owner when incrementing a meter; do not
|
||||
declare an opaque `extern byte ai_profile[]`, a partial local structure, or a
|
||||
consumer-specific view of the same global.
|
||||
|
||||
- `ai_profile.meters` begins at offset `0x0C`.
|
||||
- There are 28 meter records, each `0x88` bytes.
|
||||
- `accumulator` is at record offset `0`; `current_value` is at offset `2`.
|
||||
- A meter accumulator is therefore at `0x0C + index * 0x88`.
|
||||
|
||||
Frequently used indices and accumulator offsets:
|
||||
|
||||
| meter enum | index | offset |
|
||||
| --- | ---: | ---: |
|
||||
| `_ai_meter_encounters_updated` | 1 | `0x094` |
|
||||
| `_ai_meter_actors_updated` | 3 | `0x1A4` |
|
||||
| `_ai_meter_actors_active` | 4 | `0x22C` |
|
||||
| `_ai_meter_units_updated` | 6 | `0x33C` |
|
||||
| `_ai_meter_units_active` | 7 | `0x3C4` |
|
||||
| `_ai_meter_dead_props_acknowledged` | 9 | `0x4D4` |
|
||||
| `_ai_meter_dead_props_orphaned` | 10 | `0x55C` |
|
||||
| `_ai_meter_dead_props_unacknowledged` | 11 | `0x5E4` |
|
||||
| `_ai_meter_enemy_props_acknowledged` | 12 | `0x66C` |
|
||||
| `_ai_meter_enemy_props_orphaned` | 13 | `0x6F4` |
|
||||
| `_ai_meter_enemy_props_unacknowledged` | 14 | `0x77C` |
|
||||
| `_ai_meter_friendly_props_acknowledged` | 15 | `0x804` |
|
||||
| `_ai_meter_friendly_props_orphaned` | 16 | `0x88C` |
|
||||
| `_ai_meter_friendly_props_unacknowledged` | 17 | `0x914` |
|
||||
| `_ai_meter_collisions` | 21 | `0xB34` |
|
||||
| `_ai_meter_line_of_sight` | 22 | `0xBBC` |
|
||||
| `_ai_meter_line_of_fire` | 23 | `0xC44` |
|
||||
| `_ai_meter_action_change` | 26 | `0xDDC` |
|
||||
|
||||
The leading booleans are independently exposed through the Halo Script
|
||||
global table, which authenticates their names and offsets: `disabled` at
|
||||
`0x00`, `move_actors_randomly` at `0x01`, `show` through
|
||||
`show_sound_distance` at `0x04` through `0x0B`. The complete global is
|
||||
`0xEEC` bytes.
|
||||
|
||||
## Reconstruction checklist
|
||||
|
||||
1. Search for an existing owner before adding a constant, enum, macro, or
|
||||
typedef. Include that owner instead of redeclaring it locally when header
|
||||
placement is safe.
|
||||
2. Establish the storage type and namespace before interpreting `-1`, `0`, or
|
||||
a bit number. `NONE`, `NULL`, a tag index, and a byte terminator are not
|
||||
interchangeable merely because some bytes match.
|
||||
3. Compare exact float bytes and x87 predicates before replacing a literal
|
||||
with `_real_epsilon`, `MIN`, `MAX`, or `PIN`. Finite agreement does not
|
||||
prove NaN, infinity, tangent, or signed-zero agreement.
|
||||
4. Treat enum `_..._bit` members as bit positions and `_..._mask...` members
|
||||
as masks. Keep the owning field width; do not widen a byte/word flag field
|
||||
to `long *` for macro convenience.
|
||||
5. Treat every maximum as a capacity for its named owner, not a current count
|
||||
or a substitute capacity for a nearby array.
|
||||
6. Preserve public type widths at ABI boundaries. In particular, `real` is
|
||||
float and `boolean` is byte even when i386 register or stack mechanics make
|
||||
a mismatched declaration appear to work.
|
||||
|
||||
## Leaf Map construction constants (context-specific)
|
||||
|
||||
These values are authenticated by January's Leaf Map strings, data, control
|
||||
flow, and the reconciled private caller graph. They belong to
|
||||
`source/structures/leaf_map.c`; they are not general geometry constants.
|
||||
|
||||
| Role | Source spelling / value | Boundary |
|
||||
| --- | --- | --- |
|
||||
| BSP traversal stack capacity | `MAXIMUM_NODE_STACK_COUNT = 256` | Assertion text names the constant and aggregate field. Stack entries are signed node designators whose sign bit records the child side. |
|
||||
| Initial face polygon capacity | `MAXIMUM_LEAF_FACE_VERTICES = 64` | Bounds the local clipped polygon and the correctly owned Geometry clip call. |
|
||||
| Portal intersection capacity | `MAXIMUM_PORTAL_VERTICES = 64` | Bounds the temporary intersection polygon; it is not a generic tag-block capacity. |
|
||||
| Initial projected world square | coordinates `+/-1536.f` | The four-point polygon is clipped by every ancestor BSP plane; do not export 1536 as a world-wide coordinate bound. |
|
||||
| Leaf-face clip epsilon | `0.000244140625f` (`1/4096`) | Algorithm-specific clip tolerance, distinct from `_real_epsilon`. |
|
||||
| Portal intersection epsilon | `0.00048828125f` (`1/2048`) | Algorithm-specific intersection tolerance. |
|
||||
| Portal closure thresholds | area `< 0.0025f` or `sqrt(area)/perimeter < 0.01f` | Preserve expression order and the perimeter call; these are not generic degenerate-polygon rules. |
|
||||
|
||||
See [the Leaf Map reconciliation ledger](object_matching_logs/leaf_map_obj_private_graph_reconciliation_20260909.md)
|
||||
for symbol provenance, strict-credit boundaries, and the remaining data/BSS
|
||||
gap.
|
||||
|
||||
## Rasterizer shared-state lookup
|
||||
|
||||
Use `source/rasterizer/rasterizer_frame_statistics.h` for the complete January
|
||||
**0x170-byte** frame-statistics record and its external declaration. Do not
|
||||
introduce another consumer-specific prefix. Dynamic buffer counts are not
|
||||
maximum capacities; model skinning/lighting accumulators count uploaded
|
||||
constant bytes, not objects. See the
|
||||
[shared counter owner ledger](object_matching_logs/rasterizer_frame_statistics_obj_shared_counter_owner_20260906.md)
|
||||
for the current writer-backed fields and intentionally unreviewed interiors.
|
||||
|
||||
Use `source/rasterizer/rasterizer_debug_options.h` for the genuine January
|
||||
debug-options record; do not add another TU-local prefix. The size is **0x8C**
|
||||
(not later HCEA's 0x90). Active Camouflage flags are at 0x41/0x42; January
|
||||
`zbias` at 0x54 is `long`, not `real`; `pad3_scale` is at 0x6C and the six
|
||||
debug reals start at 0x70. The pixel-counter active/enabled pair is 0x88/0x89.
|
||||
Unknown bytes must not inherit later-build names merely by offset.
|
||||
|
||||
The complete 0xF0 Xbox `pixel_shader_definition` is in
|
||||
`source/rasterizer/xbox/rasterizer_xbox_pixel_shader.h`. Use this associated
|
||||
header when a complete type is needed; the broad Xbox header retains its
|
||||
forward declaration to avoid colliding with legacy local definitions.
|
||||
See the [shared-owner/cache admission](object_matching_logs/rasterizer_xbox_active_camouflage_obj_shared_owner_cache_20260906.md)
|
||||
for provenance, the typed initializer and pinned-compiler layout tests.
|
||||
|
||||
### PlayerProfile and S3TC constants
|
||||
|
||||
January; 2026-09-07 owner reconciliation:
|
||||
|
||||
- `source/saved games/player_profile.h` owns the 48-byte profile: name is
|
||||
12 wchar_t at +0, color short at +24, flags word at +26, ten byte map flags
|
||||
at +28, last level short at +38 and eight-byte controller settings at +40.
|
||||
These are not the larger later-PC/PDB profile layout.
|
||||
- `SAVED_GAME_FILE_BLOCK_SIZE` is 512 in saved_game_files.h. PlayerProfile's
|
||||
typed file block has 48 profile bytes, a 20-byte XDK signature and 444 bytes
|
||||
of zeroed padding. Do not serialize uninitialized padding for matching.
|
||||
- `S3TC_BLOCK_PIXELS` is 16 (4 by 4); single-pixel coordinates are 0..3.
|
||||
RGB565 is blue/green/red 5/6/5 in the project's byte-channel order.
|
||||
S3TC's weights are 0.082f, 0.6094f, 0.3086f in that order; maps are
|
||||
RGB4 {0,2,3,1}, RGB3 {0,2,1,3}. These are codec operations, not flag bits.
|
||||
- See [the coherent batch ledger](object_matching_logs/player_profile_s3tc_batch_reconciliation_20260907.md)
|
||||
for evidence limits, safe repairs, retained fuzzy work and exact debits.
|
||||
|
||||
Useful corroborating ledgers:
|
||||
|
||||
- [docs/object_matching_logs/damage_obj_object_damage_update_20260904.md](object_matching_logs/damage_obj_object_damage_update_20260904.md)
|
||||
documents project `real`, enum, flag, tick, and clamp use in a verified
|
||||
Damage owner.
|
||||
- [docs/object_matching_logs/bipeds_obj_jonas_disconnect_bsp_20260827.md](object_matching_logs/bipeds_obj_jonas_disconnect_bsp_20260827.md)
|
||||
records the January all-bits-set `NONE` representation in real object
|
||||
fields.
|
||||
- [docs/object_matching_logs/collision_bsp_obj_sphere_cluster_20260904.md](object_matching_logs/collision_bsp_obj_sphere_cluster_20260904.md)
|
||||
records a specifically authenticated byte-buffer/bit-vector boundary; it is
|
||||
an exception requiring evidence, not a blanket license for representation
|
||||
casts.
|
||||
@@ -0,0 +1,35 @@
|
||||
# January COMMON pool: ordering hypothesis and ownership limits
|
||||
|
||||
Lane C research, 2026-09-22; corrected during canonical reconciliation.
|
||||
|
||||
`linker_common.obj` is a synthetic split of tentative COMMON definitions.
|
||||
Several independently attributed records appear in contiguous clusters whose
|
||||
positions correlate with module order. This is useful as a **negative
|
||||
constraint**, but it does not prove the owner of an individual symbol.
|
||||
|
||||
Every pooled record in `config/contribs.json` resolves to synthetic module 847.
|
||||
The HCEX PDB lists these globals without a compiland. Declaration order and
|
||||
first-reference order do not reliably reproduce the pool order, either.
|
||||
Consequently, do not create a tentative definition merely because the symbol
|
||||
falls between two apparently owned records.
|
||||
|
||||
The original Lane C packet applied that inference too strongly. Canonical
|
||||
reconciliation excluded its 116-definition COMMON wave. An existing owner test
|
||||
reads January's split `rasterizer_frame_statistics` object, where its eponymous
|
||||
global appears only as an UNDEF external. That does **not** prove an import:
|
||||
csplit renders a pooled COMMON record as UNDEF (value 0) in a defining TU and in
|
||||
an importing TU alike, so the test cannot tell them apart and the owner of
|
||||
`_rasterizer_frame_statistics` remains **undetermined** (correction recorded
|
||||
2026-09-26; the test itself and its ownership checks are unchanged). The pool-order
|
||||
hypothesis does not settle it either. The same lack of
|
||||
independent proof affects `hs_syntax_data`, `ai_globals`, and
|
||||
`rasterizer_model_cortana_hack`; their Lane C moves were also not integrated.
|
||||
These are unresolved ownership questions, not credited reconstructions.
|
||||
|
||||
The useful, narrower rule remains: a genuine tentative definition must be
|
||||
uninitialised in source (`struct foo bar;`), while `= 0` or `= NULL` gives the
|
||||
symbol different COFF ownership. Compare both the January object and the
|
||||
rebuilt object's symbol class before accepting a declaration. The read-only
|
||||
`tools/campaign/linker_common_base.py` can inspect the known pool records, but
|
||||
its partial base earns **zero** matching credit under the all-or-nothing data
|
||||
metric. Its output must not be used as an ownership oracle.
|
||||
@@ -0,0 +1,171 @@
|
||||
# H1 tags cross-build intake (2026-09-06)
|
||||
|
||||
## Status and authority
|
||||
|
||||
The user supplied `C:/Users/isabe/Downloads/haloleak2024.rar`, specifically
|
||||
`halo1/h1_tags`. Five explicitly selected executables were extracted for local
|
||||
analysis. No executable was run and no tag assets were extracted. These inputs
|
||||
are **CROSSBUILD_ONLY** evidence, not the January 2002 Xbox target.
|
||||
|
||||
The user subsequently supplied the extracted folder
|
||||
`C:/Users/isabe/Downloads/haloleak2024/halo1/h1_tags`. All five symbol-executable
|
||||
SHA-256 hashes match the archive copies below exactly, so the saved analysis is
|
||||
reusable. The extracted `halo1` subtree also contains no PDB/DBG files at this
|
||||
checkpoint. The source folder remains read-only.
|
||||
|
||||
All five PE timestamps report 2020-11-23; their CodeView paths identify a
|
||||
`build/v140/Win32` build. A timestamp is a claim in the file, not independent
|
||||
build provenance. Each image has zero COFF symbols and zero exports. The
|
||||
CodeView records are **RSDS references to external PDBs**, not embedded PDB
|
||||
contents. The full archive listing contained 211,474 entries, no `.pdb` or
|
||||
`.dbg` files, and three `.map` files that are Halo 2 game assets rather than
|
||||
linker maps. Do not describe the `_symbols.exe` suffix as proof of a complete
|
||||
debug-symbol payload.
|
||||
|
||||
## Exact input identities
|
||||
|
||||
| Executable | Bytes | SHA-256 |
|
||||
| --- | ---: | --- |
|
||||
| `guerilla_symbols.exe` | 9,764,864 | `44538c3effe5a740f6995e7f6867995e81ec7d32ee8bb0bb74f04c2b9c203b83` |
|
||||
| `halo_cache_symbols.exe` | 6,672,896 | `740869688354defd295e28adf94bd4ea41385e9d4a98dc08764515285cf05b55` |
|
||||
| `halo_tag_symbols.exe` | 7,450,624 | `c5f58fe29cdde668d0e30f6848ad50b8f49a28e99c30de2b1bb75cf7bbfb0712` |
|
||||
| `sapien_symbols.exe` | 11,303,424 | `b1f0b207f5f49cb0ce90f5be7957197d3be612593ff52e7a50fc17e2b88a4828` |
|
||||
| `tool_symbols.exe` | 10,631,680 | `079d20d7792e9565b24ab2cff8115f76a6e48749a8e8ffd190f57954495f0a97` |
|
||||
|
||||
The missing PDBs must match **both GUID and age**, not just basename:
|
||||
|
||||
| PDB basename | GUID | Age (decimal) |
|
||||
| --- | --- | ---: |
|
||||
| `guerilla_symbols.pdb` | `9b751e93-d090-4fbf-9a7c-d8e3cbcb1866` | 125 |
|
||||
| `halo_cache_symbols.pdb` | `7f03f998-b7b0-4ea6-b18f-a6506e3442e5` | 14 |
|
||||
| `halo_tag_symbols.pdb` | `eac025b6-d3f8-4ae9-a47e-9882d7c58906` | 107 |
|
||||
| `sapien_symbols.pdb` | `82b677b3-b983-4c49-912e-ae5641ce5f76` | 87 |
|
||||
| `tool_symbols.pdb` | `3e2e627d-3e3b-4396-afd6-8ded91e9d954` | 80 |
|
||||
|
||||
## Local evidence and tools
|
||||
|
||||
Research root:
|
||||
`C:/Users/isabe/Documents/Codex/2026-07-13/i-w/research/symbol-build-h1-tags-20260906`
|
||||
|
||||
- `manifest.json`: PE sections, debug-directory records, exact PDB paths,
|
||||
identities, and explicit limits.
|
||||
- `inspect_builds.py`: regenerates the manifest using `pefile`, without
|
||||
executing or modifying the five input images.
|
||||
- `ghidra-scripts/CrossBuildInventory.java`: exports observed function names,
|
||||
their Ghidra source classification, and body ranges. It performs no renames.
|
||||
- `ghidra-projects/h1-tags-crossbuild.gpr`: new, separate cross-build project.
|
||||
- `ghidra-import.log`: successful automatic analysis and save of
|
||||
`halo_cache_symbols.exe` (187 seconds, no timeout).
|
||||
- `ghidra-import-remaining-retry.log`: the other four executables were imported
|
||||
and saved with `-noanalysis`. The already-imported cache executable was
|
||||
rejected as a duplicate and was **not overwritten**.
|
||||
- `ghidra-export-explicit-bundle.log` and
|
||||
`ghidra-export-cache-verified.log`: successful read-only inventory exports.
|
||||
Earlier export attempts failed independently of the saved imports. The
|
||||
explicit `ghidra-scripts/META-INF/MANIFEST.MF` and a subsequent run resolved
|
||||
script-bundle loading. The installed headless README names an unavailable
|
||||
timeout method; the installed Java source calls it `analysisTimeoutOccurred`.
|
||||
The inventory script now uses plain `GhidraScript`; analysis completion is
|
||||
established by the analysis log, not by a no-analysis export run.
|
||||
|
||||
Verified original-project status at the 2026-09-06 handoff (see the separate
|
||||
2026-09-07 analysis update below):
|
||||
|
||||
| Program | Analysis status | Observed function records |
|
||||
| --- | --- | ---: |
|
||||
| `halo_cache_symbols.exe` | Automatic analysis completed | 17,858 |
|
||||
| `halo_tag_symbols.exe` | Imported only; analysis pending | 18 |
|
||||
| `guerilla_symbols.exe` | Imported only; analysis pending | 5 |
|
||||
| `sapien_symbols.exe` | Imported only; analysis pending | 11 |
|
||||
| `tool_symbols.exe` | Imported only; analysis pending | 32 |
|
||||
|
||||
Function inventories are `<executable>.functions.tsv`. These counts include
|
||||
analysis-created functions/thunks and imports, **not recovered original Halo
|
||||
function counts**. Preserve each row's source classification and do not count
|
||||
names lacking a `FUN_` prefix as original symbols.
|
||||
For the analyzed cache executable, 17,525 records have Ghidra source `DEFAULT`,
|
||||
324 have `ANALYSIS`, and nine have `IMPORTED`; none establishes missing PDB
|
||||
contents. The `.gpr` file is a zero-byte project marker; its sibling `.rep`
|
||||
directory holds the databases and must stay with it.
|
||||
|
||||
The existing Ghidra installation was found by following its saved application
|
||||
log, not by assuming it was on PATH:
|
||||
`C:/Users/isabe/Documents/Codex/halo-tools/apps/ghidra_12.1.2_PUBLIC`.
|
||||
Its configured JDK is the sibling `jdk-21.0.11+10` directory. The live RPC
|
||||
endpoint at `127.0.0.1:18081` was offline at intake; the headless launcher is
|
||||
usable independently. Only Ghidra's local settings/cache directories needed
|
||||
additional write permission; the new project and outputs stay in the workspace.
|
||||
|
||||
IDA has not been located in the available tools, PATH, ordinary installation
|
||||
directories, registry installation entries, or the local Halo tool bundle.
|
||||
**The user's requirement to use both IDA and Ghidra remains outstanding.** Do
|
||||
not claim that Ghidra, Capstone, or a PE parser satisfies the IDA half. A usable
|
||||
installation/license or further location evidence is needed. Do not upload
|
||||
these inputs to a cloud decompiler or symbol service without authorization.
|
||||
|
||||
Keep the executables, databases, and generated bulk inventories local. This
|
||||
ledger records pointers and hashes only; it is not authorization to publish
|
||||
the supplied binary corpus.
|
||||
|
||||
## Reconstruction plan and limits
|
||||
|
||||
1. Identify the source build and validate any future PDB against the recorded
|
||||
GUID/age before loading its names/types into its own donor database.
|
||||
2. Preserve evidence categories: imported API names, disassembler inference,
|
||||
diagnostic literals, genuine debug records, and independently January-proven
|
||||
facts are different things. A generated `FUN_...` name is not an original
|
||||
name and must not become a production `code_<address>` substitute.
|
||||
3. Use diagnostic strings, callers, data references, and instruction/CFG
|
||||
comparisons to propose January correspondences. Verify each mapping locally;
|
||||
never add one global address delta across builds.
|
||||
4. "Un-inline" means recover and annotate candidate helper operations and their
|
||||
call-site relationships where evidence permits. It cannot recreate all lost
|
||||
source, local variables, or original inline boundaries. Do not rewrite the
|
||||
January target, force new calls, or emit a `point_from_line3d` COMDAT to make
|
||||
the donor's decompilation look tidier.
|
||||
5. Names and types can accelerate source reconstruction, but exact credit still
|
||||
requires the January COFF byte/relocation, source-authenticity, whole-TU,
|
||||
whole-tree regression, and object-admission gates. No canonical code bytes
|
||||
are earned by this intake or by automatic analysis alone.
|
||||
|
||||
## 2026-09-07: seven further programs analyzed and saved
|
||||
|
||||
The original project/cache analysis above remains preserved. A separate project
|
||||
now holds the four remaining Symbols programs and the three supplied Play
|
||||
programs:
|
||||
`C:/Users/isabe/Documents/Codex/2026-07-13/i-w/research/hs7/remaining-projects/h1-tags-remaining-seven.gpr`.
|
||||
Keep its sibling `.rep` directory with it. No supplied executable was run.
|
||||
|
||||
All seven Programs were saved and 21 detailed exports were produced. Input
|
||||
hashes and exported PDB GUID/ages were rechecked. The bounded analysis phases
|
||||
finished with warnings for Halo Tag Symbols (19,228 function records), Sapien
|
||||
Symbols (54,820), Guerilla Play (3,770), Sapien Play (9,045) and Tool Play
|
||||
(7,893). Guerilla Symbols (41,854) and Tool Symbols (46,630) reached their
|
||||
300-second limits and remain explicitly **partial**, not complete analyses.
|
||||
|
||||
The local guide is `research/hs7/ANALYSIS_GUIDE.md` under the outer workspace;
|
||||
the detailed functions/types/metadata exports are in `research/hs7/analyze-detailed`.
|
||||
`research/hs7/remaining-analysis-summary.json` has SHA-256
|
||||
`dbe1283d88ae4b8839b42888e7f80d70be4a87233824a99f7c6a77540bae5aaa`.
|
||||
The guide records source classifications, timeout evidence, API-type archive
|
||||
provenance and analyzer warnings, including WindowsResourceReference's OSGi
|
||||
warning. PDB analyzers were disabled because matching PDBs are absent; no
|
||||
external symbol download was performed. These generated records are not
|
||||
restored original names, inline boundaries or debug assets, and earn no exact
|
||||
code credit. IDA remains unlocated and that part of the request is outstanding.
|
||||
|
||||
## Related networking evidence
|
||||
|
||||
[Exploring The Halo 1 System Link Protocol](https://hllmn.net/blog/2023-09-18_h1x-net/)
|
||||
provides retail PAL packet/debugger evidence. Its decoded advertisement retains
|
||||
the suffix `age in a bot`. This corroborates, but does not independently prove
|
||||
for January, our source-attested join-token implementation: the first four
|
||||
bytes are transformed while the remaining twelve survive. The article's
|
||||
two-second search cadence is another comparison lead. Its PAL timing and
|
||||
absolute addresses must not replace January constants or addresses.
|
||||
|
||||
Use the article's emulator-boundary inspection method as a future local
|
||||
runtime-validation aid. No live interception or traffic manipulation was
|
||||
performed for this intake. The canonical token implementation and runtime tests
|
||||
are documented in
|
||||
`docs/object_matching_logs/network_server_manager_obj_source_attested_packet_20260906.md`.
|
||||
@@ -1,656 +0,0 @@
|
||||
# Halo Custom Edition maps
|
||||
|
||||
The native builds (Linux, Windows, Android) load and run Halo Custom Edition
|
||||
caches (`.map`, cache version 609), with the Custom Edition resource maps
|
||||
`bitmaps.map`, `sounds.map` and `loc.map`. A cache that needs OpenSauce
|
||||
(its OpenSauce header asks for memory upgrades, mod data files or the like)
|
||||
is refused, and `.yelo` files are never looked for; a `.map` that only
|
||||
carries OpenSauce's header and its `project_yellow` tags (SPV3's
|
||||
backwards-compatible releases) is run as stock Custom Edition runs it,
|
||||
neither read. The loader and the conversions come from DamnationCE
|
||||
(xshxdex98/DamnationCE), whose documentation this file grew from; in this
|
||||
build a Custom Edition map's tags are also checked by the tag validator, as
|
||||
the Xbox maps' are, before anything reads them
|
||||
(`port/linux/game/tag_validate.c`, [Checks](#checks)).
|
||||
|
||||
## Running a map
|
||||
|
||||
Custom Edition maps run when the `game.custom_edition` setting is on, as it
|
||||
is by default (`custom_edition = true` under `[game]` in `config.toml`, or
|
||||
`HALO_CUSTOM_EDITION`). Put the maps and Custom Edition's `bitmaps.map`,
|
||||
`sounds.map` and `loc.map` in the data root's `custom_maps` folder, beside
|
||||
its `maps` folder, which holds the game's own maps only; or set
|
||||
`paths.custom_edition` to a Halo Custom Edition install, whose `maps` folder
|
||||
(the Xbox drive `h:\`) is looked in after `custom_maps`.
|
||||
|
||||
A Custom Edition map's level name is `custom_maps\<name>`
|
||||
(`custom_edition_cache.h`, `CUSTOM_EDITION_LEVEL_NAME_PREFIX`), which none
|
||||
of the game's own levels has: only such a name is loaded from the Custom
|
||||
Edition folders, and never from `maps`. So a map named as one of the game's
|
||||
own levels (CMT's `a30.map`, Custom Edition's `bloodgulch.map`) is played as
|
||||
itself, apart from the level of its name, in the menus, the loader and
|
||||
network games, and is never taken for one of the campaign's levels (saved
|
||||
games, progress, the next level). The game engine keeps 63 characters of a
|
||||
level name, so a map whose file name is longer than 51 is not listed.
|
||||
|
||||
Maps keep their names. A network game's level name is the map's own
|
||||
(`custom_maps\hugeass`), and its game record's map version is the first 32
|
||||
bits of the map's hash (`port/linux/game/map_share_files.c`), so a client
|
||||
plays its file of that name and version, whatever else it has of the name
|
||||
(`custom_edition_map_find_version`); a player without it downloads it
|
||||
(`port/linux/NETCODE.md`, "Map sharing"). A download beside another version
|
||||
of its name is named `hugeass_0e2b3ee4.map`, the first 8 hexadecimal digits
|
||||
of its hash after `_`, and the menus show it as "Hugeass (2)". A level name
|
||||
without the hash (a saved last map, a test's) finds the one map of that
|
||||
name in `custom_maps`, and one with it (an earlier build's, which named
|
||||
every map so) the map given its name back. Maps in a Custom Edition
|
||||
install's folder are found and shared as `custom_maps`' are.
|
||||
|
||||
A map needs only the resource maps that hold its tags: its tag index says
|
||||
which (`cache_file_resource_maps_needed`, `cache_file_formats.c`: a tag
|
||||
whose entry's word at 0x18 is set is held whole by `bitmaps.map` for a
|
||||
bitmap, `sounds.map` for a sound, `loc.map` for a font, string list or HUD
|
||||
message text). A map without such tags of a kind plays without that
|
||||
resource map; one that lacks a resource map it needs is refused, saying
|
||||
which.
|
||||
|
||||
### In the menus
|
||||
|
||||
The map lists (New Game's, and the Map screen of Create Game's INTERNET and
|
||||
LAN and of split screen) have four kinds in their first row's chooser:
|
||||
SINGLEPLAYER (the campaign's levels), MULTIPLAYER (the Xbox's maps), and
|
||||
CUSTOM SINGLEPLAYER and CUSTOM MULTIPLAYER, the Custom Edition maps of the
|
||||
custom maps folders by the scenario type their files give (solo or
|
||||
multiplayer). A map is played as its kind says
|
||||
(`port/linux/game/menu_functions.c`):
|
||||
|
||||
- **New Game**: a CUSTOM SINGLEPLAYER map is played as the campaign's
|
||||
levels are, at the difficulty chosen next (alone, or with split screen
|
||||
co-op's two players); a CUSTOM MULTIPLAYER map is walked around alone, as
|
||||
MULTIPLAYER's are.
|
||||
- **The Map screen**: a CUSTOM SINGLEPLAYER map lists the difficulties and
|
||||
is hosted as a network co-op game (Server Setup, then the lobby), as the
|
||||
campaign's levels are; a CUSTOM MULTIPLAYER map goes on to the gametypes,
|
||||
as MULTIPLAYER's do. Split screen hosts only the multiplayer kinds.
|
||||
|
||||
The Xbox menus' multiplayer level list offers the Custom Edition multiplayer
|
||||
maps after the thirteen Xbox levels. The pregame lobby shows a Custom
|
||||
Edition map by its name and picture, multiplayer or campaign, and the game
|
||||
lists by its name (`port/linux/game/custom_edition_maps.c`). The folders are
|
||||
looked in once, and again each time a map list opens, which then shows maps
|
||||
added since. A map is listed under its file's name, `the_bay_of_pigs.map` as
|
||||
"The Bay Of Pigs". Two optional files beside the map give it what the Xbox
|
||||
levels have:
|
||||
|
||||
- `<name>.bmp`, its picture: an uncompressed 24-bit or 32-bit Windows
|
||||
bitmap, up to 8192 pixels a side; the middle of it is shown with the
|
||||
shape of the level pictures, 140 by 114 (`port/linux/game/bmp_files.c`,
|
||||
which reads it as untrusted input).
|
||||
- `<name>.txt`, its description: plain text, its lines shown as written.
|
||||
Without one, the map is described as "Halo Custom Edition map".
|
||||
|
||||
A machine joining a network game on a map it has not (a Custom Edition map
|
||||
not in its `custom_maps`, or one of the game's own not in `maps`) leaves it
|
||||
with an error that names the map and the folder to copy it into, rather
|
||||
than the damaged disc error precaching a missing map gives
|
||||
(`cache_files_map_present`, called as the host's settings arrive): also when
|
||||
the map cannot run there (Custom Edition maps turned off, the file not a
|
||||
Custom Edition cache, or `bitmaps.map`, `sounds.map` and `loc.map` missing),
|
||||
when its copy of a Custom Edition map is another version than the host's
|
||||
(the host sends its map's hash's first 32 bits as the game record's map
|
||||
version, which the Xbox left 0: `cache_files_map_version`; a host that sends
|
||||
0 is not checked), and when the host names a Custom Edition map as other
|
||||
versions of this port do (`levels\test\<name>\<name>`) and the file is in
|
||||
`custom_maps`. The
|
||||
error's text is wrapped to its dialog, in the menus' smaller font when it
|
||||
would not fit; `debug.txt` has the details.
|
||||
|
||||
A Custom Edition campaign map has no next level: winning it ends the game
|
||||
as the campaign's last level does (alone) or plays it again (network
|
||||
co-op), and it is not the campaign's saved game.
|
||||
|
||||
### From the console
|
||||
|
||||
`map_name` takes the level name: `custom_maps\<name>` for a Custom Edition
|
||||
map (`custom_maps\hugeass` plays `custom_maps\hugeass.map`). A multiplayer
|
||||
scenario needs a game variant, or no starting location qualifies and no
|
||||
player spawns:
|
||||
|
||||
```
|
||||
game_variant slayer
|
||||
map_name custom_maps\hugeass
|
||||
```
|
||||
|
||||
## What the native builds do
|
||||
|
||||
- **With `game.custom_edition` on**, the platform reserves the address
|
||||
window Custom Edition tag data is linked to, `0x40440000`-`0x41B40000`
|
||||
(`port/linux/src/xbox_memory.c`, at start-up; 23 MB of address space,
|
||||
backed as it is touched), and a Custom Edition map is loaded into it,
|
||||
converted as below, checked, and run. It is read in place, never copied
|
||||
to the cache partition: every read the game makes of it (structure BSPs,
|
||||
bitmap pixels, sound samples) is served from the map, `bitmaps.map`,
|
||||
`sounds.map` or the sounds decoded at load, according to where its offset
|
||||
falls in their combined offset space (`custom_edition_cache_read`). A map
|
||||
that fails any check is logged in `debug.txt` and not loaded: the game
|
||||
goes back to its menus.
|
||||
- **With it off**, a Custom Edition cache is named and refused, instead of
|
||||
being rejected as "an old version" of this build's caches; so is one put
|
||||
in `maps`, which is told to go in `custom_maps`.
|
||||
- **Xbox caches** take the path they took before.
|
||||
|
||||
The desktop builds' Xbox memory window is 512 MB (Android's 128 MB), in
|
||||
which the texture cache is 256 MB: Custom Edition maps draw more texture
|
||||
than the Xbox's 22 MB cache holds, and their geometry is made into
|
||||
Direct3D buffers in the same memory (`port/linux/include/halo_port_capacity.h`).
|
||||
|
||||
## Loading and conversion
|
||||
|
||||
### The loader (`cache_file_formats.c`)
|
||||
|
||||
`port/linux/game/cache_file_formats.c` (`cache_file_formats.h`) holds the
|
||||
format code: standalone C with fixed-width types and no game dependencies,
|
||||
compiled into the native builds (as every `port/linux/game` unit is) and
|
||||
into the report tool. Map files are untrusted input: every field is read
|
||||
little-endian from a bounds-checked buffer, never through a structure laid
|
||||
over the file, and every offset, count and size is checked before use, with
|
||||
overflow-safe arithmetic. `port/tools/cache_file_report.c` reports what can
|
||||
be done with each file:
|
||||
|
||||
```sh
|
||||
clang --target=i686-pc-windows-msvc -fuse-ld=lld -Iport/linux/game \
|
||||
port/linux/game/cache_file_formats.c port/tools/cache_file_report.c -o cache_file_report.exe
|
||||
cache_file_report [--maps DIRECTORY] [--dump-tags FILE] FILE...
|
||||
```
|
||||
|
||||
Resource maps are looked for next to the cache (or in `--maps`):
|
||||
`bitmaps.map`, `sounds.map` and `loc.map`. `--dump-tags` writes the converted
|
||||
tags to a file, as they would sit at `0x40440000`.
|
||||
|
||||
Loading, step by step (`custom_edition_cache_load`):
|
||||
|
||||
1. The header: signatures, version 609, terminated strings, file length (0,
|
||||
as Invader leaves it, for the whole file) within the file and the size
|
||||
limit (`0x30000000`: Halo PC's was `0x18000000`, and Invader builds
|
||||
larger maps, which Chimera runs), no compression, tag data within the
|
||||
file and the tag cache (23 MB). A cache with OpenSauce's header (its
|
||||
`yelo` signature at offset `0x70`, which Custom Edition leaves as
|
||||
padding) that sets any of its flags (memory upgrades, mod data files and
|
||||
the rest) is refused; one that sets none is a Custom Edition cache.
|
||||
2. The tag data is read to the start of the tag cache, which stands for
|
||||
`0x40440000`.
|
||||
3. The tag index (`tags` signature), every tag instance (its handle must
|
||||
match its position, its name must lie in the tag data and be terminated,
|
||||
its address must lie in the tag data; only structure BSPs may have none;
|
||||
only bitmaps, sounds, fonts, unicode string lists and HUD message text may
|
||||
be held by resource maps; OpenSauce's `project_yellow` and
|
||||
`project_yellow_globals`, which nothing reads, are left as they are), the
|
||||
model data range, and the scenario tag.
|
||||
4. Every structure BSP: its tag, its range in the file, its place in the tag
|
||||
cache (above the tag data, within the tag cache), its header (`sbsp`
|
||||
signature, no Xbox vertex buffers, its structure pointer inside it), and
|
||||
its lightmaps and their materials: every block within the BSP and aligned,
|
||||
every material's uncompressed environment vertices (56 bytes) and
|
||||
lightmap vertices (20 bytes) within the BSP and of the size their counts
|
||||
give, at most 64000 of each (the game's limit, to which the validator
|
||||
cuts a material's counts), lightmap vertices exactly when the lightmap
|
||||
has a bitmap, and every normal, binormal, tangent and incident radiosity
|
||||
within ±1.005 (the game's vertex compressor asserts on anything further
|
||||
out).
|
||||
5. The header checksum is computed as OpenSauce computes it, before anything
|
||||
changes the tag data; a mismatch is reported, not refused.
|
||||
6. The tags held by resource maps are read into the tag cache after the tag
|
||||
data, below the lowest structure BSP, and their pointers relocated. A
|
||||
sound's header in the map lacks its sample rate, encoding, compression
|
||||
and longest permutation length; they are taken from the header's copy in
|
||||
`sounds.map` ([Evidence](#observed-not-stated-by-the-sources-established-on-the-sample-maps)).
|
||||
7. Every bitmap, sound, font, unicode string list, HUD message text, model
|
||||
(`mod2`) and transparent chicago shader (`schi`, `scex`) is walked through
|
||||
its blocks: every block and data pointer must lie within the loaded tags,
|
||||
every bitmap's pixels and sound's samples within their file, and every
|
||||
model part's strip and vertices within the model data, of the kinds Custom
|
||||
Edition writes (a precompiled strip, uncompressed 68-byte vertices), with
|
||||
at most 65535 vertices and at most 22 local nodes.
|
||||
|
||||
Then `custom_edition_cache_convert` changes what only needs its bytes
|
||||
changed:
|
||||
|
||||
- **Shader types.** Custom Edition inserted *transparent chicago extended*
|
||||
as shader type 7, so its water, glass, meter and plasma shaders are types
|
||||
8 to 11 where this build has 7 to 10 (and would draw a Custom Edition glass
|
||||
shader as meter, and so on, unnoticed). Every shader gets this build's
|
||||
number for its group; a type field saying otherwise (as map protection
|
||||
leaves them) is counted and given the group's.
|
||||
- **Transparent chicago extended shaders** (`scex`) become transparent
|
||||
chicago shaders (`schi`): the two layouts agree up to the maps, of which
|
||||
`scex` has two sets, for four and for two texture stages; the four-stage
|
||||
maps are kept (this build draws four stages), or the two-stage ones when
|
||||
there are no others, and the extra flags move to where `schi` has them.
|
||||
- **Bitmaps and sound permutations** get the state of ones not yet drawn or
|
||||
played, and name their own tags: `bitmaps.map` and `sounds.map` hold the
|
||||
tag handles of whatever map they were built with.
|
||||
- **Sounds this build cannot decode** (Custom Edition's Ogg Vorbis) are made
|
||||
unplayable, by emptying their pitch ranges, which the game skips.
|
||||
- **Animation overlays naming animations that do not exist** are made to
|
||||
name none, which the game skips. Maps built with the editing kit can have
|
||||
them; Custom Edition reads past the graph's animations there, and this
|
||||
build's debug builds stop on it.
|
||||
- **HUD elements drawn from double-resolution bitmaps.** Halo PC added a
|
||||
third scaling flag to HUD placements, *use high resolution scale*
|
||||
(OpenSauce `hud_definitions.hpp`), and draws a flagged element at half the
|
||||
size of its bitmap. Custom Edition's HUD bitmaps are made for that: in
|
||||
`bloodgulch.map` every flagged element draws a bitmap exactly twice the
|
||||
size of the one its Xbox counterpart draws (256×64 for 128×32, 512×512 for
|
||||
256×256), with the same scale, and every unflagged one a bitmap of the same
|
||||
size ([Evidence](#observed-not-stated-by-the-sources-established-on-the-sample-maps)).
|
||||
This build ignores the flag, so it drew them twice too large; the
|
||||
placements of the unit, weapon and grenade HUD interfaces and the HUD
|
||||
globals' messages that have it get half their scale, and lose the flag (32
|
||||
in `bloodgulch.map`). Halo PC reads the flag only on statics, meters and
|
||||
numbers (Chimera's `hud_bitmap_scale.cpp`): crosshair and overlay items
|
||||
keep their scale. A number's scale is not its
|
||||
digits', so a flagged number keeps the flag and `hud_draw_numbers` draws
|
||||
its digits at half their size, spaced as the digits tag says. A bitmap may ask the
|
||||
same of every element that draws it, with Halo PC's bitmap flags *half hud
|
||||
scale* and *force hud use highres scale* (Invader's `bitmap.json`): an
|
||||
element drawing such a bitmap (a static or meter, its bitmap after its
|
||||
placement; a crosshair's or overlay's items, their crosshair's or
|
||||
overlay's) gets half its scale too. None of the 18 Custom Edition maps on
|
||||
hand, nor `bitmaps.map`, sets either.
|
||||
- **Maps made around Halo PC's own behaviour.** Chimera fixes Halo PC to draw
|
||||
as the Xbox does, and keeps a list of the maps made around Halo PC's way
|
||||
instead, by map name (in lower case) and tag data checksum, with the
|
||||
behaviours each relies on (`map_hacks_config.json`, by SnowyMouse; here
|
||||
`port/linux/game/custom_edition_behaviours.inc`, generated from it). This
|
||||
build draws as the Xbox does, so for a listed map it follows these where it
|
||||
can, and logs each: HUD multitexture overlays' blend functions in Halo PC's
|
||||
order (`gearbox_multitexture_blend_modes`: Halo PC picks its shader by the
|
||||
Xbox's value from shaders in alphabetical order), overlays not drawn
|
||||
(`block_multitexture_overlays`), the HUD digits' metrics halved and every
|
||||
number's digits drawn at half size (`hud_number_scale`), bitmaps' HUD scale
|
||||
flags cleared (`disable_bitmap_hud_scale_flags`), and model shaders'
|
||||
detail after reflection flag flipped (`invert_detail_after_reflection`).
|
||||
Not yet: Halo PC's fixed-function meters (`gearbox_meters`), its
|
||||
transparent chicago multiply, bump attenuation and environment shader
|
||||
types, the old widescreen HUD and embedded Lua.
|
||||
- **The score hint.** String 100 of `ui\multiplayer_game_text` is Halo PC's
|
||||
`Hold "%s" for score`, which Halo PC fills in with its score key; this
|
||||
build copies it as it is (`game_engine.c`, the press-back-for-score
|
||||
message), so `"%s"` becomes `BACK`, the button this build reads for the
|
||||
score, in the same four characters.
|
||||
|
||||
### In the game (`custom_edition_cache.c`, `custom_edition_geometry.c`, `custom_edition_bitmaps.c`)
|
||||
|
||||
- **Models.** Every `mod2` part is given this build's part layout (the first
|
||||
0x68 bytes of the 0x84-byte Custom Edition part are the same fields; the
|
||||
parts are repacked in place), its vertices are compressed from the map's
|
||||
model data by the game's own `rasterizer_geometry_compress_vertices`, its
|
||||
node indices made the model's when its model's parts have local nodes, and
|
||||
its strip copied unchanged; the game's own `rasterizer_vertex_buffer_new`
|
||||
and `rasterizer_triangle_buffer_new` make its buffers, and the tags become
|
||||
`mode` tags. Before any of that, every index a part holds is checked
|
||||
against what it names (shaders, nodes, parts, vertices). This build's
|
||||
renderer skins at most 43 nodes at once, so a model of more is drawn a
|
||||
part's own nodes at a time: a model of more whose parts have no local
|
||||
nodes is given them, each part the nodes its vertices name, and is refused
|
||||
only when a part's vertices name more than a part holds.
|
||||
- **Structure BSPs.** When the game loads a BSP, every material's vertices
|
||||
are compressed the same way (environment and lightmap vertices), and the
|
||||
material gets buffers and the compressed vertices the game reads for
|
||||
visibility, collision and lights (`scenario_structure_bsp_load` in
|
||||
`cache_files.c` calls `custom_edition_structure_bsp_load`).
|
||||
- **Bitmaps.** Every bitmap must pass the game's own `bitmap_verify` and be
|
||||
of a kind the texture cache and the swizzling code handle (a format with a
|
||||
hardware texture, a compressed flag that agrees with the format,
|
||||
power-of-two sizes unless linear, square cube maps, all its pixels
|
||||
present). Halo PC draws a 2D bitmap of any size, so an uncompressed one
|
||||
whose sides are not powers of two is made linear as the map loads, and
|
||||
drawn from its first level (birdcage-plus's 3840 by 64 needler plasma).
|
||||
Its pixels are laid out for Halo PC, levels as the tag stores them,
|
||||
unswizzled; as they arrive, the game's own
|
||||
`rasterizer_xbox_bitmap_rebuild_hardware_format` lays them out as an Xbox
|
||||
cache would (swizzled, cube maps face by face, padded).
|
||||
- **Chicago extra layers.** January's transparent chicago shader draws its
|
||||
extra layers in a loop that never advances
|
||||
(`rasterizer_xbox_transparent_geometry.c`, marked as a preserved bug). No
|
||||
Xbox map has such layers, so January never hung on it, but Custom
|
||||
Edition's editing kit can make them: the native builds advance the loop.
|
||||
- **Channel orders.** Halo PC keeps two kinds of texture in other channels
|
||||
than this build reads them from (`enum custom_edition_channel_order`,
|
||||
[Evidence](#observed-not-stated-by-the-sources-established-on-the-sample-maps)):
|
||||
a model shader's *multipurpose map*, whose auxiliary (detail) mask,
|
||||
self-illumination, specular and color change masks Halo PC keeps in red,
|
||||
green, blue and alpha, where this build's model shaders read specular from
|
||||
red, self-illumination from green, color change from blue and the
|
||||
auxiliary mask from alpha; and a *HUD meter*, whose shape Halo PC keeps in
|
||||
color and fill order in alpha, where this build's meter shader
|
||||
(`rasterizer_xbox_dynavobgeom.c`) compares the color with the meter's value
|
||||
and discards what has no alpha. Reordering the pixels would mean
|
||||
decompressing them, which the texture cache has no room for, so the game
|
||||
finds the bitmaps drawn as multipurpose maps (by model shaders) and as
|
||||
meters (by unit and weapon HUD interfaces) when the map loads, and tells
|
||||
the renderer where each bitmap's pixels arrive and in which order their
|
||||
channels are; the renderer samples them with each channel taken from where
|
||||
Halo PC keeps it (`port/linux/src/xbox_textures.c`, a texture swizzle,
|
||||
which leaves them compressed). A bitmap also drawn another way (a
|
||||
multipurpose map that is also a base map, say) keeps its channels, since
|
||||
the renderer has one order for each texture, and is logged: 3 in
|
||||
`bloodgulch.map`, all multipurpose maps.
|
||||
- **Reads.** The renderer write-protects the memory it has made textures of
|
||||
and learns of changes from the faults writes take; the kernel fails a read
|
||||
into such memory instead. Every read of the map is therefore made into a
|
||||
64 KB staging buffer and copied, as the platform's file layer does.
|
||||
- **Texture memory.** A frame of `Elite_Alpha_Siege.map` draws more than the
|
||||
22 MB of textures the Xbox texture cache holds, and textures that did not
|
||||
fit were drawn as the default one. The desktop builds' texture cache is
|
||||
256 MB, in a 512 MB memory window (`halo_port_capacity.h`), for every map;
|
||||
Android's is the Xbox's.
|
||||
- **Scripts.** A compiled script names each function it calls, and each
|
||||
engine global it uses, by its index in the engine's tables, and Halo PC's
|
||||
tables have entries this build's do not, in among the ones both have: from
|
||||
some point on, an index names another entry here
|
||||
([Evidence](#observed-not-stated-by-the-sources-established-on-the-sample-maps)).
|
||||
`hugeass.map`'s day and night script would call `playback` instead of
|
||||
`switch_bsp`. A compiled script also keeps every name, in its string data,
|
||||
so every call and every engine global is found again by name with the
|
||||
game's own `hs_find_function_by_name` and `hs_find_global_by_name`
|
||||
(`custom_edition_scripts.c`); one this build does not have does nothing
|
||||
and is logged by name (Limits, below). The value types are numbered
|
||||
alike in both builds.
|
||||
- **Multiplayer vehicle placement.** This build places a multiplayer game's
|
||||
vehicles by type: only the first three of the globals' multiplayer
|
||||
vehicles are created, and of those the ones the variant's vehicle set
|
||||
names (`game_engine_remap_vehicle`; the built-in variants name the first).
|
||||
Custom Edition maps are made for retail Halo's rules: a vehicle placement's
|
||||
multiplayer spawn flags name the game types it is placed in by default,
|
||||
and a script may create any vehicle. `hugeass.map` depends on that (above).
|
||||
For a Custom Edition map in slayer, capture the flag, king of the hill or
|
||||
oddball, the native builds place the vehicles whose spawn flags name the
|
||||
game type by default and let any vehicle be created
|
||||
(`custom_edition_objects.c`, called from `object_types_place_all` and
|
||||
`game_engine_remap_vehicle`); a variant without
|
||||
vehicles still has none, and race, which has no spawn flag, keeps this
|
||||
build's rule.
|
||||
- **Multiplayer vehicles.** `game_engine_predict_resources` takes the three
|
||||
multiplayer vehicles Xbox globals always have; a Custom Edition map's
|
||||
globals can list fewer, and oddball stopped on such a map. With fewer than
|
||||
three, the native builds predict none (`game_engine.c`).
|
||||
|
||||
## Checks
|
||||
|
||||
The loader (`cache_file_formats.c`) checks the container: the header, the
|
||||
tag index, every structure BSP, every resource-held tag and its relocated
|
||||
pointers, every bitmap pixel and sound sample range, every model part's
|
||||
geometry in the model data. Then, once the loader and the conversion of
|
||||
bytes have made the tags this build's layout, the tag validator checks
|
||||
every tag as it checks an Xbox map's (`tag_validate_custom_edition_tags`,
|
||||
called by `custom_edition_cache_tags_load`): every block and data within
|
||||
the loaded tags and overlapping no other's, counts cut to the game's
|
||||
capacities, indices, enums and tag references corrected, runtime values
|
||||
reset, then the graph checks (collision BSPs, node trees, scripts' syntax),
|
||||
and a tag name that lies in any tag's block or data is emptied (what the
|
||||
game writes there could take away its end). A map whose pointers cannot be
|
||||
trusted is refused; what can be corrected is, and logged. What differs
|
||||
from an Xbox map:
|
||||
|
||||
- the tag header has no vertex or index buffers, and the tag cache is the
|
||||
Custom Edition one (23 MB);
|
||||
- bitmap pixels and sound samples are in several files: their offsets must
|
||||
lie in the map, the sounds decoded at load, `bitmaps.map` or `sounds.map`;
|
||||
- models are gbxmodels (`mod2`), whose parts keep their geometry in the
|
||||
map's model data and a table of local nodes, which are checked against
|
||||
the model's (`tag_schema_custom_edition_groups`, in `tag_schema_models.c`);
|
||||
the game takes them as models;
|
||||
- a structure BSP's material vertices are uncompressed, and are checked
|
||||
against its uncompressed vertex data.
|
||||
|
||||
Only after the validator has passed the tags are the scripts given this
|
||||
build's function and global indices, the bitmaps checked for the texture
|
||||
cache, and the models and each structure BSP (checked as it loads, as an
|
||||
Xbox map's) given compressed vertices and buffers. The script function
|
||||
allowlist (`hs.c`) applies to Custom Edition maps as to every map.
|
||||
|
||||
`build/linux/map_validate` runs the loader, the conversion of bytes and the
|
||||
validator on maps outside the game, with the resource maps beside each map
|
||||
or in `--maps`; `--fuzz` changes words of a map's file at random.
|
||||
|
||||
## Tested
|
||||
|
||||
### Automated tests
|
||||
|
||||
- `python -m pytest tools/test_cache_file_formats.py` (130 tests; needs
|
||||
clang): synthetic Custom Edition caches and resource maps, caches that
|
||||
need OpenSauce refused and those that only carry its data loaded, every
|
||||
check of the loader and the conversion, and seeded random corruptions,
|
||||
through `port/tools/cache_file_report.c`. With `HALO_CUSTOM_EDITION_MAPS`
|
||||
naming a folder of maps, four more check real maps: against DamnationCE's
|
||||
recorded results (which are of its copies of the stock maps), and that any
|
||||
`.yelo` map among them is either refused or a Custom Edition cache.
|
||||
- `python -m pytest tools/test_bmp_files.py` (41 tests): the map pictures'
|
||||
reader.
|
||||
- `tools/test_linux_port.py`: with `HALO_CUSTOM_EDITION_MAPS` (or the
|
||||
gitignored `assets/custom_edition`), every map is loaded and checked and
|
||||
none refused, and three are fuzzed (100 runs each); the retail Xbox maps
|
||||
still need no correction.
|
||||
|
||||
### Maps
|
||||
|
||||
Two folders were checked with `map_validate`: the 20 stock Custom Edition
|
||||
maps (the halopc-restored r220 copies) and 19 community maps (`area53`,
|
||||
`bigass`, `deltaruins`, `Elite_Alpha_Siege`, `extinction`, `Fission_Point`,
|
||||
`Floodgulch5.1`, `hugeass`, `immure`, `tactics`, `the_bay_of_pigs`,
|
||||
`the_rise_of_asis`, `WW_battlefield` and copies of stock levels). None is
|
||||
refused. The stock maps need one correction each, a character of
|
||||
`loc.map`'s gamespy font 5 pixels narrower than nothing; the community maps
|
||||
some more, their own data's mistakes (an enum past its values, a region
|
||||
index past its block, a particle state of a sequence with no sprites).
|
||||
Fuzzing, 200 runs of each of those 39 maps (7,800 runs): no crash, no hang,
|
||||
and every map let through clean when checked again.
|
||||
|
||||
Run in the game (Linux release build, 40 to 50 seconds each, slayer):
|
||||
`hugeass`, `bigass`, `extinction`, `deltaruins`, `Elite_Alpha_Siege`,
|
||||
`the_rise_of_asis`, `area53`, `tactics`, `Floodgulch5.1`, `immure`,
|
||||
`WW_battlefield`, `the_bay_of_pigs` and `Fission_Point` load, are checked,
|
||||
converted and played to the end of the run without a crash; `hugeass`'s
|
||||
hangar, HUD and first-person weapon were seen drawn.
|
||||
|
||||
Two campaign maps were checked with `map_validate`: CMT's `a30.map` (2006,
|
||||
"Halo"; 13 corrections) and CMT SPV3's backwards-compatible `a50.map` (2012,
|
||||
The Truth and Reconciliation, with OpenSauce's header setting no flags and
|
||||
its two `project_yellow` tags; 43 corrections); `a30` was also run. From the
|
||||
menus (on a virtual display): New Game's CUSTOM SINGLEPLAYER `a30` played as
|
||||
a campaign level at the difficulty chosen; the Map screen's (LAN) listed its
|
||||
difficulties, set up co-op in Server Setup and showed it in the lobby as
|
||||
co-op. With `debug.network_test`, two machines on loopback played
|
||||
`custom_maps\a30` as network co-op and `custom_maps\hugeass` as slayer; a
|
||||
joining machine with a maps folder missing the host's Xbox map was shown the
|
||||
error and left the game. A joining machine without `hugeass` (or without
|
||||
`sounds.map` and `loc.map` too) downloaded them and played (map sharing,
|
||||
`port/linux/NETCODE.md`): in the lobby, into a game in progress, from the
|
||||
host and another player at once with a second machine downloading beside it
|
||||
(on loopback, and through internet play's tunnels with a local broker), each
|
||||
file the same as the host's; with `network.map_download` off, or a host with
|
||||
`network.map_share` off, it was shown the error and left.
|
||||
|
||||
### Not tested
|
||||
|
||||
- **Playing**: nobody played the maps through.
|
||||
- **Android** builds, and was not run.
|
||||
|
||||
## Evidence
|
||||
|
||||
### Sources
|
||||
|
||||
- **OpenSauce** (GPL-3.0, Kornner Studios): the `OpenSauce-master.zip`
|
||||
archive of the upstream repository (SHA-256
|
||||
`f1097c9cf5975a208506c78c3af47d6b893f998a9f47dddf89c9bbcc1f4b7c73`; newest
|
||||
entry dated 2016-01-15; `yelo_version.hpp` names OpenSauce 4.0.0).
|
||||
- **Reclaimer** (GPL-3.0, Gravemind2401): the `Reclaimer-master.zip` archive
|
||||
(SHA-256 `72fd5270abbdf662ff07a54e9cce80a6158e479c51ecfdcd979f7f9fbd6c2d03`;
|
||||
newest entry dated 2026-09-20).
|
||||
- **The Xbox maps of retail build 01.10.12.2276** (`bloodgulch.map`,
|
||||
decompressed): not the 01.01.14.2342 build this repository reconstructs,
|
||||
but their model parts have its 0x68-byte layout and their shader types its
|
||||
numbering, which makes them a check on what the conversion produces.
|
||||
|
||||
No code from OpenSauce or Reclaimer (both GPL-3.0) was copied: they were
|
||||
read as documentation of the file formats, and every layout used was then
|
||||
checked against the sample maps.
|
||||
|
||||
### Documented facts (source, checked against the sample maps)
|
||||
|
||||
| Fact | Source |
|
||||
| --- | --- |
|
||||
| Cache header layout, version 609, `head`/`foot` signatures | OpenSauce `blamlib/Halo1/cache/cache_files_structures.hpp` (`s_cache_header`) |
|
||||
| Tag index (0x28 bytes, instances at 0x28, model data as file offsets) and tag instance (0x20 bytes, resource-map flag at 0x18) | same file (`s_cache_tag_header`, `s_cache_tag_instance`) |
|
||||
| OpenSauce's header at 0x70 begins with the `yelo` signature, where Custom Edition's header has padding, and has its flags (memory upgrades, mod data files, protected, game state upgrades, compression parameters) at 0x76 | OpenSauce `YeloLib/Halo1/cache/cache_files_structures_yelo.hpp` (`s_cache_header_yelo`) |
|
||||
| Tag cache at `0x40440000`, 23 MB; file size limits | OpenSauce `cache_constants.hpp`, `saved_game_constants.hpp` |
|
||||
| Resource map header and entries | OpenSauce `data_file_structures.hpp` |
|
||||
| Groups held by resource maps: bitmaps, sounds, fonts, unicode string lists, HUD message text | OpenSauce `blamlib/Halo1/cache/cache_files.cpp` (`cache_file_data_load`) |
|
||||
| Structure BSP reference (0x20), header (0x18), structure, lightmap and material layouts | OpenSauce `scenario_definitions.hpp`, `structure_bsp_definitions.hpp`; this build's `structure_bsp_definitions.h` agrees |
|
||||
| Bitmap, sequence, sprite, bitmap data layouts; pixels in `bitmaps.map` flag | OpenSauce `bitmaps/bitmap_group.hpp` |
|
||||
| Sound definition, pitch range, permutation layouts; samples-in-`sounds.map` flag | OpenSauce `sound/sound_definitions.hpp` |
|
||||
| Gbxmodel layout: the part (0x84 bytes) is this build's 0x68-byte part followed by a local node count and a 22-entry node table | OpenSauce `models/model_definitions.hpp` (`gbxmodel_geometry_part`) |
|
||||
| Where a part's strip and vertices lie in the model data (triangle count, strip offset, vertex count and offset in the buffer fields; 68-byte vertices) | Reclaimer `Blam/Halo1/GbxmodelTag.cs` (`ReadPCMeshes`) |
|
||||
| Shader types: *transparent chicago extended* inserted at 7, before water, glass, meter and plasma; its two map sets | OpenSauce `shaders/shader_definitions.hpp` |
|
||||
| Script syntax nodes: 19001 in the stock engine | OpenSauce `hs_constants.hpp` |
|
||||
| HUD message text layout | OpenSauce `interface/hud_messaging_definitions.hpp` |
|
||||
| Font (156 bytes) and unicode string list layouts | BlamLib `Blam/Halo1/Tags/Definitions/Misc.cs`, `Resources.cs` |
|
||||
| Bitmap tags in `bitmaps.map` by index, pixels by absolute offset | Reclaimer `Blam/Halo1/CacheFile.cs`, `BitmapTag.cs`, `BitmapsAddressTranslator.cs` |
|
||||
| The header checksum: CRC-32 of the structure BSPs (packed from 0x800), the model data and the tag data, not inverted | OpenSauce `cache_files_yelo.cpp` (`CalculateChecksumFromMemoryMap`), `memory_interface_base.cpp` (`CRC`); reproduces the stored checksum of 23 of the 24 sample caches |
|
||||
|
||||
### Observed (not stated by the sources; established on the sample maps)
|
||||
|
||||
| Fact | Evidence |
|
||||
| --- | --- |
|
||||
| Structure BSPs load at the top of the tag cache (`address + size` = `0x41B40000`) | all 24 caches (those with OpenSauce's memory upgrades at the top of its larger tag cache) |
|
||||
| Bitmaps, fonts, unicode string lists and HUD text held by resource maps: the tag's address field is the entry index, the entry's name is the tag's path, the entry is the whole tag with addresses counting from its start | 9,550 bitmaps, 68 fonts, 2,248 string lists, 23 HUD texts across the sample |
|
||||
| Sounds held by `sounds.map`: the map keeps the 0xA4-byte header, whose pitch range block has a count and no address; the entry named by the tag path holds the header again, then the pitch ranges and permutations, whose addresses count from the first pitch range | 7,397 sounds, 21,870 sample ranges |
|
||||
| The map's copy of a resource-held sound's header has its compression and longest permutation length zero, and its encoding and sample rate zero too; the entry's copy has them as the Xbox has them | in `bloodgulch.map` and `beavercreek_halo3.yelo`, the two copies of all 527 resource-held sounds differ only in those four fields, in pointers, and in the map's own promotion sound reference; for the 315 sounds the Xbox `bloodgulch.map` shares, the entry's sample rate, encoding and the runtime fields after the longest permutation length equal the Xbox's; its compression does except for the 38 that Custom Edition has as Ogg Vorbis, and its longest permutation length for 273 (the others differ by a few milliseconds or more, among them the Ogg Vorbis ones); its pitch ranges' runtime fields all do |
|
||||
| Sound permutations and resource-held bitmaps name tags of another map (the one the resource map was built with) | 632 of 676 bitmaps of `bloodgulch.map`; every resource-held permutation differs from the Xbox's own sound handle |
|
||||
| Model parts: the strip and vertex data are in the model data, never in the part's blocks; the triangle buffer is a precompiled strip and the vertices uncompressed; the part flag 2 is set on exactly the parts that have a node table | all 24 maps (10,934 parts) |
|
||||
| Converting a part's vertices with the game's compressor reproduces the Xbox's | for the 335 parts of the 60 models the Custom Edition and the Xbox `bloodgulch.map` share: identical strips; positions equal to within float rounding; texture coordinates and node weights exactly what the compressor makes of the Custom Edition values (clamped to ±1, as the Xbox also has them: `plant_broadleaf_short` has coordinates up to 3.0 in both); node indices the Custom Edition ones times 3, except that the Xbox writes an unweighted second node as -1 where the compressor writes the node Custom Edition names; normals within 0.002 |
|
||||
| Every node index of a vertex names a node of its part's table (in models whose parts have local nodes) or of its model, every table entry a node of the model, and every vector is within ±1.0001 | all 24 maps |
|
||||
| Structure BSP materials: environment vertices uncompressed (type 0), with lightmap vertices (as many as the environment ones) exactly in lightmaps that have a bitmap, and no compressed vertices | all 24 maps (the lightmap vertex type field is 0 or 2 regardless) |
|
||||
| Custom Edition shader type values are 7 to 11 for `scex`, `swat`, `sgla`, `smet`, `spla`; the Xbox's are 8, 9, 10 for `sgla`, `smet`, `spla` | every shader of the 24 maps, and of the Xbox `bloodgulch.map` |
|
||||
| Chicago shaders with extra layers: none in the stock maps or the Xbox `bloodgulch.map`; 2 in `beavercreek_halo3.yelo`, 2 in `celer_exile_odst_v2.yelo`, 4 in `extinctionrevanepic2.map`, 1 in `fy_killzone.yelo` | every `schi` and `scex` of the sample |
|
||||
| Compressed color plates are left out of caches: size kept, address 0 | every bitmap in `bitmaps.map` |
|
||||
| Font style references in `loc.map` are all `NONE` | all 3 fonts |
|
||||
| Sound compression value 3 is Ogg Vorbis, value 1 is Xbox ADPCM | in `sounds.map`, all 106 value-3 permutations start with `OggS`; all 1,365 value-1 permutations are whole 36-byte blocks |
|
||||
| `bitmaps.map` bitmaps are not swizzled, and cube maps hold each level's six faces together | all 1,467; 38 of 40 cube maps match that order when checked against their next level (one is uniform, one does not match) |
|
||||
| Multipurpose maps: Custom Edition's red, green, blue and alpha hold what the Xbox's alpha, green, red and blue do | the multipurpose maps the Custom Edition and the Xbox `bloodgulch.map` share, decoded and compared channel by channel (the cyborg's, the warthog's, the boulders') |
|
||||
| HUD meters: Custom Edition's alpha holds the Xbox's color (the fill order), and its color the Xbox's alpha (the shape) | `hud_ammo_meters`: Custom Edition's 512×512 A8R8G8B8 averaged down to the Xbox's 256×256 A8Y8 differs from the Xbox's luminance by 6.6 on average in alpha and 23 in color, and from its alpha by 12.3 in color and 23.4 in alpha; `hud_unit_meters` has its sprites rearranged, and shows the same swap when viewed. January's meter shader reads the fill order from color and discards texels without alpha |
|
||||
| HUD elements flagged *use high resolution scale* draw bitmaps twice the Xbox's size; others the same size | every unit and weapon HUD placement of `bloodgulch.map` whose tag the Xbox map also has (the motion sensor's foreground, unflagged, uses a 128×128 bitmap in both) |
|
||||
| Vehicle placements: the byte at 0x58 is the multiplayer team and the word at 0x5A the multiplayer spawn flags, default bits 0 to 3 (slayer, capture the flag, king of the hill, oddball) and allowed bits 8 to 11 | `hugeass.map`'s 78 vehicle placements: the byte is 1 on exactly the blue team's; the word is 0x0303 on warthogs, tachikomas and pelicans, 0x0F0F on ghosts, 0x0404 on 16 unnamed jets, 0x0808 on the night jet and 0 on vehicles its scripts create; OpenSauce leaves these bytes unnamed |
|
||||
| Script function and engine global tables: Halo PC's have entries this build's lacks, so a compiled index names another entry from some point on; value types are numbered alike | the compiled scripts of the sample, each call's function index against the name its first child keeps, and each engine global's index against its name: `timberland.map` 23 calls shifted (`player_effect_start` by 29), `ui.map` 11 (`camera_set` by 1), `hugeass.map` 3 calls and 1 global (`rider_ejection`, 158 against 147), `extinctionrevanepic2.map` 9 calls, and 4 of a function this build lacks; no other stock map has scripts; each call's value type is the type of its function here (1,485 of 1,485 in `hugeass.map`), or one the call site casts to |
|
||||
| Bitmaps the Xbox keeps in monochrome formats and Custom Edition as 32-bit color at the same size keep their channels (A8Y8 as A8R8G8B8 with red the luminance and alpha the alpha) | 24 of the 26 such bitmaps of `bloodgulch.map` decode to exactly the Xbox's values; the other 2 have other content |
|
||||
|
||||
### Assumptions (not verified)
|
||||
|
||||
- **Placement of resource-held tags.** They are placed after the tag data,
|
||||
aligned to 4 bytes, as OpenSauce's unimplemented loader outlines
|
||||
(`s_cache_file_data_load_state`); how Custom Edition itself places them is
|
||||
not known, and nothing found depends on it.
|
||||
- **Which chicago extended maps.** The four-stage maps are kept, as the
|
||||
renderer draws four stages; that Custom Edition's two-stage maps are a
|
||||
fallback for older hardware is an inference (BlamLib's exporter makes the
|
||||
same choice).
|
||||
- **Centroid nodes of local-node parts** are taken to be the model's nodes:
|
||||
they are within the model's node count in every map, and they are only
|
||||
used to sort transparent parts.
|
||||
- **Editing-kit pointers are cleared.** The definition pointers of relocated
|
||||
blocks and data are set to 0: they refer to nothing in the game process.
|
||||
- **Name comparison** is exact (case-sensitive), which matched every sample
|
||||
sound.
|
||||
|
||||
## Limits and remaining work
|
||||
|
||||
- **What the validator corrects is lost.** A community map's data that the
|
||||
validator corrects (an index past its block, an enum past its values) is
|
||||
what the game then runs; Halo PC read past such data unchecked.
|
||||
- **Ogg Vorbis sounds** are decoded when the map loads (stb_vorbis, with
|
||||
added bounds checks: `port/third_party/stb_vorbis`) and encoded again as
|
||||
Xbox ADPCM in memory (`port/linux/game/custom_edition_sounds.c`); one that
|
||||
cannot be decoded is silenced, and still logs when played.
|
||||
- **Models of 44 nodes or more** are drawn a part's nodes at a time, given
|
||||
local nodes when they have none; one whose part's vertices name more
|
||||
nodes than a part holds is refused.
|
||||
- **Linear bitmaps whose rows are not a multiple of 64 bytes**, and
|
||||
textures larger than 4096 pixels a side, are not drawn.
|
||||
- **Halo PC's HUD meters' minimum alpha** (where the Xbox's meters have an
|
||||
overlays block) is dropped, and **its weapon functions "primary firing on"
|
||||
and "secondary firing on"** are the Xbox's primary and secondary firing.
|
||||
- **Button prompts on replaced icon sheets** show what the map's icon bitmap
|
||||
has where the Xbox's buttons are.
|
||||
- **Channel orders are per texture**: multipurpose maps and meters also drawn
|
||||
another way keep Halo PC's channels.
|
||||
- **Scripts that use what this build does not have**: a call of a function
|
||||
this build lacks, or a read of an engine global it lacks, does nothing
|
||||
(a constant of its type's harmless value, logged by name:
|
||||
`custom_edition_scripts.c`); only one that gives a script's index refuses
|
||||
the map. Maps that need OpenSauce's runtime features are refused; a map
|
||||
that only carries its tags (`project_yellow`) runs without them, as on
|
||||
stock Custom Edition.
|
||||
- **Halo PC behaviours** some maps were made around (Chimera's map list,
|
||||
`custom_edition_behaviours.inc`) are followed where this build can, and
|
||||
each is logged.
|
||||
- **The conversions are one-way and in memory**: nothing is written to the
|
||||
map files.
|
||||
|
||||
### How far Custom Edition tags are from the Xbox tags
|
||||
|
||||
`tools/custom_edition_tag_footprints.py` compares the tags a Custom Edition
|
||||
cache and the Xbox cache of the same level both keep (same group, same name),
|
||||
without any tag definitions. A tag's *footprint* is the distance from its
|
||||
address to the next tag's (its structure and the block data after it); its
|
||||
*structure size* is estimated as the distance to the lowest address in the
|
||||
footprint that the footprint points at (its first child block). Equal
|
||||
footprints, level after level, suggest a group's layout is unchanged; they do
|
||||
not prove it.
|
||||
|
||||
The Xbox caches available are the retail ones, build 01.10.12.2276, not the
|
||||
01.01.14.2342 build this repository reconstructs: they stand in for it, and
|
||||
differences between the two Xbox builds are not measured. Run on the 14
|
||||
levels both sets have (13 multiplayer levels and `ui`):
|
||||
|
||||
```
|
||||
python tools/custom_edition_tag_footprints.py --blocks assets/custom_edition "<Xbox 2276>/maps"
|
||||
```
|
||||
|
||||
- **48 groups have the same footprint for every shared tag in every level**:
|
||||
`Soul actv ant! bipd colo cont deca eqip flag fog font foot grhi hmt hud#
|
||||
hudg itmc jpt! lens lifi ligh lsnd mach metr mgs2 mply part pctl phys pphy
|
||||
scen schi senv sgla sky smet snde soso spla ssce str# swat trak udlg unhi
|
||||
vcky vehi wind`. The shader groups among them have the same layout, but
|
||||
not the same type values (above).
|
||||
- **Groups whose footprints differ, but whose structures match**: UI widgets
|
||||
(`DeLa`, 464 of 657 footprints equal, 423 of 423 structures), animations
|
||||
(`antr`, 213/239), collision models (`coll`, 331/345), effects (`effe`,
|
||||
4140/4166), projectiles (`proj`, 197/210), weapon HUDs (`wphi`, 196/222),
|
||||
weapons (`weap`, 39/182, structures 182/182), globals (`matg`, 1/14,
|
||||
structures 14/14) and scenarios (`scnr`, 0/14, structures 13/14), plus, in
|
||||
`ui` only, bitmaps, sounds and string lists. These differ in their block
|
||||
data. The flamethrower's tags account for every `effe`, `proj` and `wphi`
|
||||
difference and all but one `coll` difference; 11 of the 14 weapons (every
|
||||
player weapon and both vehicle guns) differ in every level.
|
||||
- **What differs in those blocks** (`--blocks`: the top-level blocks of each
|
||||
differing tag, found without definitions and compared): almost always
|
||||
the number of elements, or whether a block has any, which is content:
|
||||
weapons 143 count and 26 presence differences, UI widgets 158 and 63,
|
||||
scenarios 36 and 13, projectiles 13, weapon HUDs 78 presence, collision
|
||||
models 26 count. Every weapon difference checked in Blood
|
||||
Gulch lies in a predicted-resources list (8-byte elements, weapon
|
||||
offset `0x4E4`; OpenSauce `weapon_definitions.hpp`), or, for the
|
||||
flamethrower, also in its attachments; the globals differ in their
|
||||
cheat powerups (16 against 14). The rest (flamethrower effects 26,
|
||||
globals 13, animations 39, one collision model, and 3 in `ui`) keep their element counts but
|
||||
span a different amount of data up to the next block, which this method
|
||||
cannot split into element size and nested content: for the globals, the
|
||||
block in question (`player_info`, 0xF4-byte elements without blocks of
|
||||
their own) spans more than its elements, so other data sits in the span.
|
||||
No difference found has to be a layout change, and the two maps run did
|
||||
not show one.
|
||||
- **Groups only Custom Edition has**: `mod2` (models), `scex` (a transparent
|
||||
shader type), `devc` and `tagc`, in all 14 levels; **only the Xbox has**:
|
||||
`mode` (models) and `sotr` (a transparent shader type), besides the groups
|
||||
Custom Edition keeps in resource maps.
|
||||
@@ -1,761 +0,0 @@
|
||||
# The dedicated server: reference
|
||||
|
||||
`halo --server` runs the game as a host with no window, sound or player of
|
||||
its own: other machines join it on the LAN, by its invite link or from the
|
||||
server browser, as they join any host. `port/linux/README.md`, "Dedicated
|
||||
server", says how to run one; this document is the reference for what it
|
||||
takes and answers: the command line, the exit codes, the commands, the
|
||||
HTTP API, the remote console (RCON) over WebSocket, the events, the log and
|
||||
the files. `docs/master_protocol.md` is the master servers' protocol, which
|
||||
the server publishes to and the server browser reads.
|
||||
|
||||
The code is `port/linux/src/server_*.c` (the platform side: the mode, the
|
||||
standard input, the log, the rotation's grammar, the HTTP and WebSocket
|
||||
server, the master servers' publisher) and `port/linux/game/server_*.c`
|
||||
(the game side: the director that plays one game after another, the
|
||||
commands, the gametypes, the status). The Android and web builds have no
|
||||
dedicated server: they compile those files to nothing, but for
|
||||
`server_json.c` (the JSON reader, which the server browser's list of master
|
||||
servers uses in every build) and `server_rotation.c` (the rotation's
|
||||
grammar and the gametype rules), which every build compiles.
|
||||
|
||||
## Panels and fleets
|
||||
|
||||
A game panel (Pterodactyl, PufferPanel, MCSManager: `deploy/`) runs one
|
||||
server and reads its standard output; `deploy/systemd` and `deploy/docker`
|
||||
run servers on one machine. For many servers on many machines, `opence-fleet`
|
||||
([github.com/OpenCommunityEdition/opence-fleet](https://github.com/OpenCommunityEdition/opence-fleet))
|
||||
is one control plane over them all: an agent on each machine runs the
|
||||
servers and drives each through this document's API, as the owner from
|
||||
the machine itself (`server.web_owner_password`, below). What it relies on
|
||||
is named in the status's and the RCON's `capabilities`: `owner_web` (the
|
||||
owner's role over the web, from loopback), `ban_address` (`sv_ban_address`,
|
||||
`POST /api/bans`), `stop` (`sv_stop`, `POST /api/stop`, the `drain` event),
|
||||
`event_addresses` (addresses in the player events) and `identity` (the
|
||||
status's `pid`, `instance`...).
|
||||
|
||||
## Command line
|
||||
|
||||
| Argument | What it does |
|
||||
| --- | --- |
|
||||
| `--server` | Dedicated server mode (as `HALO_SERVER=1` or `server.enabled = true`) |
|
||||
| `--config <path>` | The settings file; default `config.toml` beside the executable. `HALO_CONFIG_FILE`, when it is set, wins over `--config` |
|
||||
| `--version` | Prints `OpenCE build-<n> (network version <v>)` and exits 0 |
|
||||
| `--keygen` | Writes a new publisher key (`server.publisher_key_file`) unless one exists, prints its public key and key id, exits 0; exits 3 when the key cannot be made, read or written |
|
||||
| `--sign <text>` | Prints the publisher key's Ed25519 signature of the text, in hex (an application's proof of key), exits 0; exits 3 without a text or a usable key |
|
||||
| `--probe [<invite>]` | A look at a server, for a list site that shows its state: joins nothing and never starts a server (whatever `--server`, `HALO_SERVER` or `server.enabled` say). It finds the invite's game over its tunnel (without an invite, the LAN's first) and prints it as one line of JSON, the game of the invite's host alone (never another game that answers), and exits 0; when nothing answers in 30 seconds it prints `{"ok":false,"error":"no game answered in 30 seconds"}` and exits 1. Internet play is as set (`network.online`, on by default), which an invite needs |
|
||||
| `--help` | Prints these, exits 0 |
|
||||
|
||||
`--version`, `--help`, `--keygen`, `--sign` and `--probe` write no settings: the
|
||||
settings file is read, never completed or made. `--probe` wins over
|
||||
`--server`, `HALO_SERVER` and `server.enabled`: a probe never writes to
|
||||
`config.toml`.
|
||||
|
||||
A probe's line:
|
||||
|
||||
```json
|
||||
{"ok":true,"name":"OpenCE Server","map":"bloodgulch","gametype":"ctf","players":5,"max_players":16,
|
||||
"teams":true,"in_progress":true,"open":true,"dedicated":true,"network_version":38,"kind":0}
|
||||
```
|
||||
|
||||
`gametype` is the game engine's name (`ctf`, `slayer`, `oddball`, `king`,
|
||||
`race`, or `none`), `kind` the OpenCE gametype's kind the host sends (0 for
|
||||
none), `open` whether it takes players now.
|
||||
|
||||
The release has a `halo-server` script beside `halo`, which runs
|
||||
`halo --server` with its arguments.
|
||||
|
||||
## Exit codes and signals
|
||||
|
||||
| Code | Meaning |
|
||||
| --- | --- |
|
||||
| 0 | Stopped: `quit`, `sv_stop` (now, or at the end of its drain), SIGTERM or SIGINT |
|
||||
| 1 | A fatal error in the game (a halt, a map that failed to load); the last error lines were logged. The process exits within 5 seconds of the error, even when what runs at the exit (a hook, a listing's withdrawal) does not return |
|
||||
| 2 | No usable game data: `maps/ui.map`, or every rotation map, missing or not a cache file; nothing was bound |
|
||||
| 3 | Bad server configuration: no rotation entry that can be played (and `server.rotation_fallback` off), `server.web_port` past 65535, a web port the server may not bind (a port below 1024 without the right to it) or whose `server.web_bind` is an address the machine does not have, or a web password (admin, moderator or viewer) shorter than 8 characters with the web port bound beyond loopback (on loopback, a warning), or the owner's (`server.web_owner_password`) shorter than 8 wherever it is bound; `--keygen` or `--sign` failing. An entry that cannot be played (a bad gametype file among them) is left out with a warning: the server stops only when none is left |
|
||||
| 4 | A port in use: the tunnel's UDP port, or the web port (another program listens on it) |
|
||||
| 5 | Restart asked for (`sv_restart`, now or at the end of its drain, or an update installed: `server.auto_update = "install"` installs a new release once the server has been empty for 10 minutes, on a thread of its own: the server goes on meanwhile, and stops with 5 once it is empty again (a player who joined during the install plays on). An install that fails is tried again at the next check, 6 hours on) |
|
||||
| 128 + n | Stopped by signal n: a second SIGTERM or SIGINT, or the shutdown not done 5 seconds after the first |
|
||||
|
||||
SIGTERM and SIGINT stop the server: a game in progress goes to its
|
||||
postgame, every machine is told, the listings are withdrawn, and it exits 0.
|
||||
SIGHUP reloads the server's settings, the rotation and the gametype files
|
||||
(`sv_reload`). SIGUSR1 prints the status on standard output. SIGPIPE and
|
||||
SIGTTIN are ignored.
|
||||
|
||||
## Standard output
|
||||
|
||||
One line per event, for the operator and the panel:
|
||||
|
||||
```
|
||||
2026-10-19T18:03:11Z INFO server: ready (tunnel 2302/udp, web 127.0.0.1:8080, listing public)
|
||||
2026-10-19T18:03:40Z INFO player: Milenko joined (slot 0, machine 1)
|
||||
2026-10-19T18:04:02Z INFO game: started: CTF on bloodgulch, 2 players
|
||||
```
|
||||
|
||||
The fields are the time (UTC), the level (`INFO`, `WARN`, `ERROR`), the
|
||||
category (`server`, `lobby`, `game`, `player`, `chat`, `moderation`, `net`,
|
||||
`master`, `console`, `health`) and the text. `server: ready` is printed once,
|
||||
when the lobby is open and, for a public server, its listing has been
|
||||
published (or 10 seconds on, as the brokers are other people's): it is the
|
||||
line a panel waits for. With `server.log_format = "json"` each line is an
|
||||
object instead, and the line a panel waits for holds `"msg":"ready (`:
|
||||
|
||||
```json
|
||||
{"time":"2026-10-19T18:03:11Z","level":"info","cat":"server","msg":"ready (tunnel 2302/udp, ...)"}
|
||||
```
|
||||
|
||||
Every line is also kept in the log the web's viewers read (`/api/log`,
|
||||
`sv_log`, the RCON's `log` events), but for these, which go to standard
|
||||
output alone: the web password a first start makes, the invite (a
|
||||
private server's lets anyone in; `/api/status` gives it to admins), and
|
||||
the owner's console, the commands typed on standard input or read from the
|
||||
init file and what they answered (a password's command is shown as `(a
|
||||
password's command)` there too).
|
||||
|
||||
A health line comes once a minute: `health: players=3 frame_ms_max=4.1
|
||||
frame_ms_avg=1.20 cpu=2.1% rss=96MB` (the longest and the mean frame of
|
||||
the last minute, in milliseconds). Standard error keeps the platform
|
||||
layer's `halo-linux:` lines, and `debug.txt` everything, as for a player's
|
||||
game.
|
||||
|
||||
## Commands
|
||||
|
||||
The same commands come from standard input, `server.init_file` (run once at
|
||||
the start, a command a line, `#`, `;` and `//` starting comments), the telnet
|
||||
console (`debug.telnet_console`, loopback), the RCON, `POST /api/command`
|
||||
and the web page. Each runs on the game's thread between frames. Every
|
||||
command has a role; a caller may run it if their role is that one or above:
|
||||
**viewer** < **moderator** < **admin** < **owner** (standard input, the
|
||||
init file and the telnet console are the owner's: whoever holds the
|
||||
process; so is a sign-in to the web or the RCON with
|
||||
`server.web_owner_password` from the machine itself: "Signing in"). When
|
||||
standard input ends and `server.console_exit_on_eof` is on, its last line
|
||||
runs, whether or not a line's end ended it, and then the server stops.
|
||||
|
||||
A `<player>` is a slot number (`sv_players` lists them) or the start of a
|
||||
name; a name that begins more than one player's is refused. A `<duration>`
|
||||
is a number and a unit (`45s`, `30m`, `2h`, `7d`, `1w`), a bare number of
|
||||
minutes, or `forever`; ten years at most. A word in quotes (`"two words"`)
|
||||
is one word.
|
||||
|
||||
A command's text (a notice, a reason, `sv_set`'s value, a name) is kept to
|
||||
printable ASCII: control characters (a line's end, a tab) and other bytes
|
||||
outside it are dropped, as are the quotes around the whole text, and
|
||||
standard input's and the init file's lines are cleaned so before they run.
|
||||
The web is stricter where it takes a value as it is: `PUT /api/settings`
|
||||
refuses a value with a control character (`schema`), and nothing is changed
|
||||
for that setting. A command's reply is sent whole, however many lines.
|
||||
|
||||
Commands that are not the server's (the game's own console commands, the
|
||||
scripts' globals and functions) need the owner role: from the web or the
|
||||
RCON they are refused (`not a command of the server's`) but to the owner's
|
||||
session. The server's
|
||||
commands come first, so `kick` and `ban` are always the server's below, not
|
||||
the game's console commands of those names.
|
||||
|
||||
| Command | Role | What it does |
|
||||
| --- | --- | --- |
|
||||
| `help [command]` | viewer | The commands, or one command's use |
|
||||
| `sv_status [--json]` | viewer | The server's state, map, gametype, players, uptime, games played, network version, listing and next game |
|
||||
| `sv_players [--json]` | viewer | Each player's slot, name, team, score, kills, deaths, assists, ping and machine; with the owner role or `server.log_addresses`, their address and hardware id |
|
||||
| `sv_rotation` (`sv_mapcycle`), `sv_maps`, `sv_gametypes`, `sv_version`, `sv_log [n]` | viewer | Lists: the rotation, the maps there are, the gametypes, the build, the log's last n lines |
|
||||
| `sv_bans` (`sv_banlist`), `sv_settings` | admin | Lists: the bans of `bans.txt`, the settings `sv_set` changes |
|
||||
| `sv_masters`, `sv_publisher` | viewer | The master servers and how each answered; the publisher key's id and public key (never its seed) |
|
||||
| `say <text>` (`sv_say`) | moderator | A notice on every machine's screen |
|
||||
| `tell <player> <text>` | moderator | A notice on one player's machine |
|
||||
| `kick <player>` (`sv_kick`) | moderator | Drops the player's machine; it may join again |
|
||||
| `ban <player> [<duration>] [<reason>]` (`sv_ban`) | moderator (a day at most), admin | Drops the player's machine and bans its address and hardware id, for the duration (else for ever). A moderator must give a duration of a day or less: a ban for ever, or longer, is refused |
|
||||
| `unban <number\|address\|hardware id>` (`sv_unban`) | admin | Takes a ban out of `bans.txt`; the machine may join again at once, by the LAN or the internet |
|
||||
| `sv_ban_address <address\|hardware id> [<duration>] [<reason>]` | admin | Bans an IPv4 address (`a.b.c.d`) or a hardware id (up to 32 hex digits), its machine here or not: its line in `bans.txt` as `ban` writes it (the other part `none`), so that `sv_bans`, `unban` and `GET /api/bans` see it, and a machine present of that address or hardware id is dropped as `ban` drops it (`player_left`'s reason `banned`). Answers `ban <n> added` (`n`: its number in `sv_bans`) |
|
||||
| `mute <player> [<minutes>]`, `unmute <player>` | moderator | The host's mute of a player's chat and voice for everyone |
|
||||
| `sv_map <map> [<gametype>]`, `sv_map <entry>` | moderator | Plays that game (or a rotation entry, `map:gametype+rule=value`; a co-op one too), below |
|
||||
| `sv_map_next` (`sv_next`) | moderator | Ends the game without its scores and plays the rotation's next |
|
||||
| `sv_end_game` | moderator | Ends the game: its scores, then the next |
|
||||
| `sv_rotation_set <entries>`, `sv_rotation_add <entry>`, `sv_rotation_del <n>`, `sv_rotation_begin [<n>]` (`sv_mapcycle_add`, `_del`, `_begin`) | admin | Changes the rotation (written to `server.rotation`, 4096 characters at most) |
|
||||
| `sv_set <setting> <value>` | admin | Changes one of the server's settings, now where it can be, and in `config.toml` (below); a setting its environment variable sets is refused. A value is 256 characters at most |
|
||||
| `sv_name <name>`, `sv_maxplayers <n>`, `sv_password [<password>]`, `sv_public <0\|1>`, `sv_motd <text>` | admin | `sv_set` of `server.name`, `server.max_players`, `server.password`, `server.public`, `server.motd` |
|
||||
| `sv_reload` | admin | Reads `config.toml`'s server settings, the rotation and the gametype files again (as SIGHUP) |
|
||||
| `sv_stop [now\|game\|empty] [<notice>]`, `sv_stop cancel` | owner | Stops the server (exit code 0): `now` (the default) as `quit` does; `game` once the game being played is over, `empty` once nobody plays (a drain, below); `cancel` the drain waiting. The notice is said to every machine first |
|
||||
| `sv_restart [now\|game\|empty] [<notice>]`, `sv_restart cancel` | owner | As `sv_stop`, with exit code 5 (restart me) |
|
||||
| `quit` (`exit`) | owner | Stops the server (exit code 0) |
|
||||
|
||||
`sv_map`'s game is played as soon as it can be, and its answer says when:
|
||||
`next: <entry> (now)` in the lobby before its start was sent (the lobby
|
||||
takes the entry, and the rotation's entry it replaced is played after it),
|
||||
`(now: this game ends)` while a game is played (it ends at once, without
|
||||
its scores), and `(once this game is over)` once the lobby's start was sent
|
||||
or while a map loads (it is the next game). `sv_map` of the game being
|
||||
played plays it again. The rotation goes on after it.
|
||||
|
||||
A drain (`sv_stop` or `sv_restart` with `game` or `empty`, `POST
|
||||
/api/stop`) is a stop that waits: the listings are withdrawn as `sv_public
|
||||
0` withdraws them (a new invite, the masters told), without the setting
|
||||
changing; new machines are refused as while a map loads (the game is not
|
||||
open: the LAN's search shows it closed, a join by the invite is told the
|
||||
game is not open); then the server stops. With `game` it stops once no
|
||||
game is played nor about to be: at once in the lobby with nobody in it, or
|
||||
with no countdown running (fewer players than `server.min_players`);
|
||||
otherwise once the game played (or about to start) is over and its
|
||||
postgame shown. With `empty` it stops once nobody is on the server (at once
|
||||
if nobody is now). `sv_stop cancel` (or `sv_restart cancel`) ends the
|
||||
drain: the server is listed again as `server.public` says and takes new
|
||||
players. A `drain` event says each (`after`: `now`, `game`, `empty` or
|
||||
`cancel`), and the stop that ends a drain has the `shutdown` reason
|
||||
`drained`. `/api/status`'s `drain` is the drain waiting, or `null`.
|
||||
|
||||
A co-op entry (`<level>:coop`) is ended as a game is: by `sv_end_game`,
|
||||
`sv_map_next`, `sv_map`, `server.empty_seconds` and `server.idle_minutes`.
|
||||
It has no scores: the server goes back to the lobby at once (no postgame),
|
||||
and a level won ends it with `game_ended`'s reason `score`.
|
||||
|
||||
`sv_set` (and the settings of the web page, `PUT /api/settings`) changes
|
||||
these settings, which `sv_settings` and `GET /api/settings` list:
|
||||
`server.name`, `server.max_players`, `server.min_players`,
|
||||
`server.password`, `server.public`, `server.rotation_fallback`,
|
||||
`server.lobby_seconds`, `server.postgame_seconds`, `server.empty_seconds`,
|
||||
`server.idle_minutes`, `server.team_start`, `server.motd`,
|
||||
`server.frame_rate`, `server.web_password`,
|
||||
`server.web_moderator_password`, `server.log_format`,
|
||||
`server.log_addresses`, `server.status_file`, `server.auto_update`,
|
||||
`server.coop_difficulty`, `server.region`, `server.master_publish`,
|
||||
`server.chat_filter`, `server.chat_filter_slurs`, `server.chat_filter_swearing`,
|
||||
`server.chat_filter_insults`,
|
||||
`server.master_publish_address`, `server.metrics`, and `network.text_chat`,
|
||||
`network.voice_lobby`, `network.voice_mode`, `network.voice_kbps`,
|
||||
`network.votekick`, `network.votekick_minutes`,
|
||||
`network.votekick_ban_minutes`, `network.map_share`,
|
||||
`network.map_share_upload`, `network.public_address`,
|
||||
`network.coop_friendly_fire`, `network.coop_player_collisions`,
|
||||
`network.coop_ally_friendly_fire` and `network.shield_effects`. Of them,
|
||||
`server.status_file`, `server.auto_update` and `server.log_addresses` need
|
||||
the owner role: from the web's admin, `sv_set` of one of them (`POST
|
||||
/api/command`) answers `403 forbidden`, and `PUT /api/settings` leaves it
|
||||
out, in its `errors` with the code `forbidden` and the message `<setting>
|
||||
needs the owner role (the server's console)`; the owner's session changes
|
||||
them both ways. A web password is empty or
|
||||
8 characters or more. A value outside a setting's choices or range is
|
||||
refused (`400 failed` from `sv_set`, `schema` in `PUT /api/settings`'s
|
||||
`errors`), with `<setting> takes a whole number from <min> to <max>` (or
|
||||
`from <min>`) or `<setting> is one of <a>|<b>|<c>`; a choice may be given
|
||||
in either case, and is kept as the table spells it:
|
||||
|
||||
| Setting | Choices or range |
|
||||
| --- | --- |
|
||||
| `server.max_players` | 2 to 127 |
|
||||
| `server.min_players` | 1 to 16 |
|
||||
| `server.lobby_seconds`, `server.postgame_seconds` | 0 to 300 |
|
||||
| `server.empty_seconds`, `server.idle_minutes` | 0 or more |
|
||||
| `server.frame_rate` | 30 to 120 |
|
||||
| `server.team_start` | `one`, `both`, `skip` |
|
||||
| `server.log_format` | `text`, `json` |
|
||||
| `server.auto_update` | `off`, `check`, `install` |
|
||||
| `server.coop_difficulty` | `easy`, `normal`, `hard`, `impossible` |
|
||||
| `network.text_chat` | `on`, `links`, `off` |
|
||||
| `server.chat_filter` | `off`, `censor`, `block` |
|
||||
| `server.chat_filter_slurs`, `server.chat_filter_swearing`, `server.chat_filter_insults` | `off`, `severe`, `strong`, `mild` |
|
||||
| `network.voice_mode` | `off`, `team_proximity`, `team_enemy_proximity`, `team_global`, `team_global_enemy_proximity` |
|
||||
| `network.voice_kbps` | 8 to 64 |
|
||||
| `network.votekick_minutes` | 0 to 60 |
|
||||
| `network.votekick_ban_minutes` | 1 to 1440 |
|
||||
| `network.map_share_upload` | 16 to 20480 |
|
||||
| `network.coop_friendly_fire` | `off`, `on`, `shields_only`, `explosives_only` |
|
||||
| `network.shield_effects` | `stock`, `glow`, `light_show`, `overshield`, `glow_overshield`, `light_show_overshield`, `players` |
|
||||
|
||||
A dedicated server may also keep words out of its chat and its players'
|
||||
names (`server.chat_filter`, off by default): the words of streamer mode's
|
||||
list, by group, each group from the least severity its setting names
|
||||
(`server.chat_filter_slurs`, `mild` by default: every slur;
|
||||
`server.chat_filter_swearing` and `server.chat_filter_insults`, `off`).
|
||||
`censor` shows a line's words as stars to everyone; `block` refuses the
|
||||
line (its sender is told "Your line was not sent: it has words this server
|
||||
does not allow") and refuses at the door a machine whose player's name has
|
||||
them, which an updated game shows as "The host refused: your player name"
|
||||
(an older one says the game is closed). Each is logged (`chat filter: …`,
|
||||
`refusing a machine … its name has words the server's filter keeps out`).
|
||||
Links are `network.text_chat`'s, refused by default. A list of words is
|
||||
not a moderator: spaced letters and look-alikes get past it.
|
||||
|
||||
A dedicated server's text chat is its `network.text_chat`'s, listed or
|
||||
not: `on` by default (lines with links refused), `links`, or `off`, live
|
||||
(`sv_set network.text_chat off`). A game a player hosts has no text chat
|
||||
while it is listed in the server browser; a dedicated server is the
|
||||
exception, and the players who join it from the browser's dedicated servers
|
||||
have the chat as it says, as long as a master server lists it (the
|
||||
masters' word that it is an approved operator's; a listing's own flag is
|
||||
not enough, so a dedicated server listed by the brokers alone, before its
|
||||
operator is approved, has none for them).
|
||||
|
||||
The settings `sv_set` does not change (`server.web_viewer_password`,
|
||||
`server.web_owner_password`, `server.web_port`, `server.web_bind`, `server.web_trusted_proxy`, the
|
||||
paths, the master servers' files...) are changed in `config.toml` or their
|
||||
environment variables: `sv_reload` reads the file's `server.*` settings
|
||||
again, and the web port and its address are bound once, at the start. The
|
||||
rotation is changed by the `sv_rotation_*` commands.
|
||||
|
||||
## HTTP
|
||||
|
||||
The server listens on `server.web_port` (8080; 0 for none) at
|
||||
`server.web_bind` (`127.0.0.1`, an IPv4 address). Bound beyond loopback,
|
||||
every web password that is set (admin, moderator, viewer) must have 8
|
||||
characters or more, else the server exits with code 3; the owner's
|
||||
(`server.web_owner_password`) must have 8 or more wherever the port is
|
||||
bound. The page (`/`), the API
|
||||
(`/api/...`), the RCON (`/ws`), `/healthz` and `/metrics` share the port.
|
||||
|
||||
Requests are HTTP/1.1 (or 1.0), `GET`, `HEAD`, `POST`, `PUT` or `DELETE`
|
||||
(`HEAD` is answered as `GET` is, without the body, and counts as a read,
|
||||
as a `GET`; `/api/login` takes `POST` alone), a head of 8 KB at most whose
|
||||
lines end with CRLF (a bare LF, a CR inside a line, or more after the empty
|
||||
line that ends it: `400 bad_request`) and a body of 64 KB at most, sent within 10 seconds of the
|
||||
connection's opening or of its last answer (a connection that sends
|
||||
nothing is closed then too). `Transfer-Encoding` and `Expect` are refused.
|
||||
24 connections are taken at once; when they are all taken, the oldest that
|
||||
waits for a request (no RCON, no request being answered) is closed for a
|
||||
new one. A client that does not read its answers is read no further once
|
||||
256 KB of them wait, and is closed past 2 MB.
|
||||
|
||||
Every request but `/healthz` counts against its address's allowance, the
|
||||
page's files, `/metrics`, a sign-in and the RCON's upgrades (`/ws`) too: 60
|
||||
a minute, or 600 with a session (429 `rate_limited` past it, with
|
||||
`Retry-After: 60`). Behind `server.web_trusted_proxy`, a request's address
|
||||
is the last entry of its `X-Forwarded-For` (the one the proxy appended: an
|
||||
IPv4 address, `a.b.c.d` or `a.b.c.d:port`, or an IPv6 one, `v6`, `[v6]` or
|
||||
`[v6]:port`), and its `X-Forwarded-Host` and `X-Forwarded-Proto` are
|
||||
believed, whether or not it sends `X-Forwarded-For`; from any other
|
||||
address they are ignored. IPv6 clients are counted by their /64: one
|
||||
host's addresses share its allowance and its lockouts. Every answer is JSON
|
||||
(`Content-Type: application/json`) unless said, with
|
||||
`Cache-Control: no-store`, `X-Content-Type-Options: nosniff`,
|
||||
`Referrer-Policy: same-origin` (under `no-referrer` a browser would send
|
||||
the page's own changes with `Origin: null`) and
|
||||
`Content-Security-Policy: default-src 'self'; frame-ancestors 'none'`.
|
||||
|
||||
### Signing in
|
||||
|
||||
`POST /api/login` with `{"password":"…"}` answers
|
||||
`{"ok":true,"token":"<64 hex>","role":"admin","csrf":"<32 hex>","expires":<unix seconds>}`
|
||||
and sets the cookie `opence_session=<token>; HttpOnly; SameSite=Strict;
|
||||
Path=/`, with `Secure` when the request came through
|
||||
`server.web_trusted_proxy` with `X-Forwarded-Proto: https` (never from
|
||||
another address, whatever it says). The admin password
|
||||
(`server.web_password`) gives the admin role, the moderator password
|
||||
(`server.web_moderator_password`) the moderator role, the viewer password
|
||||
(`server.web_viewer_password`) the viewer role; `{"by":"…"}` beside the
|
||||
password names who signed in, in the log. A session lasts 12 hours, or 30
|
||||
minutes without a request (the RCON's messages do not count: a page left
|
||||
open asks `GET /api/session` now and then); 16 are kept at most, of every
|
||||
role.
|
||||
|
||||
The owner's password (`server.web_owner_password`, empty by default: none)
|
||||
gives the owner role, for a supervisor on the server's own machine (a
|
||||
fleet's agent, a panel's daemon): what standard input may do, over the
|
||||
API and the RCON (`quit`, `sv_stop`, `sv_restart`, `POST /api/stop`, the
|
||||
owner's settings by `sv_set` and `PUT /api/settings`, the game's own
|
||||
console commands by `POST /api/command`, the players' addresses and
|
||||
hardware ids in `/api/players` and the events). It signs in only when the
|
||||
connection's own peer address is in `127.0.0.0/8` and is not the trusted
|
||||
proxy's: never by `X-Forwarded-For`, and never through
|
||||
`server.web_trusted_proxy`, even one on the machine itself. From any other
|
||||
address the right owner's password is refused with `403 forbidden` (the
|
||||
RCON's `auth`: `{"code":"forbidden"}`, and the connection closes 1008),
|
||||
and counts toward the address's lockout as a wrong password does. An
|
||||
owner's session is used from the machine itself alone, as it was begun
|
||||
(from elsewhere its token is no session: `401`, the RCON's `auth` with it
|
||||
`denied`). A password that is also another role's gives the owner role
|
||||
from the machine itself and the other role from elsewhere: give the owner
|
||||
a password of its own.
|
||||
|
||||
A script passes `Authorization: Bearer <token>`. The page passes the
|
||||
cookie, and on every request that changes something the header
|
||||
`X-CSRF-Token: <csrf>`; the `Origin` of such a request (and of the
|
||||
WebSocket's) must be the server's own. An `Origin: null` is taken only
|
||||
when the browser's `Sec-Fetch-Site` says `same-origin`.
|
||||
|
||||
`POST /api/logout` ends the session (with the `X-CSRF-Token` by the
|
||||
cookie; `GET` answers 405). `GET /api/session` answers
|
||||
`{"ok":true,"role":…,"csrf":…,"expires":…}`, or 401.
|
||||
|
||||
When `server.web_password`, `server.web_moderator_password`,
|
||||
`server.web_viewer_password` or `server.web_owner_password` changes
|
||||
(`sv_set` and the settings change the first two; `sv_reload` reads any of
|
||||
them from `config.toml`), the sessions of its role end and that role's RCON
|
||||
connections close (1008, `the password changed`).
|
||||
|
||||
Five wrong passwords from an address (an IPv6 one's /64) in 10 minutes
|
||||
lock it out for 10 minutes (429), and no more than 30 passwords a minute
|
||||
are checked in all. `/api/login` takes `POST` alone (any other method:
|
||||
405).
|
||||
|
||||
### Errors
|
||||
|
||||
```json
|
||||
{"ok":false,"error":{"code":"forbidden","message":"needs the admin role"}}
|
||||
```
|
||||
|
||||
| Status | Codes |
|
||||
| --- | --- |
|
||||
| 400 | `bad_request`, `schema` (a field missing or out of range), `failed` (the command ran and failed: its lines in `lines`), `rejected` (rotation entries: `rejected[]`), `invalid` (a gametype file: `line`) |
|
||||
| 401 | `denied` (no session, or a wrong password) |
|
||||
| 403 | `forbidden` (the role; the owner's password from beyond the machine), `csrf`, `origin` |
|
||||
| 404 | `not_found` (also a command that is not one, a player or a ban that is not there) |
|
||||
| 405 | `method` |
|
||||
| 409 | `pinned` (a setting its environment variable sets), `changed` (a player's action whose slot holds another player now: the current name in `name`, nothing done) |
|
||||
| 413 | `too_large` |
|
||||
| 426 | `bad_request` (the WebSocket's version is not 13) |
|
||||
| 429 | `rate_limited`, `locked` (with `Retry-After`) |
|
||||
| 500 | `internal` (out of memory, a file that cannot be written) |
|
||||
| 503 | `loading` (the game did not answer in 20 seconds, as while a map loads; with `Retry-After: 5`), `starting`, `busy` (8 RCON connections already; with `Retry-After: 5`) |
|
||||
|
||||
### Endpoints
|
||||
|
||||
| Method, path | Role | Body → answer |
|
||||
| --- | --- | --- |
|
||||
| `GET /healthz` | none | `200 {"state":"lobby"}` (or `loading`, `playing`, `postgame`) while the server hosts and its frames run; `503` with `{"state":"starting"}`, `{"state":"stalled"}` (no frame for a minute) or the other state otherwise |
|
||||
| `GET /metrics` | none (`server.metrics`) | Prometheus text |
|
||||
| `GET /api/status` | viewer | The status (below) |
|
||||
| `GET /api/players` | viewer | `{"ok":true,"players":[<player>…]}` (with `address` and `hwid` for the owner, or every role with `server.log_addresses`) |
|
||||
| `POST /api/players/{slot}/kick` | moderator | `{"name":"<the player's name, checked>"}` → `{"ok":true,"lines":[…]}`, or `409 changed` when the slot holds another player |
|
||||
| `POST /api/players/{slot}/ban` | moderator | `{"name":…,"duration":"1d","reason":"…"}` (no duration: for ever, which a moderator's ban cannot be: `400 failed`) |
|
||||
| `POST /api/players/{slot}/mute` | moderator | `{"name":…,"minutes":10}` |
|
||||
| `POST /api/players/{slot}/unmute` | moderator | `{"name":…}` |
|
||||
| `POST /api/players/{slot}/tell` | moderator | `{"name":…,"text":"…"}` |
|
||||
| `POST /api/say` | moderator | `{"text":"…"}` |
|
||||
| `GET /api/rotation` | viewer | `{"ok":true,"index":0,"entries":[<entry>…],"next":<entry>}` |
|
||||
| `PUT /api/rotation` | admin | `{"entries":["bloodgulch:ctf",…]}` → the rotation, or `400 rejected` with `"error":{…,"rejected":[{"index":1,"entry":"…","reason":"…"}]}` and nothing changed |
|
||||
| `POST /api/rotation/next` | moderator | `{}`: `sv_map_next` |
|
||||
| `POST /api/rotation/play` | moderator | `{"map":"…","gametype":"…"}`: `sv_map` (a map or gametype that cannot be played: `400 failed`) |
|
||||
| `GET /api/gametypes` | viewer | `{"ok":true,"builtin":["slayer",…],"schema":{"fields":[<field>…]},"files":[{"name":…,"base":…,"description":…,"error":null}]}` (`builtin`: the Xbox's gametypes, then OpenCE's; a file that cannot be read has `base` and `description` empty and `error` saying why) |
|
||||
| `GET /api/gametypes/{name}` | viewer | `{"ok":true,"name":…,"text":"<the TOML>"}` |
|
||||
| `PUT /api/gametypes/{name}` | admin | `{"text":"<TOML>"}` → `{"ok":true}`, or `400 invalid` with `line` and `message` (a name is `a`–`z`, `0`–`9`, `_` and `-`, 32 at most) |
|
||||
| `DELETE /api/gametypes/{name}` | admin | `{"ok":true}` |
|
||||
| `GET /api/maps` | viewer | `{"ok":true,"maps":[{"name":"bloodgulch","level":"levels\\test\\bloodgulch\\bloodgulch","kind":"xbox","title":"Blood Gulch"}…]}` (`kind`: `xbox` or `custom`; `title` is the map's display name, else its `name`) |
|
||||
| `GET /api/bans` | admin | `{"ok":true,"bans":[{"n":0,"when":"2026-10-19 18:00:00","ip":"…","hwid":"…","players":"…","reason":"…","until":<unix>\|null}…]}` |
|
||||
| `POST /api/bans` | admin | `{"ip":"203.0.113.5","hwid":"…","names":"…","duration":"1d","reason":"…"}` (`ip` or `hwid`, or both; the rest may be left out: no duration is for ever) → `{"ok":true,"n":<the new ban's number in GET /api/bans>}`: `sv_ban_address`, a machine present of the address or the hardware id dropped; `400 schema` for an address that is not IPv4, a hardware id that is not hex, a duration that is not one |
|
||||
| `DELETE /api/bans/{n}` | admin | `{"ok":true}` |
|
||||
| `GET /api/settings` | admin | `{"ok":true,"settings":[<setting>…]}` |
|
||||
| `PUT /api/settings` | admin | `{"server.name":"…","server.max_players":16,"server.public":true,…}` (a value as JSON, a boolean, a number or a string, or its text: `"true"`, `"16"`; `null` empties it) → `{"ok":true,"applied":["server.name"],"errors":[{"name":…,"code":…,"message":…}]}`; each setting is changed or refused on its own |
|
||||
| `POST /api/command` | the command's | `{"line":"sv_status"}` (511 characters at most) → `{"ok":true,"lines":["…"]}`, or a refusal (`failed`, `forbidden`, `not_found`, `pinned`) with the command's `lines` |
|
||||
| `POST /api/stop` | owner | `{"after":"now\|game\|empty","notice":"…","restart":false}` (`notice` and `restart` may be left out) or `{"cancel":true}` → `{"ok":true,"lines":["…"]}`: `sv_stop` (`sv_restart` with `restart`) `after notice`, or `sv_stop cancel` (`400 failed` with no drain waiting); `400 schema` for another `after` |
|
||||
| `GET /api/log?after=<n>&limit=<m>` | viewer | `{"ok":true,"lines":[{"n":12,"time":<ms>,"level":"info","cat":"game","text":"…"}…],"next":12,"missed":0}` (`limit` 1 to 1024, 256 by default; the chat's lines for admins only) |
|
||||
| `GET /api/events?after=<seq>` | viewer | `{"ok":true,"events":[<event>…],"next":<seq>,"missed":0}` (`player_joined` and `player_left` with `address` and `hwid` for the owner, or every role with `server.log_addresses`) |
|
||||
| `GET /ws` | | The RCON (below) |
|
||||
| `GET /`, `/app.js`, `/app.css`, `/icon.svg` | none | The page (`server.web_ui`) |
|
||||
|
||||
`next` is the `after` of the next request: the last line's `n` (or event's
|
||||
`seq`) read. An `after` past the latest (as after a restart) reads from the
|
||||
start. `missed` counts lines or events that left the ring (2048 lines, 512
|
||||
events) before they were asked for.
|
||||
|
||||
### The status
|
||||
|
||||
```json
|
||||
{"ok":true,"time":1760900000123,"name":"OpenCE Server","state":"playing",
|
||||
"build":"build-206","network_version":38,"uptime":3600,"games_hosted":4,
|
||||
"map":"bloodgulch","level":"levels\\test\\bloodgulch\\bloodgulch","gametype":"ctf","variant":"CTF","teams":true,
|
||||
"players":5,"max_players":16,"machines":5,"countdown":-1,"game_seconds":312,"team_scores":[2,1],
|
||||
"listing":{"online":true,"public":true,"password":false,"invite":"halo://join/…"},
|
||||
"rotation":{"index":0,"count":3,"next":{"text":"sidewinder:team_slayer","map":"sidewinder","gametype":"team_slayer"}},
|
||||
"frame_ms_max":4.1,"frame_ms_avg":1.2,"tick_ms_avg":1.2,
|
||||
"masters":[{"url":"https://master1.example.org","listed":true,"probe":"ok","code":"","message":"","updated":1760899990}],
|
||||
"update":{"available":false,"build":""},
|
||||
"drain":null,
|
||||
"pid":4021,"started":1760896400,"instance":"eu-1","region":"eu","tunnel_port":2302,
|
||||
"publisher_key_id":"3f9a2c7d1e5b8a04","web_port":8080,
|
||||
"capabilities":["events","status","rotation","settings","bans","owner_web","ban_address","stop","event_addresses","identity"]}
|
||||
```
|
||||
|
||||
`state` is `waiting` (the menus settling), `hosting` (making the game),
|
||||
`lobby`, `loading`, `playing`, `postgame` or `stopping`. `countdown` is the
|
||||
lobby's seconds left, `-1` when it is not counting. `team_scores` is `null`
|
||||
in a game without teams. `frame_ms_max` and `frame_ms_avg` are the longest
|
||||
and the mean frame of the last minute (`tick_ms_avg` is the mean again, for
|
||||
older readers). `invite` is given to admins only (empty for others). An entry of the rotation is
|
||||
`{"text":"sidewinder:team_slayer+score=50","map":"sidewinder","gametype":"team_slayer","rules":{"score":50},"rejected":null}`
|
||||
(`rejected` is why it cannot be played, else `null`). `drain` is the
|
||||
drain waiting (`sv_stop game`...), `{"after":"game","restart":false,"since":<unix
|
||||
seconds>}`, else `null`. `pid` is the server's process, `started` when it
|
||||
started (seconds since 1970), `instance` the name the master servers know
|
||||
it by (`server.instance`, else the slug of `server.name` they are given),
|
||||
`region` `server.region`, `tunnel_port` the tunnel's UDP port
|
||||
(`network.tunnel_port`; 0 when `network.online` is off), `publisher_key_id`
|
||||
the publisher key's id (16 hex digits; empty without a key: `sv_publisher`)
|
||||
and `web_port` `server.web_port`. `capabilities` is the RCON's hello's. The rotation's
|
||||
`index` (in the status and `GET /api/rotation`) is the entry being played,
|
||||
`-1` while an `sv_map` game is played or before the first lobby; `next` is
|
||||
the entry after the one played last (the first while none has been).
|
||||
|
||||
A player is
|
||||
`{"slot":0,"name":"Milenko","team":0,"score":3,"kills":3,"deaths":1,"assists":0,"ping":42,"machine":1,"joined":1760899000,"muted":false}`;
|
||||
with the owner role, or `server.log_addresses`, also
|
||||
`"address":"203.0.113.5","hwid":"…"`. `team` is 0 (red), 1 (blue) or -1
|
||||
(no teams); `ping` is in milliseconds, `null` when it is not known yet.
|
||||
`client` is the player's machine's build as its game tells it (shortly
|
||||
after it joins), for every role:
|
||||
`{"build":282,"flavor":"release","version":"OpenCE Linux | build 282 (release)","repository":"OpenCommunityEdition/OpenCE","mods":["trollface 1.0"]}`
|
||||
(`build` 0 for a build CI did not number, `repository` empty when the build
|
||||
does not know it, `mods` the mods it plays in their load order, each its
|
||||
folder and its version), or `null` from a game that does not tell it. It is
|
||||
what the player's game says, which a changed build can make anything.
|
||||
|
||||
A setting is
|
||||
`{"name":"server.name","type":"string","value":"OpenCE Server","default":"OpenCE Server","comment":"…","env":"HALO_SERVER_NAME","pinned":false,"secret":false,"choices":null,"min":null,"max":null}`;
|
||||
`type` is `boolean`, `integer`, `real` or `string`, and `value` and
|
||||
`default` are of that type in JSON (`true`, `16`, `"OpenCE Server"`); a
|
||||
reader should also take their text (`"true"`, `"16"`), which older servers
|
||||
sent. `choices` lists a word setting's words, `min` and `max` bound a
|
||||
number's, each `null` where there is none (the table above). `env` is
|
||||
`null` for a setting no environment variable sets. A secret one (the
|
||||
passwords) has `value` and `default` empty and `"set":true` when it is
|
||||
set. `pinned` is a setting
|
||||
its environment variable (`env`) sets: it cannot be changed.
|
||||
|
||||
A gametype schema field is
|
||||
`{"key":"score_to_win","alias":"score","table":"universal","engine":"all","type":"integer","min":0,"max":999,"choices":null,"default":null,"description":"…"}`
|
||||
(`table`: the gametype file's table it goes in, `universal`, `options`,
|
||||
`ctf`, `slayer`, `oddball`, `king` or `race`; `engine`: `all`, or the game
|
||||
engine whose table it is; `type`: `integer`, `boolean` or `choice`).
|
||||
|
||||
## The RCON
|
||||
|
||||
`GET /ws` with `Upgrade: websocket` and the subprotocol `opence-rcon-1`.
|
||||
Every frame is text holding one JSON object. The server speaks first:
|
||||
|
||||
```
|
||||
→ {"type":"hello","protocol":1,"server":"OpenCE Server","build":"build-206","network_version":38,
|
||||
"capabilities":["events","status","rotation","settings","bans","owner_web","ban_address","stop","event_addresses","identity"]}
|
||||
← {"type":"auth","password":"…","by":"paul"} or {"type":"auth","token":"<session token>"}
|
||||
→ {"type":"auth","ok":true,"role":"admin"}
|
||||
→ {"type":"auth","ok":false,"error":{"code":"denied"}} and the connection closes (1008)
|
||||
← {"type":"command","id":1,"line":"kick Milenko"} or {"type":"command","id":1,"command":"say","args":["two words"]}
|
||||
→ {"type":"reply","id":1,"ok":true,"lines":["Milenko kicked by the host"]}
|
||||
→ {"type":"reply","id":2,"ok":false,"lines":["…why…"]} (the command ran and failed)
|
||||
→ {"type":"reply","id":3,"ok":false,"lines":[],"error":{"code":"busy","message":"…"}} (not run)
|
||||
← {"type":"subscribe","events":["player","chat","game","moderation","status","log","master"],"after":1830}
|
||||
→ {"type":"event","seq":1831,"time":1760900000123,"event":"player_joined","slot":3,"name":"Milenko",…,"replay":true}
|
||||
→ {"type":"event","seq":1831,"time":…,"event":"status","status":{…the status…}} (at the subscribe, then every 2 s)
|
||||
→ {"type":"event","time":…,"event":"log","n":5120,"level":"info","cat":"game","text":"…"} (no seq: n is its sequence)
|
||||
← {"type":"ping"}
|
||||
→ {"type":"pong"}
|
||||
→ {"type":"overflow"} and the connection closes (1013): the client read too slowly
|
||||
→ {"type":"error","id":…,"error":{"code":"…","message":"…"}} (an unknown type, a malformed message)
|
||||
```
|
||||
|
||||
A connection signed in with the page's cookie (on the same origin) needs no
|
||||
`auth` message: its `hello` is followed by `{"type":"auth","ok":true,…}`.
|
||||
The `capabilities` say what the server has beyond the first release's
|
||||
(`events`, `status`, `rotation`, `settings`, `bans`): `owner_web`,
|
||||
`ban_address`, `stop`, `event_addresses` and `identity` ("Panels and
|
||||
fleets"); a client checks for one before it uses it. The owner's password
|
||||
signs in from the server's own machine alone ("Signing in").
|
||||
A command is a `line`, or a `command` and its `args`, which the server
|
||||
joins with spaces, quoting an argument that holds a space or is empty (511
|
||||
characters in all at most). Ids are the client's (a number or a string),
|
||||
echoed in the reply; each command gets exactly one reply. A connection
|
||||
runs one command at a time: a command sent before the last one's reply is
|
||||
not run. A reply whose command ran has `ok` and the command's `lines`, and
|
||||
no `error`, whether it succeeded or failed; one that was not run has `ok`
|
||||
false, no lines and an `error`: `denied` (not signed in), `rate_limited`
|
||||
(32 commands a second, in bursts of 64), `bad_request` (no command, or too
|
||||
long), `busy` (another command's reply is awaited) or `loading` (the game
|
||||
did not answer in 20 seconds; the command may still have run, and is never
|
||||
sent again by the server). `after` replays the events still in the ring
|
||||
since that sequence number, marked `"replay":true`. A connection holds 1024
|
||||
messages for the client at most; 8 connections are taken at once (a ninth
|
||||
upgrade answers `503 busy`), and each upgrade counts against its address's
|
||||
allowance (above). The
|
||||
event groups are `player` (`player_joined`, `player_left`, `map_share`), `chat`
|
||||
(`chat`), `game` (`lobby_opened`, `countdown`, `game_started`,
|
||||
`game_ended`, `postgame`, `score`, `kill`), `moderation` (`kick`, `ban`,
|
||||
`unban`, `mute`, `unmute`, `speed_hack`), `status` (`status`), `log`
|
||||
(`log`, each log line as `{"n","level","cat","text"}`), `master`
|
||||
(`master`), and `server` (`server_started`, `reloaded`, `warning`,
|
||||
`drain`, `shutdown`), which every subscriber gets.
|
||||
The log's lines of the `chat` category go to the `chat` group, the others
|
||||
to `log`.
|
||||
`status` and `log` events go to their subscribers as they come and are
|
||||
not kept in the ring: `after` does not replay them (`/api/log` reads the
|
||||
log's own ring). A `status` event's `seq` is the latest event's (no new
|
||||
number: the same one comes again until another event), and a `log` event
|
||||
has no `seq`: its `n`, the log line's number and `/api/log`'s cursor, is
|
||||
its sequence. A client keeps one cursor for the events (`seq`, of the
|
||||
events of the ring) and another for the log's lines (`n`); a client that
|
||||
reconnects with `after` may get events it had, and drops those whose `seq`
|
||||
it has seen (a `status` event is never dropped so).
|
||||
|
||||
## Events
|
||||
|
||||
Every event has `seq` (rising, never reused while the server runs; a
|
||||
`status` event has the latest one's, a `log` event none: above), `time`
|
||||
(milliseconds since the epoch) and `event`:
|
||||
|
||||
| Event | Fields |
|
||||
| --- | --- |
|
||||
| `server_started` | `name, build, network_version, pid, started, instance, region, tunnel_port, publisher_key_id, web_port` (as the status's), `rotation[]` (the entries' texts) |
|
||||
| `lobby_opened` | `map, gametype, variant` (the gametype's name as the game shows it), `teams, index` (the rotation's entry) |
|
||||
| `countdown` | `seconds` (-1: paused) |
|
||||
| `game_started` | `map, gametype, variant, teams, team_scores[]` (team games), `players[]` |
|
||||
| `game_ended` | `map, gametype, variant, teams, reason` (`score`, `time`, `idle`, `empty`, `command`, `next`), `duration` (seconds), `team_scores[]` (team games), `players[]` |
|
||||
| `postgame` | `seconds` |
|
||||
| `player_joined` | `slot, name, team, machine`; `address, hwid` for the owner, or every role with `server.log_addresses` |
|
||||
| `player_left` | `slot, name, reason` (`left`; `kicked` and `banned` when the server's `kick`, `ban` or `sv_ban_address` dropped the machine, `banned` for a speed hack's drop too); `address, hwid` (as it joined) as `player_joined`'s |
|
||||
| `chat` | `channel` (`everyone`, `team`, `vehicle`), `slot, name, text` (admins only; the lines the host sends on) |
|
||||
| `kill` | `killer, victim` (slots; -1 for none), `weapon` (the killer's weapon's or the killing object's tag name, or null), `friendly_fire` |
|
||||
| `score` | `map, gametype, variant, teams, team_scores[]` (team games), `players[]` (once a second at most, on a change) |
|
||||
| `kick`, `ban`, `unban`, `mute`, `unmute` | `name, by, reason?, until?` |
|
||||
| `speed_hack` | `machine, names, rate, ahead_ticks, action` (`kicked`, or `unverified`: its datagrams alone said so, and it stays) |
|
||||
| `map_share` | `machine, map, state` (`asked`, `downloading` at each tenth, `downloaded` or `failed` once for each request), `progress` (0 to 100: a percentage already) |
|
||||
| `warning` | `text` (a newer release, with `server.auto_update`) |
|
||||
| `reloaded` | `rotation_changed, rejected[]` (`{"entry","reason"}` of each entry left out) |
|
||||
| `master` | `url, listed, probe, code, message` |
|
||||
| `drain` | `after` (`now`, `game`, `empty`, `cancel`), `restart` (exit code 5), `notice` (empty for none) |
|
||||
| `shutdown` | `reason` (`quit`, `sv_stop`, `sv_restart`, `drained`: a drain's end, `signal <n>`, `update installed`, `nothing to play`, `debug.exit_after`), `code` (the exit code) |
|
||||
|
||||
Players in events are as in `/api/players` for the viewer role (no
|
||||
addresses), but for `player_joined` and `player_left`, which carry the
|
||||
player's address and hardware id (`""` when not known) to the owner, and to
|
||||
every role when `server.log_addresses` is on (`/api/players`' rule), in the
|
||||
RCON's events, their replay and `GET /api/events` alike. `variant` is the gametype's name as the game shows it (`Co-op`
|
||||
in a co-op entry).
|
||||
|
||||
## Bans
|
||||
|
||||
A ban is a line of `bans.txt` (in `paths.logs`, else the data root). A
|
||||
timed ban is kept out by its line's `until=` alone, and ends then. A ban
|
||||
for ever, and a machine dropped for cheating, also keep the machine out
|
||||
for the rest of the run by its address, its real address or its hardware
|
||||
id. `sv_ban_address` and `POST /api/bans` write such a line for an address
|
||||
or a hardware id with no player of it needed (the part not given is
|
||||
`none`). `unban` takes the line out and readmits the machine by
|
||||
the line's address or hardware id, whether it joins on the LAN or by
|
||||
internet play.
|
||||
|
||||
## The rotation
|
||||
|
||||
`server.rotation` (and `sv_rotation_set`, `PUT /api/rotation`) is a list of
|
||||
entries, `map[:gametype[+rule=value...]]`, separated by commas, semicolons
|
||||
or new lines; a line that begins with `#` is a comment (to its line's end,
|
||||
commas and all). The text is 4096 characters at most (the entries past it
|
||||
are left out, with a warning), an entry 255 characters and the list 64
|
||||
entries. `config.toml` keeps a string setting of up to 4096 characters, so
|
||||
a rotation that long is saved whole and read back after a restart.
|
||||
|
||||
- The map is a multiplayer map's name (`bloodgulch`: the Xbox's
|
||||
`maps/<name>.map`, else a Custom Edition map of `custom_maps`),
|
||||
`custom_maps\<name>` (a Custom Edition map; `/` is taken for `\`), or a
|
||||
level's path (`levels\test\bloodgulch\bloodgulch`). A campaign level is
|
||||
played as co-op only: `<level>:coop`, at `server.coop_difficulty`.
|
||||
- The gametype (`slayer` when there is none) is a built-in's name
|
||||
(`slayer`, `team_slayer`, `slayer_pro`, `elimination`, `phantoms`,
|
||||
`endurance`, `rockets`, `snipers`, `stalker`, `ctf`, `ironctf`,
|
||||
`ctf_pro`, `invasion`, `oddball`, `team_oddball`, `reverse_tag`,
|
||||
`accumulation`, `juggernaut`, `king`, `team_king`, `king_pro`,
|
||||
`crazy_king`, `race`, `team_race`, `rally`, `team_rally`, and Halo PC's
|
||||
names `ffa`, `ffa_slayer`, `teamslayer`, `tslayer`, `koth`, `team_koth`,
|
||||
`iron_ctf`, `teamrace`, `teamoddball`), an OpenCE gametype's (`swat`,
|
||||
`infection`, `gun_game`, `hardcore`, `hardcore_ctf`, `hardcore_oddball`,
|
||||
`hardcore_king`), a gametype file's name (`gametypes/<name>.toml`), or
|
||||
`file=<name>` (a gametype a player's game saved, below). A gametype's
|
||||
name is letters, digits, `_`, `-` and `.`, in any case.
|
||||
- A rule is a gametype rule's name or its short name (`score`, `time`,
|
||||
`weapons`, `ff`...; `GET /api/gametypes`'s schema lists them), with a
|
||||
value it takes; a rule of another game engine than the gametype's is
|
||||
refused. 48 rules at most; a rule given twice is the last.
|
||||
|
||||
An entry that cannot be played (a map that is not there, a bad gametype
|
||||
file, a rule out of range) is left out with a warning, at the start and at
|
||||
`sv_reload`; `sv_rotation_set` and `PUT /api/rotation` change nothing when
|
||||
one of their entries cannot be played.
|
||||
|
||||
A change of the rotation (`sv_rotation_*`, `PUT /api/rotation`,
|
||||
`sv_reload`) keeps its place: the next game is the entry after the one
|
||||
played last, found again in the new list (the first entry only when none
|
||||
has been played yet). `sv_reload` takes the rotation again when its text
|
||||
changed, and also when only its entries' rejections changed (a map or a
|
||||
gametype file added or taken out since).
|
||||
|
||||
`server.team_start` decides how a team game starts. `one` (the default)
|
||||
starts it with the players of one team. `both` waits, saying nothing,
|
||||
for a player on each team. `skip`, when one player waits for a team game
|
||||
that `sv_map` did not ask for, plays the rotation's next entry without
|
||||
teams instead (if it has one); it is checked when the lobby opens and
|
||||
again when its countdown would begin. With no entry left, the server
|
||||
stops with exit code 3 (2 when no rotation map is there), or plays
|
||||
`bloodgulch:slayer` with `server.rotation_fallback`.
|
||||
|
||||
## Gametype files
|
||||
|
||||
A gametype file, `gametypes/<name>.toml` (the name `a`–`z`, `0`–`9`, `_`
|
||||
and `-`), is a built-in or OpenCE gametype (`base`) and rules over it:
|
||||
|
||||
```toml
|
||||
base = "team_king" # the gametype it starts from
|
||||
name = "Moving Hill" # the name the game shows: 11 characters of printable ASCII
|
||||
|
||||
[universal]
|
||||
score_to_win = 3
|
||||
|
||||
[options]
|
||||
time_limit = 15
|
||||
friendly_fire = "off"
|
||||
|
||||
[king]
|
||||
moving_hill = true
|
||||
```
|
||||
|
||||
Each rule goes in its table (the schema's `table`): `[universal]`,
|
||||
`[options]`, and one game engine's, `[ctf]`, `[slayer]`, `[oddball]`,
|
||||
`[king]` or `[race]`. A file gives each rule its full name
|
||||
(`vehicle_set`, `team_vehicles`, `score_to_win`): the short names
|
||||
(`vehicles`, `score`) are the rotation's alone. A file is 64 KB at most.
|
||||
`deploy/gametypes` has examples. The server reads the `gametypes` folder
|
||||
beside `config.toml` if there is one, else the data root's, and writes the
|
||||
web page's files to it.
|
||||
|
||||
A gametype a player's game saved is played with `file=<name>`: copy the
|
||||
saved gametype, as `<name>.gametype`, into the same `gametypes` folder
|
||||
(beside `config.toml` if there is one, else the data root's).
|
||||
|
||||
## The listing
|
||||
|
||||
A public server (`server.public`, with `network.online` and
|
||||
`network.public_lobby`) is published to each master server of
|
||||
`masters.txt` (`docs/master_protocol.md`). A change that a list shows (the
|
||||
listing made public or private, a player joining or leaving, the name, the
|
||||
map) is published within 5 seconds. Made private, the server makes a new
|
||||
invite and sends the masters a closed publish, which takes it off their
|
||||
lists;
|
||||
`network.public_lobby = false` stops the publishing too. A master's
|
||||
`Retry-After` is kept (a day at most). `key_revoked` and
|
||||
`publisher_revoked` stop the publishing to that master for the run;
|
||||
`unknown_key`, `publisher_pending`, `application_denied` and
|
||||
`listing_taken` are logged once a minute while they last.
|
||||
|
||||
## Files
|
||||
|
||||
| File | What |
|
||||
| --- | --- |
|
||||
| `config.toml` | Every setting (beside the executable; `HALO_CONFIG_FILE`, else `--config`, names another) |
|
||||
| `init.txt` (`server.init_file`) | Commands run at the start, in the data root unless a full path |
|
||||
| `gametypes/<name>.toml` | Gametype files: the `gametypes` folder beside `config.toml` if there is one, else the data root's |
|
||||
| `gametypes/<name>.gametype` | Gametypes saved by a player's game (`file=<name>` in the rotation): the same `gametypes` folder |
|
||||
| `publisher.key` | The publisher key for the master servers (beside `config.toml`). On Windows, a server's `config.toml` and `publisher.key` are given an access list of their owner alone (the entries inherited for Administrators and SYSTEM taken out) |
|
||||
| `masters.txt` | The master servers (`server.masters_file`: beside `config.toml`, else beside the executable); one that names none leaves the official master, built in |
|
||||
| `bans.txt`, `cheaters.txt`, `debug.txt` | In `paths.logs`, else the data root |
|
||||
| `status.json` (`server.status_file`) | The status, written every 2 seconds |
|
||||
| A password's file (`HALO_SERVER_WEB_PASSWORD_FILE`, `HALO_SERVER_WEB_OWNER_PASSWORD_FILE`, `HALO_SERVER_WEB_MODERATOR_PASSWORD_FILE`, `HALO_SERVER_WEB_VIEWER_PASSWORD_FILE`, `HALO_SERVER_PASSWORD_FILE`) | A container's secret: when the plain variable is not set, the file's first line (its CR and LF off) is the setting's value, which is then pinned as the plain variable's would be (`sv_set` and `PUT /api/settings` refuse it, `409 pinned`). Read once, at the start; a file that cannot be read is logged, and the setting is `config.toml`'s |
|
||||
|
||||
## Releases
|
||||
|
||||
Each release has `SHA256SUMS` (the SHA-256 of each of its files, as
|
||||
`sha256sum` writes them: `<hex> <name>`, written by `tools/ci_build.py
|
||||
sums`) and `SHA256SUMS.sig`: the Ed25519 signature of that file's exact
|
||||
bytes by the project's release key, in 128 lowercase hex digits and a
|
||||
newline (the form `opence-master-server`'s `cmd/release-sign` writes). The
|
||||
public key is `deploy/release-key.pub` (64 hex digits:
|
||||
`d04e8b101007d1641cace8b95fcca76f7f44709f6885c3d031b52394dbdf9376`).
|
||||
`tools/release_sign.sh verify SHA256SUMS` checks the signature (OpenSSL 3),
|
||||
and `sha256sum -c --ignore-missing SHA256SUMS` the files downloaded. The
|
||||
build workflow signs with the `RELEASE_SIGNING_KEY` secret (the key's seed,
|
||||
64 hex digits) and checks the signature against `deploy/release-key.pub`
|
||||
before it publishes the release.
|
||||
@@ -0,0 +1,374 @@
|
||||
# Exact-match acceleration playbook
|
||||
|
||||
This document records techniques with broader application to the January 2002
|
||||
Halo Xbox decompilation. Object-specific measurements remain in
|
||||
`docs/object_matching_logs/`; this file contains only controls, triage rules,
|
||||
and campaign practices that have survived strict comparison.
|
||||
|
||||
The objective is faster reconstruction without lowering the bar. A candidate
|
||||
is not exact because it is correct, similar, the same size, or 99% fuzzy. The
|
||||
admission evidence remains XDK 3911 output, exact normalized bytes, exact
|
||||
relocation shape and resolved destinations, exact owned data/layout, and a
|
||||
whole-translation-unit regression audit.
|
||||
|
||||
## Campaign strategy
|
||||
|
||||
1. **Finish objects, not isolated functions.** Prefer a unit with a bounded
|
||||
residual and known data ownership over a larger number of unrelated leaves.
|
||||
Once an object is opened, carry it through code, data, ownership, regression,
|
||||
documentation, and `Matching` admission unless a measured compiler tie
|
||||
satisfies the parking standard.
|
||||
2. **Prioritize reusable foundations.** Scenario/BSP accessors, real-math
|
||||
leaves, player/unit layouts, tag/object accessors, datum iterators, compiler
|
||||
wrapper families, and complete donor translation units reduce later work.
|
||||
3. **Separate reconstruction from tuning.** First recover the January
|
||||
semantics, types, call graph, private ABI, and owned data. Tune source shape
|
||||
only after target size/relocation evidence says the structure is close.
|
||||
4. **Work atomic private-ABI clusters together.** Static helpers and their
|
||||
callers can form a register-allocation fixed point. Splitting them across
|
||||
lanes produces false blockers.
|
||||
5. **Use a bounded experiment budget.** Test one source factor at a time,
|
||||
record the exact result, and stop repeating compiler-equivalent spellings.
|
||||
A parked result needs explicit size, relocation, first-divergence, and
|
||||
exhausted-control evidence.
|
||||
6. **Automate candidate generation, never acceptance.** Shape-transfer and
|
||||
donor tools may propose source, but the unchanged strict comparator and
|
||||
regression gates decide admission.
|
||||
|
||||
### Select closeouts from strict evidence, not the ordinary percentage
|
||||
|
||||
Run `python -m tools.rank_object_closeouts` after regenerating the ordinary
|
||||
and semantic reports. The ranking deliberately combines:
|
||||
|
||||
- the complete function inventory from the ordinary report;
|
||||
- the reviewed strict `accepted_ledger`;
|
||||
- object `Matching` status; and
|
||||
- the evidence-backed parked-function catalog.
|
||||
|
||||
This prevents three recurring campaign mistakes:
|
||||
|
||||
1. treating a differently numbered local jump-table label as unfinished code;
|
||||
2. repeatedly dispatching a one-function object whose only residual is already
|
||||
a proven compiler tie; and
|
||||
3. overlooking a data-only closeout after every function is exact.
|
||||
|
||||
The tool is a triage aid, not an admission oracle. `NEAR_CLOSEOUT` means the
|
||||
remaining work is unparked and bounded; it does not predict that source tuning
|
||||
will succeed. `LEDGER_REVIEW` means earlier object work exists and its
|
||||
do-not-repeat/reopen rules must be read before dispatch. `PROVEN_BLOCKED` means
|
||||
every remaining function is in the
|
||||
reviewed parked ledger and must not be reopened without satisfying its stated
|
||||
reopen criterion. Always read the object's Markdown ledger before editing.
|
||||
|
||||
## Evidence hierarchy
|
||||
|
||||
From strongest to weakest:
|
||||
|
||||
1. January target bytes, relocation metadata, linked addresses, and section
|
||||
ownership.
|
||||
2. January sibling functions and exact donor translation units.
|
||||
3. January assert strings, source paths, help tables, tag definitions, and call
|
||||
sites.
|
||||
4. XDK 3911 headers and synthetic compiler experiments under the exact flags.
|
||||
5. October Xbox, Halo PC/CEA/HCEX PDBs, community forks, and later-engine types.
|
||||
|
||||
Levels 4 and 5 generate hypotheses. They do not override January evidence.
|
||||
Every imported field, enum, prototype, or name must be corroborated locally.
|
||||
|
||||
## High-yield source controls
|
||||
|
||||
### Ownership and alias modeling
|
||||
|
||||
VC7 code generation depends on what it can prove about globals:
|
||||
|
||||
- Aggregate storage can force address common-subexpression elimination or
|
||||
destroy an index because sibling fields may alias.
|
||||
- Separate globals can preserve a live SIB index and eliminate reloads.
|
||||
- A one-field structure can retain field-oriented optimizer behavior while a
|
||||
separate array supplies non-aliasing proof. This closed
|
||||
`game_engine_multiplayer_sounds.obj`: it preserved `dec; mov; je` flags in
|
||||
the update while producing SIB stores in the queue helper.
|
||||
- Static versus external linkage affects alias knowledge, section order,
|
||||
symbol storage class, and whether zero-initialized data becomes `.bss` or a
|
||||
tentative/common symbol.
|
||||
|
||||
Always verify the full object. A linkage change can leave every function exact
|
||||
while silently deleting or reordering `.bss`.
|
||||
|
||||
### Statement and branch order
|
||||
|
||||
- VC7 often reflects the original failure-first versus success-first topology.
|
||||
Reversing an `if` can fix multiple relocation-address regions at once.
|
||||
- Tail-merging is sensitive to deliberately asymmetric source duplication.
|
||||
If two switch cases must share a forward machine-code tail but an explicit
|
||||
shared label sinks a callee-save or changes the prologue, keep the simple
|
||||
early path's tiny terminal test locally and route the longer path forward to
|
||||
the other case's copy. In `shaders.obj`, VC7 cross-jumped that readable
|
||||
duplicate into one shared target tail while preserving the required ESI
|
||||
lifetime. Verify relocation identities: this is a measured block-placement
|
||||
control, not permission to duplicate arbitrary logic.
|
||||
- Common stores in two branches may be tail-merged, but a constant-valued
|
||||
branch can instead materialize an immediate store and grow the function.
|
||||
- Comparison polarity matters even when predicates are logically equivalent;
|
||||
it controls `cmp` operand order, signed branches, and register lifetimes.
|
||||
- Use a single return when the target structure permits it. When the exact
|
||||
source requires multiple source returns to reproduce a common compiler
|
||||
epilogue, record that as an evidence-backed house-style exception.
|
||||
|
||||
### Scalar stores versus aggregate operations
|
||||
|
||||
- Field-wise stores give the scheduler independent operations and can reproduce
|
||||
interleavings that `{0}`, aggregate assignment, `memset`, or `rep stos`
|
||||
cannot.
|
||||
- Conversely, aggregate assignment is useful when the target uses `rep movs`
|
||||
or a single calculated element address.
|
||||
- VC7 groups local-struct zero initialization by brace level. If member zero
|
||||
is itself an aggregate, `= {0}` can produce one whole-struct zero live range,
|
||||
while `= {{0}}` can split the first member's fill from the implicit trailing
|
||||
fill. A target whose zero stores split exactly at that member boundary is
|
||||
evidence for testing the extra brace; this closed
|
||||
`telnet_console_initialize` without changing behavior.
|
||||
- Preserve target load and store order before trying declaration-order noise.
|
||||
|
||||
### Local lifetime is more important than local spelling
|
||||
|
||||
Naming an expression does not necessarily change VC7 output; the optimizer can
|
||||
fold a short-lived alias immediately. What matters is where the value becomes
|
||||
live and how long it must survive. In `data_packets.obj`, naming
|
||||
`decoded_data + sizeof(short)` beside its final memory call did nothing across
|
||||
several experiments. Computing the same readable payload pointer *before* the
|
||||
range assert and keeping it live across validation plus an intervening integer
|
||||
encode changed no instruction by itself, but rotated three later scratch
|
||||
registers and closed a 768-byte function exactly.
|
||||
|
||||
In plain English: do not keep renaming a value and expect different code. Move
|
||||
the point where the program genuinely needs to remember it, then measure the
|
||||
whole function. This is especially useful around asserts and calls, where an
|
||||
additional live pointer changes the compiler's interference graph without
|
||||
inventing operations.
|
||||
|
||||
### Integer width and signedness
|
||||
|
||||
- `movsx`/`movzx`, partial-register operations, and signed branch opcodes reveal
|
||||
the real promotion boundaries.
|
||||
- Function parameter widths matter even when the x86 ABI still occupies a
|
||||
four-byte stack slot. In `rasterizer_xbox_motion_sensor.obj`, changing a
|
||||
render-target parameter from `long` to the proven `word` transformed
|
||||
`movzx` into the target's `xor reg, reg; mov reg16, [memory]` sequence and
|
||||
closed the entire remaining half of a 1,920-byte function.
|
||||
- Change signedness only where the target proves it. A `jle` versus `jbe`
|
||||
difference is often a type error; an ESI/EDI mirror is not.
|
||||
- Recover narrow accumulators instruction by instruction rather than relying
|
||||
on C's default integer promotions.
|
||||
|
||||
### x87 controls
|
||||
|
||||
- A value live after a store selects `fst`; a dead value selects `fstp`.
|
||||
- Source operand order controls non-commutative subtraction/division memory
|
||||
forms. VC7 canonicalizes commutative addition/multiplication; spelling order
|
||||
is not a lever there.
|
||||
- Passing, returning, or globally storing a floating result produces distinct
|
||||
stack-staging patterns.
|
||||
- Never substitute mathematically equivalent expressions that change signed
|
||||
zero, NaN payload/sign, intermediate precision, or rounding.
|
||||
- When a shared inline vector helper matches standalone but changes scheduling
|
||||
at one caller, preserve the donor's **expression surface**, including
|
||||
apparently redundant parentheses. In `collision_features.obj`, changing
|
||||
`(v->i*t) + p->x` to the equally readable `v->i*t + p->x` altered inline IR
|
||||
without changing the helper's standalone meaning and restored a January
|
||||
`fstp`/address-formation boundary. Treat this as a measured inline-context
|
||||
lever, not a license for blind parenthesis permutations.
|
||||
- VC7 reassociates a one-expression commutative dot product, so merely reversing
|
||||
its written terms may do nothing. If January proves a specific x87 load/add
|
||||
order, sequential accumulation can preserve it. The exact
|
||||
`collision_prism_test_vector` form initializes the `k` product, then adds
|
||||
`j`, then `i`; every intermediate remains a normal `real` value.
|
||||
|
||||
### XDK inline wrappers
|
||||
|
||||
Stock XDK `D3DINLINE` under this compiler emits the January out-of-line D3D
|
||||
wrapper families when called normally. Address-taking forces a different
|
||||
standard-ABI body, and redefining `D3DINLINE` as plain `static` can emit a
|
||||
thunk. Prefer the stock header form and verify every emitted wrapper in the TU.
|
||||
One motion-sensor translation unit instantiated ten such wrappers exactly in a
|
||||
single build, including both 432-byte and 544-byte dispatchers. Treat the
|
||||
header recipe as a high-yield candidate generator, but still compare every
|
||||
wrapper and its relocation destinations independently.
|
||||
|
||||
### Diagnose the first true divergence
|
||||
|
||||
- Ignore downstream branch displacements and relocation-address drift until
|
||||
the earliest semantic or instruction-length difference is closed.
|
||||
- Decode cdecl pushes right-to-left before blaming register allocation. A wrong
|
||||
argument order can make a large suffix look like a scheduler problem.
|
||||
- If a small type correction makes a long suffix exact automatically, the
|
||||
suffix was displacement drift, not a collection of independent problems.
|
||||
- Zero-byte intrinsics such as `_ReadWriteBarrier()` are measured controls, not
|
||||
universal fixes. They can prevent desirable argument hoisting and make an
|
||||
otherwise close function worse.
|
||||
- A one-byte `push eax` where the reconstruction emits the two-byte `push 0`
|
||||
after testing a result is evidence that the original passes the tested
|
||||
result, not a literal. Preserving that value into the error arm can change a
|
||||
large register-allocation suffix even when alignment leaves the padded size
|
||||
unchanged. For size-exact functions containing a switch, inspect padding
|
||||
and jump-table tails as well as the nominal body.
|
||||
|
||||
### Recover the type before tuning the schedule
|
||||
|
||||
A value that stays live in a register longer than expected is often evidence
|
||||
of a wrong prototype or field width, not a mysterious compiler decision.
|
||||
Before trying declaration orders, barriers, or control-flow rewrites:
|
||||
|
||||
- Check what the target returns in `EAX` or `AL`. If the target preserves a
|
||||
meaningful value until `ret`, a function currently declared `void` may
|
||||
actually return that value.
|
||||
- Check whether the target consistently reads, masks, or writes only the low
|
||||
byte or low word. A `char`, `boolean`, `short`, or `word` may be the real
|
||||
type even when a 32-bit placeholder produces correct gameplay behavior.
|
||||
- Prefer the smallest type that is supported by all call sites and target
|
||||
instructions. Do not narrow a type merely because it happens to improve the
|
||||
bytes.
|
||||
|
||||
In `texture_page.obj`, recovering `spacing_mask` as a 16-bit `word` made a
|
||||
736-byte packing function exact. Recovering
|
||||
`texture_page_textures_end` as a `boolean` function explained why January kept
|
||||
the packing result in `AL` across the loop and made its remaining 112 bytes
|
||||
exact. In plain English: the compiler was not being stubborn; we had told it
|
||||
the wrong facts about the program.
|
||||
|
||||
### Private ABI controls
|
||||
|
||||
A source-static, non-address-taken, frameless helper can receive arguments in
|
||||
ECX/EDX or another caller-derived convention. External linkage, address-taking,
|
||||
or a stack frame can destroy that convention. Work from a forced-register
|
||||
caller outward; do not tune a private helper in isolation.
|
||||
|
||||
### Compiler provenance before compiler hunting
|
||||
|
||||
Do not attribute a stubborn register or scheduling residual to an unknown
|
||||
compiler patch until the target's own debug records have been checked.
|
||||
PDB 2.00 module streams can contain `S_COMPILE2_ST` records with independent
|
||||
front-end and back-end version triples. For the January `players.obj`, the
|
||||
record proves `13.0.9254` for both halves, matching the campaign compiler's
|
||||
reported build.
|
||||
|
||||
Use this order:
|
||||
|
||||
1. Decode the target compiland's compiler record.
|
||||
2. Compile the unchanged TU once with each genuinely distinct local compiler
|
||||
binary.
|
||||
3. Compare normalized hashes for every residual, not just the first
|
||||
instruction.
|
||||
4. If all variants are byte-identical, stop the compiler hunt and return to
|
||||
source provenance or a demonstrated legal-C control.
|
||||
|
||||
For Players, VC7 `13.00.9210` and `13.00.9254.1` emitted byte-identical
|
||||
candidate hashes for all four residuals. That falsifies the available
|
||||
patch-level lever and prevents repeated SDK downloads or speculative flag
|
||||
changes.
|
||||
|
||||
## Transfer and donor rules
|
||||
|
||||
- A donor is usable only when its source text is resolved and its target
|
||||
machine shape is exact.
|
||||
- Derive every recipient callee/global substitution from the recipient target
|
||||
relocations, never by name similarity.
|
||||
- Equal relocation-masked bytes can hide a wrong-callee wrapper. Destination
|
||||
identity and addends remain strict.
|
||||
- Preserve target statement order; relocation sequence is often its strongest
|
||||
surviving proof.
|
||||
- Reject stubs, unresolved donors, inconsistent substitution maps, prologue
|
||||
mismatches, and data-ownership changes automatically.
|
||||
|
||||
### Candidate-only helper COMDATs
|
||||
|
||||
An inlined helper can occasionally leave an unreferenced out-of-line COMDAT
|
||||
copy in the candidate object. Never dismiss it just because the target
|
||||
function compares equal. It is acceptable only after all of the following are
|
||||
proved:
|
||||
|
||||
- the extra section is a discardable COMDAT with the expected selection rule;
|
||||
- no relocation in the object refers to it;
|
||||
- every target-owned function and data section remains strict-exact;
|
||||
- the ordinary link actually discards it; and
|
||||
- the consolidated link, semantic audit, and progress report remain clean.
|
||||
|
||||
This is a linker-level representation difference, not permission to ignore
|
||||
extra ordinary code or data.
|
||||
|
||||
## Parking standard
|
||||
|
||||
Park only when:
|
||||
|
||||
- target and candidate padded size are exact;
|
||||
- relocation count, types, and destinations are exact, or a reviewed
|
||||
representation-only difference has independently resolved destinations;
|
||||
- the remaining divergence is classified precisely;
|
||||
- legal-C controls appropriate to that class have been exhausted;
|
||||
- the object ledger records a reproducible first divergence and reopen
|
||||
criterion.
|
||||
|
||||
A 92% function with different size or relocations is structural work, not a
|
||||
compiler tie. A one-instruction scheduler swap can be parked only after the
|
||||
dependency and source-control search are documented.
|
||||
|
||||
## Admission checklist
|
||||
|
||||
Before marking an object `Matching`:
|
||||
|
||||
1. Build with XDK 3911 and the repository flags.
|
||||
2. Compare every function with the hardened COFF comparator.
|
||||
3. Verify every owned `.data`, `.rdata`, and `.bss` span, including symbol
|
||||
offsets, storage classes, and relocation destinations.
|
||||
4. Confirm the ordinary report does not hide a strict false positive.
|
||||
5. Run the whole-TU regression gate against a pre-edit snapshot. Review every
|
||||
intentional ownership transition; never suppress unrelated failures.
|
||||
6. Run the consolidated build, semantic audit, and progress report.
|
||||
7. Update the object ledger with retained and rejected experiments.
|
||||
8. Mark `Matching` only after all evidence passes.
|
||||
|
||||
### Greenfield regression gates
|
||||
|
||||
An empty skeleton has no previously exact code or owned data for a pre-edit
|
||||
manifest to protect. A correct reconstruction will therefore appear to the
|
||||
regression gate as a set of new functions, symbols, COMDATs, and data. Do not
|
||||
force that report green and do not waive its findings:
|
||||
|
||||
- confirm that it reports no changed previously exact function or section;
|
||||
- classify every addition against the January target;
|
||||
- admit the object only after strict function, relocation, ownership,
|
||||
consolidated-build, and semantic-progress checks pass;
|
||||
- immediately capture a post-admission manifest and verify it is stable, so
|
||||
later edits are checked against the newly completed object.
|
||||
|
||||
## Original bugs
|
||||
|
||||
Exact reconstruction preserves proven original behavior. Mark a defect
|
||||
`BUG (original)` only when January evidence proves it. In the matching source,
|
||||
retain the original behavior and add a concise comment describing a safe
|
||||
corrected-build alternative. Do not silently repair it and do not label our
|
||||
own reconstruction mistake as an original bug.
|
||||
|
||||
An original uninitialized read is an exceptional case, not a general codegen
|
||||
lever. Preserve one only when the January control flow proves the read, an
|
||||
independent build or source lineage corroborates it, and a bounded search shows
|
||||
that defined readable-C alternatives do not match. Record the safe initialized
|
||||
form and its measured result in the object log. Never introduce a new
|
||||
uninitialized value merely because it improves register allocation.
|
||||
|
||||
Do not infer a fallback assignment merely because target code reloads a value
|
||||
after a fatal assertion or `system_exit`. In `data_decode_memory`, that
|
||||
seemingly sensible repair was the sole cause of a whole-function register
|
||||
allocation mismatch; the January/October machine code plus an exact-unique
|
||||
HCEA PDB local record and HCEA PPC body showed that the original impossible
|
||||
default arm left its sole size local unassigned. Remove such a repair only
|
||||
with the full original-bug evidence gate above, then state the safe corrected
|
||||
alternative in source and measure it in the object log.
|
||||
|
||||
## Prohibited shortcuts
|
||||
|
||||
No inline assembly, volatile byte forcing, undefined aliasing, object-byte
|
||||
patches, compiler pragmas used only to force bytes, flag changes, fuzzy-only
|
||||
credit, or invented symbols/types. Compiler experiments belong in disposable
|
||||
worktrees; production admission must remain readable evidence-backed C.
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
# Fake-match source review
|
||||
|
||||
`tools/fake_match_scan.py` finds unusual C/C++ constructs that deserve a
|
||||
credibility or semantics review. It is a heuristic lead generator, not an
|
||||
object comparator, admission gate, or proof that source is fake. A byte match
|
||||
does not make nonsensical source credible, and a scanner hit does not make
|
||||
ordinary source wrong.
|
||||
|
||||
These examples run from the repository root (the script also derives the
|
||||
repository root correctly when invoked by an absolute path from elsewhere):
|
||||
|
||||
```text
|
||||
python tools/fake_match_scan.py
|
||||
python tools/fake_match_scan.py source/ai/actions.c source/game
|
||||
python tools/fake_match_scan.py --format json --fail-on-findings source/ai
|
||||
python tools/fake_match_scan.py --list-rules
|
||||
```
|
||||
|
||||
The default input is the repository's `source/` directory. Explicit file and
|
||||
directory inputs are de-duplicated and emitted in deterministic path/line/rule
|
||||
order. Known vendored libtiff, zlib, `third_party`, and `vendor` trees are
|
||||
skipped unless `--include-vendored` is supplied. Comments and string/character
|
||||
literals are masked before scanning so examples and assert text do not become
|
||||
findings.
|
||||
|
||||
Exit status is deterministic:
|
||||
|
||||
- `0`: the scan completed; findings may be present.
|
||||
- `1`: findings are present and `--fail-on-findings` was requested.
|
||||
- `2`: an input is invalid or a source file cannot be read.
|
||||
|
||||
Every finding should prompt a source review, not an automatic rewrite. Check
|
||||
whether the construct expresses plausible original program intent, whether the
|
||||
logic is meaningful for all inputs, and whether first-party source, names,
|
||||
target CFG/relocations, or a credible contemporary codebase supports it. Re-run
|
||||
the strict object and regression gates after any resulting edit. Exact bytes
|
||||
alone are not provenance.
|
||||
|
||||
Semantic validity is an admission requirement even when every byte matches.
|
||||
Reject code whose behavior is nonsensical, whose conditions or data flow are
|
||||
meaningless, or whose source shape almost certainly would not have existed in
|
||||
the original program. A coincidental exact result must be reverted or replaced
|
||||
with the best honest fuzzy reconstruction and parked with its evidence.
|
||||
|
||||
The rule set intentionally omits several noisy shortcuts. It does not condemn
|
||||
ordinary `volatile` declarations, generic representation casts, `!!value`, or
|
||||
`value != value`; those can express hardware synchronization, serialization,
|
||||
boolean normalization, or a NaN test. It also performs no data-flow proof, so a
|
||||
clean scan cannot establish that variables are initialized or that logic is
|
||||
sound.
|
||||
@@ -0,0 +1,63 @@
|
||||
# source/linker_common: what a comparison base can and cannot earn
|
||||
|
||||
*2026-09-22, Lane C. Built at the owner's direction, from January's verified
|
||||
COMMON records only, and scored separately from the board.*
|
||||
|
||||
## What the unit is
|
||||
|
||||
`source/linker_common` is not a translation unit. It is csplit's name for the
|
||||
pooled COMMON block of January's image: 242 records totalling 1,272,664 bytes,
|
||||
gathered by the linker from tentative definitions across the whole program
|
||||
(`_render` 643,732, `_ai_debug` 547,628, `_dsound_globals` 30,924, and ~200
|
||||
smaller ones, down to single-byte debug toggles). `objdiff.json` gives it a
|
||||
`target_path` and **no `base_path`**, because our build produces no such object -
|
||||
our COMMON symbols live in their owning objects' symbol tables with section 0.
|
||||
So it reports 0.000% structurally, not because anything is wrong.
|
||||
|
||||
## The base, and its score
|
||||
|
||||
`tools/campaign/linker_common_base.py` builds a comparison base containing ONLY
|
||||
verified records: a symbol January pools that our tree independently emits as a
|
||||
COMMON symbol of the identical size. Nothing is invented, and nothing
|
||||
initialised is copied - a `.bss` record carries no bytes, only a name and a
|
||||
size, and the size used is the one our own objects request. Records we do not
|
||||
emit, emit at a different size, or emit in a real section are dropped.
|
||||
|
||||
kept 58 records 1,214,903 bytes
|
||||
dropped 184 records 56,787 bytes
|
||||
|
||||
Scored on its own (`objdiff-cli report generate` over a one-unit config):
|
||||
|
||||
.bss 1,272,568 95.541%
|
||||
.rdata 96 0.000%
|
||||
credited 0
|
||||
|
||||
**It earns nothing.** Data is credited per section only at 100%, so 95.541% is
|
||||
worth exactly as much as 0%. The number's value is diagnostic: it says 95.5% of
|
||||
the pooled block is already correct in our tree, and names precisely what is not.
|
||||
|
||||
## What the remaining 4.5% is
|
||||
|
||||
181 records, 56,187 bytes, absent from our tree entirely. Only 27 of them
|
||||
(1,125 bytes) are CRT/XDK/dsound runtime symbols. The rest are genuine Halo
|
||||
globals no TU of ours declares: `_dsound_globals` 30,924, `_rasterizer_lights`
|
||||
7,172, `_sound_channels` 6,144, `_wind_globals` 3,340, `_error_globals` 2,056,
|
||||
`_global_window_parameters` 600, and so on. Plus two pooled `.rdata` records
|
||||
(96 bytes) that are not COMMON at all and so are outside this base by
|
||||
construction, and one size mismatch, `_file_location_volume_names`, which is the
|
||||
out-of-bounds array bug recorded separately.
|
||||
|
||||
Closing the section therefore needs those 181 globals declared as tentative
|
||||
definitions in the right units - spread across many TUs, several of which are
|
||||
not reconstructed - and it pays nothing until every one of them is present.
|
||||
|
||||
## Rules this establishes
|
||||
|
||||
* A symbol in `linker_common` was a TENTATIVE DEFINITION in January: declared
|
||||
with no initialiser. **Never add `= {0}` to such a global** - that moves it out
|
||||
of the pool. Check `linker_common` before touching any global's initialiser.
|
||||
This is how the `actors.c` `= NULL` defect was found and fixed.
|
||||
* Conversely, a global January keeps in its OWN object's `.bss` (director,
|
||||
render_objects) was initialised in source, and must keep its initialiser.
|
||||
* Do not wire this base into `objdiff.json`. It would fold a structurally
|
||||
uncreditable section into the board number without closing anything.
|
||||
@@ -1,650 +0,0 @@
|
||||
# The master servers' protocol, version 1
|
||||
|
||||
A master server lists dedicated servers and vouches for who publishes them.
|
||||
An operator applies to a master once with the public half of an Ed25519
|
||||
key, the *publisher key*, through the master's Discord bot; once an
|
||||
approver approves the application, the
|
||||
operator's servers publish to the master with requests signed by that key,
|
||||
and the master lists them after probing their UDP port. The game's server
|
||||
browser fetches each master's list, checks the master's signature with the
|
||||
key pinned in `masters.txt`, and joins a listed game by the invite in its
|
||||
listing, as it joins a game heard on the brokers.
|
||||
|
||||
A master carries no game traffic: each list entry holds the host-signed
|
||||
listing the game publishes to the signalling brokers (`p2p_lobby.c`), so
|
||||
the join path is unchanged and nobody needs the master to be honest about a
|
||||
game's details.
|
||||
|
||||
This document is the contract between the game (the publisher in
|
||||
`port/linux/src/server_master.c`, the probe's answer, the list client in
|
||||
`port/linux/src/master_list.c`) and the masters' implementations. The
|
||||
project's implementation is `opence-master`
|
||||
(github.com/OpenCommunityEdition/opence-master-server, Go, AGPL-3.0-or-later),
|
||||
whose `testdata/vectors.json` holds fixed keys and every value this
|
||||
document derives from them, and whose `tests/conformance` is the test a
|
||||
master must pass to be an official one. `docs/dedicated_server.md` is the
|
||||
server's side: its settings, `--keygen` and `--sign`.
|
||||
|
||||
## Conventions
|
||||
|
||||
| Thing | Form |
|
||||
| --- | --- |
|
||||
| Hexadecimal | Lowercase, two digits a byte, no prefix |
|
||||
| Base64 | The standard alphabet (RFC 4648 section 4) with `=` padding |
|
||||
| Times | Unix seconds, decimal, UTC |
|
||||
| JSON | UTF-8; every string the protocol defines is printable ASCII (0x20 to 0x7E) |
|
||||
| Signatures | Ed25519 as RFC 8032 defines it (with SHA-512): Monocypher's `crypto_ed25519_sign` and `crypto_ed25519_check`, Go's `crypto/ed25519` |
|
||||
| Transport | HTTPS. A master refuses publishes, key changes and peers' requests over plain HTTP except from loopback |
|
||||
| Unknown JSON fields | Ignored by both sides, so later versions can add fields |
|
||||
|
||||
## Keys and identifiers
|
||||
|
||||
| Thing | Definition |
|
||||
| --- | --- |
|
||||
| Key file (`publisher.key`, `master.key`) | One line of 64 hexadecimal digits: the Ed25519 seed (32 bytes). Anything after `#` is a comment; blank lines are skipped. Mode 0600 |
|
||||
| Public key, as text | `ed25519:` and the 32-byte public key in hexadecimal (64 digits) |
|
||||
| Key id | The first 8 bytes of SHA-256 of the 32-byte public key. Written as 16 hexadecimal digits (`keyid=`, `key_id`, `Signature-Key`); in the probe's packets it is the 8 raw bytes |
|
||||
| Instance | A name the operator gives each server process (`server.instance`): 1 to 32 characters of `a-z`, `0-9`, `-` and `_`, the first a letter or a digit |
|
||||
| Server id | The first 16 hexadecimal digits (8 bytes) of SHA-256 of the ASCII text of the key id's 16 hexadecimal digits followed by the instance's text, with nothing between them |
|
||||
|
||||
The server id hashes the key id **as its 16 characters of text**, not its 8
|
||||
bytes. With the vectors' publisher key (RFC 8032's first test seed):
|
||||
|
||||
```
|
||||
seed 9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60
|
||||
public key ed25519:d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a
|
||||
key id 21fe31dfa154a261 (SHA-256 of the 32 key bytes: 21fe31dfa154a261...)
|
||||
instance main
|
||||
hashed "21fe31dfa154a261main" (20 ASCII bytes)
|
||||
server id 4c5f15237c866f6f (SHA-256 of those 20 bytes: 4c5f15237c866f6f...)
|
||||
```
|
||||
|
||||
The same instance under another key is another server id, so a server
|
||||
keeps its id across restarts as long as it keeps its key and its instance.
|
||||
A master refuses a public key whose point has a small order (its X25519
|
||||
form multiplied by a clamped scalar is zero, as `p2p_ed25519_verify`
|
||||
checks), since anyone can make signatures that verify under one.
|
||||
|
||||
`masters.txt` (the one beside `config.toml`, else the one beside the
|
||||
executable) lists the masters, one per line:
|
||||
`https://master1.example.org ed25519:<64 hex>`; `#` starts a comment; the
|
||||
first 4 are used. A file that names none (missing, empty, or comments alone,
|
||||
as the release's) leaves the official master, built into the game
|
||||
(`master_list_read_defaults` in `port/linux/src/master_list.c`) and the web
|
||||
page (`servers.js`):
|
||||
`https://master.opencommunityedition.com ed25519:89f4eda71229f11f3538679f49ef7fb0c2b407b380093f7f4fe02105b92225aa`.
|
||||
The web build reads its site's `masters.json` before the official master. The URL is an origin with no path, or a path
|
||||
the master is served under as it is (a proxy must not rewrite paths, since
|
||||
the path is signed).
|
||||
|
||||
## Signed requests
|
||||
|
||||
A publisher's requests carry a detached signature in one header:
|
||||
|
||||
```
|
||||
Authorization: OpenCE-Ed25519 keyid=<16 hex>, ts=<unix seconds>, nonce=<32 hex>, sig=<base64 of 64 bytes>
|
||||
```
|
||||
|
||||
The signature is the key's over the bytes of this string, its parts joined
|
||||
by single line feeds (0x0A) and no line feed at the end:
|
||||
|
||||
```
|
||||
OpenCE-Master-v1
|
||||
<the receiving master's key id>
|
||||
<METHOD>
|
||||
<PATH>
|
||||
<ts>
|
||||
<nonce>
|
||||
<SHA-256 of the body, in hexadecimal>
|
||||
```
|
||||
|
||||
| Part | Rule |
|
||||
| --- | --- |
|
||||
| Master key id | The key id of the master the request is sent to: the first 8 bytes of SHA-256 of the master's list-signing public key (the key pinned for it in `masters.txt`), as 16 lowercase hexadecimal digits. It binds the request to that master: a request signed for one master does not verify at another, even within the replay window. A master checks the signature with its own key id |
|
||||
| `METHOD` | The request's method in capitals: `PUT`, `DELETE`, `GET`, `POST` |
|
||||
| `PATH` | The path exactly as the request line sends it, without the query string: `/v1/servers/4c5f15237c866f6f`, `/v1/me`, `/v1/publishers` |
|
||||
| `ts` | The same decimal text as in the header: no sign, no leading zeros |
|
||||
| `nonce` | 16 random bytes in hexadecimal (32 digits), new for each request |
|
||||
| Body hash | Of the exact body bytes sent; an empty body's is SHA-256 of no bytes, `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855` |
|
||||
|
||||
The four parameters come once each, in any order, separated by commas with
|
||||
optional spaces; a publisher sends them in the order above. The master
|
||||
checks, in this order, and answers the first failure:
|
||||
|
||||
| Check | Failure |
|
||||
| --- | --- |
|
||||
| The header parses (scheme, the four parameters and their forms) | `401 bad_signature` |
|
||||
| `ts` is within 300 seconds of the master's clock | `401 clock` (the body's `master_time` is the master's clock, for the server to log) |
|
||||
| The key id is a publisher's, or an application's | `403 unknown_key` |
|
||||
| The signature verifies, for this master's key id | `401 bad_signature` |
|
||||
| The nonce was not seen with this key in the last 600 seconds | `401 replay` |
|
||||
|
||||
Since `unknown_key` is answered before the signature is checked, anyone can
|
||||
learn whether a key id is known to a master (a publisher's or an
|
||||
application's) by sending it with any signature. This is a known property
|
||||
of version 1: key ids are not secret (each is a hash of a public key, which
|
||||
an operator hands out when applying), and the answer says nothing more of
|
||||
the key than that the master has seen it.
|
||||
|
||||
The vectors' `GET /v1/me` to the vectors' master (key id
|
||||
`39f713d0a644253f`) at 1760900001 with the nonce
|
||||
`f0e0d0c0b0a090807060504030201000` signs
|
||||
|
||||
```
|
||||
OpenCE-Master-v1\n39f713d0a644253f\nGET\n/v1/me\n1760900001\nf0e0d0c0b0a090807060504030201000\ne3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
|
||||
```
|
||||
|
||||
and sends
|
||||
|
||||
```
|
||||
Authorization: OpenCE-Ed25519 keyid=21fe31dfa154a261, ts=1760900001, nonce=f0e0d0c0b0a090807060504030201000, sig=duRZ+WKAI8hbvidtC63U1XHxOSoeRN5mcrZvw4qihhlilhZjbVBCLYjsQLr4+F2C1gy6lN9/ixqevFX7dfNGDA==
|
||||
```
|
||||
|
||||
## Publishing
|
||||
|
||||
`PUT /v1/servers/{server_id}`, signed, with a JSON body of 16 KB at most.
|
||||
A server publishes to every master in `masters.txt` every 30 seconds, and
|
||||
within 5 seconds of a change (the lobby opened, a game started or ended, a
|
||||
player joined or left, the name or map changed). On shutdown it publishes
|
||||
`closed: true` (or `DELETE`s) and waits up to 2 seconds.
|
||||
|
||||
```json
|
||||
{"protocol":1,"instance":"main","name":"OpenCE Dedicated","map":"bloodgulch","gametype":"CTF","variant":"CTF",
|
||||
"players":5,"max_players":16,"teams":true,"in_progress":false,"password":false,"dedicated":true,
|
||||
"network_version":38,"build":"build-206","region":"eu","tunnel_port":2302,
|
||||
"listing":"<base64 of the host-signed listing>","closed":false,"serial":412}
|
||||
```
|
||||
|
||||
(The vectors' publish, made at network version 38: "The listing" says
|
||||
why the examples keep it.) The game's publisher sends `protocol`,
|
||||
`instance`, `listing` (but in a tombstone), `tunnel_port`, `dedicated`,
|
||||
`build`, `region` and `variant` when they are set, `address` with
|
||||
`server.master_publish_address`, `serial` and `closed`; the listing holds
|
||||
the rest. A server that goes private, or off the internet, sends one more
|
||||
publish, `closed: true`, to each master that listed it.
|
||||
|
||||
| Field | Type | Required | Meaning |
|
||||
| --- | --- | --- | --- |
|
||||
| `protocol` | number | yes | 1 |
|
||||
| `instance` | string | yes | The instance; the path's server id must be the server id of the signing key's id and this instance, else `400 server_id` |
|
||||
| `listing` | string | yes, but with `closed: true` | Base64 of the exact bytes `listing_make` makes, the bytes the game publishes to the brokers |
|
||||
| `tunnel_port` | number | yes, unless `address` is given | The UDP port the game's tunnel socket is bound to (`network.tunnel_port`), 1 to 65535 |
|
||||
| `address` | string | no | `"203.0.113.5:2302"`: an IP address (IPv4, or IPv6 in brackets) and a port to probe instead of the request's source address. Sent only with `server.master_publish_address`; a master serves it in its list only if its own policy allows (`MASTER_SERVE_ADDRESSES`). It must be globally routable (below); a private or loopback address is taken only from a private or loopback source |
|
||||
| `dedicated` | boolean | no | A dedicated server. Also read from the listing's flag 32, which a dedicated server sets; either makes the entry dedicated. A player's public game, published with the player's publisher key, sends `false` |
|
||||
| `variant` | string | no | The gametype's name as the server shows it; printable ASCII, cut to 24 |
|
||||
| `build` | string | no | The game's build (`build-206`); cut to 32 |
|
||||
| `region` | string | no | Up to 16 of `a-z`, `0-9` and `-` (`server.region`) |
|
||||
| `serial` | number | no | A whole number the server raises at each change; kept and shown to admins |
|
||||
| `closed` | boolean | no | `true`: unlist the server now |
|
||||
| `name`, `map`, `gametype`, `players`, `max_players`, `teams`, `in_progress`, `password`, `network_version` | | no | Informational only: the listing is authoritative. A value that differs from the listing's is ignored, and the answer's `warnings` says so |
|
||||
|
||||
The master parses the listing and checks the host's signature (below), and
|
||||
takes from it the name, the map, the gametype, the players and most
|
||||
players, the gametype's engine, the game's kind, the open, in-progress,
|
||||
teams and password flags, and the network version, so a publish cannot
|
||||
claim more than the host signed. A listing that does not parse or verify
|
||||
is `400 listing`. So is one whose own time is more than 3600 seconds from
|
||||
the master's clock. A listing with the same host key and a lower sequence
|
||||
than the one the master holds is not taken (the newer stays; a warning
|
||||
says so). A listing with the closed flag unlists the server, as
|
||||
`closed: true` does.
|
||||
|
||||
The master records the request's source address (behind a reverse proxy,
|
||||
the address its trusted proxy forwards) to probe the server. It keeps the
|
||||
addresses 7 days at most after a server's last publish, for probes and
|
||||
abuse handling, and never serves them.
|
||||
|
||||
The addresses a master probes and serves are an allowlist of globally
|
||||
routable unicast addresses: an IPv4 address outside IANA's special-purpose
|
||||
ranges (`0/8`, `10/8`, `100.64/10`, `127/8`, `169.254/16`, `172.16/12`,
|
||||
`192.0.0/24`, `192.0.2/24`, `192.88.99/24`, `192.168/16`, `198.18/15`,
|
||||
`198.51.100/24`, `203.0.113/24`, `224/4`, `240/4`); an IPv6 address in
|
||||
`2000::/3` outside `2001::/23`, `2001:db8::/32`, `3fff::/20` and
|
||||
`5f00::/16`; a 6to4 (`2002::/16`) or well-known NAT64 (`64:ff9b::/96`)
|
||||
address whose embedded IPv4 address is global. An IPv4-mapped address is
|
||||
judged as its IPv4 address. Everything else (link-local, site-local
|
||||
`fec0::/10`, unique local, multicast, `64:ff9b:1::/48`, zones) is refused
|
||||
(`400 schema`, `field: address`), except a private or loopback address
|
||||
from a private or loopback source (a master on the same network). A
|
||||
publish from a source address outside the allowlist without `address` is
|
||||
refused the same way when the master probes.
|
||||
|
||||
A listing's host key is published by one publisher at a time: a listing
|
||||
whose host key is that of a live server of another publisher is refused,
|
||||
`403 listing_taken`, so a listing's bytes copied from a list cannot be
|
||||
published by someone else. The same publisher may carry it under another
|
||||
server id (another key or instance). A host makes a new listing (a higher
|
||||
sequence) at each of its publishes, so a live server that has taken no newer
|
||||
listing of its host key for 90 seconds (3 intervals) is replaying a copy:
|
||||
a publish of a newer listing of that host key takes the host key from it,
|
||||
and its server is unlisted. A server an admin hid, or whose publisher or key
|
||||
is not approved, holds no host key. A master shows its admins the publishes
|
||||
it refused with `listing_taken`, to settle (see "Known limitations").
|
||||
|
||||
### The answer
|
||||
|
||||
`200` once the publish is taken and the master's decision for now is made;
|
||||
`202` while the first probe of the server's address is unanswered:
|
||||
|
||||
```json
|
||||
{"ok":true,"server_id":"4c5f15237c866f6f","listed":true,"interval":30,"ttl":90,"probe":"ok","reachable":true,
|
||||
"observed_address":"203.0.113.5","master_time":1760900000}
|
||||
{"ok":true,"server_id":"4c5f15237c866f6f","listed":false,"interval":30,"ttl":90,"probe":"pending","reachable":false,
|
||||
"observed_address":"203.0.113.5","probe_address":"203.0.113.5:2302","master_time":1760900000}
|
||||
```
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `listed` | Whether the list shows the server now |
|
||||
| `interval` | Seconds between publishes the master expects (30) |
|
||||
| `ttl` | Seconds after its last publish that a server is unlisted (90): one lost publish does not unlist it, three do |
|
||||
| `probe` | `pending` (no answer yet at this address), `ok`, `failed` (three attempts unanswered), `skipped` (an admin marked the server trusted), `off` (the master does not probe) |
|
||||
| `reachable` | The probe was answered |
|
||||
| `observed_address` | The address the master saw the request come from |
|
||||
| `probe_address` | With `pending` and `failed`: the address and port the master probes |
|
||||
| `hidden`, `reason` | An admin hid the server: it is listed to nobody, and `reason` says why. With `probe: failed`, `reason` is the hint to log: `let UDP port <n> through your firewall or NAT, or set network.public_address` |
|
||||
| `closed` | `true` after `closed: true`, a tombstone or `DELETE` |
|
||||
| `warnings` | Body fields the listing contradicts, which were ignored |
|
||||
| `master_time` | The master's clock |
|
||||
|
||||
A server with a failed probe is unlisted unless the master's policy lists
|
||||
unreachable servers (`MASTER_LIST_UNREACHABLE`), as `reachable: false`.
|
||||
The server logs each change of outcome once (not every 30 seconds), and
|
||||
the failed probe's hint once a minute until the probe passes.
|
||||
|
||||
`DELETE /v1/servers/{server_id}`, signed by any key of the server's
|
||||
publisher with an empty body, unlists the server at once and answers
|
||||
`200 {"ok":true,"server_id":…,"listed":false,"closed":true,…}`; `404
|
||||
not_found` for a server that is not the publisher's.
|
||||
|
||||
### Limits
|
||||
|
||||
| Limit | Answer |
|
||||
| --- | --- |
|
||||
| A server publishes at most once each 5 seconds, with a burst of 2 | `429 rate_limited` with `Retry-After` |
|
||||
| 120 publishes a minute per source address, and per key | `429 rate_limited` |
|
||||
| A body is 16 KB at most | `413 too_large` |
|
||||
| A publisher has at most its quota of live servers at once (default 4; live: published within `ttl` and not closed) | `403 quota_exceeded` |
|
||||
| An instance is published by one key of a publisher at a time | `403 instance_taken` (another key's server of that instance is live) |
|
||||
| A publisher holds at most its quota and 16 server records (one per server id); for a new server id past that, its oldest records that are not live are dropped, and if none can be | `403 too_many_instances` |
|
||||
|
||||
## The listing
|
||||
|
||||
The listing is `p2p_lobby.c`'s (`listing_make`, `listing_read`), in network
|
||||
byte order. The master reads it as `listing_read` does and checks its
|
||||
signature as `listing_signed` does.
|
||||
|
||||
| Offset | Size | Field |
|
||||
| --- | --- | --- |
|
||||
| 0 | 2 | `"HL"` |
|
||||
| 2 | 1 | Format: 1 |
|
||||
| 3 | 2 | Network version (`HALO_PORT_NETWORK_VERSION`, 39 now) |
|
||||
| 5 | 1 | Flags (below) |
|
||||
| 6 | 4 | Sequence: the host's count of its listings (the newest wins) |
|
||||
| 10 | 4 | The host's Unix time when it made the listing |
|
||||
| 14 | 32 | The host's Ed25519 public key (one per run of the game) |
|
||||
| 46 | 16, or 56 with the password flag | The invite's token (zero in a tombstone); with the password flag the token sealed with the password's key: nonce (24), MAC (16), the token encrypted (16), XChaCha20-Poly1305 with the host's key as additional data (`p2p_seal_token`) |
|
||||
| then | 1 | Players (at most 255) |
|
||||
| | 1 | Most players |
|
||||
| | 1 | The gametype's engine: 0 none (co-op), 1 CTF, 2 Slayer, 3 Oddball, 4 King of the Hill, 5 Race |
|
||||
| | 1 + up to 32 | The game's name: a length byte, then that many bytes |
|
||||
| | 1 + up to 32 | The map's name |
|
||||
| | 1 + up to 24 | The gametype's name |
|
||||
| | 8 | The stamp: the game's kind (`game_modes_kind`: the OpenCE mode, 1 SWAT, 2 Infection, 3 Gun Game, or 0; with 0x80 for Hardcore), then 7 reserved bytes, zero |
|
||||
| | 64 | The Ed25519 signature, by the listing's key, of the 12 ASCII bytes `hceu-lobby-1` followed by every byte before the signature |
|
||||
|
||||
| Flag | Meaning |
|
||||
| --- | --- |
|
||||
| 1 | Open: it takes players now |
|
||||
| 2 | In progress: a game is under way (or loading) |
|
||||
| 4 | Teams |
|
||||
| 8 | Closed: a tombstone, the host stopped |
|
||||
| 16 | Password: the token is sealed |
|
||||
| 32 | Dedicated: a dedicated server (`halo --server` sets it, since network version 39) |
|
||||
|
||||
A listing is 140 bytes at least (all names empty) and 268 at most (a
|
||||
password and every name at its length). A reader refuses one outside those
|
||||
sizes, without `"HL"` and format 1, with a name's length byte past its
|
||||
field's maximum or past the end, or whose stamp and signature do not end it
|
||||
exactly. The names are sanitised as the game's `sanitize` does: a byte
|
||||
outside 0x20 to 0x7E becomes `?`, and a zero ends the name. A master also
|
||||
refuses a listing whose key has a small order.
|
||||
|
||||
The vectors' first listing (an open team game of a dedicated server,
|
||||
sequence 412, 5 of 16 players, CTF on bloodgulch, named `OpenCE Dedicated`)
|
||||
is these 169 bytes, of which the first 105 are signed. The vectors were made
|
||||
at network version 38 and are kept as they are (the bytes and signatures
|
||||
are fixed): their listings carry version 38 with flag 32, which the game
|
||||
sets from version 39 on, so a game of version 39 reads them, checks their
|
||||
signatures and hides them from its browser as another version's games, as
|
||||
it does any. The examples' `network_version` of 38 in this document are the
|
||||
vectors' too.
|
||||
|
||||
| Field | Bytes |
|
||||
| --- | --- |
|
||||
| Magic, format | `484c` `01` |
|
||||
| Network version 38, flags 37 (open, teams, dedicated) | `0026` `25` |
|
||||
| Sequence 412, time 1760900000 | `0000019c` `68f533a0` |
|
||||
| Host key | `fc51cd8e6218a1a38da47ed00230f0580816ed13ba3303ac5deb911548908025` |
|
||||
| Token | `a0a1a2a3a4a5a6a7a8a9aaabacadaeaf` |
|
||||
| Players 5, most 16, engine 1 (CTF) | `05` `10` `01` |
|
||||
| Name, map, gametype | `10` `4f70656e434520446564696361746564`, `0a` `626c6f6f6467756c6368`, `03` `435446` |
|
||||
| Stamp (kind 0) | `0000000000000000` |
|
||||
| Signature | `633dc63eb27828d6e589e34dc4336dbb2d514b2018e4bf4a3adf5aeb774b6a523fe662c3d29241c6f91c8714a8ca2b5e493aacb32bcaeb9bce715f15b76d230f` |
|
||||
|
||||
(`testdata/vectors.json` has it whole, with a password game's, a
|
||||
tombstone's and an altered one that must be refused.)
|
||||
|
||||
## The probe
|
||||
|
||||
Before it lists a server, the master proves that the server's UDP port is
|
||||
reachable from the internet and that the publisher key's holder answers on
|
||||
it. It sends a datagram to the probe address (the published `address`, or
|
||||
the request's source address with `tunnel_port`) from its probe socket:
|
||||
|
||||
| Offset | Size | Probe (35 bytes) |
|
||||
| --- | --- | --- |
|
||||
| 0 | 10 | `"OPCE-PROBE"` |
|
||||
| 10 | 1 | 1 |
|
||||
| 11 | 8 | The master's key id, raw |
|
||||
| 19 | 16 | A nonce |
|
||||
|
||||
The game's tunnel socket, which dispatches what it receives by its first
|
||||
bytes, recognises the magic and answers from the same socket to the
|
||||
address the probe came from:
|
||||
|
||||
| Offset | Size | Answer (103 bytes) |
|
||||
| --- | --- | --- |
|
||||
| 0 | 14 | `"OPCE-PROBE-ACK"` |
|
||||
| 14 | 1 | 1 |
|
||||
| 15 | 8 | The master's key id, as the probe had it |
|
||||
| 23 | 16 | The nonce, as the probe had it |
|
||||
| 39 | 64 | The publisher key's Ed25519 signature of the 29 bytes `"probe"`, the master's key id, the nonce |
|
||||
|
||||
The server answers only a probe of exactly 35 bytes whose key id is that of
|
||||
a master in its `masters.txt`, only to the probe's source, a given nonce at
|
||||
most once per second, at most 2 answers a second to one source address and
|
||||
at most 10 answers a second in all, so the probe cannot be used to reflect
|
||||
traffic (a 103-byte answer to a 35-byte probe is the whole amplification),
|
||||
and probes forged from one address cannot use up the answers a master's
|
||||
probe needs. A probe whose nonce was answered in the same second counts
|
||||
against neither limit.
|
||||
The master takes only an answer from the probed address and port, with its
|
||||
own key id, a nonce it made for that address and key, and a signature that
|
||||
verifies with the key that signed the publish.
|
||||
|
||||
| Rule | Value |
|
||||
| --- | --- |
|
||||
| Attempts | 3, 2 seconds apart; failed 2 seconds after the third |
|
||||
| Again | Every 5 minutes while the server is reachable (it stays listed meanwhile); a failed server at its first publish a minute or more after the failure; at once when its probe address or key changes |
|
||||
| Nonce | Opaque to the server. A master uses a fresh nonce for each probe round (the round's attempts share it), and never the same one for two rounds of one address and key. `opence-master`'s is stateless: the first 16 bytes of HMAC-SHA-256(seed, `"opence-probe-1"` 0x00 address 0x00 key id 0x00 step), the step the decimal Unix time of the round's start divided by 30; it accepts the current and the previous hour's random seed and the current and the previous step, and starts rounds of one address and key at least a step apart |
|
||||
| Duplicates | A server answers a given nonce at most once per second: it remembers the nonces it answered (the last 64) with the Unix second they came in, and ignores a probe whose nonce it answered in the same second, whatever came between (A, B, A in one second: the second A is ignored). A master's retries, 2 seconds apart, are answered again; a nonce resent within the second is not |
|
||||
|
||||
With the vectors' master key (id `39f713d0a644253f`) and the nonce
|
||||
`101112131415161718191a1b1c1d1e1f`, the probe is
|
||||
`4f5043452d50524f42450139f713d0a644253f101112131415161718191a1b1c1d1e1f`, the
|
||||
signed message `70726f626539f713d0a644253f101112131415161718191a1b1c1d1e1f`,
|
||||
and the publisher's answer
|
||||
`4f5043452d50524f42452d41434b0139f713d0a644253f101112131415161718191a1b1c1d1e1f`
|
||||
followed by the signature
|
||||
`a63af355db038dff90e6c82abc0e252eddbd1ed3562580d7becaf3e4edbdd39cef7ef3163b91849ba57f6e83240b92df1efbce15dfa42f4a12981590a0234109`.
|
||||
|
||||
## The list
|
||||
|
||||
`GET /v1/servers`, with the optional query `network_version=<n>`,
|
||||
`dedicated=1` (or `0`), `region=<region>`, `q=<text>` (a case-insensitive
|
||||
substring of the name, map, gametype or variant; 32 characters at most).
|
||||
No signature is needed and plain HTTP is allowed: the body is signed.
|
||||
|
||||
```json
|
||||
{"protocol":1,"master":{"name":"OpenCE Master 1","key_id":"39f713d0a644253f","time":1760900000},
|
||||
"servers":[{"id":"4c5f15237c866f6f","publisher":{"id":"p_kz3c5lb2xvq7mdpa","name":"Milenko's servers","since":"2026-10"},
|
||||
"name":"OpenCE Dedicated","map":"bloodgulch","gametype":"CTF","variant":"CTF","players":5,"max_players":16,
|
||||
"teams":true,"in_progress":false,"password":false,"open":true,"dedicated":true,"kind":0,"engine":1,
|
||||
"network_version":38,"build":"build-206","region":"eu","reachable":true,"updated":1760899990,
|
||||
"listing":"<base64>"}]}
|
||||
```
|
||||
|
||||
| Entry field | Meaning |
|
||||
| --- | --- |
|
||||
| `id` | The server id |
|
||||
| `publisher` | The publisher's id (`p_` and up to 32 of `a-z0-9`), display name, and the year and month it was approved |
|
||||
| `name`, `map`, `gametype`, `players`, `max_players`, `teams`, `in_progress`, `password`, `open`, `kind`, `engine`, `network_version` | From the listing |
|
||||
| `variant`, `build`, `region` | From the publish |
|
||||
| `dedicated` | The listing's flag 32 or the publish's `dedicated` |
|
||||
| `reachable` | The last probe was answered (`false` for a trusted server or under `MASTER_LIST_UNREACHABLE`) |
|
||||
| `updated` | The time of the server's last publish |
|
||||
| `address` | Only with the operator's and the master's consent (above); absent otherwise |
|
||||
| `listing` | Base64 of the listing's exact bytes, as the server published them |
|
||||
|
||||
The list holds at most 512 entries: dedicated servers first, then by
|
||||
players. Its headers:
|
||||
|
||||
| Header | Value |
|
||||
| --- | --- |
|
||||
| `Signature` | `ed25519=` and the base64 of the master key's signature of the body's exact bytes (before any `Content-Encoding`) |
|
||||
| `Signature-Key` | The master's key id, 16 hexadecimal digits |
|
||||
| `Signature-Time` | The body's `master.time` |
|
||||
| `ETag` | `"` and the first 16 hexadecimal digits of SHA-256 of the body, and `"`; `If-None-Match` with it answers `304` |
|
||||
| `Cache-Control` | `public, max-age=5` (the master serves the same body for 5 seconds) |
|
||||
| `Content-Encoding` | `gzip` when the request's `Accept-Encoding` asks for it |
|
||||
| `Access-Control-Allow-Origin` | `*` (and `Access-Control-Expose-Headers` names the four above), for the web build |
|
||||
|
||||
A client:
|
||||
|
||||
1. checks `Signature` over the decompressed body bytes with the key in
|
||||
`masters.txt`, and that `Signature-Key` is that key's id, and refuses
|
||||
the whole body otherwise (a missing `Signature-Key` too; a client that
|
||||
cannot check Ed25519, such as an old browser, refuses every list rather
|
||||
than show one unchecked);
|
||||
2. parses the body, and refuses it unless `protocol` is 1, `master.key_id`
|
||||
is the key's id, and `master.time` is no older than 300 seconds and no
|
||||
more than 300 seconds ahead of the client's clock (a list dated ahead
|
||||
would be taken for longer when it is replayed later, and a clock that
|
||||
far off is wrong). The time is in the signed body: `Signature-Time` only
|
||||
repeats it, since a header is not signed, and a client need not read
|
||||
it;
|
||||
3. type-checks each entry, decodes its `listing`, runs `listing_read` and
|
||||
the host signature's check on it, and skips an entry that fails rather
|
||||
than the list; it shows the name, map, gametype and players of the
|
||||
signed listing (an entry's own fields are the master's word, and may
|
||||
differ); it filters control characters from every name, and takes at
|
||||
most 512 entries (a 512-entry list is some 26,000 JSON tokens: the game
|
||||
reads a list of 65,536 tokens at most);
|
||||
4. merges the masters' lists: entries with the same `id` are one game (the
|
||||
newest `updated` wins), and an entry whose listing key is also heard on
|
||||
the brokers is one game, shown as master-listed;
|
||||
5. never pings listed servers (that would tell every server the player's
|
||||
address): it shows the `region`, and the ping once a game is joined.
|
||||
|
||||
The vectors' signed body is
|
||||
`{"protocol":1,"master":{"name":"OpenCE Master 1","key_id":"39f713d0a644253f","time":1760900000},"servers":[]}`
|
||||
with `Signature: ed25519=18dmQnIfmRnC+wUwRJ/loxAH1VfASRBVnZgCfRuHrAw/2uo4thTibWnNQFScgRju+5lQtt709blK86BLT0fYCw==`
|
||||
and `ETag: "cd755a50c5cfc457"`.
|
||||
|
||||
`GET /v1/servers/{server_id}` answers one listed server the same way:
|
||||
`{"protocol":1,"master":{…},"server":{<entry>}}` with the same headers, or
|
||||
`404 not_found`.
|
||||
|
||||
## Other endpoints
|
||||
|
||||
| Request | Who | Answer |
|
||||
| --- | --- | --- |
|
||||
| `GET /v1/publishers/{id}` | anyone (the list's limit) | `{"ok":true,"id","name","since":"2026-10","status","servers":<listed now>}`, or `404` |
|
||||
| `POST /v1/applications`, `/v1/applications/…` | anyone | `410 applications_by_discord`: applications are made with the master's Discord bot (below), not over HTTP |
|
||||
| `POST /v1/keys` | signed, an approved publisher's active key | Body `{"public_key":"ed25519:…"}`: adds a key (8 active at most). `201 {"ok":true,"key_id","status":"active"}`; `409 key_exists`; `403 too_many_keys` |
|
||||
| `GET /v1/me` | signed, any key the master knows | The publisher's record: `{"ok":true,"key_id","status","publisher":{"id","name","since","status","quota","origin","keys":[{"key_id","public_key","status","updated","last_used"}],"servers":[{"id","instance","key_id","listed","probe","reachable","hidden","trusted","updated","name","players","max_players"}]}}`; for a key still in an application, `"publisher":null` and `"application":{"id","status","reason","created"}`; `403 key_revoked` |
|
||||
| `GET /v1/master` | anyone | The master's name, key id, public key, contact, data policy and limits (informational: clients use the key in `masters.txt`) |
|
||||
| `GET /healthz` | anyone | `200 {"ok":true,…}` while the database answers |
|
||||
| `GET /metrics` | anyone (the list's limit) | Prometheus text, read at most once each 5 seconds: `master_servers{reachable}`, `master_publishers{status}`, `master_publishes_total{result}`, `master_probes_total{result}`, `master_list_requests_total`, `master_peer_requests_total`, `master_build_info{version,protocol}` |
|
||||
| `GET /`, `GET /apply`, `/admin/*` | people | The list page (the list's limit), how to apply (the Discord bot, and an invite to its server), the admin pages |
|
||||
|
||||
## Applications
|
||||
|
||||
An operator applies with the master's Discord bot, in the master's
|
||||
Discord server (the `/apply` page links to it): the bot's `/apply` command
|
||||
takes the region (a menu of the master's choices) and the number of servers
|
||||
at once as its options, and answers the applicant alone with a nonce for
|
||||
the proof of key,
|
||||
`opence-apply-<unix>-<16 hex>`, good for 24 hours and bound to that Discord
|
||||
user (a nonce given to another user, or to none, does not prove this one's
|
||||
key), and a button that opens the application's form: a display name, the
|
||||
public key, the proof, and a note. The application's name is 3 to 32 printable ASCII characters,
|
||||
`servers` is 1 to 64, and the region up to 16 of `a-z`, `0-9` and `-`. The
|
||||
proof of key is required unless the master's policy says otherwise
|
||||
(`MASTER_REQUIRE_PROOF`, true by default): it is the publisher key's
|
||||
Ed25519 signature of the nonce's ASCII text, in hexadecimal (128 digits,
|
||||
what `halo --server --sign <nonce>` prints) or base64. An application
|
||||
without one is shown to the approvers as unproven. A key already a
|
||||
publisher's is refused, and so is a key with an application pending. The
|
||||
applicant is answered on Discord, and told of the decision by a direct
|
||||
message; the applicant's identity is their Discord user id and username.
|
||||
|
||||
Each application is posted to the master's log channel with Approve and
|
||||
Deny buttons, which only the members of the master's approver roles may
|
||||
press; the admin pages decide too. Once decided, anywhere, the message
|
||||
shows the outcome and who decided. The master's operator can also add an
|
||||
application on its command line (`opence-master challenge` for the nonce,
|
||||
then `add-application`), as the conformance test does.
|
||||
|
||||
A master limits applications, since each one is posted to its approvers:
|
||||
`opence-master` takes one pending application at a time and 3 a day per
|
||||
Discord user, 3 a day per key, and, of applications without a proof of key,
|
||||
100 an hour in all; one with a proof is not refused for the hour's number,
|
||||
but past 100 applications in an hour the approvers are alerted once and the
|
||||
next ones are not posted one by one (its settings change these numbers). It
|
||||
deletes a denied application 30 days after its denial.
|
||||
|
||||
The earlier HTTP application (`POST /v1/applications` with an e-mail
|
||||
address verified by a mailed link, `GET /v1/applications/challenge`, and
|
||||
the application's status by its mailed token) is gone: its endpoints
|
||||
answer `410 applications_by_discord`. A master keeps the applications made
|
||||
that way readable to its admins.
|
||||
|
||||
## Approval sharing between masters
|
||||
|
||||
The official masters share approvals, so an operator applies once. Each
|
||||
master fetches each peer's `GET /v1/publishers?since=<unix>` (every minute
|
||||
in `opence-master`), signed with its own master key in the request scheme
|
||||
above (`keyid` is its master key id, and the signed string's master key id
|
||||
is the peer's, the one it fetches from; a master answers only the peers it
|
||||
is configured with, else `403 not_a_peer`). The answer is signed as the list
|
||||
is (`Signature`, `Signature-Key`, `Signature-Time`, the body's
|
||||
`master.time`):
|
||||
|
||||
```json
|
||||
{"protocol":1,"master":{"name","key_id","time"},
|
||||
"publishers":[{"id","name","status","since","updated","origin","quota",
|
||||
"keys":[{"key_id","public_key","status","updated"}]}]}
|
||||
```
|
||||
|
||||
A master shares only what it holds a word of its own on: the publishers it
|
||||
approved or moderated (`status` is its own word: `approved`, `suspended` or
|
||||
`revoked`; `null` when it only vouches for keys), and the keys it added or
|
||||
revoked (`active` or `revoked`). `origin` is the key id of the master that
|
||||
approved the publisher, as the sharing master knows it (a master records a
|
||||
publisher new to it as come from the peer it fetched the record from,
|
||||
whatever origin the record claims, and only that peer's records rename
|
||||
it); `since` its approval time; `updated` the time of
|
||||
the newest word in the record; `since=` returns the records updated after
|
||||
it. The next fetch's `since` is the answer's `master.time` less 120 seconds,
|
||||
on the peer's own clock.
|
||||
|
||||
The importing master keeps each master's word apart and takes the most
|
||||
restrictive of the trusted masters' words as the publisher's status
|
||||
(`revoked` over `suspended` over `approved`) and the smallest quota given;
|
||||
a newer word from a master replaces that master's older one. So a
|
||||
suspension or revocation anywhere wins everywhere, and only the master that
|
||||
suspended a publisher can lift its suspension. A key revoked by any trusted
|
||||
master is revoked, for good; a key two publishers claim is refused. A
|
||||
master may refuse a peer's words (`MASTER_PEERS_TRUST`); they then count
|
||||
for nothing.
|
||||
|
||||
## Errors
|
||||
|
||||
Every error is `{"ok":false,"error":{"code":"…","message":"…","field":"…"?},"master_time":<unix>}`.
|
||||
The message is for people and may change; programs read the code.
|
||||
|
||||
| Status | Code | Meaning | A server's publisher should |
|
||||
| --- | --- | --- | --- |
|
||||
| 400 | `schema` | A field is missing, of the wrong type or out of range (`field` names it), or the body is not one JSON object | Log it once; it is a bug |
|
||||
| 400 | `server_id` | The path's id is not the key's and the instance's | Log it once |
|
||||
| 400 | `listing` | The listing does not parse, its signature fails, its key has a small order, or its time is an hour off | Log it once |
|
||||
| 401 | `bad_signature` | The Authorization header is malformed or its signature fails | Log it once |
|
||||
| 401 | `clock` | `ts` is more than 300 seconds from `master_time` | Log the difference (from the answer's `master_time`): the machine's clock is wrong |
|
||||
| 401 | `replay` | The nonce was used in the last 600 seconds | Send a new nonce |
|
||||
| 403 | `unknown_key` | No publisher or application has the key | Log `master: apply with key <id>` once a minute |
|
||||
| 403 | `publisher_pending` | The key's application waits for review | Log `master: publisher pending` once a minute; keep publishing every 30 s |
|
||||
| 403 | `application_denied` | The key's application was denied (`message` says why) | Log it once a minute |
|
||||
| 403 | `publisher_suspended` | The publisher is suspended | Log it; keep publishing slowly |
|
||||
| 403 | `publisher_revoked`, `key_revoked` | Revoked for good | Log it; stop publishing to that master |
|
||||
| 403 | `quota_exceeded` | The publisher has its quota of servers live | Log it |
|
||||
| 403 | `instance_taken` | Another key of the publisher has a live server of this instance | Log it; the old server expires after `ttl` |
|
||||
| 403 | `listing_taken` | The listing's host key is that of another publisher's live server, which has renewed it within 90 seconds | Log it once a minute; it is someone else's listing, or the host key is shared; keep publishing |
|
||||
| 403 | `too_many_instances` | The publisher holds its quota and 16 server records, none of which can be dropped | Log it; use fewer instance names |
|
||||
| 403 | `tls_required` | Plain HTTP from beyond loopback | Use the `https://` URL |
|
||||
| 403 | `not_a_peer` | A peer's request from a master not configured as a peer | |
|
||||
| 404 | `not_found` | No such server, publisher or endpoint | |
|
||||
| 409 | `key_exists` | The key added (`POST /v1/keys`) is known already | |
|
||||
| 410 | `applications_by_discord` | An application sent over HTTP: applications are made with the master's Discord bot | Log it: apply with the bot's `/apply` |
|
||||
| 413 | `too_large` | The body is over 16 KB | |
|
||||
| 429 | `rate_limited` | Too many requests; `Retry-After` gives the seconds to wait | Wait that long (the header's name read in any case; the game waits a day at most, and 30 seconds without one) |
|
||||
| 500 | `internal` | The master failed | Try again at the next interval |
|
||||
|
||||
## Privacy and limits
|
||||
|
||||
| What | Rule |
|
||||
| --- | --- |
|
||||
| Servers' addresses | Kept 7 days after the server's last publish, for probes and abuse handling; never served unless the operator and the master both chose to; not in the master's log unless its operator asks (`MASTER_LOG_ADDRESSES`) |
|
||||
| Applicants | Their Discord user id and username, seen by the master's admins and approvers (the log channel) only; no address is kept |
|
||||
| Applications | A denied one: deleted 30 days after the denial |
|
||||
| Servers' records | A closed server's: deleted an hour after it closed; one not published again: after 24 hours (unless an admin flagged it) |
|
||||
| Contacts | Discord names (and the earlier HTTP applications' e-mail addresses) are seen by the master's admins and approvers only, and are not shared with peers |
|
||||
| Strings | Printable ASCII, cut to the listing's lengths: name 32, map 32, gametype and variant 24, build 32 |
|
||||
| Requests | 60 list requests a minute per address (the list, one server, a publisher's page, the list page and the metrics together); the application limits above; bodies 16 KB at most; the publish limits above. Every limit by address counts an IPv6 address by its /64 |
|
||||
|
||||
## Known limitations
|
||||
|
||||
A listing's host key is bound to the first publisher whose live server
|
||||
publishes it, not to the host's own publisher: the listing does not say
|
||||
which publisher key the host chose. A publisher that copies a listing from a
|
||||
list while the host's publisher is not publishing (more than `ttl`) holds
|
||||
the host key, and the host's publisher is refused `listing_taken`, until the
|
||||
copy goes 90 seconds without a newer listing; one that keeps copying the
|
||||
host's newest listings from other lists keeps it until an admin hides its
|
||||
server or suspends it. The planned fix is in the listing: the host signs the
|
||||
key id of the publisher key it publishes with into the listing (a new
|
||||
listing format, with a new network version), and a master takes a listing
|
||||
only from that key.
|
||||
|
||||
## Versions
|
||||
|
||||
This is protocol 1: `protocol` in bodies, `/v1/` in paths and
|
||||
`OpenCE-Master-v1` in signed strings (followed by the receiving master's
|
||||
key id). A change that an older client or
|
||||
server would misread is a new version, with new paths; fields may be added
|
||||
to version 1, and both sides ignore what they do not know. The listing's
|
||||
own format follows the game's network version: a client hides entries
|
||||
whose `network_version` is not its own, as it does for the brokers'
|
||||
listings.
|
||||
|
||||
## Testing an implementation
|
||||
|
||||
`testdata/vectors.json` in the master's repository has, from fixed seeds:
|
||||
three key pairs with their key ids (the publisher's, the master's, a
|
||||
host's), a server id, a signed publish and a signed `GET /v1/me` to the
|
||||
vectors' master (its key id, the canonical strings, the signatures, the
|
||||
headers), a probe and its answer,
|
||||
four listings (a dedicated team game, a password game in progress with its
|
||||
sealed token, a tombstone, and an altered listing that must be refused), a
|
||||
signed list body with its headers and ETag, a small-order key that must be
|
||||
refused, and a proof of key. Monocypher's `crypto_ed25519_sign`,
|
||||
`crypto_ed25519_check` and `crypto_aead_lock` give the same bytes.
|
||||
`tests/conformance/opence_publisher.py` is a reference publisher in Python
|
||||
(keys, signatures, listings, publishing, the probe's answer), and
|
||||
`tests/conformance/test_master_protocol.py` runs a master through the whole
|
||||
flow: an application (on the master's command line, since the Discord bot
|
||||
is beyond a test's reach), the HTTP application's `410`, a pending
|
||||
publish, approval, the probe, the listed
|
||||
server's exact bytes in a signed list, closing, every refusal, and two
|
||||
masters sharing an approval, a suspension and a revocation.
|
||||
@@ -0,0 +1,178 @@
|
||||
# Exact-matching methodology
|
||||
|
||||
This document records recurring January 2002/XDK 3911 matching failures and
|
||||
the source-level changes that have actually moved them. It is an operational
|
||||
checklist, not permission to accept approximate code. Exact status still
|
||||
requires padded bytes, normalized bytes, relocation count/type/address/target/
|
||||
addend, ABI, build, and regression evidence.
|
||||
|
||||
## Triage decision tree
|
||||
|
||||
Before guessing literals or reconstructing diagnostics, consult the
|
||||
[common constants reference](common_constants.md) and
|
||||
[shared assertion API](assertions.md). They identify existing owners and
|
||||
target-specific representation pitfalls; they do not authorize numeric or
|
||||
source-shape substitutions just because a value looks familiar.
|
||||
|
||||
1. Establish the untouched baseline: padded size, meaningful size, normalized
|
||||
hash, relocation table, first differing instruction, and sibling status.
|
||||
2. If relocation targets or addresses differ, recover source structure before
|
||||
tuning registers: statement order, branch fall-through, linkage, field
|
||||
ownership, and eager versus lazy evaluation.
|
||||
3. If the target uses 16-bit arithmetic, map every promotion and truncation
|
||||
boundary. Treat this separately from register allocation.
|
||||
4. If instruction structure is identical modulo registers, locate a
|
||||
hardware-forced anchor before changing declarations:
|
||||
- `rep movs`/`rep stos` force ESI, EDI, and ECX;
|
||||
- variable shifts force CL/ECX;
|
||||
- multiply and divide force EAX/EDX;
|
||||
- ABI/API boundaries may force ECX/EDX or preserve callee-saved registers.
|
||||
5. For private same-translation-unit helpers, make callers exact first. Start
|
||||
from the hardware-forced caller and propagate the convention toward the
|
||||
helper; do not tune the helper in isolation.
|
||||
6. Stop after five evidence-based source shapes if only an interchangeable
|
||||
register or dependency-free instruction ordering remains. Record and park
|
||||
the case instead of perturbing unrelated exact code.
|
||||
7. Run the strict semantic ledger before assigning work. A function already
|
||||
listed in `build/semantic_report.json` must not be reimplemented merely
|
||||
because objdiff displays a fuzzy percentage.
|
||||
8. When a target macro or expression is known from an exact donor, preserve
|
||||
its **lvalue topology** as well as its arithmetic. VC7 can emit different
|
||||
code for mathematically equivalent forms such as transforming a temporary
|
||||
and transforming the destination member in place. Prefer the donor's
|
||||
assignment destination, member access, and read-back pattern before
|
||||
permuting commutative terms or adding artificial temporaries.
|
||||
|
||||
## Source-credibility gate
|
||||
|
||||
An exact object is necessary evidence, but exact bytes alone do not make a
|
||||
reconstruction admissible. Retained source must express coherent program logic
|
||||
and remain plausible for the original January 2002 codebase. Reject inert,
|
||||
contradictory, undefined, or artificial source whose only credible purpose is
|
||||
to steer VC7 into the target byte sequence. This includes unexplained empty
|
||||
branches, self-assignments, fixed conditions, volatile or aliasing tricks,
|
||||
synthetic lifetime anchors, raw instruction emission, and compiler-control
|
||||
directives. A target-proven original bug is the narrow exception and must meet
|
||||
the original-bug policy below.
|
||||
|
||||
Review semantics across all reachable inputs, not only the path that resembles
|
||||
the disassembly. Corroborate unusual topology with January code/data/relocation
|
||||
evidence, authenticated names or type records, first-party source, or a
|
||||
credible contemporary analogue such as Marathon. When ordinary, meaningful C
|
||||
does not reach exactness after the bounded methodology, retain the best honest
|
||||
fuzzy reconstruction, record the residual, and park it.
|
||||
|
||||
`python tools/fake_match_scan.py` provides conservative lexical review leads
|
||||
for several common smells. Its findings are neither proof of fake source nor a
|
||||
substitute for manual semantic and provenance review, and a clean scan is not
|
||||
proof of credibility.
|
||||
|
||||
## Blocker classes
|
||||
|
||||
### A. Recoverable source-shape mismatch
|
||||
|
||||
The emitted differences indicate that the reconstructed C is not yet shaped
|
||||
like the original source. Productive levers include statement order, branch
|
||||
polarity, local lifetime, explicit versus inlined expressions, linkage, and
|
||||
structure ownership.
|
||||
|
||||
### B. Integer promotion/truncation mismatch
|
||||
|
||||
The target contains operand-size prefixes, partial-register operations, or
|
||||
`movsx`/`movzx` boundaries that ordinary C promotions erase. Recover the width
|
||||
of the accumulator and place signed/unsigned casts only at disassembly-proven
|
||||
boundaries. Do not file this as a register mirror.
|
||||
|
||||
### C. Private-ABI/register fixed point
|
||||
|
||||
The instruction graph, sizes, and relocations agree, but a translation-unit
|
||||
cluster assigns interchangeable registers differently. Find a forced-register
|
||||
caller and solve outward. If the complete cluster remains a pure permutation
|
||||
after the checklist, park it as a compiler allocation tie.
|
||||
|
||||
### D. Scheduler/lifetime tie
|
||||
|
||||
Two dependency-free instructions are transposed, or local lifetimes alter
|
||||
spills without changing semantics. Try only source changes justified by the
|
||||
surrounding target ordering. Do not add undefined behavior, inline assembly,
|
||||
compiler pragmas, or flag changes to force the result.
|
||||
|
||||
### E. Comparator/reporting mismatch
|
||||
|
||||
The machine code is exact but COFF producers encode internal labels or
|
||||
relocation placeholders differently. Credit only through the hardened
|
||||
semantic comparator and the reviewed `config/semantic_matches.json` allowlist;
|
||||
each entry is reverified against current objects during `ninja progress`.
|
||||
|
||||
### F. Credible but unclassified residual
|
||||
|
||||
The retained source can be semantically and historically grounded even when
|
||||
the fail-closed classifier cannot distinguish a remaining source-width,
|
||||
optimizer-context, register, or scheduling cause. Park such a case as
|
||||
`unclassified` instead of inventing a specific mechanism. An unclassified
|
||||
park carries no code-generation recipe and grants no exact credit; its ledger
|
||||
must state the positive source evidence, the unresolved machine differences,
|
||||
and the evidence required to reopen it.
|
||||
|
||||
## Case catalog
|
||||
|
||||
| Case | Class | Evidence and source lever | Outcome / next action |
|
||||
|---|---|---|---|
|
||||
| `lra_new` (`f0e5a48`) | A | Reordering field initialization to the target's emitted store order aligned the failure block and lifecycle setup. | Exact; make store-order recovery a standard first pass. |
|
||||
| `object_new` (`claude/object-new-16`, then the isolated XDK scheduler-control lane) | A then D | Writing the cleanup as failure-first eliminated 10 relocation differences and two divergence regions. Only `fmuls` versus deferred `add esp, 0x18` ordering remained. A production-context reproducer then tested 20 one-factor legal-C controls; all forms that moved `fmuls` first also changed x87 dataflow or other bytes. | Preserve failure-first shape; park the dependency-free scheduler tie unless new source provenance identifies a distinct original expression. |
|
||||
| `hashtable_remove` (`f2d30b9`) | A | Source-oriented comparison order, reload points, and the shared deletion path aligned 496 padded bytes and 20 relocations. | Exact; use comparison polarity and reload timing before register tuning. |
|
||||
| `csstrcasecmp` (`e5852f8`, `claude/csstrcasecmp-15`) | A then C | `if (c1 != c2)` reproduces the target operand order; `if (c2 != c1)` does not. The remainder is an ESI/EDI parameter/local permutation. | Land only evidence-backed logic changes; handle the remaining mirror through a forced-register caller or park. |
|
||||
| terminal tab stops (`a917110`) | A | Identical six-byte data still failed because `static` produced storage class 3 while the target symbol was external, class 2. | Exact after external linkage/name recovery; audit symbol class, not just bytes. |
|
||||
| `generate_private_key` (`public_key_crypt.obj`) | A | Applying the exact `SWAP4` donor arithmetic to a local temporary selected the wrong accumulator form across hundreds of equivalent expression trees. Assigning the helper result to `private_key->dwords[i]` and applying `SWAP4` directly to that same member preserved frontend lvalue provenance and reproduced January exactly. | Exact without assembly, volatility, undefined behavior, or flag changes; preserve donor lvalue topology before classifying a commutative residual as a register tie. |
|
||||
| `objects.obj` BSS ownership | A/E | Explicit zero initialization plus declaration order recovered the linked 13-byte layout (`object_name_list@0`, `object_memory_pool@4`, `object_globals@8`, debug byte `@12`) without changing any exact function. January PDB/public-symbol and cross-TU-reference evidence proves the first three globals are source-private; csplit had defaulted their manually split labels to external because `symbols.json` omitted `"static": true`. | Keep the globals source-static and mark exactly those three csplit symbols static. Regenerate the split target and require exact size, offsets, storage classes, and whole-TU regression; do not paper over the difference with a semantic allowlist. |
|
||||
| `tif_packbits.obj` (`7c9c092`) | A | Target linkage, RCSID ownership, `_csmemcpy`, and disassembly-proven TIFF field offsets were required. Repository header layout differed from the target object. | Five functions and data exact; raw offsets are acceptable only with explicit target-layout evidence. |
|
||||
| random-math globals (`aef5a7c`) | A | Replacing an anonymous address placeholder with the real externally linked 20-byte globals structure fixed BSS ownership and relocation addends. | Exact functions retained; model globals explicitly before function tuning. |
|
||||
| `default_hash_function` (`f2d30b9`) | B | Target uses 16-bit product/partial-register code while natural C promotes the polynomial and key byte to 32 bits (80 target versus 64 candidate bytes). | Reopen only with a promotion/truncation lattice derived instruction by instruction. |
|
||||
| LRA verify/free/lock cluster (`f0e5a48`) | C | Seven functions share cache-in-EBX versus cache-in-EDI and private helper conventions. Isolated helper shaping did not move the joint allocation. | Anchor on callers with forced registers, then propagate; otherwise park the whole permutation together. |
|
||||
| hashtable probe helper `code_0010b270` (`073e794`) | C | Size, relocations, control flow, and operations agree; two return blocks mirror ECX and EDX. | Try return-materialization/single-exit shape once under the checklist, then park if unchanged. |
|
||||
| `reference_list_copy` lane | C | Target and candidate reduce to the same operations with a callee-saved register mirror after source-shape attempts. | Revisit only from its caller cluster and a hardware-forced anchor. |
|
||||
| `object_get_marker_by_name` lane | A | Recovering the direct object-header block access removed the artificial wrapper lifetime and reproduced the original call/dataflow structure. | Exact: 272 padded bytes, 11 relocations, and normalized SHA-256 `302db0f36677f304c6d076e0f16f3bb4e9603519b34d650a4311c296bd21c8cf`. |
|
||||
| `object_compute_node_matrices` (`claude/object-compute-node-matrices` plus the E2 closeout) | D | The corrected C now has the exact 6,560-byte padded size, `0xA44` frame, and 318 relocation identities. The first address drift is relocation 245: January homes `tag_get_name`'s EAX result to `[ebp-8]`, while VC7 keeps EAX live. Independent source, PDB, tail-diff, and legal-C shape audits found no controllable semantic or structural difference. | Park as an EAX-liveness/register-allocation tie. Reopen only if new local-variable provenance or a demonstrated legal-C compiler control appears. |
|
||||
| `data_decode_array` (`d0a735d`) | E | Padded bytes and 31 semantic relocations are exact; objdiff reports 85.19% because one target symbol plus addends corresponds to several rebuilt local labels. | Credited through the dynamic semantic ledger; no source work required. |
|
||||
| 37-function switch/local-label set (`24c998a`) | E | Full dual sweep found 37 real functions and 21,051 meaningful bytes exact under conservative COFF normalization but fuzzy under objdiff. | The allowlist is reverified on every progress run; uncertain or changed entries fail closed. |
|
||||
|
||||
## Complexity gate
|
||||
|
||||
For large aggregate objects such as `objects.obj`, queue a remaining function
|
||||
only when all of the following hold:
|
||||
|
||||
- padded size is below approximately `0x60`;
|
||||
- local state is small and unambiguous;
|
||||
- relocation count is low;
|
||||
- no large inlined helper or private-ABI cluster dominates the function.
|
||||
|
||||
Larger functions require a specific leverage reason (new structure proof,
|
||||
forced-register anchor, or reusable subsystem insight) before consuming an
|
||||
implementation lane.
|
||||
|
||||
## External type-information gate
|
||||
|
||||
For the supplied `h1_tags` executables, start with the
|
||||
[cross-build intake and missing-PDB identities](crossbuild_h1_tags_intake_20260906.md).
|
||||
The `_symbols.exe` images contain external PDB references, not complete
|
||||
embedded debug records. That ledger also records the IDA/Ghidra requirement
|
||||
and separates analysis-generated names from original-symbol evidence.
|
||||
|
||||
HCEX, Halo PC, October 2001, and community sources are hypothesis generators.
|
||||
Every imported field or enum value must carry a January-Xbox disassembly proof.
|
||||
Unproven spans remain named `reserved`/`unknown` and documented as such. No CEA
|
||||
offset enters a trusted header merely because it compiles or looks plausible.
|
||||
|
||||
## Original-bug policy
|
||||
|
||||
Exact builds preserve confirmed original behavior. Mark only defects supported
|
||||
by binary and layout evidence:
|
||||
|
||||
```c
|
||||
/* BUG (preserved for exact matching): <target behavior and evidence>.
|
||||
* A corrected build should <safe replacement>.
|
||||
*/
|
||||
```
|
||||
|
||||
Keep the safe fix disabled in the exact build. Do not label suspicious code as
|
||||
a bug without target-machine and structure-layout proof.
|
||||
-329
@@ -1,329 +0,0 @@
|
||||
# Mods
|
||||
|
||||
A mod is a folder of Halo PC tag files that the game plays over a map's own
|
||||
tags on your machine, as a resource pack does: sounds (a high-res audio
|
||||
pack), bitmaps (a texture pack, a HUD redraw), text (a translation) and
|
||||
models (higher-detail weapons, vehicles and scenery). Only the machine that
|
||||
has a mod plays it. Nothing of a mod is sent to another machine, and a mod
|
||||
changes nothing that the machines of a network game must agree on, so you
|
||||
can play with mods in any game, with players who have other mods or none. (A host's mod sounds of other lengths change how long
|
||||
the host's scripts and AI wait for dialogue to end; the host decides those
|
||||
for every machine, so they still agree.)
|
||||
|
||||
The game's code is `port/linux/game/mods.c` (with `mod_sounds.c`,
|
||||
`mod_bitmaps.c`, `mod_strings.c` and `mod_models.c`, one for each kind of
|
||||
tag) and `port/linux/src/port_mods.c` (the mods folder and its files).
|
||||
|
||||
## A mod's folder
|
||||
|
||||
The mods are in the `mods` folder of the data root (the folder with
|
||||
`maps/`; on Android the app's data folder, on the web the browser's storage
|
||||
for the site). Each mod is a folder in it, with a `mod.toml` and a `tags`
|
||||
folder:
|
||||
|
||||
```
|
||||
mods/
|
||||
hd_audio/
|
||||
mod.toml
|
||||
tags/
|
||||
sound/sfx/weapons/assault rifle/fire.sound
|
||||
sound/dialog/...
|
||||
german/
|
||||
mod.toml
|
||||
tags/
|
||||
ui/hud/hud_item_messages.unicode_string_list
|
||||
```
|
||||
|
||||
The files in `tags` have the paths of the tags they replace: a tag's name,
|
||||
then its group's extension, as the Halo Editing Kit and Invader keep them.
|
||||
`tags/sound/sfx/weapons/assault rifle/fire.sound` replaces the sound tag
|
||||
`sound\sfx\weapons\assault rifle\fire` of every map that has one. Names are
|
||||
not case-sensitive. The game only looks up the names of the map's tags among
|
||||
a mod's files: a mod cannot add tags, and no tag name of a map makes a path
|
||||
outside the mod.
|
||||
|
||||
`mod.toml` says what the mod is. Every key is optional:
|
||||
|
||||
```toml
|
||||
name = "High-res audio" # what the Mods menu shows (else the folder's name)
|
||||
id = "hd_audio" # what other mods name it by (else the folder's name)
|
||||
version = "1.0"
|
||||
authors = ["Someone", "Someone else"] # or one string
|
||||
description = "The game's sounds at 44 kHz"
|
||||
maps = ["a10", "bloodgulch"] # the maps it is for, by their files' names (else every map)
|
||||
load_after = ["hd_textures"] # mods it plays over: they load before it
|
||||
load_before = ["fixes"] # mods that play over it: they load after it
|
||||
incompatible = ["other_audio"] # mods it cannot be played with
|
||||
format = 1 # the mods' format it is made for
|
||||
```
|
||||
|
||||
`load_after`, `load_before` and `incompatible` name other mods by their `id`
|
||||
or their folder's name, not case-sensitive. A mod they name that is not in
|
||||
the mods folder is passed over. `maps = []` is every map.
|
||||
|
||||
A folder without `mod.toml` is not a mod. A mod made for a later `format`
|
||||
than the build's, or whose `maps` names no map, is not played. The game
|
||||
logs anything else wrong in `mod.toml` (an unknown key, a value of the
|
||||
wrong type) and uses the rest; a `mod.toml` that is not TOML at all is
|
||||
logged, and the mod played without what it says.
|
||||
|
||||
The game's log is its output: the terminal on Linux, `halo.log` beside
|
||||
`halo.exe` on Windows, logcat on Android, and the page's log on the web.
|
||||
|
||||
Limits: 256 mods, folder names of 63 bytes at most, 262144 files in all, 24
|
||||
folders deep under `tags`, and 64 maps in a mod's `maps`.
|
||||
|
||||
## The load order
|
||||
|
||||
Every mod in the mods folder is on until you turn it off. The mods load in
|
||||
an order, and where two mods have a file for the same tag, the one loaded
|
||||
later plays.
|
||||
|
||||
- The default order is the folders' names in alphabetical order (not
|
||||
case-sensitive), except that the mods a mod must load after (those it
|
||||
asks to load after, and those that ask to load before it) are taken to
|
||||
just before it. Mods that ask in a ring (a after b, b after a) load
|
||||
alphabetically, and the game's log says so.
|
||||
- The main menu's **Mods** (in the PC version's menus, `display.menus =
|
||||
"pc"`, the default) is laid out as the game lobby is: the mods on the
|
||||
left as a resource pack list has them, the one at the top playing over
|
||||
all those below it (the load order upside down: the mod loaded last is at
|
||||
the top), and the chosen mod's details in the frame on the right (its
|
||||
name, what is wrong with it, whether it is on, its priority, 1 the top,
|
||||
and its version, authors, folder, maps and description). Choosing a mod
|
||||
(A, or a click on the chosen one: the first click chooses it) turns it on
|
||||
or off (ON, OFF); left and right, or **Move up** and **Move down**, move
|
||||
the chosen mod (up: over one more mod). **OK** keeps the order and plays
|
||||
it at once (on a map that is loaded, too); **Cancel** leaves it as it was.
|
||||
- A warning sign beside a mod means it is on the wrong side of a mod it
|
||||
asks to load before or after (both on): a mod that loads after another is
|
||||
above it in the menu. A red cross means a mod that is on says it cannot be
|
||||
played with this one, or that it cannot be played at all (made for a later
|
||||
build, or its `maps` names none): it stays off. The details say which.
|
||||
|
||||
The menu keeps the order, and the mods turned off, in `mods/load_order.toml`,
|
||||
by the mods' folders' names:
|
||||
|
||||
```toml
|
||||
order = ["german", "hd_audio", "hd_textures"]
|
||||
disabled = ["hd_textures"]
|
||||
```
|
||||
|
||||
A mod added to the folder later is put where the default order puts it,
|
||||
after the mod before it there (but on the side it asks for of the mods it
|
||||
names), and is on. A mod gone from the folder is left out. When the file
|
||||
cannot be written, the game says so in its log and keeps the order until it
|
||||
quits.
|
||||
|
||||
### Mods that cannot be played together
|
||||
|
||||
When a mod that is on names another that is on as `incompatible`, the game
|
||||
asks as it starts, before the window opens:
|
||||
|
||||
- **Play anyway** plays them all (closing the box does too);
|
||||
- **Turn off ...** turns off the mods named as incompatible (if mod A says
|
||||
it cannot be played with mod B, B is turned off), and keeps that in
|
||||
`load_order.toml`;
|
||||
- **Quit** closes the game.
|
||||
|
||||
The Mods menu turns them on again. On the web, **Quit** starts the page
|
||||
again. A run nobody watches (`debug.hidden_window`, `debug.null_renderer`,
|
||||
`debug.exit_after` or `debug.network_test`) is not asked: it plays them all,
|
||||
and the game's log says which conflict.
|
||||
|
||||
At the console:
|
||||
|
||||
| Command | What it does |
|
||||
| --- | --- |
|
||||
| `mods_list` | Lists the mods in the mods folder in their load order, and which are on, then how many of the map's string lists, bitmaps, sounds and models the mods play. |
|
||||
| `mods_reload` | Finds the mods again and reads their files again: a changed file is read again (one that now fails a check leaves what was played before), a new one is played, and the map's tag comes back for a file that is gone. If a sound changed, all sounds stop. It does nothing while `mods_enable false`. |
|
||||
| `mods_enable false` | Plays the map's own tags until `mods_enable true` or the next map. |
|
||||
|
||||
These commands work in any game, a client's too: they change nothing of the
|
||||
game.
|
||||
|
||||
### Getting a mod onto each platform
|
||||
|
||||
- **Linux, Windows**: put the mod's folder in `mods/` next to `maps/`.
|
||||
- **Android**: put it in `mods/` in the app's data folder,
|
||||
`/sdcard/Android/data/com.halo.decomp/files/mods`, for example with
|
||||
`adb push hd_audio /sdcard/Android/data/com.halo.decomp/files/mods/`.
|
||||
- **Web**: on the page, **Mods**, **Add a mod folder…** copies a mod's
|
||||
`mod.toml` and `tags` folder into the browser's storage for the site.
|
||||
**Remove** deletes it again.
|
||||
|
||||
## What a mod can replace
|
||||
|
||||
The game plays these groups from a mod. It does not read the files of any
|
||||
other group (a `.weapon`, `.vehicle`, `.model_collision_geometry` or
|
||||
`.scenario`, for example): they would change what the machines of a network
|
||||
game must agree on.
|
||||
|
||||
| Group | Extension | What it is |
|
||||
| --- | --- | --- |
|
||||
| Sound | `.sound` | Sounds, music and dialogue |
|
||||
| Bitmap | `.bitmap` | Textures, sprites, the HUD's pictures |
|
||||
| Unicode string list | `.unicode_string_list` | The text the game shows |
|
||||
| String list | `.string_list` | Other text |
|
||||
| Model | `.gbxmodel` (Halo PC's), `.model` (the Xbox's) | What objects look like: weapons, first-person weapons and arms, vehicles, scenery, characters |
|
||||
|
||||
A file must be a Halo PC tag file of its group, as the Halo Editing Kit's
|
||||
tools and Invader write them (a model also as `invader-extract` writes an
|
||||
Xbox map's: `.model`). The game checks every count, size and offset
|
||||
in it against the file, and every value against what the game reads, before
|
||||
it uses the file. A file that fails a check is left out (the map's tag
|
||||
plays), and `debug.txt` and the console say why.
|
||||
|
||||
### Sounds
|
||||
|
||||
- The samples can be 16-bit PCM, Xbox ADPCM or Ogg Vorbis, mono or stereo,
|
||||
at 22 or 44 kHz. The game converts them to the Xbox ADPCM that it plays,
|
||||
as it does for Custom Edition maps: mono at 22 kHz, stereo at its own rate.
|
||||
- Empty values are filled in as a map's build fills them in: the defaults
|
||||
of the sound's class, the playback rates and the bend.
|
||||
- A sound must have permutations: a file with an empty pitch range (some
|
||||
Halo PC translations have them) is left out.
|
||||
- A permutation must fit in a block of the sound cache (one sound's samples:
|
||||
`MAXIMUM_SOUND_DATA_SIZE`).
|
||||
|
||||
### Bitmaps
|
||||
|
||||
- A bitmap's types and formats are those the game draws: 2D, 3D and cube
|
||||
maps; A8, Y8, AY8, A8Y8, R5G6B5, A1R5G5B5, A4R4G4B4, X8R8G8B8, A8R8G8B8,
|
||||
DXT1, DXT3, DXT5 and P8 bump. Sides are 4096 at most (512 for a 3D
|
||||
bitmap). A bitmap that is not a power of two on each side is drawn
|
||||
linear, as a Custom Edition map's is: it must be an uncompressed 2D
|
||||
bitmap.
|
||||
- One bitmap's pixels may take a quarter of the texture cache: 64 MB on
|
||||
Linux and Windows, 5.5 MB on Android and the web (a 2048 x 2048 DXT5 with
|
||||
its mipmaps fits on all of them).
|
||||
- A bitmap replaces the map's bitmap of its name, and the map's other tags
|
||||
use it as the map's: it must have at least as many bitmaps, of the same
|
||||
types, and as many sequences, each with at least as many sprites. It can
|
||||
be larger: a redraw at twice the size is drawn at the map's size, sharper.
|
||||
- The HUD draws a bitmap at its own size. So for each HUD element that draws
|
||||
a mod's bitmap, the game scales the element by the map's size of what it
|
||||
draws (its sprite, or with no sprites its bitmap) to the mod's, when that
|
||||
is the same ratio for all of them. A bitmap the HUD draws that is not the
|
||||
map's redrawn so (Halo PC's HUD bitmaps lay their sprites out to other
|
||||
sizes) is left out. The HUD's digits can be the map's size or twice it.
|
||||
- The menus draw a bitmap in their widgets' bounds, whatever its size.
|
||||
- Halo PC keeps the channels of a model shader's multipurpose maps and of
|
||||
the HUD's meters in another order than the Xbox. The game finds those
|
||||
bitmaps among the mod's and draws them in the Xbox's order, as it does for
|
||||
Custom Edition maps (`custom_edition_bitmaps.c`).
|
||||
- The pixels are read from the file when the texture cache loads them, not
|
||||
kept in memory.
|
||||
|
||||
### Text
|
||||
|
||||
- A list keeps the map's number of strings: a mod's strings past it are
|
||||
left out, and the map's own strings stay where the mod's list is shorter.
|
||||
- The game uses many strings as the format of what it prints
|
||||
(`%s was killed by %s`). A mod's string replaces the map's only if it has
|
||||
the same conversions in the same order (`%s`, `%d`, ...); otherwise the
|
||||
map's string stays. A translation keeps the conversions of the original.
|
||||
- Unicode strings are UTF-16, as the tool writes them.
|
||||
- The main menu is the port's own (the PC version's menus, `port/assets/menus`),
|
||||
whose text is in tags named `pc\...`. A mod's `ui\shell` lists change the
|
||||
Xbox's menus (`display.menus = "xbox"`) and the text shown while playing
|
||||
(HUD messages, the multiplayer messages, the pause menu).
|
||||
|
||||
### Models
|
||||
|
||||
A model is more than what is drawn: its nodes (its skeleton) are what its
|
||||
animations move, its markers are where projectiles leave a weapon, where a
|
||||
unit sits and where things attach, and its regions and permutations are what
|
||||
damage and an object's variant choose among. The machines of a network game
|
||||
agree on those, so a mod's model must have the map's:
|
||||
|
||||
- the same nodes: their names, hierarchy and default positions;
|
||||
- the same markers: their names, regions, permutations, nodes, positions
|
||||
and rotations (on the model's permutations, as the Halo Editing Kit keeps
|
||||
them, or on the model, as a map does);
|
||||
- the same regions and permutations: their names and flags.
|
||||
|
||||
Positions and rotations may differ from the map's by 0.001 at most (a model
|
||||
exported again is not always bit for bit the map's). Only what is drawn is
|
||||
the mod's: the geometries, their parts and vertices, which geometry each
|
||||
permutation draws at each detail level, the detail levels' cutoffs, the
|
||||
base map's scale, and which shaders each part is drawn with. A detail level
|
||||
the map draws must draw one of the mod's geometries, and one the map draws
|
||||
nothing at stays so. Every shader must be one the map has (a mod cannot add
|
||||
tags); a mod's bitmaps can redraw them.
|
||||
|
||||
The model is checked against each map's own model of its name as that map
|
||||
loads. On a map whose model of that name has other nodes, markers or
|
||||
regions (a custom map's own assault rifle, say), or lacks a shader the mod
|
||||
names, the mod's model is left out and the map's drawn; the mod's other
|
||||
files still play there. `maps` in `mod.toml` keeps a mod to the maps it is
|
||||
made for.
|
||||
|
||||
- Where a mod has both, its `.gbxmodel` plays; otherwise the file of the mod
|
||||
loaded later, whichever its format.
|
||||
- What the tool works out as it builds a map is worked out as it does: a
|
||||
part's strip is its triangles block, its centroid's nodes are its most
|
||||
weighted, its links of 0 to the parts drawn before and after it are none,
|
||||
a base map scale of 0 is 1, and a model whose tag asks for it has the
|
||||
normals of its vertices that share a position blended. The vertices are
|
||||
compressed as the game draws them.
|
||||
- A part's links to the parts drawn before and after it (for transparency)
|
||||
must not go round.
|
||||
- A model of 44 nodes or more (the renderer skins 43 at once; only Custom
|
||||
Edition maps' have so many) is drawn a part's own nodes at a time, as a
|
||||
Custom Edition map's is: a part's vertices may name 22 nodes at most.
|
||||
- The collision geometry, the animations and the object's tag are the map's:
|
||||
a larger weapon still hits and is hit where the map's does, and an object
|
||||
is still left undrawn by the map's bounds of it (a much larger model may
|
||||
vanish at the screen's edges).
|
||||
- Every model made from a file is kept until the map changes, a file edited
|
||||
and read again by `mods_reload` too, and counts against the mods' memory.
|
||||
|
||||
### Shaders
|
||||
|
||||
A model's parts can be drawn with a shader of every group Halo PC has but
|
||||
one: `shader_transparent_chicago_extended`, which Gearbox added for Halo PC.
|
||||
The Xbox game does not have it, so do not use it: use a
|
||||
`shader_transparent_chicago` shader instead. (A Custom Edition map's
|
||||
chicago extended shaders become chicago shaders as the map loads, keeping
|
||||
only their four-stage maps: see
|
||||
[custom_edition_caches.md](custom_edition_caches.md).) As for every
|
||||
shader, it must be one the map has.
|
||||
|
||||
## Making a mod
|
||||
|
||||
1. Get the tags you want to change as tag files. `invader-extract` extracts
|
||||
them from a map, and the Halo Editing Kit's tags are Halo PC's own.
|
||||
2. Change them with the Halo Editing Kit or Invader (`invader-bitmap`,
|
||||
`invader-sound` and `invader-model` build bitmaps, sounds and models from
|
||||
images, audio files and JMS files). Keep each tag's name.
|
||||
3. Put them in `tags/` of a folder in `mods/`, with a `mod.toml`.
|
||||
4. Load a map (a new mod is on). `mods_reload` at the console reads the
|
||||
files again as you change them, without loading the map again.
|
||||
|
||||
`debug.txt` has a line for every file the game leaves out, and why, and a
|
||||
summary of what each kind of tag plays from the mods:
|
||||
|
||||
```
|
||||
mods: 9 string lists from their files (9 new), 0 given back, 0 left out
|
||||
mods: 66 HUD placements scaled to draw larger bitmaps at the map's size
|
||||
mods: 354 bitmaps from their files (354 new), 0 given back, 6 left out
|
||||
mods: 313 sounds from their files (313 new), 0 given back, 2 left out
|
||||
mods: 4 models from their files (4 new), 0 given back, 1 left out
|
||||
```
|
||||
|
||||
## How it operates
|
||||
|
||||
- When a map's tags load, at `mods_reload` and at the Mods menu's **OK**,
|
||||
the game lists the files of the mods that are on, once, in a table of
|
||||
their tag paths. Each of the map's sound, bitmap, string list and model
|
||||
tags is looked up in it.
|
||||
- A tag replaced by a mod takes the file's values in place, so everything
|
||||
that holds the tag keeps it, and the map's own values come back when the
|
||||
file goes. A sound playing or a texture in the cache is never changed
|
||||
under the game: before a reload changes anything, the sounds stop and the
|
||||
caches let go of what they hold.
|
||||
- The mods' tags keep at most 512 MB in memory (192 MB on Android and the
|
||||
web): their files, their sounds' samples, their bitmaps' tags and their
|
||||
models' geometry.
|
||||
- A Custom Edition map takes mods as an Xbox map does.
|
||||
@@ -0,0 +1,113 @@
|
||||
# objdiff v3.3.1 mis-scores MSVC data relocations
|
||||
|
||||
*2026-09-22, Lane C. Established independently three ways: by reading objdiff's
|
||||
source at tag v3.3.1, by black-box perturbation of January's own object files,
|
||||
and by auditing this project's own adjudication ledger. All three agree.*
|
||||
|
||||
## The defect
|
||||
|
||||
A data section's objdiff score is decided by its **relocations**. Two
|
||||
relocations are compared by `reloc_eq` in `objdiff-core/src/diff/data.rs`, which
|
||||
first tries `symbol_name_matches()`. That helper assumes a `$` in a symbol name
|
||||
is the Metrowerks `symbol$1234` unique-ID separator:
|
||||
|
||||
```rust
|
||||
if let Some((prefix, suffix)) = left_name.split_once('$') {
|
||||
if !suffix.chars().all(char::is_numeric) { return false; }
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Every MSVC mangled string literal contains `?$AA` — the encoded NUL. For example
|
||||
`??_C@_0P@LFOALBOL@objects_update?$AA@`. The suffix after the first `$` is
|
||||
`AA@`, which is not numeric, so **the helper returns false for two
|
||||
character-for-character identical names**.
|
||||
|
||||
`reloc_eq` then falls through to `address_eq`, which requires the target literal
|
||||
to sit at the same offset inside the *synthetic combined* `.rdata` that
|
||||
`report generate` builds (it forces `combine_data_sections: true`, and
|
||||
`do_combine_sections` concatenates every same-named section in COFF
|
||||
section-table order, padding each to `max(align, 4)`). csplit lists January's
|
||||
`.rdata` COMDATs in image order; CL emits ours in its own order. So the address
|
||||
test fails too, and a byte-perfect relocation is scored as a mismatch.
|
||||
|
||||
That costs the section twice. Relocated bytes are counted twice in
|
||||
`diff_data_symbol`
|
||||
|
||||
match_ratio = (bytes_ratio*len + relocs_ratio*reloc_bytes) / (len + reloc_bytes)
|
||||
|
||||
and, worse, the whole-section byte fallback in `diff_data_section` is gated
|
||||
behind `if all_left_relocs_match`, so it never runs. Since `report.rs` credits
|
||||
data all-or-nothing per section, one mis-compared relocation forfeits the
|
||||
entire section.
|
||||
|
||||
The code path is immune: `diff/code.rs::reloc_eq` compares names with plain `==`.
|
||||
|
||||
Fixed upstream in **objdiff v3.6.0** (2026-01-25), which added
|
||||
`get_normalized_symbol_name` in `obj/read.rs`; it returns `None` for
|
||||
`??_C@...?$AA@` so `symbol_name_matches` falls back to exact equality.
|
||||
|
||||
## Reproduction
|
||||
|
||||
Copy January's `objects.obj`, swap only the two `.rdata` COMDAT section headers
|
||||
for `_object_memory_release_procs` (24 B) and the `objects_update` literal
|
||||
(15 B), fixing symbol section numbers; change nothing else. January against
|
||||
itself scores `.data` 100.0; January against that header-swapped copy scores
|
||||
`.data` 99.739235 — the exact production number. Swapping two COFF *symbol
|
||||
table* entries instead leaves it at 100.0, so symbol-table order is inert.
|
||||
|
||||
## Scale, measured at HEAD
|
||||
|
||||
40 data sections / **32,262 bytes** have identical size, identical raw bytes and
|
||||
an identical relocation multiset, and would score exactly 100.000000 under an
|
||||
exact-name rule. Of those:
|
||||
|
||||
* **37 sections / 29,582 bytes are already credited** by
|
||||
`config/semantic_data_matches.json`. No progress bytes are being lost there —
|
||||
but they are credited as *adjudications*, and the standing rule is that
|
||||
adjudicated does not count as closed.
|
||||
* **3 sections / 2,680 bytes are genuinely uncredited**:
|
||||
`source/ai/actions .rdata` (2,388), `source/ai/ai_communication .data` (276),
|
||||
`source/ai/actions .data` (16).
|
||||
|
||||
## Recommendation
|
||||
|
||||
Upgrading the differ to >= v3.6.0 is the root-cause fix. It would recover the
|
||||
2,680 uncredited bytes and let roughly 37 adjudications be retired, converting
|
||||
29,582 bytes from adjudicated to genuinely exact. That is a shared build-tool
|
||||
change and needs an owner decision, and it must be measured board-wide first,
|
||||
because a differ upgrade re-scores everything.
|
||||
|
||||
Do **not** chase these sections with source edits. The only source-side lever is
|
||||
which `.rdata` COMDATs a TU emits and in what order, so that a literal lands at
|
||||
January's combined offset — and the target order is csplit's, i.e. the linked
|
||||
image's layout, which is a link-time property. Reordering or inventing literals
|
||||
to shift an offset fails the strip test.
|
||||
|
||||
Do **not** add new adjudications for them either; that papers over the
|
||||
instrument. Two entries were retired on 2026-09-22 for the opposite reason —
|
||||
`cheats .bss` and `tif_version .data` became genuine matches, so their
|
||||
adjudications were deleted at no cost to credited progress.
|
||||
|
||||
## Triage rule this establishes
|
||||
|
||||
Run the January-against-January self-diff **before** spending any wave on data,
|
||||
and **regenerate it whenever the differ changes**. Rewrite `objdiff.json` with
|
||||
`base_path = target_path` and absolute paths, drop `custom_make`/`build_target`,
|
||||
then `objdiff-cli report generate`; it takes 0.12 s over all 833 units.
|
||||
|
||||
Under v3.3.1 it capped 47 sections / 87,889 bytes. **Under v3.6.0 it caps
|
||||
nothing at all** - 0 sections, 0 bytes. Every one of those "permanent" ceilings
|
||||
was this same defect: a January-side string COMDAT comparing unequal to itself,
|
||||
so even a byte-identical copy could not reach 100. The campaign treated 87,889
|
||||
bytes as unreachable on the strength of a number produced by the broken
|
||||
comparator. Do not quote the old figure, and do not kill a target with a stale
|
||||
ceiling report.
|
||||
|
||||
## Resolution
|
||||
|
||||
Landed 2026-09-22: `sln.objdiff_tag` pinned to v3.6.0, and the 40 adjudications
|
||||
the fix makes redundant retired in the same commit. Board effect, measured on
|
||||
identical objects: raw data +34,886, raw code and functions unchanged, zero
|
||||
units losing anything, credited data +5,296, adjudications 43 -> 3. v3.8.1 was
|
||||
measured and rejected - same data gain, but it loses 6 bytes of code.
|
||||
@@ -0,0 +1,91 @@
|
||||
# Object exact-match strategy logs
|
||||
|
||||
For the completed/interrupted Opus 2 and new Fable 5 lanes, start with the
|
||||
[current reconciliation queue](../reconciliation_queue_20260907.md). It separates
|
||||
published progress, donor claims, dirty work, owner holds and tooling defects.
|
||||
|
||||
Every object that receives implementation or matching work must maintain one
|
||||
Markdown ledger in this directory. The filename is the object name with
|
||||
`_obj.md`, for example `players_obj.md`.
|
||||
|
||||
General techniques that apply across translation units belong in
|
||||
`docs/exact_match_acceleration_playbook.md`; object-specific measurements stay
|
||||
in the individual ledger.
|
||||
|
||||
Start constant and diagnostic recovery with the
|
||||
[common constants reference](../common_constants.md) and
|
||||
[shared assertion API](../assertions.md), before testing guessed literals.
|
||||
|
||||
The purpose is to make matching work cumulative. A new lane must be able to
|
||||
distinguish an untried evidence-backed source shape from a spelling that has
|
||||
already compiled to the same bytes.
|
||||
|
||||
## Required contents
|
||||
|
||||
Each ledger must include:
|
||||
|
||||
1. **Scope and provenance**
|
||||
- source translation unit and target object;
|
||||
- exact compiler identity and flags;
|
||||
- target-build provenance used for names, layouts, or source topology.
|
||||
2. **Validated baseline**
|
||||
- exact/total function count and padded code bytes;
|
||||
- exact/total data sections and bytes;
|
||||
- for every residual: target/base size, relocation count, normalized hash,
|
||||
and first meaningful divergence.
|
||||
3. **Accepted controls**
|
||||
- the source shapes retained in production;
|
||||
- why each shape is supported by binary or provenance evidence.
|
||||
4. **Experiment matrix**
|
||||
- every meaningful source shape tested;
|
||||
- resulting size, relocations, normalized hash, first divergence, and
|
||||
sibling-regression result;
|
||||
- whether it was retained or reverted.
|
||||
5. **Do-not-repeat list**
|
||||
- equivalent spellings or compiler-control attempts already exhausted;
|
||||
- unsafe or prohibited techniques.
|
||||
6. **Residual classification**
|
||||
- source/topology, ABI/register, scheduling, ownership/relocation, data, or
|
||||
unresolved;
|
||||
- clearly separate measured fact from inference.
|
||||
7. **Reopen criteria**
|
||||
- the exact new evidence that would justify spending another lane.
|
||||
8. **Disposition**
|
||||
- strict exact and eligible for `Matching`, still active, or rigorously
|
||||
parked;
|
||||
- never grant credit from a fuzzy percentage, equal size alone, or semantic
|
||||
plausibility.
|
||||
|
||||
## Lane rules
|
||||
|
||||
- Update the ledger after every bounded experiment batch, not only at handoff.
|
||||
- Rebuild with XDK 3911 and the repository flags after each retained change.
|
||||
- Gate every function and owned data section with the hardened comparator.
|
||||
- Run the whole-translation-unit regression sweep before committing.
|
||||
- Revert failed source shapes immediately.
|
||||
- Treat exact bytes as necessary but not sufficient: reject semantically
|
||||
nonsensical, historically implausible, logically meaningless, or inert
|
||||
compiler-steering source, even when it happens to match. Coincidental byte
|
||||
equality never authenticates the source. Park the best honest fuzzy
|
||||
reconstruction when a natural exact spelling is not available.
|
||||
- Do not use inline assembly outside a sparse, provenance-backed helper/math
|
||||
exception. Never use volatile byte forcing, undefined behavior, object-byte
|
||||
patches, or compiler-flag changes.
|
||||
- A parked residual must preserve enough evidence for another agent to
|
||||
reproduce the classification without redoing the full search.
|
||||
- Label a defect `BUG (original)` only when January binary/source evidence
|
||||
proves the defective behavior belongs to the original game. A mistake or
|
||||
omission in our reconstruction is not an original bug. Preserve proven
|
||||
original behavior in the matching build and document the corrected-build
|
||||
alternative in a comment without changing the matching token/line shape.
|
||||
- When retroactively documenting an old lane, state which experiment details
|
||||
were not preserved. Never manufacture source variants, hashes, or outcomes
|
||||
to make a historical matrix look complete.
|
||||
|
||||
## Minimal experiment row
|
||||
|
||||
```markdown
|
||||
| ID | Source shape | Size T/B | Relocs T/B | Base hash | First divergence | Siblings | Decision |
|
||||
|---|---|---:|---:|---|---|---|---|
|
||||
| E01 | ... | `0x.../0x...` | `N/N` | `...` | `+0x...: ...` | `K/K exact` | reverted |
|
||||
```
|
||||
@@ -0,0 +1,113 @@
|
||||
# action_alert.obj complete reconstruction and fuzzy closeout (2026-09-01)
|
||||
|
||||
## Result
|
||||
|
||||
`source/ai/action_alert.obj` advanced from five exact functions and seven
|
||||
unwritten functions to eleven exact functions and one complete, documented
|
||||
fuzzy residual. There are no unwritten functions left in the object.
|
||||
|
||||
The newly exact functions are:
|
||||
|
||||
- `action_alert_setup`
|
||||
- `action_alert_flush_position_indices`
|
||||
- `action_alert_flush_structure_indices`
|
||||
- `distance_squared3d`
|
||||
- `action_alert_update`
|
||||
- `action_alert_perform`
|
||||
|
||||
The remaining private function was recovered as
|
||||
`action_alert_next_position`; the address-derived symbol was removed from
|
||||
`config/symbols.json` and the symbol remains translation-unit private.
|
||||
|
||||
## Evidence and donor audit
|
||||
|
||||
The reconstruction was checked against all Action Alert ledgers, repository
|
||||
history, registered branches and worktrees, the January target disassembly and
|
||||
relocations, and the later HCEA semantic sources under:
|
||||
|
||||
`research-cache/halocea-full-blobs-20260830/src/blam/ai/action_alert_*.c`
|
||||
|
||||
Pastudan's setup/update reconstruction was also inspected. Marathon contains
|
||||
no direct Action Alert donor. No registered worktree contains a complete
|
||||
definition of either `action_alert_perform` or `action_alert_next_position`,
|
||||
and no farther candidate than the retained source was found.
|
||||
|
||||
The HCEA source and AI definitions corroborate the complete behavior:
|
||||
|
||||
- disabled/passenger, no-order, and no-encounter rejection;
|
||||
- encounter, squad, and move-position traversal;
|
||||
- current-position, actor-distance, noncombat-sequence, and nearby-prop
|
||||
availability tests;
|
||||
- cseries bit-vector tracking of unavailable positions;
|
||||
- weighted random selection and forward, ping-pong, and per-tick-random
|
||||
traversal;
|
||||
- dwell-time selection, animation startup, and move-position state updates.
|
||||
|
||||
Action Alert prototypes now live in the closest owner header, `actions.h`,
|
||||
rather than as ad hoc declarations in `actions.c`. Accesses use the project's
|
||||
typed actor, unit, definition, tag-block, and scenario helpers. The source
|
||||
uses semantic cseries types and enum constants and keeps explicit returns.
|
||||
|
||||
## Residual measurement
|
||||
|
||||
Focused gate after reconstruction:
|
||||
|
||||
```text
|
||||
residual 784 _action_alert_next_position [size 768!=784, sha]
|
||||
== exact 11 residual 1 unwritten 0 (of 12 listed)
|
||||
```
|
||||
|
||||
Fresh full campaign-report similarity for the residual is `99.46479%`.
|
||||
This value, rather than a separate aligned-disassembly score, is recorded in
|
||||
`config/parked.json`.
|
||||
|
||||
- Target: 784 padded bytes, 18 relocations, normalized SHA-256
|
||||
`677fd6cc1a9e66de32123c4614de5a0cc1188501baee69ea20fd5bf74eac3fe4`.
|
||||
- Candidate: 768 padded bytes, 18 relocations, normalized SHA-256
|
||||
`4e16c85b544ded3352df48ee7baa0e19b5a34a45e421a975cf11cd771184f371`.
|
||||
|
||||
Aligned instruction comparison is retained only as diagnostic evidence. It
|
||||
shows that the geometry, prop-iterator, bit-vector, random-selection, and
|
||||
ordered-traversal body is byte-identical. The remaining decoded differences
|
||||
are limited to January preloading the `NONE` result in EAX, the resulting
|
||||
AL/CL and EAX/ECX allocation choices in the entry guard, two equivalent
|
||||
full-EAX versus AX `NONE` returns, and target-envelope padding.
|
||||
|
||||
## Bounded source-shape audit
|
||||
|
||||
Ordinary-C probes covered combined, separate, and enclosing entry guards;
|
||||
short and long default-result lifetimes; declaration order; direct and
|
||||
assigned random returns; natural `for` and `while` traversal; and switch
|
||||
default/case arrangements. The retained `while` traversal reproduces
|
||||
January's initialization schedule, and initializing the traversal direction
|
||||
before a semantic enum switch with no redundant default reproduces January's
|
||||
entire switch body. The remaining entry/result variants either returned to
|
||||
the same compiler fixed point or disturbed larger exact regions.
|
||||
|
||||
No volatile or register forcing, compiler barrier, pragma, inline assembly,
|
||||
fake dependency, raw structure offset, undefined behavior, forced inlining,
|
||||
or nonsensical control flow is retained. The function is parked as
|
||||
`register-allocation` and should reopen only for authoritative January source
|
||||
or local-variable records, or a natural compatible-compiler donor that
|
||||
explains the default-result lifetime.
|
||||
|
||||
## Validation
|
||||
|
||||
The admission run passed:
|
||||
|
||||
- full `ninja`, including report, semantic report, and progress validation;
|
||||
- an independent strict per-function sweep against a clean build of base
|
||||
`f73b19d30`: 5,026 exact to 5,032 exact, exactly the six Action Alert gains
|
||||
above, with zero lost functions and zero unit-read errors;
|
||||
- focused gates: Action Alert `11/12` exact with one parked residual, Actions
|
||||
`58/63` exact with its five pre-existing parks, Units `189/189`, objects
|
||||
`121/121`, and object types `31/31`;
|
||||
- `python -m tools.parked_functions`: 78 active, zero stale, zero invalid;
|
||||
- `python -m pytest -q`: 255 passed;
|
||||
- semantic audit: 5,032 strict exact functions, 134 hidden exact
|
||||
functions, and zero unit errors;
|
||||
- fake-match scan of all changed C/header files: zero findings;
|
||||
- object-admission audit: no contradictions or revocations (one unrelated
|
||||
pre-existing `player_rumble` ownership-review candidate);
|
||||
- all-unit `point_from_line3d` owner comparison against the base: no new or
|
||||
lost COMDAT owner.
|
||||
+152
@@ -0,0 +1,152 @@
|
||||
# `action_alert.obj`: `distance_squared3d` wrapper fixed point (2026-08-26)
|
||||
|
||||
## Outcome
|
||||
|
||||
No production source change and no matching credit. One evidence-backed
|
||||
candidate disproved the locally renamed inline-wrapper topology for
|
||||
`_distance_squared3d`: the candidate emitted 48 padded bytes, while January
|
||||
and every exact donor emit 64. The source was immediately reverted without a
|
||||
tuning compile, the committed five-function baseline was rebuilt, and its
|
||||
whole-TU manifest is green.
|
||||
|
||||
`action_alert.obj` therefore remains 5/12 exact functions and 177/2,120
|
||||
meaningful code bytes. The retained production commits remain:
|
||||
|
||||
- `020449c3b3518fd6bbc1dfbe739ab3a15762befa`
|
||||
(`Match action alert geometry wrappers`);
|
||||
- `5196b8e4b409c571abc6be5634d0d09bc90ac9e5`
|
||||
(`Record action alert geometry validation`).
|
||||
|
||||
## Frozen target and baseline
|
||||
|
||||
The clean committed translation unit was frozen at `5196b8e4` in:
|
||||
|
||||
- `build/audit/action_alert_distance_squared_baseline_20260826.json`;
|
||||
- manifest SHA-256
|
||||
`f1ceaca1e7bd5c97bbac65192214909d4068cb9532af1f0cd29973938a3ec30c`.
|
||||
|
||||
The January target is:
|
||||
|
||||
- 49 meaningful / 64 padded bytes;
|
||||
- zero relocations;
|
||||
- normalized SHA-256
|
||||
`f42fa39f289bfa50174aa61e77b345b092df8329d46f43f88ca127227ad1e9c8`;
|
||||
- split-object SHA-256
|
||||
`bb7a70aae881cdf5672ae48c3b9c5b7d0cdcc9a30a90730672f04b71fa1cab5f`.
|
||||
|
||||
The baseline source SHA-256 is
|
||||
`0682c4b9fbf896d8434a1a8f6f78b355c2fabf20669601be3d25f64541fee93b`
|
||||
and its Git blob is `8de8debb9ac7108acc7352c53e36e305f75d06f7`.
|
||||
|
||||
## Same-name donor census
|
||||
|
||||
The canonical nested body is owned by `source/math/real_math.h`:
|
||||
|
||||
```c
|
||||
__inline real distance_squared3d(
|
||||
real_point3d const *a,
|
||||
real_point3d const *b)
|
||||
{
|
||||
real_vector3d v;
|
||||
return magnitude_squared3d(vector_from_points3d(a, b, &v));
|
||||
}
|
||||
```
|
||||
|
||||
The read-only census script
|
||||
`build/audit/find_action_alert_distance_donors_20260826.py` has SHA-256
|
||||
`c8989f86e767ca76965766eace71c8f8a9d326d96b32545df14e219fd3a32e72`.
|
||||
It found twelve rebuilt objects defining the same-name section, and hardened
|
||||
comparison reports every one `all_equal: true` against the action-alert
|
||||
target:
|
||||
|
||||
- `source/ai/action_fight.obj`;
|
||||
- `source/ai/action_guard.obj`;
|
||||
- `source/ai/action_search.obj`;
|
||||
- `source/ai/action_uncover.obj`;
|
||||
- `source/ai/actor_perception.obj`;
|
||||
- `source/effects/material_effects.obj`;
|
||||
- `source/game/game_engine.obj`;
|
||||
- `source/objects/objects.obj`;
|
||||
- `source/physics/breakable_surfaces.obj`;
|
||||
- `source/physics/collisions.obj`;
|
||||
- `source/physics/physics.obj`;
|
||||
- `source/units/units.obj`.
|
||||
|
||||
Direct hardened comparisons against both `action_fight.obj` and `units.obj`
|
||||
independently prove the 64 padded bytes and zero-relocation inventory. The
|
||||
donors obtain the COMDAT from a real call to the canonical header inline;
|
||||
none supplies an ordinary out-of-line source definition that can be
|
||||
transplanted verbatim.
|
||||
|
||||
## Sole candidate and rejection
|
||||
|
||||
The candidate locally renamed `distance_squared3d` across the header include
|
||||
and added the ordinary wrapper:
|
||||
|
||||
```c
|
||||
real distance_squared3d(
|
||||
real_point3d const *a,
|
||||
real_point3d const *b)
|
||||
{
|
||||
return distance_squared3d_inline(a, b);
|
||||
}
|
||||
```
|
||||
|
||||
This is ordinary C89 and obeys all formatting and return rules. Exactly one
|
||||
normal VC7 compile was spent. The preserved first candidate is:
|
||||
|
||||
- `build/audit/action_alert_distance_squared_first_current_tu_20260826.obj`;
|
||||
- raw SHA-256
|
||||
`c20dfa1ae881e1fae04d85b0a1f8e8911c837ece78b17bc33f64bcac6d5734c6`.
|
||||
|
||||
Its `_distance_squared3d` section is:
|
||||
|
||||
- 48 padded bytes;
|
||||
- zero relocations;
|
||||
- normalized SHA-256
|
||||
`3e3811d46757035eda49d4b9374d60a716646e589c018726d37a8e0ae2e3564a`.
|
||||
|
||||
The wrapper therefore changes the compilation context enough for VC7 to
|
||||
collapse the canonical nested operation into a shorter form. It is not the
|
||||
same emission topology as the donor COMDAT. The candidate whole-TU gate also
|
||||
fails closed on the additive symbol/debug inventory and records
|
||||
`_distance_squared3d` in `changed_nonexact`. Direct comparison proves the five
|
||||
accepted bodies themselves remained byte-exact, but the manifest failure is
|
||||
independently sufficient to reject the candidate.
|
||||
|
||||
No second spelling, hand expansion, compiler option, object permutation,
|
||||
allowlist, adjudication, exception, synthetic caller, or byte-forcing form was
|
||||
compiled.
|
||||
|
||||
## Restoration
|
||||
|
||||
The candidate source was removed with `apply_patch`, returning
|
||||
`source/ai/action_alert.c` byte-for-byte to the committed blob. The generated
|
||||
object path was resolved inside the authoritative worktree, that single object
|
||||
was deleted, and one restoration build was run. Its nondeterministic raw
|
||||
SHA-256 is
|
||||
`28105c5cf2ead523cf5e98dfb87afb09330164d4e5cb233f3c776167345f92b3`.
|
||||
|
||||
The frozen manifest then reports:
|
||||
|
||||
- `ok: true`;
|
||||
- no failures or warnings;
|
||||
- `changed_nonexact: []`;
|
||||
- `_action_alert_begin`, `_action_alert_control`,
|
||||
`_vector_from_points3d`, `_magnitude_squared3d`, and
|
||||
`_real_random_range` all `still_exact`.
|
||||
|
||||
Direct hardened comparison of the same five functions remains
|
||||
`all_equal: true`. No protected path changed, no tracked path was deleted,
|
||||
and nothing was pushed.
|
||||
|
||||
## Reopen criterion
|
||||
|
||||
Do not retry the renamed-inline wrapper. Reopen `_distance_squared3d` only
|
||||
with genuinely new evidence that reproduces the donor COMDAT emission context
|
||||
without a synthetic caller—for example an authenticated ordinary definition,
|
||||
a grounded VC7 inline/COMDAT topology explanation, or another natural
|
||||
translation-unit use that makes the canonical header definition emit under
|
||||
the function's real ownership. A direct ordinary copy of the canonical body
|
||||
is a distinct unmeasured hypothesis, but it is not justified for another
|
||||
production compile merely by the failed wrapper result.
|
||||
@@ -0,0 +1,124 @@
|
||||
# `action_alert.obj` Jonas prefix recovery
|
||||
|
||||
This Jonas/Codex ledger records a bounded, fail-closed recovery of the five
|
||||
requested prefix bodies in `source/ai/action_alert.obj`. Only
|
||||
`_action_alert_control` was independently strict on the first natural
|
||||
candidate, so it alone is retained. The object advances from 2/12 to 3/12
|
||||
exact functions and remains `NonMatching`; no data or whole-object credit is
|
||||
claimed.
|
||||
|
||||
## Scope and provenance
|
||||
|
||||
- Authoritative integration base:
|
||||
`7d2ff479dde012f94cc08857e4cc74650b85b9af`.
|
||||
- Baseline `action_alert.c` blob:
|
||||
`45f0eae365e5f6e087507143bd68549c676ab736`.
|
||||
- Retained `action_alert.c` blob:
|
||||
`01c9af4f179f4fc7e3792413c7a18cf3d7899c5a`.
|
||||
- Retained source SHA-256:
|
||||
`d10627b7393f20bd86037df3da279333b2c0e99c0a7adb24d77320e5865d5865`.
|
||||
- January executable SHA-256:
|
||||
`4cc87b45f721270392a96f1674ed2b5cd4a7bb4355faeab4531d1cf1884d9520`.
|
||||
- January split-object SHA-256:
|
||||
`bb7a70aae881cdf5672ae48c3b9c5b7d0cdcc9a30a90730672f04b71fa1cab5f`.
|
||||
- The raw candidate-object hash is deliberately omitted because the XDK COFF
|
||||
container timestamp changes across forced builds. The normalized function
|
||||
hashes below are the reproducible admission identities.
|
||||
- Clean HCEA semantic donor commit:
|
||||
`c168af2e747d3095d9a29418ae401f3a39544863`. The screened source blobs
|
||||
are `a8494315eb9fbbc0b57fe9ae169b76f5203044fe` (setup),
|
||||
`bdc904682c5a2ba16a90f308cfeef79c97be2a68` (control),
|
||||
`16f1703d50e1daa0b8f9fa15a6d5aad76c3a484d` (flush position),
|
||||
`3018bec7791130ca7a11f95f320d0c05cf257f81` (flush structure), and
|
||||
`c4f463bf4613fc0240debabaa8ad40cc494eb252` (update).
|
||||
|
||||
HCEA supplies semantic names and natural control-flow evidence. The January
|
||||
COFF remains the sole authority for bytes, padding, relocations, and symbolic
|
||||
destinations.
|
||||
|
||||
## One-shot strict result
|
||||
|
||||
The five requested bodies were compiled together once with the repository's
|
||||
natural XDK 3911 command. Each body was compared independently with the
|
||||
hardened COFF comparator. The four nonexact bodies were then removed without
|
||||
another source-shape experiment or any code-generation tuning. The later full
|
||||
build and forced regression are validation replays of this fail-closed final
|
||||
source.
|
||||
|
||||
| Function | Target meaningful | Target padded | Relocations | Target normalized SHA-256 | First candidate result |
|
||||
| --- | ---: | ---: | ---: | --- | --- |
|
||||
| `_action_alert_setup` | 126 | 128 | 7 | `225015f380c74c1a19d563730b7820375cd37490eb40cb6d67e3404bc46c9cc0` | rejected: 144 padded, 7 relocations, SHA `47b3dc2358c61240e9d48276b9d00caf88d8384cfc505e764f2929cf32ba7491` |
|
||||
| `_action_alert_control` | 73 | 80 | 3 | `8be5d8f243b76cbf9dd2c4f7f35b4509c349bc970a9b2fc1518a71e3e6a1fbb3` | **retained: strict exact** |
|
||||
| `_action_alert_flush_position_indices` | 40 | 48 | 2 | `02db3d8b0b933d6e26b970c3c7a3639e7005e78304692915295d835f61eff579` | rejected: 48 padded, 2 relocations, SHA `90abe46d68627d1a83f1a5a89d4d7ecd6d86b0ee14b514917b19c73f96d17335` |
|
||||
| `_action_alert_flush_structure_indices` | 39 | 48 | 2 | `1b6fb9035cd64ac3bd1a66e1be208f3dc09ea95d32ef17f960e5bd960540a466` | rejected: 48 padded, 2 relocations, SHA `75fef43de1d32d255e61481ac5402bab1d683f3c801fb2a252438d8ba603434d` |
|
||||
| `_action_alert_update` | 323 | 336 | 13 | `0b4be7a9c0704dc3075a31fabf85a1f5ab7868be9d5fc3676685252d0aeaaa43` | rejected: 336 padded, 13 relocations, SHA `13ed6e0ef99086fe5eb49463dfa54e086057c8155982114cd78ea8e212608dea` |
|
||||
|
||||
The retained control body is exact in padded size, every normalized byte, and
|
||||
all three relocation addresses, types, destinations, and addends. It uses the
|
||||
established typed `actor_get` and `actor_definition_get` accessors, sets the
|
||||
January-proven noncombat idle-look value `1`, tests the named actor-definition
|
||||
bit 6, and sets both crouch Booleans when that bit is active.
|
||||
|
||||
The wave adds 73 meaningful and 80 padded exact code bytes. Together with the
|
||||
pre-existing exact `_action_alert_begin` and `_real_random_range`, the final
|
||||
object measures 3/12 exact functions, 101/2,120 meaningful code bytes, and
|
||||
128/2,240 padded code bytes. The preserved functions were replayed directly:
|
||||
|
||||
| Preserved function | Meaningful | Padded | Relocations | Normalized SHA-256 |
|
||||
| --- | ---: | ---: | ---: | --- |
|
||||
| `_action_alert_begin` | 1 | 16 | 0 | `499f1f307c1cb989f968a6b7fcaec591e1828877223d0b0e7e8e8b76cde8c9ca` |
|
||||
| `_real_random_range` | 27 | 32 | 2 | `7ed2e50e8e1a701a98fcceeb6a6b67e05d997f21bdb9ff5ee2e848fd1a8f409a` |
|
||||
|
||||
## Fail-closed omissions and policy boundary
|
||||
|
||||
The setup, both flushes, and update definitions are absent from the final
|
||||
candidate. The two large target-only bodies `_code_00000950` and
|
||||
`_action_alert_perform` were never added or compiled in the candidate lane.
|
||||
The rejected update's temporary local 0x3C animation-reference view and its
|
||||
scenario, object, and unit includes were removed with the body. No shared
|
||||
header, tag-definition storage, configuration, semantic exception, parked
|
||||
record, or completion label changes.
|
||||
|
||||
The retained source is readable typed C with vertically formatted parameters
|
||||
and an explicit terminal `return;`. It contains no assembly, raw object-header
|
||||
access, pointer or union pun, inactive-union access, integer-address
|
||||
reconstruction, volatile scheduling device, force-inline annotation,
|
||||
optimizer pragma or barrier, synthetic anchor, byte-forcing expression, or
|
||||
undefined-behavior match.
|
||||
|
||||
The target owns 80 ordinary non-code bytes; the final candidate owns none and
|
||||
receives zero data credit. The existing exact begin and random-range bodies
|
||||
are textually unchanged.
|
||||
|
||||
## Validation
|
||||
|
||||
- Complete `halobetacache_build` and `libcmt_build`: pass.
|
||||
- Direct hardened comparison: retained control plus both preserved functions
|
||||
pass with exact normalized bytes and relocations.
|
||||
- Semantic audit: 470 units, 3,995 functions evaluated, 3,855 semantic exact,
|
||||
101 hidden exact, 36 ordinary-only, 3,916 accepted exact, and zero unit
|
||||
errors.
|
||||
- Campaign progress: 375/833 complete objects, 3,903/11,060 exact functions,
|
||||
472,316/2,198,102 exact code bytes, and 1,835,088/4,176,062 matched data
|
||||
bytes.
|
||||
- Halo progress: 273/468 complete objects, 3,736/7,574 exact functions,
|
||||
459,402/1,770,166 exact code bytes, and 1,829,896/3,923,451 matched data
|
||||
bytes.
|
||||
- Object-admission audit: zero candidates and zero revocations; only the
|
||||
inherited `source/shell/shell_xbox` completion-label contradiction remains.
|
||||
- Parked-function audit: three active, zero stale, and zero invalid entries.
|
||||
- Complete tooling suite: 179/179 tests pass.
|
||||
- Clean committed-state forced single-unit regression snapshot/check: all
|
||||
three accepted functions remain exact, with no failure or ownership change.
|
||||
- `git diff --check`, deleted-path, policy-token, and frozen-scope audits:
|
||||
pass.
|
||||
|
||||
The five frozen large-object sources are byte-identical to the integration
|
||||
base: `vehicles.c` (`4a01dc7c54717e1b063a0cac72b0178b4bb2bf04`),
|
||||
`ai_debug.c` (`517731845431f1e240b06742ab9ddfbf6e67e929`),
|
||||
`ai_script.c` (`c3c858af2e4d6bf1df6dccf013b9ba6ee09f332d`),
|
||||
`actions.c` (`b594c1d52afe683e3fc794be08bf40e2b7045e26`), and
|
||||
`units.c` (`19a15c4a3a47849ffd8ba0c13989c0c389452519`).
|
||||
Only `source/ai/action_alert.c` and this new Jonas ledger are tracked changes.
|
||||
No tracked file is deleted, no object is marked complete, and nothing is
|
||||
pushed.
|
||||
@@ -0,0 +1,212 @@
|
||||
# `action_alert.obj`: safe geometry pair (2026-08-26)
|
||||
|
||||
## Outcome
|
||||
|
||||
Two ordinary geometry helpers are newly strict-exact:
|
||||
|
||||
- `_vector_from_points3d`;
|
||||
- `_magnitude_squared3d`.
|
||||
|
||||
The wave adds two exact functions and 76 meaningful code bytes.
|
||||
`action_alert.obj` advances from 3/12 to 5/12 exact functions and from 101
|
||||
to 177 matched meaningful code bytes. It remains incomplete; no completion
|
||||
label, semantic exception, adjudication, data credit, or comparator waiver was
|
||||
added.
|
||||
|
||||
Source commit:
|
||||
|
||||
- `020449c3b3518fd6bbc1dfbe739ab3a15762befa`
|
||||
(`Match action alert geometry wrappers`).
|
||||
|
||||
## Frozen evidence
|
||||
|
||||
The untouched translation unit was frozen at commit
|
||||
`fe2e8631136da957ce6fe286fde456a480cbc2ba` in:
|
||||
|
||||
- `build/audit/action_alert_safe_geometry_pair_baseline_20260826.json`;
|
||||
- manifest SHA-256
|
||||
`769e1bda19900e12f7c3622d1e4f6632debc1ef84b5fcc6fe42ca72ce10c089d`.
|
||||
|
||||
The target functions have these authenticated January fingerprints:
|
||||
|
||||
| Function | Meaningful / padded bytes | Relocations | Normalized SHA-256 |
|
||||
| --- | ---: | ---: | --- |
|
||||
| `_vector_from_points3d` | 38 / 48 | 0 | `905f56dbe4597d2bacc201456ffc33464b166e0b6392dda24a1a3e109b637aa2` |
|
||||
| `_magnitude_squared3d` | 38 / 48 | 0 | `0d04579096eeab3a1c45f87774e1eb20ce4856dbac219f624a855e8c9ae99725` |
|
||||
|
||||
The canonical bodies and ABIs are fixed by `source/math/real_math.h`.
|
||||
Direct comparison against the exact same-name definitions in
|
||||
`build/base/source/math/real_math.obj` proves all 48 padded bytes of each
|
||||
function. The repository-wide same-name census also found 25 exact donors for
|
||||
`_vector_from_points3d` and 33 for `_magnitude_squared3d`. Both target
|
||||
sections have zero relocations, so there is no unresolved callee, owner, or
|
||||
addend hypothesis. This is a same-name, same-ABI transfer rather than a
|
||||
masked-shape guess.
|
||||
|
||||
`_distance_squared3d` was deliberately excluded. Its target section is 49
|
||||
meaningful / 64 padded bytes with zero relocations and normalized SHA-256
|
||||
`f42fa39f289bfa50174aa61e77b345b092df8329d46f43f88ca127227ad1e9c8`,
|
||||
but its canonical source nests another helper. That makes definition order and
|
||||
inline topology a separate evidence question; it was not bundled into this
|
||||
independent two-function wave.
|
||||
|
||||
## Claude documentation and tooling audit
|
||||
|
||||
All locally reachable Claude records that name this object or the applicable
|
||||
matching tools were reconciled before candidate selection.
|
||||
|
||||
- The Claude residual census at
|
||||
`C:/halo-worktrees/claude-near-complete-objects-20260816/research/residual_frontier.json`
|
||||
lists the three geometry functions only as January `target_only` sections.
|
||||
It records no candidate, residual measurement, source experiment, or fixed
|
||||
point for the selected pair. The file SHA-256 is
|
||||
`db87717092d2e7c71160619e9df25f0b940f1762725c81f8bd2d6ece77fbde0d`.
|
||||
- No reachable `claude/*` branch changes `source/ai/action_alert.c`. The
|
||||
current history contains the prior Jonas/Codex prefix, control, and random
|
||||
range recovery only.
|
||||
- The Claude copies of `docs/matching_methodology.md` and
|
||||
`docs/shape_transfer_executor_strategy.md` are byte-identical across the
|
||||
near-complete, finish-hs, and untried worktrees and to the current files.
|
||||
Their SHA-256 values are respectively
|
||||
`3eb52f6b2df7b94b4d732161c0f86e2becebbcf0b546824deb957882118b1b5c`
|
||||
and
|
||||
`072ee7b2b3a2900e401bec7f69bff475f57639456d9c6270d2ea51189aaefa83`.
|
||||
- Claude's `docs/house_rules.md`, SHA-256
|
||||
`9294b81dc2e1c92d75ffd2f9f289287131bdba3564ba95bb054b08189781bfe1`,
|
||||
requires ordinary C, canonical vector expressions, and evidence before a
|
||||
compile. The retained component expressions are the canonical header forms
|
||||
and are corroborated by exact same-name donors.
|
||||
- Claude's flag-provenance census confirms this TU uses the normal
|
||||
`/O2 /Oy- /DDEBUG /Dxbox` profile and contradicts `/QIfist` as a whole-TU
|
||||
alternative. No flag change was considered or used.
|
||||
- The Claude campaign README identifies
|
||||
`tools/coff_compare.section_infos_equal` as the acceptance gate. The
|
||||
current hardened comparator and whole-TU regression manifest were used
|
||||
directly; no in-memory edit harness, alias adjudication, or comparator
|
||||
exception was used.
|
||||
|
||||
The earlier local record
|
||||
`docs/object_matching_logs/action_alert_obj_jonas_prefix_recovery.md` was also
|
||||
read in full. Its one-shot covered setup, control, the two flush helpers, and
|
||||
update; only control survived. It did not compile or measure either helper in
|
||||
this wave, so no fixed point was reopened.
|
||||
|
||||
## Candidate discipline
|
||||
|
||||
The two inline identifiers are locally macro-renamed across the include block,
|
||||
then ordinary out-of-line definitions are appended after the already accepted
|
||||
random-range wrapper. `action_alert.c` has an empty private-code tail, so the
|
||||
append preserves every existing function section index. The macros only avoid
|
||||
duplicate C definitions; they do not alter optimization, calling convention,
|
||||
or emitted instructions.
|
||||
|
||||
The one normal VC7 candidate compile was strict-exact for both functions on
|
||||
the first attempt. There was no object permutation, compiler-flag change,
|
||||
allowlist, adjudication, comparator exception, object patch, intrinsic,
|
||||
alignment directive, synthetic anchor, or byte-forcing expression.
|
||||
|
||||
The preserved first candidate is:
|
||||
|
||||
- `build/audit/action_alert_safe_geometry_pair_first_current_tu_20260826.obj`;
|
||||
- raw SHA-256
|
||||
`76977841b7e1bac6c02bf3ca86ca56785c5d47a6f3d55bda7019847d270e0ad4`.
|
||||
|
||||
## Exact comparison and frozen gate
|
||||
|
||||
The hardened comparator reports `all_equal: true` for both additions and all
|
||||
three previously accepted functions:
|
||||
|
||||
- `_vector_from_points3d`;
|
||||
- `_magnitude_squared3d`;
|
||||
- `_action_alert_begin`;
|
||||
- `_action_alert_control`;
|
||||
- `_real_random_range`.
|
||||
|
||||
The frozen gate reports exactly the pair as `newly_exact`, all three inherited
|
||||
functions as `still_exact`, and `changed_nonexact: []`. Its sole hard finding
|
||||
is the expected additive symbol inventory from defining the two functions.
|
||||
|
||||
## Clean committed state and replay
|
||||
|
||||
The clean committed manifest is:
|
||||
|
||||
- `build/audit/action_alert_safe_geometry_pair_committed_20260826.json`;
|
||||
- commit `020449c3b3518fd6bbc1dfbe739ab3a15762befa`;
|
||||
- SHA-256
|
||||
`940551915655b88e2affb548bb9e62d687ec109d672b4d02dde0a79cd85af98f`.
|
||||
|
||||
Its post-rebuild check returns `ok: true`, no failures, no warnings, no
|
||||
changed nonexact functions, and all five functions above as `still_exact`.
|
||||
|
||||
The generated object path was resolved inside this worktree. That single file
|
||||
was deleted and rebuilt once from the committed source. Raw base-object hashes
|
||||
were:
|
||||
|
||||
- before replay:
|
||||
`76977841b7e1bac6c02bf3ca86ca56785c5d47a6f3d55bda7019847d270e0ad4`;
|
||||
- after replay:
|
||||
`c7646f7851aa760a7de32c2b52f9b391137eae2ede49cb028cb74740e9810acb`.
|
||||
|
||||
VC7 debug/build records are nondeterministic, so raw object hashes are not the
|
||||
equality oracle. The post-replay manifest is green and direct hardened
|
||||
comparison remains `all_equal: true`.
|
||||
|
||||
Pinned artifacts:
|
||||
|
||||
- target split object:
|
||||
`bb7a70aae881cdf5672ae48c3b9c5b7d0cdcc9a30a90730672f04b71fa1cab5f`;
|
||||
- source file before/after:
|
||||
`84e4f2c3591554c6d34dc0701173bbfb11fb137ff4053a571cf3a55041d252ad` /
|
||||
`0682c4b9fbf896d8434a1a8f6f78b355c2fabf20669601be3d25f64541fee93b`;
|
||||
- source blob before/after:
|
||||
`01c9af4f179f4fc7e3792413c7a18cf3d7899c5a` /
|
||||
`8de8debb9ac7108acc7352c53e36e305f75d06f7`;
|
||||
- canonical report:
|
||||
`932d130576c91043f603dec2712ad9afb5dc9bfc98a1d5a991af3ebf482ca4f6`;
|
||||
- semantic report:
|
||||
`33c07f434de44fc536e8ba0ddbf98b3d4eb0b9056fe243e84dceed5ec6721bde`;
|
||||
- VC7 compiler:
|
||||
`483e00c47bb08d699475a642bcff15b5b2036350b31c540e88a506baf101da11`;
|
||||
- hardened comparator:
|
||||
`411e41698a9491a7b69430307d03f844ee3144633e5d3038d3ffde81a8eccfb7`;
|
||||
- regression gate:
|
||||
`d09b46dd2331ff7ca677cad78a66c780c4effa41a5389f0c614c9760d7632a5f`.
|
||||
|
||||
Supporting audits:
|
||||
|
||||
- admission SHA-256:
|
||||
`f0aa45c22cc604fb74abc388b06dd79a27e7a0b498a5d28837a9e785680c9a36`;
|
||||
- parked-frontier SHA-256:
|
||||
`cfac03aea5be607c19a6a40bcdbc1164e71ffb0179602af4bd37b3fd50e26d1d`.
|
||||
|
||||
## Canonical progress and gates
|
||||
|
||||
After regeneration:
|
||||
|
||||
- canonical code: 508,806/2,198,102 bytes and 4,215/11,060 functions;
|
||||
- complete files: 377/833;
|
||||
- Halo category: 495,892/1,770,166 code bytes and 4,048/7,574 functions;
|
||||
- Halo complete files: 275/468;
|
||||
- semantic audit: 470 units and 4,323 functions evaluated, 4,180 semantic
|
||||
exact, 114 hidden-exact functions / 64,705 hidden bytes, 4,241 accepted
|
||||
exact, and zero unit errors.
|
||||
|
||||
Repository gates:
|
||||
|
||||
- object admission: zero candidates and zero revocations; only the inherited
|
||||
`shell_xbox` completion-label contradiction remains;
|
||||
- parked validation: three active, zero stale, zero invalid;
|
||||
- tooling tests: 179/179 pass;
|
||||
- Halo and libcmt dry graphs: no work;
|
||||
- protected-path touches: zero;
|
||||
- deleted tracked paths: zero;
|
||||
- no push.
|
||||
|
||||
## House-rule audit
|
||||
|
||||
Every parameter is on its own line and both functions end with explicit value
|
||||
returns. The retained source is C89. It contains no assembly, `register`,
|
||||
`volatile`, barrier, pragma, explicit intrinsic, attribute, raw address,
|
||||
pointer/integer reconstruction, pointer or union pun, undefined behavior,
|
||||
synthetic anchor, or byte-forcing form. These functions perform no tag or
|
||||
object access, so the typed-access rules are not implicated.
|
||||
+119
@@ -0,0 +1,119 @@
|
||||
# `action_alert.obj`: setup store-order one-shot rejection (2026-08-30)
|
||||
|
||||
## Scope and result
|
||||
|
||||
This lane tested one independently sourced ordinary-C shape for
|
||||
`_action_alert_setup` and no other residual owner. The candidate was rejected
|
||||
after its first compile. The source was restored immediately; the object
|
||||
remains **5/12 exact** and **224/2240 padded bytes exact**.
|
||||
|
||||
The five inherited exact owners were rechecked after restoration:
|
||||
|
||||
- `_action_alert_begin`
|
||||
- `_action_alert_control`
|
||||
- `_vector_from_points3d`
|
||||
- `_magnitude_squared3d`
|
||||
- `_real_random_range`
|
||||
|
||||
## New premise
|
||||
|
||||
The fresh premise came from the readable Pastudan history at commit
|
||||
`1146f5b799111ab72f2f5e37303a4c050945b88b`, file
|
||||
`src/halo/math/vector_math.c` (the action-alert implementation around lines
|
||||
368-388 in that snapshot). Unlike the previously tested HCEA-derived shape,
|
||||
it preserves the January target's post-`csmemset` field-store order:
|
||||
|
||||
1. conditional `move_position_order`
|
||||
2. `target_move_position_index = NONE`
|
||||
3. `pending_move_position_index = initial_move_position_index`
|
||||
4. `move_position_increasing = TRUE`
|
||||
5. `wait_ticks = 0`
|
||||
6. `must_play_animation = FALSE`
|
||||
|
||||
The canonical declaration was retained unchanged:
|
||||
|
||||
```c
|
||||
boolean action_alert_setup(
|
||||
long actor_index,
|
||||
short move_position_order,
|
||||
long initial_move_position_index,
|
||||
struct alert_state_data *state_data);
|
||||
```
|
||||
|
||||
This was deliberately only a store-order adoption, not the complete Pastudan
|
||||
lift. The Pastudan snapshot's recovered formal sequence at line 372 is
|
||||
`int actor_handle, int value, short field, void *state`: its second argument is
|
||||
full width and its third is narrow. This lane retained the canonical
|
||||
`long, short, long, pointer` declaration rather than changing a cross-TU ABI
|
||||
as part of the source-shape test.
|
||||
|
||||
The body used typed fields, `actor_get`, the line-35 `state_data` assertion,
|
||||
`csmemset(state_data, 0, sizeof(*state_data))`, and the store sequence above.
|
||||
It used no inline assembly, `volatile`, `register`, pragmas, raw structure
|
||||
offsets, type punning, or byte-forcing constructs.
|
||||
|
||||
## Strict comparison
|
||||
|
||||
Only `build/base/source/ai/action_alert.obj` was scheduled; the Ninja dry run
|
||||
showed exactly one `CL` edge. The first and only candidate compile produced:
|
||||
|
||||
| Measurement | January target | Candidate |
|
||||
|---|---:|---:|
|
||||
| Padded section size | 128 | 128 |
|
||||
| Relocations | 7 | 7 |
|
||||
| Normalized SHA-256 | `225015f380c74c1a19d563730b7820375cd37490eb40cb6d67e3404bc46c9cc0` | `daee1bee0eae9da35692ad6ae86ae233ed996083745a65e1f1303842181b29c2` |
|
||||
|
||||
All seven relocation offsets and destinations were identical. The first
|
||||
normalized byte divergence was at section offset `+0x55`: target `0x03`,
|
||||
candidate `0x04`; 40 normalized bytes differed in total. The local contexts
|
||||
were:
|
||||
|
||||
- target: `0c84c0740433c0eb038b450c668b55106689065f66c74606`
|
||||
- candidate: `0c84c0740433c0eb040fbf450c668b55106689065f66c74606`
|
||||
|
||||
Decoded at `+0x54`, the target has `eb 03 8b 45 0c`: it jumps over a
|
||||
three-byte `mov eax, dword ptr [ebp+0x0c]`. The candidate has
|
||||
`eb 04 0f bf 45 0c`: it jumps over a four-byte sign-extending word load. The
|
||||
first miss therefore reflects the retained `short move_position_order`
|
||||
formal, not a difference in the Pastudan-derived post-memset store sequence.
|
||||
This is recorded as provenance evidence, not used as a tuning instruction.
|
||||
|
||||
The earlier rejected setup candidate was 144 padded bytes with seven
|
||||
relocations and normalized SHA-256
|
||||
`47b3dc2358c61240e9d48276b9d00caf88d8384cfc505e764f2929cf32ba7491`.
|
||||
The new provenance therefore improved the section extent and relocation
|
||||
topology, but strict byte identity still failed.
|
||||
|
||||
## Restoration and boundary
|
||||
|
||||
The setup body was removed immediately, the baseline object was rebuilt only
|
||||
to restore it, and `tools/coff_compare.py` reconfirmed all five inherited
|
||||
owners exact. The restored source blob is
|
||||
`8de8debb9ac7108acc7352c53e36e305f75d06f7`; the January split object SHA-256
|
||||
is `bb7a70aae881cdf5672ae48c3b9c5b7d0cdcc9a30a90730672f04b71fa1cab5f`.
|
||||
|
||||
Do **not** tune this Pastudan store-order candidate from the observed byte
|
||||
differences and do not retry it. Reopen `_action_alert_setup` only with a new,
|
||||
independent prototype/source-shape adjudication. A defensible future premise
|
||||
would need to establish the likely `long, long, short, pointer` prototype and
|
||||
its cross-translation-unit impact in `source/ai/actions.c`; the byte difference
|
||||
alone is insufficient. The two flush helpers,
|
||||
`_action_alert_update`, `_distance_squared3d`, `_action_alert_perform`, and
|
||||
`_code_00000950` were not compiled in this lane. In particular, current HCEA
|
||||
flush topology is not a new enough premise to override their existing
|
||||
fail-closed boundaries.
|
||||
|
||||
## Documentation and tooling consulted
|
||||
|
||||
- `docs/matching_methodology.md`
|
||||
- `tools/campaign/README.md`
|
||||
- `docs/object_matching_logs/README.md`
|
||||
- the three earlier `action_alert.obj` ledgers
|
||||
- repository `CLAUDE.md` guidance from the canonical, Stian, and Pastudan trees
|
||||
- January `build/split/source/ai/action_alert.obj`
|
||||
- `tools/coff_compare.py` and `tools/campaign/board.py`
|
||||
- current HCEA action-alert history and the Pastudan snapshot named above
|
||||
|
||||
The Discord note that Bungie's fast `ftol` may have been handwritten applies
|
||||
only as Matrix Math provenance. It did not alter this lane's ordinary-C-only
|
||||
admission rules.
|
||||
+193
@@ -0,0 +1,193 @@
|
||||
# Action Alert: restore genuine math-header ownership (2026-09-05)
|
||||
|
||||
## Disposition
|
||||
|
||||
Root has applied the single source-only normalization packet to canonical
|
||||
Action Alert. The actual full canonical Ninja build passes, and the complete
|
||||
stable sweep remains 6,217 exact functions out of 8,245, with zero losses.
|
||||
Root's actual all-section comparison and full tooling/tests also pass.
|
||||
The actual Ninja object is runtime-identical to the reviewed PID candidate:
|
||||
SHA-256 `c15f370e118de1a78c8cbcab7e3d4cd07f255d2c50af6c4b81e7c2cf391b46da`.
|
||||
The exact baseline-to-actual changes are only the three selection transitions
|
||||
and two unreferenced alias removals documented below. All 281 parks validate,
|
||||
the admission audit has no contradictions or revocations, and 288 tests plus
|
||||
26 subtests pass. The pytest cache permission warning affects only caching.
|
||||
Root evidence: `scratch/math-owner-schema-actual-action_alert-20260905.json`,
|
||||
`scratch/math-owner-schema-actual-summary-20260905.json`, and
|
||||
`scratch/math-owner-schema-canonical-first-20260905.json`.
|
||||
|
||||
The first natural candidate retains all
|
||||
11 strict exact functions, the identical existing complete residual, all six
|
||||
runtime data owners, and every gameplay ABI and instruction. No exact bytes
|
||||
are gained or lost. The object remains 11 exact / 1 residual / 0 unwritten,
|
||||
not whole-object Matching.
|
||||
|
||||
This is an ownership correction, not a new gameplay or residual experiment.
|
||||
Canonical production source, headers, configuration and build outputs were
|
||||
not changed by this worker.
|
||||
|
||||
## Source provenance and prior adjudication
|
||||
|
||||
Read in full before the test:
|
||||
|
||||
- `docs/matching_methodology.md` and `tools/campaign/README.md`;
|
||||
- `action_alert_obj_jonas_prefix_recovery.md`;
|
||||
- `action_alert_obj_jonas_safe_geometry_pair_20260826.md`;
|
||||
- `action_alert_obj_jonas_distance_squared_fixed_point_20260826.md`;
|
||||
- `action_alert_obj_jonas_setup_store_order_rejection_20260830.md`;
|
||||
- `action_alert_obj_complete_fuzzy_closeout_20260901.md`;
|
||||
- `action_charge_obj_jonas_math_helper_recovery_rejection_20260826.md`;
|
||||
- `action_charge_obj_jonas_math_helper_recovery_v2_20260826.md`;
|
||||
- `action_charge_obj_jonas_real_random_recovery_20260826.md`;
|
||||
- `game_sound_obj_obstruction_current_owner_boundary_20260905.md`.
|
||||
|
||||
The geometry-recovery ledger explicitly introduced local pre-header aliases
|
||||
and duplicate ordinary external math bodies to add selected code owners while
|
||||
the real gameplay callers were still unwritten. It described the macros as
|
||||
duplicate-definition avoidance; they nevertheless changed ordinary COMDAT
|
||||
ownership and now materialize two additional alias-named helper bodies.
|
||||
The complete 20260901 reconstruction introduced the genuine gameplay uses.
|
||||
|
||||
The old distance fixed point tested a fourth renamed wrapper, not removal of
|
||||
the existing alias layer to restore normal header topology. The old setup and
|
||||
next-position source-shape exhaustion is unrelated and is not reopened.
|
||||
No prior natural owner-header normalization experiment is documented in these
|
||||
ledgers. The new concrete premise is the demonstrated current canonical
|
||||
LNK2005 from Action Alert's ordinary selection-1 duplicate when natural real
|
||||
callers in Game Sound and Observer emit the same header API as selection 2.
|
||||
|
||||
`source/math/real_math.h` owns the actual APIs and bodies:
|
||||
|
||||
- line1027: `__inline real_vector3d *vector_from_points3d(...)`;
|
||||
- line1049: `__inline real magnitude_squared3d(...)`;
|
||||
- line1090: `distance_squared3d`, which genuinely invokes both above;
|
||||
- line1359: `__inline real real_random_range(...)`.
|
||||
|
||||
`source/ai/actions.h:12` already includes that header, and Action Alert also
|
||||
explicitly includes it. The existing distance callers in update, next-position
|
||||
and perform plus the random-range caller in perform naturally expose all
|
||||
three helpers. No synthetic caller, forced-inline annotation, compiler flag,
|
||||
header edit, or code-generation control is required.
|
||||
|
||||
## Exact minimal edit
|
||||
|
||||
Apply only the three replacement records in
|
||||
`scratch/action_alert_natural_math_owners_20260905.edits.json` to
|
||||
`source/ai/action_alert.c`:
|
||||
|
||||
1. Remove three pre-include `#define original original_inline` aliases.
|
||||
2. Remove their three corresponding `#undef` lines.
|
||||
3. Remove the duplicate ordinary external definitions of real_random_range,
|
||||
vector_from_points3d and magnitude_squared3d.
|
||||
|
||||
Every include, gameplay body, private declaration, type, constant, enum, and
|
||||
call remains untouched. This restores existing owner APIs; it does not add
|
||||
inlining or relax the January point_from_line3d schedule.
|
||||
|
||||
## First natural gate and full runtime audit
|
||||
|
||||
Commands from the canonical worktree, with ordinary per-TU flags:
|
||||
|
||||
```text
|
||||
python tools/campaign/gate.py source/ai/action_alert --all --out scratch/action-alert-natural-math-baseline-replay-20260905.obj --forbid-emitted-symbol _point_from_line3d
|
||||
python tools/campaign/gate.py source/ai/action_alert --edits scratch/action_alert_natural_math_owners_20260905.edits.json --all --out scratch/action-alert-natural-math-first-20260905.obj --forbid-emitted-symbol _point_from_line3d
|
||||
python scratch/action_alert_natural_math_owner_audit_20260905.py
|
||||
python scratch/action_alert_natural_math_link_review_20260905.py --scan --link
|
||||
```
|
||||
|
||||
Exactly one untouched baseline replay and one natural changed compile were
|
||||
used. No source retry followed. Both gates report 11E/1R/0U and no forbidden
|
||||
point_from_line3d owner. The residual next-position remains 768 candidate
|
||||
versus 784 target padded bytes; its complete section fingerprint is unchanged.
|
||||
|
||||
The complete all-section audit includes anonymous/code/data/debug/directive
|
||||
sections, COMMON and symbol inventories, offsets, storage and type, section
|
||||
flags and selection, and ordered relocations including full target-symbol
|
||||
metadata. It does not mistake function-only equality for whole-owner equality.
|
||||
|
||||
- Target:12 code owners,6 data owners.
|
||||
- Actual baseline and untouched replay:14 code owners,6 data owners.
|
||||
- Candidate:12 code owners,6 data owners.
|
||||
- No new runtime owner, no COMMON owner or COMMON change.
|
||||
- The only removed runtime owners are `_vector_from_points3d_inline` and
|
||||
`_magnitude_squared3d_inline`, each48 padded bytes. Neither exists in January.
|
||||
- The only inherited runtime changes are COMDAT selection1 to selection2 for
|
||||
the three actual public math helpers. Each is otherwise completely identical
|
||||
in bytes, ordered relocations, symbol metadata/offsets and section flags.
|
||||
- All other inherited code, data and runtime records are completely identical,
|
||||
including the parked body; there is not even a compiler-local-label change.
|
||||
- Actual baseline and untouched PID replay have no runtime differences.
|
||||
- COFF runtime header characteristics are unchanged. Debug/output-path records
|
||||
are separately preserved in the raw audit and are not runtime credit.
|
||||
|
||||
The target selection1 metadata is retained in the audit. This packet does not
|
||||
patch csplit metadata or claim that its original source-object selection was
|
||||
recovered from the linked January image. The natural header source generates
|
||||
ordinary select-any owners and repairs real current-source ownership debt.
|
||||
|
||||
## All-owner census and ordinary link checks
|
||||
|
||||
The census parsed all833 configured January targets and572 actual canonical
|
||||
bases, with zero errors. Among current base definitions:
|
||||
|
||||
| Helper | Base owners | Selection-1 owners |
|
||||
|---|---:|---|
|
||||
| vector_from_points3d |51|Action Alert only|
|
||||
| magnitude_squared3d |67|Action Alert only|
|
||||
| real_random_range |8|Action Alert only|
|
||||
|
||||
Every other base copy is selection2. Both alias-named extras exist only in
|
||||
Action Alert; there are zero incoming relocations to either alias across all
|
||||
target and base objects. Their removal cannot leave a referenced alias owner
|
||||
unresolved.
|
||||
|
||||
All magnitude and random-range copies have the January size/hash. Fifty
|
||||
vector copies have the January hash; the existing Breakable Surfaces copy has
|
||||
hash `a947d351c7b0abf577d0b6e41f02a4f0a7418104d3099e62f6835a862b355b57`.
|
||||
That frozen48-byte/zero-relocation copy differs only by moving the argument
|
||||
load `mov edx,[ebp+8]` before rather than after the first FLD. All26 decoded
|
||||
instructions and dataflow otherwise agree. It uses the actual real_math.h
|
||||
API and is semantically/ABI equivalent, not byte-identical. No expression or
|
||||
source change was made to suppress or force this ordinary pooled copy.
|
||||
|
||||
Ordinary XDK Link.Exe `/NOLOGO /DLL /NOENTRY /NODEFAULTLIB` tests with unchanged
|
||||
frozen natural Action Alert + Game Sound and Action Alert + reviewed Observer,
|
||||
each in both input orders, now have no LNK2005. The previous actual-baseline
|
||||
Game Sound pair has LNK2005 in both orders in its durable rejection ledger.
|
||||
The new runs still end in expected unrelated LNK1120 unresolveds (57 for Game
|
||||
Sound,40 for Observer), and none produces a DLL. Thus this is a passed bounded
|
||||
duplicate-symbol check, not successful whole-link proof. No /FORCE, /IGNORE,
|
||||
object patches, synthetic stubs, header shim or linker accommodation is used.
|
||||
|
||||
## Frozen evidence
|
||||
|
||||
All following paths are relative to the canonical worktree.
|
||||
|
||||
| Artifact | SHA-256 |
|
||||
|---|---|
|
||||
| scratch/action-alert-natural-math-target-20260905.obj |351ff0de9ddfea9b3c03a9038abab75b0c4b48290443b33e09c33105b41ab61a|
|
||||
| scratch/action-alert-natural-math-before-20260905.obj |b82fd9a16f40c01fc45ac810240ad9ea9e02287ae629827c01306b17f7e38d30|
|
||||
| scratch/action-alert-natural-math-baseline-replay-20260905.obj |35bbfb9e7f3f0690af27b6772189d4360e1fbddad71ba81b57b98f027397f549|
|
||||
| scratch/action-alert-natural-math-first-20260905.obj |62ffdb7cd1e7c082b6f03216d4c10bc3437a8f3d0d11d01ba454b0981fc8ac44|
|
||||
| scratch/action_alert_natural_math_before_20260905.c |3a57d07c1c1173cb26903ca40da1b4fc714d11779e65e34bfe8e6f7a40e1ce6d|
|
||||
| scratch/action_alert_natural_math_candidate_20260905.c |27d9268805f0e92024ec10304fbb3dee1398d54055cfb01219d8796f7f0f28af|
|
||||
| scratch/action_alert_natural_math_owners_20260905.edits.json |a91e4428803f9cc697e4d06b52abfbe82c69f8425b9d518360dede80a9624374|
|
||||
| scratch/action_alert_natural_math_owner_audit_20260905.json |9c4bcb9e971e188518b8dda1a9ea20d894bfbd56f12e7fd7e7426902a5eef889|
|
||||
| scratch/action_alert_natural_math_all_owners_20260905.json |737872e034ecd35ee428462306ed87cf6b12f244413944be5625f4701c07ac92|
|
||||
| scratch/action_alert_natural_math_ordinary_links_20260905.json |f1b5c5d828edd62cffa6882d9469c59f50c14a2d985547394852c9a4c169d682|
|
||||
|
||||
## Canonical integration status
|
||||
|
||||
Root read the complete source packet, manifest and primary scratch ledger,
|
||||
then applied only the minimal Action Alert source removals. The full canonical
|
||||
Ninja build passes. The complete stable sweep reports 6,217 exact functions
|
||||
out of 8,245, with zero exact losses and no new exact credit from this cleanup.
|
||||
These are actual canonical results, separate from the frozen scratch results
|
||||
above.
|
||||
|
||||
Full actual runtime-owner comparison and the remaining tooling/tests are
|
||||
pending at the time this durable ledger is authored. Root must complete those
|
||||
checks before treating this batch as fully verified. The existing residual
|
||||
and park remain unchanged, and no whole-object completion or new-byte claim
|
||||
is made. The ordinary two-object linker diagnostics above remain bounded
|
||||
duplicate checks, not a successful full-game link.
|
||||
@@ -0,0 +1,95 @@
|
||||
# action_alert.obj — opus5 150K lane, wave w2 (2026-09-14)
|
||||
|
||||
## Baseline and final
|
||||
|
||||
| gate | result |
|
||||
| --- | --- |
|
||||
| baseline real file | `== exact 11 residual 1 unwritten 0`, guard passes |
|
||||
| final real file (unchanged) | `== exact 11 residual 1 unwritten 0`, guard passes, park drift 0, fake scan 0 leads |
|
||||
|
||||
`git diff --stat -- source/ai/action_alert.c` is empty. No credit is claimed.
|
||||
|
||||
## `_action_alert_next_position` (parked, register-allocation)
|
||||
|
||||
Target 784 / 18 relocs / nsha `677fd6cc1a9e66de`; real-file candidate 768 / 18 / `4e16c85b544ded33`.
|
||||
|
||||
### New evidence
|
||||
|
||||
Aligned diff of the real file:
|
||||
|
||||
- January preloads `or eax,0xffffffff` before the `vehicle_passenger` test (3 B).
|
||||
- January's NONE returns are 32-bit (`mov eax,0xffffffff` on the no-position tail, `or eax,-1` in the guard return block at +0x2f8).
|
||||
- The encounter guard jumps past that block because EAX already holds -1.
|
||||
|
||||
Measured VC7 facts:
|
||||
|
||||
- `return NONE;` in a `short` function emits a 16-bit `or ax,0xffff`. So does `return result;` when result is constant-propagated (d7).
|
||||
- Only an assignment to a `short` result variable emits the 32-bit form.
|
||||
|
||||
The function is therefore single-exit (brief section 9 single-exit law). The earlier park probes had not tested this with the complete assignment topology.
|
||||
|
||||
### Shapes
|
||||
|
||||
| shape | result |
|
||||
| --- | --- |
|
||||
| v1: init `result = NONE`, three-way `&&` guard, `if (any) {...}`, `result = next` | 784/18 `2c7d5520` (shrink-wrapped pushes, result in ECX) |
|
||||
| v2: nested guard; v3: result merged into `next_position_index` | identical to v1 |
|
||||
| v4: no init, `else { result = NONE; }`, `if (!any) result = NONE;` | 768/18 `6ac81fbc` (guards merged into one block, no preload) |
|
||||
| v5: nested if/else; n1: `else if (encounter == NONE) result = NONE;` | identical to v4 |
|
||||
| diagnostic d5: guards `return NONE`, init, no-position store, loop `return` | 1 instruction off (`or ax,0xffff`) |
|
||||
| diagnostic ea: ec without the no-position store | frame 0x24, wrong |
|
||||
| **ec / d10** | **strict EXACT 784/18 `677fd6cc`; whole TU 12/12 exact** |
|
||||
|
||||
The ec / d10 body:
|
||||
|
||||
```c
|
||||
short result = NONE;
|
||||
|
||||
if (actor->input.vehicle_passenger || move_position_order == _move_position_order_none)
|
||||
{
|
||||
result = NONE; /* redundant with the initialiser */
|
||||
}
|
||||
else if (actor->meta.encounter_index != NONE)
|
||||
{
|
||||
/* encounter/squad lookup, swarm assert */
|
||||
if (move_position_order == _move_position_order_repeat && current_position_index != NONE)
|
||||
result = current_position_index;
|
||||
else
|
||||
{
|
||||
/* availability scan (unchanged) */
|
||||
if (!any_position_available)
|
||||
result = NONE; /* redundant with the initialiser */
|
||||
else if (move_position_order == _move_position_order_random)
|
||||
result = choose_random_array_element(...);
|
||||
else
|
||||
{
|
||||
/* clamp + do/while traversal (unchanged) */
|
||||
result = next_position_index;
|
||||
}
|
||||
}
|
||||
}
|
||||
return result;
|
||||
```
|
||||
|
||||
Scratch candidate: `scratch/workers/model_animations_actor_stimulus_etc/aa_ec.c` (patch `aa_ec.patch`). Its checks:
|
||||
|
||||
- the 11 siblings stay exact;
|
||||
- the `_point_from_line3d` guard passes;
|
||||
- parkcheck reports drift only on the park itself;
|
||||
- fake scan finds 0 leads (the scanner does not detect redundant stores);
|
||||
- the function set is unchanged.
|
||||
|
||||
### Disposition
|
||||
|
||||
This is not proposed as an admissible reopen. Exactness requires two NONE stores that the initialiser already guarantees. Every non-redundant spelling measured returns to a different fixed point (v1-v5, n1, d11). Brief section 5 prohibits redundant stores. Previous verifiers rejected the `_action_vehicle_desirable` and `_action_obey_command_begin` re-stores. `_extract_sequence` (January-proven redundant logic) was also left parked. This is an **owner-ruling item**.
|
||||
|
||||
### Reopen criterion
|
||||
|
||||
Either of:
|
||||
|
||||
- an owner ruling that admits January-proven redundant default-result stores (land the aa_ec.c body with a disclosure comment and unpark);
|
||||
- a non-redundant spelling that produces the separate 32-bit NONE materialisations.
|
||||
|
||||
## Do-not-repeat
|
||||
|
||||
v1-v5, n1, d11 (no-init explicit else after the encounter branch), and ea.
|
||||
@@ -0,0 +1,202 @@
|
||||
# ActionCharge: authentic math owners and private names (2026-09-06)
|
||||
|
||||
## Result and scope
|
||||
|
||||
Starting at published `71128a19fc9707f678f970e380b97ee3181db05e`, remove the
|
||||
reconstructed ActionCharge-only alias/duplicate-definition packages for
|
||||
`square_root` and `magnitude_squared2d`. Their existing, identical definitions
|
||||
in `source/math/real_math.h` now supply the ordinary source call sites.
|
||||
The header itself is unchanged. No implementation body is rewritten or tuned.
|
||||
|
||||
Both helpers still materialize and remain strict exact on the first natural
|
||||
compile. All **20 inherited exact ActionCharge functions** survive. The
|
||||
688-byte candidate `action_charge_setup` residual is also byte/relocation
|
||||
identical to its pre-trial version; `action_charge_perform` remains unwritten.
|
||||
ActionCharge remains **20 exact / 1 residual / 1 unwritten**, not complete.
|
||||
|
||||
Across the campaign all **6,271 strict functions** survive. Meaningful exact
|
||||
code remains **919,549 bytes**, credited functions **6,225**, matched data
|
||||
**2,061,024 bytes**, and Matching objects **391/833**. This is source-ownership
|
||||
progress, **zero new function/byte credit**. The helper bodies were already
|
||||
counted; changing their owner representation does not count them again.
|
||||
|
||||
## Why this is authentic reconstruction
|
||||
|
||||
The source previously renamed these two header functions before including
|
||||
`actions.h`, undefined the aliases afterwards, and supplied duplicate external
|
||||
C definitions. The historical recovery ledgers explain that those packages
|
||||
were introduced during reconstruction to reproduce selected-object helper
|
||||
ownership. They are not original source evidence. Review included the
|
||||
2026-08-26 math-helper rejection and wave-2 ledgers, real-random recovery,
|
||||
the 2026-08-28 public residual recovery, and 2026-08-29 helper reintegration.
|
||||
|
||||
HCEX's actual debug records authenticate `real_math.h` ownership and report
|
||||
`WasSpecifiedAsInline=true` and `WasInlined=true` for both functions:
|
||||
|
||||
- `square_root`: RVA 0x169DC28, source lines 644-646;
|
||||
- `magnitude_squared2d`: RVA 0x169DC50, source lines 733-739.
|
||||
|
||||
Use `research/tools/DIA2Dump/x64/Release/DIA2Dump.exe -sym <name>` and
|
||||
`-lines <name>` against
|
||||
`research/hcea_jun2011_prototype/payload/Halo CE Anniversary (Jun 24 2011)/HCEX_Release.pdb`,
|
||||
relative to the outer `i-w` workspace. Both line records name
|
||||
`d:\projects\code\hcex\sources\math\real_math.h`, source MD5
|
||||
`DE0F004C6EB037D8BE384822F84E002C`.
|
||||
|
||||
The January symbol atlas at
|
||||
`research/halo-symbol-atlas/symbols/halo_ce/4cc87b45f721270392a96f1674ed2b5cd4a7bb4355faeab4531d1cf1884d9520.jsonl`
|
||||
marks adjacent `normalize2d`, `magnitude3d` and `normalize3d` as inline
|
||||
functions selected from ActionCharge. It omits these smaller two symbols;
|
||||
do not misrepresent that omission as direct January name/inline evidence.
|
||||
January's actual helper bytes and the current header bodies independently
|
||||
agree; the original selected COFF representation is not proof of a hand-written
|
||||
external wrapper in the original C file.
|
||||
|
||||
Current ordinary call sites justify retention without a fabricated anchor:
|
||||
`magnitude2d` calls `square_root(magnitude_squared2d(v))`, and `magnitude3d`
|
||||
calls `square_root` on the three-component squared magnitude. Reuse those
|
||||
unaltered calls and the existing ordinary header definitions. No new inline
|
||||
annotation, static-inline conversion, qualifier, forced emission, new source
|
||||
alias, compiler switch, object patch or comparator exception is introduced.
|
||||
|
||||
## Full compiled-object proof
|
||||
|
||||
Root's complete before/first ordinary COFF fingerprint comparison finds
|
||||
**38 COFF sections: 36 unchanged and exactly two ownership changes**
|
||||
(34 unchanged non-debug sections plus both unchanged debug sections).
|
||||
Only the COMDAT selection of `square_root` and `magnitude_squared2d` changes
|
||||
from NODUPLICATES (1) to SELECT_ANY (2). Every executable/data byte, relocation,
|
||||
symbol name/storage, debug section, COMMON owner and other runtime header
|
||||
property is unchanged. No section is added or removed. The existing selected
|
||||
`point_from_line3d` body is unchanged; there is no new copy or inline scheduling
|
||||
change. The first gate retains both exact helpers and all inherited functions.
|
||||
|
||||
Normalized helper hashes remain:
|
||||
|
||||
- `square_root`, 16 padded bytes, zero relocations:
|
||||
`0717923dacb4356a94553a32f0ba8a314904fae6d7d0bfc42ecc4af6f10415b7`;
|
||||
- `magnitude_squared2d`, 32 padded bytes, zero relocations:
|
||||
`9d8460618a63e41e020b2ce8071486fe278a849abccad44e5ea444da9700d014`.
|
||||
|
||||
The genuine header is unchanged, so no other translation unit needs a source
|
||||
rebuild. A full Ninja run compiles ActionCharge and regenerates the campaign
|
||||
reports. In this owner-only phase, all other current base objects and every
|
||||
selected target remain identical to the frozen baseline. The full strict census has zero
|
||||
gains and zero losses. **650 tests plus 26 subtests** pass; parks remain
|
||||
**297 active / zero stale / zero invalid**. Admission retains five existing
|
||||
rejections and has zero candidates, contradictions or revocations. The source
|
||||
has zero fake-match scanner leads.
|
||||
|
||||
## Current owner census and actual link outcomes
|
||||
|
||||
The complete 572-base-object census now finds 60 `square_root` definitions
|
||||
and 15 `magnitude_squared2d` definitions, **all SELECT_ANY**, with identical
|
||||
target-correct bytes within each family. There is no remaining NODUPLICATES
|
||||
definition for either name. `dot_product2d` remains seven identical definitions:
|
||||
ActionCharge's one NODUPLICATES and six SELECT_ANY copies.
|
||||
|
||||
Root's actual VC7 `/DLL /NOENTRY /NODEFAULTLIB` links of the frozen complete
|
||||
PathObstacles and ActionCharge objects, in both input orders, now report only
|
||||
`dot_product2d` as LNK2005. The previous `square_root` and
|
||||
`magnitude_squared2d` duplicate errors are gone. The expected 23 unrelated
|
||||
unresolved dependencies remain and no successful full engine link is claimed.
|
||||
No forced-multiple-definition flag, object suppression or synthetic stub
|
||||
removes the remaining conflict.
|
||||
|
||||
## Authenticated private names, without behavior changes
|
||||
|
||||
After freezing and verifying the two-owner restoration, a separate `named`
|
||||
phase replaces exactly two address placeholders in declarations, definitions,
|
||||
calls and the symbol comment:
|
||||
|
||||
| January file offset | Old placeholder | Authentic private name |
|
||||
| ---: | --- | --- |
|
||||
| 4304 | `code_000010d0` | `action_charge_find_target_range` |
|
||||
| 9168 | `code_000023d0` | `action_charge_valid_melee_destination` |
|
||||
|
||||
The exact January atlas cited above supplies both names at lines 7 and 14,
|
||||
each attributed to ActionCharge. HCEX Release DIA independently identifies
|
||||
both as static and not specified inline, with source lines 821-854 and 860-901
|
||||
in `d:\projects\code\hcex\sources\ai\action_charge.c`. The source was already
|
||||
static; the two matching `config/symbols.json` entries now record the genuine
|
||||
names and `static: true` rather than csplit's default external ownership.
|
||||
|
||||
The source argument types and all executable statements remain unchanged.
|
||||
In particular, the melee destination's second argument remains
|
||||
`real_point3d const *goal`: HCEX's `short goal` type metadata is contradicted
|
||||
by actual January point loads and by the later decompiler's own corrected
|
||||
body. January reads `[ESI]`, `[ESI+4]` and `[ESI+8]`, while its caller supplies
|
||||
the prop's center of mass. Do not import the erroneous short signature.
|
||||
|
||||
January's helper does not access or write through `melee_target_point`, and
|
||||
the caller never consumes that discarded local. The HCEA semantic body and
|
||||
caller corroborate this. Keeping `(void)melee_target_point;` therefore
|
||||
preserves actual behavior; do not invent an output write or use the parameter
|
||||
name as proof of missing executable logic. Whole-TU optimization could remove
|
||||
historical dead stores, so the audit does not claim to prove the original text
|
||||
never contained an assignment.
|
||||
|
||||
Root's full before-name/after-name fingerprint comparison reports all **38
|
||||
runtime sections unchanged**, once the two authenticated symbol identities
|
||||
are mapped for comparison. No instruction, literal, data, relocation offset,
|
||||
addend, debug record or ownership change exists in the base object beyond
|
||||
those names. The selected target changes names and the two static-storage
|
||||
records. Across all 1,405 current objects, only the ActionCharge base and
|
||||
selected target hashes change; every other object is byte-identical. The
|
||||
full rebuild and strict census again preserve all 6,271 exact functions.
|
||||
This audit-name mapping is not a comparator exception or new byte credit.
|
||||
|
||||
## Remaining boundary
|
||||
|
||||
`dot_product2d` has the same authenticated header-inline provenance, but no
|
||||
live source caller in current ActionCharge. Its real use belongs to the still
|
||||
unwritten `action_charge_perform`. Do not invent a caller or a retention anchor
|
||||
to make an uncalled header definition materialize. Its old duplicate-definition
|
||||
package remains outside this two-owner restoration and needs the genuine
|
||||
caller closure. Other inherited ActionCharge aliases/prototype
|
||||
debts are not certified by this patch, and the large residual is not reopened.
|
||||
|
||||
This does not claim a complete engine link or whole-object admission. It
|
||||
reconciles two real duplicate-owner families while preserving all compiled
|
||||
behavior and accounting. Active Opus implementations and donor worktrees are
|
||||
untouched. Original binary evidence and temporary link outputs stay local.
|
||||
|
||||
## Frozen evidence
|
||||
|
||||
Two independent post-implementation audits pass. The owner audit replays the
|
||||
full before/first COFF comparison, verifies all 572 named-phase base objects,
|
||||
and runs the actual VC7 diagnostic links in both orders. Its script hard-pins
|
||||
the imported comparison tools and linker. The separate private-name audit
|
||||
checks all section and relocation records, caller targets/addends, exact source
|
||||
and config changes, and all 1,405 current base/selected object hashes.
|
||||
|
||||
- Owner replay script: `scratch/action_charge_two_owner_postimplementation_audit_20260906.py`,
|
||||
SHA-256 `0cc2e805f87cc55920a6bc3202aa284185e36374cbd7eb335e5c1ad15e86fa9d`.
|
||||
- Independent owner report: `scratch/action-charge-two-owner-postimplementation-audit-final-20260906.json`,
|
||||
SHA-256 `096b850bd6c00d0e3b8692dea0fbe0ad4e4789556a868a78ab84ed9b8dc9a397`.
|
||||
- Independent private-name report: `scratch/action-charge-private-name-postimplementation-independent-20260906.json`,
|
||||
SHA-256 `380291ccd1dd183ca88231dd08b2b68f5aae04639e60fdfffc767006228b11a4`.
|
||||
|
||||
These reports are local frozen evidence, not target binaries to distribute.
|
||||
Both audits preserve the distinction between the remaining `dot_product2d`
|
||||
link conflict and the two genuinely resolved duplicate-owner families.
|
||||
|
||||
- Baseline: `scratch/action-charge-math-owner-before-20260906.json`,
|
||||
SHA-256 `34ccf1a6d5e32b4348364235802ba488b62c48317e83c45d0317f9fdc93fa4dc`.
|
||||
- First: `scratch/action-charge-math-owner-first-20260906.json`,
|
||||
SHA-256 `fd64316616dca63d976bd3c9ca367b9061a69e80ae0c28f27e61a443cdd210d5`.
|
||||
- Final: `scratch/action-charge-math-owner-final-20260906.json`,
|
||||
SHA-256 `a81dcaced90b94c6726aa7004b04bb56213c2f2208efe21a8b1898771183d7c5`.
|
||||
- Before C/base object: `e8096e28a0a821ae5f97b0461c61ae6f828f51037b0cb62b75f5b1d8fb0be366` /
|
||||
`45c5386b96ba99b67834dd3ffd85e797dc5fdb8385db4cd4ab1e73d006f8df6d`.
|
||||
- Pre-name two-owner C/base object: `5f182feceec9ccf33d2d8eade40c88db42c697cbfe4d26f5682fce3121bd193a` /
|
||||
`8c19c85deb223ff89aeaed6ff768e192139e040496c853b1fb91e31eef5c315b`.
|
||||
- Unchanged math header: `4e640d1be7b2c843dc7c9acb198afcd5d7d390eb310e5e14eedd484cf99535d4`.
|
||||
- `scratch/action-charge-math-owner-{before,first}-stable-20260906.json`:
|
||||
6,271 strict functions, zero gains/losses.
|
||||
- Named final: `scratch/action-charge-math-owner-named-20260906.json`,
|
||||
SHA-256 `1d4305f1d603e619889f2e94dd282ca40a364d3115ea447ddb579a7c7e257a88`.
|
||||
- Named final C: `75961e822a451f5d23910def9cc4661e1fbd0bdefa9caa314f776cf0aa21e81d`;
|
||||
base object: `cecd4d02fc1dbcf8a355ef289899f7230bd3463b3299abe486cb36ee871ef371`;
|
||||
selected target: `a906f0ec24b0313a056d4a413eaf85ee32f22f02c45878261bcae4521bfa63c8`;
|
||||
symbols configuration: `57d80ec4aa5d567067f97ac9f4552bba4d85dc777201d480fdadd47f93b06ccf`.
|
||||
Loaded 100 of 7750 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user