55 lines
6.0 KiB
Markdown
55 lines
6.0 KiB
Markdown
# Knox Buildworks - Viewpoint Compatibility
|
|
|
|
Enable **Knox Buildworks - Viewpoint Compatibility** after Knox Buildworks, Project Viewpoint and 6244 models for Viewpoint. The mod ID is `hrsys_knoxbuildworksviewpoint`. Existing saves or server configurations using the earlier ID `KnoxBuildworksViewpointCrates` need to enable the new ID. Fully restart the game after this update.
|
|
|
|
Suggested mods link: `C:\Users\Hudson\Zomboid\mods\hrsys_knoxbuildworksviewpoint`, pointing at the repository root.
|
|
|
|
## What it actually matches
|
|
|
|
- Green military crate: both orientations and stacked sprite variants, six bindings.
|
|
- Gray military crate: the green crate meshes in both orientations and stacked variants, retextured toward **#626763** with the source shading/detail preserved; six bindings. Lighting changes its apparent color in-game.
|
|
- White military crate: six manually adapted variants. These reuse the gray crate meshes and UVs with a neutral white texture atlas. White color is an approximation. The object's custom paint tint is not added by this model pack.
|
|
|
|
The matching script can identify direct authored bindings, verify Knox sprite aliases by object/container metadata, and find identical sprite artwork with the same anchor, family and unambiguous model transform. It ranks less certain candidates for review. It does not automatically apply a model just because its name or tile number is similar.
|
|
|
|
This distinction matters: Knox white crate indices 16/17 correspond to military **signs** in vanilla. That automatic alias is rejected; the reviewed rules use actual crate meshes instead.
|
|
|
|
## Catalogue results
|
|
|
|
The expanded scan checks all **3,467 catalogue entries**, including templates, material/variant sprites, finishes, door states and game-defined entity SpriteConfig rows. The previous simple scan omitted some inherited/game-defined references. Current results supersede the older `buildworks-model-audit.json` report.
|
|
|
|
The installed authored model pack already binds 2,821 distinct sprite names referenced by this catalogue. This compatibility patch adds 18 bindings. Most other references have native floor, edge, tile geometry, overlay or roof metadata. Those are recorded separately: lacking a 6244 model binding does not mean the object is invisible. Roof-family classifications still require visual checking.
|
|
|
|
**216 buildables have parts with no accepted compatible authored model (561 sprite references).** I reviewed their families, metadata, candidate matches and relevant sprite contact sheets. They include specialized wall/door trims, curtains/open states, particular window shapes, signage and multi-tile railing parts. Assigning similar furniture, signs with different artwork, or a complete model to each small section would produce incorrect objects. Their existing native rendering is retained. Faithful additional replacements require suitable model assets or new mesh/texture work; the script does not claim that these gaps are fixed.
|
|
|
|
- `reports/unmatched.md`: the focused list of remaining buildables and reasons.
|
|
- `reports/results.md`: complete readable matching/native-rendering results.
|
|
- `reports/applied-matches.json`: every applied source-to-target assignment.
|
|
- `reports/sprite-decisions.json`: evidence, native routes and candidate shortlists per sprite.
|
|
- `reports/buildable-coverage.json`: all catalogue entries with their referenced sprites/statuses.
|
|
- `tools/reviewed-matches.json`: editable manual assignments, white adaptation rules, stack variants and review decisions.
|
|
|
|
## Run the matcher
|
|
|
|
From the repository root in PowerShell:
|
|
|
|
```powershell
|
|
.\tools\Match-KnoxViewpoint.ps1
|
|
```
|
|
|
|
The launcher uses the Python bundled with Codex on this computer. Elsewhere, pass `-PythonExecutable` with Python 3.10+ and Pillow installed. Pass `-WorkshopRoot` and `-GameDirectory` if Steam uses a different library. The default output is the repository root (`common` and `42.20`); reports go in `reports/`. Use a normal rebuild when the repository is symlinked into the mods folder.
|
|
|
|
`tools/Build-KnoxViewpointPatch.ps1` is now a compatibility launcher for the expanded matcher. Run the matcher again after Workshop updates. It reads the source author's actual manifest registration order, checks that reviewed crate targets/sources still identify crates, and copies only the selected OBJ files and their material/texture dependencies. Source Workshop files are untouched.
|
|
|
|
Add a reviewed assignment under `matches` in `tools/reviewed-matches.json` using an existing source sprite, evidence, and expected source/target CustomName. A regular assignment reuses the source model and transform; `adaptation: white-crate` additionally creates a white texture atlas. A `tint` value such as `#626763` retints a green atlas while preserving relative luminance and alpha. Reviewed choices take precedence over automatic aliases. Candidate shortlists are suggestions, not approved assignments. Rebuild after editing.
|
|
|
|
## Validation and limits
|
|
|
|
- Matcher regression tests cover the crate/sign numbering collision, real aliases, properties-only tile blocks, variant IDs, capitalized/hyphenated sprite names, native routes, manifest precedence, review suggestions and white adaptation/source preservation.
|
|
- Installed Viewpoint Java parsers accept all 18 bindings, meshes, materials and texture references with zero manifest errors.
|
|
- Zomboid's Kahlua compiler and mocked boot/start registration/retry checks pass.
|
|
- `docs/crate-model-preview.png` is an offline mesh preview, not an in-game screenshot.
|
|
- In-game appearance has not been visually tested. Check green, gray and white crates in both orientations and in stacks after restarting. Existing crates should pick up their bindings when loaded. Colored paint finishes may remain neutral white in Viewpoint.
|
|
|
|
This patch changes rendering bindings only. It does not rewrite save objects, sprite names, recipes, inventory or container contents/capacity. Disable this patch to remove its bindings while keeping the original construction mods enabled. The bundled asset copies are for this private local build; sour_kisel owns the source models and textures.
|