git:20261001.26cc402 to git:20261001.e42d2f4

---

name: dayz-texture-pipeline

description: Use when working with DayZ textures, .paa files, .rvmat materials, _co/_nohq/_smdi/_as/_mc/_dt maps, hiddenSelectionsTextures, hiddenSelectionsMaterials, material swaps, damage/destruct materials, emissive lights, glass, penetration materials, Multi shader masks, uvTransform, TexView/ImageToPAA, Blender/Substance texture export, or native PBR materials (MatPBR shader, .emat files, metallic/roughness/albedo maps) for DayZ.

---

# DayZ Texture Pipeline

Use this skill to design, edit, validate, and package DayZ texture/material work. It covers visual texture maps, `.paa` conversion, `.rvmat` authoring, config material wiring, damage materials, emissive/glass variants, penetration materials, and advanced Multi shader masks.

## Non-negotiable rules

1. Verify every DayZ path, config property, and material pattern against the current mod or unpacked vanilla data before writing a final answer or diff.

2. Prefer the lowest-risk material route that meets the goal:

- texture-only skin: `hiddenSelectionsTextures[]` / `_co.paa`;

- changed roughness/specular/normal/emissive behavior: `.rvmat`;

- health visual states: damage/destruct `.rvmat` through `healthLevels[]`;

- bullet/surface response: collision LOD penetration `.rvmat` with `.bisurf`;

- many tiled materials on one static mesh: Multi shader only after section count and UV requirements justify it;

- source is an authored metallic/roughness PBR set and damage-overlay/terrain support is not needed: MatPBR `.emat` route — community-verified, not Bohemia-documented; prefer Super/`.rvmat` when either is required.

3. Treat `_nohq` as DirectX/Y- for DayZ. If the source normal is OpenGL/Y+, invert the green channel before final DayZ export.

**Packing `[MECHANISM VERIFIED]` (vanilla `hatchback_02`/`sedan_02` `_nohq` mip 128 raw, 2026-08-30; same layout on two LFQuad2 maps the same night):** shipped `_nohq` is DXT5nm, not RGB-in-DXT5. Stored `(R,G,B,A)=(0,Y,Z,X)` with `TAGG SWIZ 05 04 02 03`; **X lives in alpha**. `ImageToPAA` with a `_nohq` filename deswizzles to RGB `(X,Y,Z)`. Measure amplitude/relief on that PNG, never on the raw DXT block. Do not infer packing from the suffix: read the current file **and** a vanilla `_nohq`.

**Sign if height comes from albedo luminance:** dark pixels are valleys. A dark seam that comes out as a ridge is an inverted mold. Confirm with a 1D sweep across a known dark line (entering a horizontal groove: R>128; leaving: R<128; use G for a vertical sweep). Recalibrate Sobel gain per atlas — copying a strength that worked at another resolution or contrast overshoots. An exaggerated normal looks worse than a weak one. Detail: `references/map-conventions.md`.

4. Copy the closest vanilla `.rvmat` category first. Do not invent absolute stage constants when vanilla examples diverge by asset class.

5. Mark templates as `[DESIGN]` until adapted to the real addon paths, selections, UV sets, and verified vanilla reference.

6. **UI textures (loading screens, menu backgrounds, map images): NEVER change the tone curve on the strength of an offline model — the engine's transfer function must be MEASURED from a screenshot first** (added 2026-08-21, rewritten same day after the first version shipped a regression).

- **What is measured**: a mod running in production carried a full `sRGB→linear` decode on its source. An offline model built from a vault note ("1.29 washes UI by +35% luma, contrast 76→58", Bohemia T198202) said this was a ~4x overshoot, so it was replaced with a gentle photographic curve. **In-game the result was much brighter than before** — the user's report, the only real datum in the whole exercise. Working backwards, `linear→sRGB` on the old texture predicts a render of 132.31 against a source median of 132.51: an exact cancellation. So the engine plausibly treats the UI `.paa` as LINEAR data and encodes it for display, making `sRGB→linear` on the source the correct inverse and the note's "+35%" model wrong or measured on something else.

