QOLLOCK (Deadlock Panorama Source 2 Mod)

This repository contains the source for the QOLLOCK HUD/UI mod for Deadlock, built on Panorama (XML/CSS/JS) in Source 2.

Context Docs (Read First In New Sessions)

Start with Architecture and AI contributor guide for runtime contexts, file ownership, configuration, lifecycle and verification limits. Before changing runtime code, read HELPERS.md, then the actual helper implementation and a caller in the same script context. Read the relevant feature/core/UI document for the task; read LOCALIZATION.md when changing visible text and ADDING_SETTINGS.md when changing settings. There is no need to read every document for every task.

The architecture guide is the consolidated entry point. Use these focused references for implementation details; historical migration notes are not the current runtime contract:

• Existing helpers and their contracts
• Localization contract and translation workflow
• Adding settings
• Preset and binding maintenance
• Panorama pitfalls
• Performance guardrails
• Offline checks and their limits
• Maintainer release checklist
• Open tasks

Build / Pack / Launch

Compilation, VPK repacking and game installation are maintainer-only. Agents must not run the build scripts or resourcecompiler.exe, modify game addons, or create/modify VPKs. The commands below document the maintainer's workflow; they are not permission for an agent to execute it.

First-time setup

After cloning, run once to install git pre-commit hooks:

bash setup-hooks.sh

This validates JS imports and runs the smoke test before every commit. Skip with: QOLLOCK_SKIP_HOOKS=true git commit ...

Regular workflow

Use:

build_mod/build_mod.bat (Windows), or build_mod/build_mod.ps1 directly.

At the build destination prompt, enter 1 for a local VPK or 2 for the game addons folder. Add f or -f for a clean rebuild (for example, 1 f or 2 -f). Enter s to start Deadlock, r to restart it, or 0 for build tool settings. The build tool compiles Panorama .svg sources to .vsvg_c assets.

Project expectation:

• close Deadlock
• compile changed files
• pack
• launch Deadlock once at the end

Publishing a public release

QOLLOCK's Settings version does not change for every release, so it is not used to detect updates. Before publishing a build to GitHub, Discord or another public channel, use the public qollock-updates repository:

1. Read its Current release marker and choose the next whole number.
2. Set QOL_UPDATE_MARKER in panorama/scripts/ql_update_checker.js to that same number.
3. In the public repository's Actions tab, run Publish QOLLOCK update marker with that number. Leave Dry run off.
4. Wait for the workflow's green checkmark, then pack and publish QOLLOCK.

The Action creates the new current marker, retires all old markers and updates its README automatically. No image editing or manual upload is required. Do this for every public release, even when the Settings version stays the same.