diff --git a/docs/dev/release-completion.md b/docs/dev/release-completion.md index ca77752c..fa3e0f65 100644 --- a/docs/dev/release-completion.md +++ b/docs/dev/release-completion.md @@ -61,7 +61,7 @@ is `docs/dev/macos-moltenvk-decision.md`. - [x] Streaming and avatar-overlay workloads no longer send the Windows AMD OpenGL driver through openQ4's persistent-mapped upload/fence path. AMD systems retain the modern renderer but automatically use the safer orphaned map-range stream without persistent-path fence waits, avoiding the driver-timeout and follow-on access-violation corridor reported with OBS and PNG-tuber software in 0.10.0. Windows crash logs now also identify the module, load address, and relative offset that raised an exception, so driver or capture-hook faults are distinguishable from openQ4 faults without first symbolizing the minidump. - [x] Story checkpoints no longer abort or crash when a stock map retains a transient area-location reference outside the saved object graph. The serializer once again writes that reference as null, matching retail Quake 4 behavior, while failed saves no longer retry object serialization from a destructor after map shutdown has released those objects. This fixes the timing-sensitive automatic checkpoint crash reported just after the first detonation-pack sequence in Interior Hangar (`game/hangar2`). - [x] Every retail Quake 4 and Raven map-pack mapDef with a `loadimage` now has a complete center/left/right/top/bottom TGA+DDS levelshot set. The stock engine capture workflow supplied the 24 missing sets, while a source-indexed validation test keeps all 56 base and 7 map-pack loadimages classified, structurally valid, and complete. This resolves GitHub issue #11. -- [x] A partial Quake 4 asset copy can no longer hide its missing dialogue media behind a successful core-PK4 check: client startup now warns when no unsuffixed `zpak_.pk4` base archive is mounted and explains where to install it or point openQ4 at the retail files. Numbered patch archives no longer suppress this warning, matching a known partial-install pattern where `zpak_english_01.pk4` through `_04` were present but `zpak_english.pk4` was absent. The check recognizes the supported base filename without claiming archive completeness, stays non-fatal for dedicated servers, and remains disabled with the existing assetless-validation override. This improves the diagnosis for GitHub issue #87 while the reporter's Linux output-path retest remains pending. +- [x] A partial Quake 4 asset copy can no longer hide its missing dialogue media behind a successful core-PK4 check: client startup now warns when no unsuffixed `zpak_.pk4` base archive is mounted and explains where to install it or point openQ4 at the retail files. Numbered patch archives no longer suppress this warning, matching the reporter-confirmed partial-install pattern where `zpak_english_01.pk4` through `_04` were present but `zpak_english.pk4` was absent. The check recognizes the supported base filename without claiming archive completeness, stays non-fatal for dedicated servers, and remains disabled with the existing assetless-validation override. Controlled `game/airdefense2` validation reproduced both linked symptoms with that incomplete media set: all dialogue was silent and the conversation thread remained before Bidwell's move, leaving him at `(5372, 2625, 244)` through 75 seconds. Restoring the unsuffixed archive moved him to the stock target at `(5437, 2575, 244)` by 60 seconds with no navigation failure. This root-causes and resolves GitHub issues #87 and #88 as an incomplete retail installation while keeping the startup diagnostic and player guidance explicit. - [x] The original Apple Silicon launch crash tracked by GitHub issue #73 is now closed after two reporters confirmed it fixed in v0.8.0. Later FBO and single-player module-switch failures received their own fixes, and the remaining washed-out rendering report is tracked separately by issue #98; macOS support remains experimental pending current Apple-hardware signoff. - [x] Dynamically expanded widescreen and ultrawide loading screens are now published atomically. A short or interrupted write can leave only a disposable staging file; it can no longer replace the live TGA with a truncated image that aborts map loading with `LoadTGA: incomplete file`. If publication fails, openQ4 uses the original levelshot and continues loading. This resolves GitHub issue #102. - [x] Experimental macOS Vulkan can now find bundled MoltenVK in both supported loose-package layouts: beside the executable or under a `Frameworks/` child directory. SDL surface creation and the Vulkan module probe the same ordered paths, preventing a flat `.install` development run from missing the staged library or binding two different loader images. This resolves GitHub issue #95. diff --git a/docs/dev/releases/v0.12.0.md b/docs/dev/releases/v0.12.0.md index ceab9fe4..0569aef7 100644 --- a/docs/dev/releases/v0.12.0.md +++ b/docs/dev/releases/v0.12.0.md @@ -29,7 +29,7 @@ - Existing settings and compatible saves do not need to be reset. As a precaution, retain a copy of important saves before replacing an older installation. - The exact older broad shadow-filter defaults are upgraded once to the new balanced contact-shadow values; customized shadow profiles are left untouched. `r_shadowMapCasterCulling 2` remains the recommended value but now means topology-aware automatic culling rather than far-shell storage. Use `0` for an always-two-sided comparison or `1` to force near-shell culling. - Level-load data under the active `fs_savepath` `generated/` directory is private and disposable. `com_levelLoadModernization` defaults to `0` and overrides older archived cache settings, so ordinary play uses the classic source path. Set it to `1` only for focused cache evaluation. Never delete the original retail or mod assets. -- Retail Quake 4 assets are still required. Point openQ4 at a complete retail installation, including the unsuffixed base dialogue archive such as `zpak_english.pk4`. +- Retail Quake 4 assets are still required. Point openQ4 at a complete retail installation, including the unsuffixed base dialogue archive such as `zpak_english.pk4`. Numbered files such as `zpak_english_01.pk4` are patches and must not be renamed as a substitute; without the base archive, dialogue is silent and conversation-gated campaign scenes can fail to advance. - OpenGL remains the default and recommended renderer. Vulkan is experimental and opt-in with `r_renderApi vulkan`, applied after an engine restart. The modern OpenGL visible path also remains guarded and experimental. - Temporal presentation is experimental and defaults off. Set `r_temporalAA 1` to try native-history TAA/TAAU; optionally add `r_rendererDynamicResolution 1` and tune `r_dynamicResolutionMinScale`/`r_dynamicResolutionMaxScale`. For a fixed lower 3D resolution, leave automatic scaling off and set `r_screenFraction` below `100`. HUD, menus, console, screenshots, and save previews remain isolated from temporal accumulation. Set both temporal controls to `0` to return immediately to the established SMAA/spatial path. - PBR material support is experimental and defaults to `r_pbrMaterials 0`. Retail Quake 4 materials do not contain PBR declarations and remain on their classic path. For authored materials, provide classic `bumpmap`/`diffusemap`/`specularmap` fallback stages, then use a packed ORM map, individual metallic/roughness/AO maps, or scalar values. `tools/assets/pack_pbr_orm.py` creates packed `R=AO`, `G=roughness`, `B=metallic` data from an explicitly selected stored input channel. `tools/validation/generate_pbr_fixture.py` creates an original deterministic temporary fixture only below `.tmp/`; it incorporates no external assets and is not shipped as game content. Visible OpenGL PBR and probe evaluation also requires `r_rendererModernVisible 1`; enabling a material or probe leaf alone does not promote a visible PBR frame. `r_pbrIBL 1` and `r_pbrIBLIntensity` control the built-in PBR-only analytic environment contribution on that guarded OpenGL path. A conventional one-stage `blend blend` source-alpha material is supported when it uses the PBR albedo map; complex transparency remains classic. Vulkan's native route requires an opaque metallic/roughness material with a packed ORM map, `normalFormat tangentXYZ`, and exactly one declared, active classic bump stage, diffuse stage, and specular stage in that order. Duplicate, inactive, invalid, or reordered interaction owners and any custom-lighting co-owner remain entirely classic; an admitted packed-PBR draw replaces only the final interaction submit. Vulkan does not support separate data maps, source alpha, analytic IBL, authored probes, or clustered decals. Keep image-program paths parser-safe (use underscores rather than hyphens). diff --git a/docs/user/getting-started.md b/docs/user/getting-started.md index b360a351..e3a0421a 100644 --- a/docs/user/getting-started.md +++ b/docs/user/getting-started.md @@ -55,6 +55,11 @@ If you prefer a self-contained setup, keep these side by side in the same root f > [!IMPORTANT] > Do **not** copy retail PK4 files into `baseoq4/`. That folder is for openQ4 runtime files. +> Copy the complete retail `q4base/`, including the unsuffixed language-media archive such as +> `zpak_english.pk4`. Small numbered files such as `zpak_english_01.pk4` are patches, not a +> replacement for the base archive. If the unsuffixed archive is missing, character dialogue is +> silent and conversation-gated campaign scenes may not advance; verify or reinstall the retail +> files instead of renaming a numbered patch. ## Platform Notes