- **Status: HYPOTHESIS.** It fits one qualitative report and arithmetic, not a measurement. Do not act on it either. Get a screenshot of the actual UI texture on screen, compare it pixel-wise against the known texture that produced it, and derive the real curve. One screenshot ends the guessing permanently.

- **Second-order trap worth knowing**: storing linear data in an 8-bit DXT1 texture starves the shadows, and the engine's gamma expansion then amplifies exactly that quantization. Measured on the production mod: raw DXT1 error averaged 2.64/255, but in DISPLAY space it hit mean 7.46 / max 77 in the darkest 18% of the image — blotchy, banded shadows that read as "the picture looks a bit off" while the overall tone is perfect. If the linear-storage route is correct, the fix for that is precision (uncompressed/higher-bit PAA, or dithering before encode), NOT a tone change.

- **Gate**: decode the shipped `.paa` back and compare its luma median against the source — a build script that "ran fine" proves nothing about the curve it applied. And an offline round-trip never predicts the render: look at it in-game before believing any of this.

- **Power-of-two is an `ImageToPAA.exe` limit, not an engine limit.** The tool rejects 2048×1152 and 1920×1080 with `Error (Img is not of power of 2 size)`, yet non-POT `.paa` load fine at runtime (the loading-screen mask that ships in these mods is 1920×1080). Consequence: forcing a 16:9 source into 2048×1024 costs ~12.5% vertical stretch — budget a crop or another encoder before promising 16:9.

7. **For a UI texture (loading screens, menu backgrounds, map images): use a `.paa` from `ImageToPAA.exe`; do not ship a hand-written `.edds`.**

- **What failed**: a Python-written `.edds` did not render — not self-contained LZ4, not a structural clone of a production file with the same tags, not `COPY`. `LoadImageFile` returned `true` in every case, so the log does not catch it. A Python round-trip `max_diff=0` does not predict the render; look at it in-game.

- **What worked**: a `.paa` from DayZ Tools `ImageToPAA.exe`, referenced from script. First try. ~1 MB vs ~14 MB. 2048×1024 accepted; 1536×1024 rejected as not power-of-two.

- **Decoder is for INSPECTING a foreign `.edds`, not for writing one.** Six production files decoded with `max_diff=0` on mip 0 vs their source PNG. Runtime layout: 128-byte DDS header (loading-screen backgrounds were BGRA8 uncompressed: `pf.flags 0x41`, R=`0x00FF0000`, A=`0xFF000000`; mips = floor(log2(max(w,h)))+1); from offset 128, 8 bytes per mip = `tag`(4) + uint32 size, tag `'COPY'` (raw) or `'LZ4 '`, smallest mip first, then payloads in the same order. DayZ Tools has no CLI writer; production files come from Workbench PNG import (the `.meta` records it).

- **LZ4 slices are linked blocks.** A `'LZ4 '` payload is `uint32` uncompressed mip size, then 65536-byte slices each prefixed by compressed size with `OR 0x80000000` on the last. Slice 0 decompresses alone; later slices fail with "corrupt input or insufficient space" unless the previous slice is passed as dictionary (`lz4.block.decompress(data, uncompressed_size=n, dict=prev)`). That error reads as a size bug and is not.

### Material and atlas preflight (added 2026-08-31)

Before workflow step 2 borrows any vanilla `.rvmat`, run **Ambient-shadow maps and borrowed RVMATs**

below: measure `_as` per channel and verify Stage4, Stage5, and every `uvSource`. Before changing UV

orientation or winding, run **Atlas identity before mapping diagnosis**: decode the selected atlas

and overlay the affected faces first.

## Workflow

1. Identify the asset type, selections, UV sets, and intended runtime behavior.

2. Read the nearest existing `.rvmat`, `config.cpp`, and texture paths from the mod or `P:\DZ`.

3. Pick the route:

- simple color/skin: use `references/config-and-damage.md`;

- new material response: use `references/rvmat-cookbook.md`;

- damage/destruct: use `references/config-and-damage.md`;

- glass, emissive, or penetration: use `references/rvmat-cookbook.md`;

