# openQ4 Agent Guide

This file describes project goals, rules, and upstream credits for anyone working on openQ4.

**Project Metadata**
- Name: openQ4
- Author: themuffinator
- Company: DarkMatter Productions
- Version: 0.1.010
- Website: `www.darkmatter-quake.com`
- Repository: `https://github.com/themuffinator/openQ4`
- Companion GameLibs Repo (local): `E:\Repositories\openQ4-game`

**Goals**
- Deliver a complete, open-source code replacement for Quake 4 (engine + game code).
- Preserve behavior required by the shipped Quake 4 assets (base PK4s) where practical.
- Maintain full single-player and multiplayer parity with in-tree game code.
- Modernize the engine and game code while keeping stock-asset compatibility as a guiding constraint.
- Package both SP/MP under one unified game directory (`baseoq4/`) with `game_sp` + `game_mp`.
- Establish a cross-platform foundation targeting modern systems (Windows, Linux, macOS; x64 first) through SDL3 and Meson.
- Keep Quake4SDK-derived game-library source ownership in `openQ4-game`, with openQ4 consuming those sources directly at build time.
- Keep BSE source integrated in-tree under `src/bse/` and treat it as first-party openQ4 code.

**Rules**
- Do not target compatibility with the proprietary Quake 4 game DLLs; openQ4 ships its own game modules and keeps full freedom to evolve the project.
- Treat `E:\Repositories\openQ4-game` as part of the same development workspace for planning, edits, and validation.
- For SDK/game-library work, make canonical source edits in `openQ4-game` first; openQ4 loads game sources from that companion repo and should not mirror them under `src/game`.
- Treat `src/bse/` as the canonical BSE source location.
- Build BSE into the client executable; do not reintroduce an external `openQ4-BSE_<arch>` runtime module without an explicit project decision.
- Dedicated server builds keep the disabled BSE manager path unless a change proves they genuinely need the full effect runtime.
- Keep `baseoq4/` as the single unified game directory; do not split SP/MP into separate mod folders.
- Keep repo-authored runtime overrides under `content/baseoq4/`; treat `.install/baseoq4/` as staged output rather than an editing target.
- Prefer changes that match Quake 4 SDK expectations and shipped content behavior.
- Document significant changes in the documentation and keep `README.md` accurate.
- Treat release changelog maintenance as part of feature completion. User-facing curated release notes belong in `docs/dev/releases/vX.Y.Z.md`, and the manual release workflow will publish that file when it exists.
- Write release notes for end users first: lead with the visible benefit, call out any action or compatibility note the reader needs, and avoid dumping internal implementation trivia unless it materially helps the audience.
- Use `builddir/` as the standard Meson build output directory for local builds, VS Code tasks, and launch configurations.
- Never add VS Code `preLaunchTask` entries to launch configurations; launch tasks must remain direct game launches.
- Treat `.install/` as the release-style package root; stage built binaries into `.install/` and `.install/baseoq4/`.
- Keep game-module outputs available under both `builddir/baseoq4/` (direct run) and `.install/baseoq4/` (staged package).
- Keep `.install/` focused on runtime/staged content: engine executables in `.install/`, game DLLs and staged overrides/assets in `.install/baseoq4/`.
- Do not rely on `.install/` as a linker artifact store; keep compiler/linker intermediates and development-only outputs in `builddir/`.
- MSVC import libraries (`*.lib`) are not runtime requirements for openQ4 execution; prefer keeping them in `builddir/` (or other developer artifact output), not in release-style `.install/` packages.
- Use `meson install -C builddir --no-rebuild --skip-subprojects` (via `tools/build/meson_setup.ps1`) when staging `.install/` to avoid third-party subproject installs outside the package tree.
- `tools/build/meson_setup.ps1` can trigger SDK/game-library builds in `../openQ4-game` during `compile` when `OPENQ4_BUILD_GAMELIBS=1`; openQ4 no longer syncs a local `src/game` mirror.
- On Windows, do not invoke raw `meson ...` from an arbitrary shell; use `tools/build/meson_setup.ps1 ...` (or run `tools/build/openq4_devcmd.cmd` first) so `cl.exe`/MSVC tools are always available.
- Prefer platform abstractions through SDL3 and avoid introducing new platform-specific dependencies in shared engine code when an SDL3 path exists.
- Keep Meson as the primary build entry point and keep dependency management through Meson subprojects.
- Treat x64 as the baseline architecture for active support while staging additional modern architectures incrementally.
- Keep credits accurate and add new attributions when incorporating upstream work.
- Localize all user-facing UI text: never introduce hardcoded display strings in GUIs/UI code when a `#str_*` lookup is possible; add/update language-table entries whenever new text is needed.
- Avoid adding engine-side content files (e.g., custom material scripts) unless absolutely required for compatibility; the goal is to run with the original game assets and only openQ4 binaries (engine + game modules, plus minimal external libs).
- Any existing custom `q4base/` content is treated as an expedient bootstrap, not a long-term solution. The goal is to remove this reliance by fixing engine compatibility issues rather than shipping replacement assets.
- For investigations, reference the log file written by `logFileName` (VS Code launch uses `logs/openq4.log`), located under `fs_savepath\<gameDir>\` (e.g. `${workspaceFolder}\\.home\\baseoq4\\logs\\openq4.log`).
- For runtime validation, use mode-specific launch tasks: use the SP launch task for single-player testing and the MP launch task for multiplayer testing.
- Do not treat main-menu startup as sufficient validation; enter in-game/map gameplay relevant to the change before concluding tests.
- For macOS testing/debugging, use the compliant Apple-hardware VM/host workflow in `docs/dev/macos-vm-testing-workflow.md` and `tools/macos/Invoke-openQ4MacOSWorkflow.ps1`. Keep macOS installer/restore-image inventory under `E:\ISO\macos\`. Do not use Windows VMware macOS unlocker/Hackintosh-style setup guides for openQ4 automation.
- Use `.tmp/` directory in repository for any temporary files required for tasks.
- Always consider cross-platform compatibility for any changes.

**.install/ Folder Layout (Staging Target)**
- `.install/` is the runtime package root used by local staging and `fs_cdpath` overlays.
- Keep executable/runtime artifacts here (for example `.install/openQ4-client_x64.exe`, `.install/openQ4-ded_x64.exe`, `.install/baseoq4/game-sp_x64.dll`, `.install/baseoq4/game-mp_x64.dll`).
- Stage editable override content under `.install/baseoq4/` (for example GUI scripts in `.install/baseoq4/guis/`).
- Avoid shipping build-only linker artifacts in `.install/`; keep `*.lib` in `builddir/` unless intentionally producing a developer SDK artifact set.

**Development Procedure (Correct Direction)**
1. Develop against the installed Quake 4 assets only (base PK4s), not repo `q4base/` content.
2. Prefer launching from the repo `.install/` directory so locked `fs_cdpath` targets staged openQ4 overlays; use a different working directory only when intentionally testing stock-only behavior.
3. If something is missing or broken, fix the engine/game/loader/parser rather than shipping new material/decl/shader assets.
4. If engine-side shaders are needed, prefer internal defaults or generated resources that ship with the executable.
5. Re-run Procedure 1 after each fix to verify clean initialization without custom content.

**Release Changelog Workflow**
1. Treat release-note maintenance as part of the definition of done for any shipped user-facing, packaging, compatibility, input, rendering, or platform change.
2. Keep candidate release material current in `docs/dev/release-completion.md` while work is in progress.
3. Before cutting or re-cutting a release, create or update `docs/dev/releases/vX.Y.Z.md` with polished release notes intended to be read directly by players and package users.
4. Prefer a clean Markdown structure with short sections such as `Highlights`, `Upgrade Notes`, and `Change Log`, using concise bullets that scan well on GitHub releases.
5. Write in benefit-first language: explain what changed, why it matters, and whether the reader needs to reinstall, replace files, or rebind anything.
6. Keep curated notes free of internal-only clutter such as source paths, temporary investigation details, or commit-by-commit noise unless that detail is genuinely useful to the release audience.
7. If no curated file exists, the manual release workflow falls back to the generated commit-history notes; treat that fallback as a safety net, not the preferred release presentation.

**Procedure 1 (Debug Loop)**
1. Launch using the correct mode-specific task (`SP` launch task for single-player, `MP` launch task for multiplayer).
2. Close the game after 3 seconds.
3. Read `fs_savepath\<gameDir>\logs\openq4.log` (commonly `${workspaceFolder}\\.home\\baseoq4\\logs\\openq4.log`).
4. Identify errors and warnings to resolve.
5. Resolve the errors and warnings.
6. Repeat until clean.

**Planned Review**
- Strong preference to review and reduce `q4base/` usage, file-by-file, until the engine runs cleanly without any repo content overrides.

**References (Local, Not Included In Repo)**
- Quake 4 SDK: `E:\_SOURCE\_CODE\Quake4-1.4.2-SDK`
- Quake 4 asset source: `E:\_SOURCE\_ASSETS\Q4`
- Upstream engine base (local folder name retained): `E:\_SOURCE\_CODE\Quake4Doom-master`
- Quake 4 BSE (Basic Set of Effects): `E:\_SOURCE\_CODE\Quake4BSE-master`
- Quake 4 engine decompiled (Hex-Rays): `E:\Repositories\Quake4Decompiled-main`
- Quake 4 installation (Steam): `C:\Program Files (x86)\Steam\steamapps\common\Quake 4`

**Upstream Credits**
- Justin Marshall.
- Robert Backebans.
- id Software.
- Raven Software.