- Multi material masks: use `references/multi-rvmat-section-texturing.md`;

- native PBR source (Substance/Quixel/AI-generated metallic-roughness sets), no damage overlay or terrain needed: use `references/matpbr-emat-pipeline.md`.

4. Export textures using the map conventions in `references/map-conventions.md`.

5. Validate with `references/validation-checklist.md` and, where useful, run:

```powershell

python .\scripts\rvmat_lint.py path\to\material.rvmat --pdrive-root P:\

```

6. If creating a new material from a template, start with:

```powershell

python .\scripts\rvmat_template.py super --prefix "myaddon\data\asset" --output "myaddon\data\asset.rvmat"

```

Then replace every placeholder with verified real paths.

## Reference loading guide

- `references/map-conventions.md`: texture suffixes, normal map orientation, SMDI packing, export notes.

- `references/rvmat-cookbook.md`: Super, flat, emissive, glass, penetration, and common stage patterns.

- `references/config-and-damage.md`: `hiddenSelectionsTextures[]`, `hiddenSelectionsMaterials[]`, `healthLevels[]`, vehicle light material swaps.

- `references/multi-rvmat-section-texturing.md`: enriched Multi shader reference with RGB+black mask mapping and UV requirements.

- `references/validation-checklist.md`: review gates before packaging or handing off.

- `references/vehicle-materials-and-color-variants.md`: shader choice (Super when faces have a _co vs NormalMapSpecularMap for constant-color/no-_co parts), tiled detail for overlapping/un-baked UVs, _nohq DirectX Y- orientation, and the color-variant subclass pattern (`color` hidden selection).

- `references/matpbr-emat-pipeline.md`: native PBR route via the MatPBR shader — `.emat`/`.rvmat` pairing, required albedo/normal/roughness/metallic/AO maps, env cubemap prep, Workbench import steps, glass presets, and hard limitations (no damage overlay, no terrain). Community-verified, not officially documented — read the Evidence section before treating any claim as settled.

## Stop and ask

Ask for clarification before generating final files when any of these are unknown:

- target addon root and packed path;

- exact selections that will receive texture/material swaps;

- whether the asset has one or two UV sets;

- whether the texture is only cosmetic or must affect surface, damage, glass, light, or penetration behavior;

- whether the output should be a mod diff, standalone reference, or `.skill` package.

## Checklist normal bake high→low (added 2026-06-24)

### Pre-bake (imagen target)

### Bake settings

### Post-bake (formato DayZ)

```python

from PIL import Image

im = Image.open("normal_ogl.png").convert("RGB")

r, g, b = im.split()

g = g.point(lambda v: 255 - v)

Image.merge("RGB", (r, g, b)).save("zombie_body_nohq.png")

```

- `pv_A_normal_*` = low + normal map aplicado.

- `pv_B_flat_*` = low plano (sin normal).

- `pv_C_high_*` = high original.

## Ambient-shadow maps and borrowed RVMATs (added 2026-08-31)

Audit `_as` files **per channel, never as grayscale**. In the measured vanilla

`pile_of_planks_as.paa`, the AO signal is in G (min 0, mean 53.1; 74% of pixels below 48) while

R, B, and A are constant 255. A luminance conversion reports a bright image around 185 and hides the

very shadows the shader consumes.

**`_as` encoding and gate criterion (added 2026-09-14, LFQuad3).** [EXACT] The native ImageToPAA route encodes `_as` by filename: the `*_as.*` pattern compresses DXT1 with `channelSwizzleR="1"`, `channelSwizzleG="G"`, `channelSwizzleB="1"`, `channelSwizzleA="1"` and `dynRange=0`, so the AO stays in G while R, B and A sit at 255 (confirmed decoding five vanilla vehicle `_as.paa`: civiliansedan, hatchback_02_body, sedan_02_body, truck_01_cab, offroad_02_wheel). [DESIGN] Gate a produced `_as` by decoding the PAA and requiring max G error <= 8/255 against the source, with R, B and A at 255. Never require per-channel RGB error against a gray PNG: that criterion pushed a worker to bypass the swizzle through an intermediate `_dxt1` suffix and ship gray `_as` maps (R=G=B). Keep the `_as` source name plain, with no intermediate suffixes.

Borrowing a vanilla `.rvmat` also borrows mesh-specific baked data. Its Stage4 `_as` can paint dark

patches from the donor mesh onto a custom model and look like broken lighting or normals; Stage5

`_smdi` carries the same reuse risk. Check the coordinate source too: the measured Stage4 uses

`uvSource="tex1"`, a second UV set that many custom MLODs do not have. Measuring the map over the

model's UV0 window does not prove what the shader samples. Engine behavior when UV1 is absent remains

unverified.

To remove donor AO, use the vanilla-proven neutral stage:

```cpp

texture="#(argb,8,8,3)color(1,1,1,1,AS)";

```

The source census found that form 4,262 times. If depth is wanted, bake an `_as` for the actual mesh

and route it through `uvSource="tex"`. An offline renderer that omits Stage4 is structurally unable

to detect this defect. Before trusting a visual bench, prove that the known-bad material makes it

red. The adjudicating control was an in-game, one-variable A/B: donor `_as`, neutral `_as`, and

self-shadow disabled.

## Atlas identity before mapping diagnosis (added 2026-08-31)

Before blaming mirrored UVs, winding, or the V convention:

1. Decode the atlas to PNG and **look at it**. Pillow opens DXT1/DXT5 DDS inputs directly.

2. Overlay the affected faces' UV polygons on that image with `image_y = (1 - v) * H`.

3. Only then investigate mapping conventions or geometry.

This two-minute preflight catches the expensive case where the selected atlas belongs to a different

asset. It also prevents a source-game material resolver from inventing color data: materials named

`*_[PRIMARY]` or `*_[SECONDARY]` intentionally have no diffuse atlas because their color comes from

the source game's paint palette. Use a flat paint texture or author a `_co`; never bind “the largest

atlas available”. Aircraft atlases can also contain a pre-mirrored copy of one side so markings read

correctly on both sides. Mirrored text on both sides does not by itself justify a global U flip.

|---|---|

|---|---|---|

| API | indexa | comentario de vanilla |

|---|---|---|

| `SetObjectTexture` / `SetObjectMaterial` (`entityai.c:2895,2898`) | `hiddenSelections` | «Change texture/material **in hiddenSelections**» |

| `SetSimpleHiddenSelectionState` / `IsSimpleHiddenSelectionVisible` (`entityai.c:2891-2892`) | `simpleHiddenSelections` | «**Simple** hidden selection state; 0 == hidden» |

`GetBeardIndex()`, `playerbase.c:9055-9057`).

```c

{

TStringArray selectionNames = new TStringArray;

m_magazineSimpleSelectionIndex = selectionNames.Find("magazine");

}

```

|---|---|

## A selection the log calls painted can be hidden by config (SP-445, added 2026-09-28)

[EXACT] `hiddenSelectionsTextures[] = {""}` in config HIDES the selection — the script-side material/texture apply then succeeds and still nothing renders. Vanilla precedent: `XmasLights.HideOnItem` clears selection textures and materials with `""` (`xmaslights.c:94-103`), and `Blowtorch` hides its flame with `SetObjectTexture(0, "")` (`blowtorch.c:48-51`) (DayZ 1.30.164014 Exp). A selection whose material is swapped from script must declare its REAL texture in config, like `BatteryCharger` (`gear_camping/DZ/gear/camping/config.cpp:6975-6977`). [DESIGN] If the emissive must stay visible over a dark `_co` region, also switch that selection to a bright procedural colour texture (`#(argb,8,8,3)color(r,g,b,1,CO)`); not yet verified in game on its own.

| campo | valores |

|---|---|

| `dir[]` | `{0,0,0}` **65.495** · `{0,0,1}` **42.460** · y media docena mas |

| `aside[]` | `{1,0,0}` **75.099** · `{10,0,0}` 43.045 · `{4,0,0}` 493 · ... |

(`DZ\vehicles\wheeled\offroad_02\data\offroad_02_decals.rvmat:7-12`).