diff --git a/docs/research/hull-decals-and-wear-prior-art.md b/docs/research/hull-decals-and-wear-prior-art.md new file mode 100644 index 000000000..e8e62a16a --- /dev/null +++ b/docs/research/hull-decals-and-wear-prior-art.md @@ -0,0 +1,70 @@ +# Hull decals, panel lines and wear layering: prior art + +Eyes pass, 2026-10-10, before the hull shader design fork (operator: "I want tiling materials with global effects on top, plus decals ... Needs a new shader in unity to apply parallax decals for nice panel lines"). Related release-map follow-ups: hull-decals, hull-damage-wear. Facts only; tags mark FETCHED, SEARCH and KNOWLEDGE (unverified). + +# Hull decals and wear: prior-art facts (Eyes, 2026-10-10) + +Target (operator): tiling PBR materials + global per-ship wear/dirt masks + parallax panel-line decals, authored with DECALmachine 2.17 (Blender 5.2). +Tags: FETCHED = page read this session; SEARCH = search-result summary only; KNOWLEDGE = unverified recall; PROJECT = read from origin/master. +Placement: F:\Projects\Aetheria has no docs/research on origin/master, so this file sits in the scratchpad for Self to commit. + +## 5. Project / Unity constraints (PROJECT, origin/master; ProjectSettings are LFS pointers, read via `git lfs smudge`) +- Unity 6000.3.24f1 (ProjectVersion.txt). Built-in pipeline: GraphicsSettings m_CustomRenderPipeline {fileID: 0}. +- Colour space linear: ProjectSettings m_ActiveColorSpace: 1. +- GraphicsSettings: m_DefaultRenderingPath: 1, m_DefaultMobileRenderingPath: 1, tier settings (m_BuildTarget 1, Tier 2) renderingPath: 1, useHDR: 1, useDetailNormalMap: 1, standardShaderQuality 2. (Enum reading, KNOWLEDGE: 1 = Forward.) +- Per-camera override, counted in scenes/prefabs: m_RenderingPath: 1 on 21 cameras, -1 (use project setting) on 5, 3 (Deferred) on 4: Assets/Scenes/ARPG.unity:30582, FieldShieldTest.unity:1695, Main Menu.unity:1258, TestScene.unity:3781. Not checked: which camera ARPG:30582 is, or whether it is the gameplay camera. Effective path is forward for most cameras, deferred on those four. +- QualitySettings: single level "Amazing", pixelLightCount 4, shadows 0, shadowCascades 4, shadowDistance 150, anisotropicTextures 0, textureQuality 0. +- Graphics APIs set: Windows m_APIs 0200000012000000 (KNOWLEDGE decode: 2 = D3D11, 0x12 = Vulkan), Android 0b000000 (KNOWLEDGE: GLES3), iOS Metal; not decoded further. +- GlowFade (Assets/Shaders/GlowFade.shader, "Aetheria/GlowFade") is a CGPROGRAM surface shader: `#pragma surface surf Standard fullforwardshadows noambient vertex:vert`, `#pragma target 3.0`, Cull Off, RenderType Opaque, FallBack Diffuse. + - Samplers declared: _MainTex, _MetallicGlossMap, _OcclusionMap, _FadeTex, _BumpMap (5). All except _FadeTex sampled with uv_MainTex; _FadeTex uses uv_FadeTex. + - Includes "Dither Functions.cginc" and Volumetric.cginc (VolumeSampleColorSimple at vertex, ambientColor into Emission * 10). Sampler use inside Volumetric.cginc not inspected. + - Dither-clip fade via screenPos; multi_compile FLOW_GLOBAL / FLOW_SLOPE / NOISE_SLOPE; per-instance _Fade via UNITY_INSTANCING_BUFFER. Metallic = _Metallic * m.r, Smoothness = _Glossiness * m.a (packed metallic-smoothness). Normal = UnpackNormal(...) * _BumpScale. + - Input struct has no viewDir, worldPos, worldNormal or uv2; only uv_MainTex, uv_FadeTex, screenPos, ambientColor. +- docs/aetheria-release-map.md:358 lists `hull-decals` as a full-game follow-up ("Insignia and damage decals"); :1651 "With a mask texture, painted-in logos can live in the mask; only separate insignia and damage decals remain"; :2140 names `hull-damage-wear` as "the first real Ship parameter". No decal code or shader on origin/master (git grep decal over cs/shader/md hits only that doc). +- Assets/Materials/PBR holds 12 .mat folders (e.g. Carbon_Fibre, Gunmetal_Dark) each with Color, MetallicSmoothness, Normal(GL), Roughness maps. Shader used by those .mat files not determined (LFS pointer parse failed). +- Unity 6.5/6.6 manual banner (FETCHED, docs 6000.6 decals-birp page): Built-In RP "is deprecated and will be made obsolete in a future release", supported incl. bug fixes through the 6.7 LTS lifecycle. That page's only BiRP decal technique is the legacy Projector component. SEARCH: 6.3 LTS docs had no such banner. +- Sampler limits (SEARCH, Unity forum/issue tracker): D3D11 allows 16 active texture samplers per shader (issue tracker "maximum ps_4_0 sampler register index 16 exceeded"); surface shaders spend some internally (lightmaps, shadows); sampling the same texture twice reuses its sampler; a later Unity fix shares some internal samplers inline. No official Unity page stating the number found. Forum mentions GLES 3.0 as the min spec when more are needed. +- Unity Standard shader (FETCHED, StandardShaderMaterialParameterDetail): Secondary Maps = second Albedo and second Normal, usually tiled finer; Detail Mask limits where; "The Secondary normal map channel is more expensive than the primary one". Page does not name the UV set. SEARCH (old forum thread): only detail albedo and normal can use the secondary UV; occlusion cannot. +- Unity built-in has no decal system beyond Projector (FETCHED above). Deferred decals sample = Unity's "RenderingCommandBuffers" project (SEARCH, Unity manual GraphicsCommandBuffers older versions): "each decal is implemented as a box ... affects any geometry inside the box volume", "very similar to how lights are done in deferred shading, except instead of accumulating the lighting we modify the G-buffer textures". Command buffers attach via Camera.AddCommandBuffer at a CameraEvent; in deferred, depth is resolved at AfterGBuffer and shadows at BeforeLighting (SEARCH). The blog post body could not be fetched (404). + +## 1. DECALmachine export (machin3.io/DECALmachine/docs/...) +- Export intro (FETCHED, export_introduction): "DECALmachine 2.0 supports 3 approaches for exporting to Unity, Unreal Engine, etc.": Atlasing, Trim Sheets, Baking. +- Main page (FETCHED, machin3.io/DECALmachine): Atlases "for deferred rendering engines such as Unity HDRP and Unreal Engine"; Trim Sheets "anywhere, including forward renderers like Unity URP"; Baking = decals baked into the parent's UV space. +- Atlas (FETCHED, export_atlas): + - Output: texture set copied to a target folder plus `data.json` (each decal's position in the sheet). Atlas and trim sheet share the data format, so atlased decals appear as "Trims" in the file. Atlased decals get UVs remapped to atlas position; reversible. Channel packing is in the Atlas section of the Decal Export panel. Decal meshes export through the same panel or Blender's native exporter. + - Texture types named: Height, Opacity/masks (example packing: R = diffuse+emissive mask, G = normal mask, B = metallic+roughness mask, from Subset Occlusion / Alpha dropdowns), Base Color, Roughness/Metallic, Normal. + - Unity HDRP: deferred decals blending with the material underneath; Shader Graph decal shaders (Simple/Subset/Panel and Info) on GitHub; Amplify Shader Editor can build equivalents "and add parallax that matches Blender". Unity parallax: possible via ASE using the height map. + - Unity URP: forward, "decals are always opaque", no deferred projectors, trim sheets suggested; "a simple Lit shader with optional alpha mapping is possible, but matching materials is manual"; URP cannot reproduce HDRP material blending. + - Unreal 4.24: mesh decals (not decal actors) for performance; decal-domain material combining base colour/metal/rough/normal and the opacity map; per-channel opacity needs an engine patch; height map into a POM node on the UVs, Bump Offset as cheaper alternative. That section is by a third party. + - Caveats stated: no colour map is produced for normal-mapped decals or atlases (fake AO by blackening normal-only regions in base colour); UE 4.24 mesh decals lack AO. +- Trim sheet export (FETCHED, export_trim_sheet): models with trim detail export via native Blender export; textures via the Atlas export tools after adding one Trim Decal from the sheet and setting the sheet as its atlas; textures can be channel packed. No second-UV or parent-material description on the page. +- Bake (FETCHED, export_bake): "bakes decal textures onto the UV space of their parent objects"; works on objects with decals and at least one UV channel; one or several objects. Fetched page has an empty "Using Bake" heading and no texture list. The caveat "There is an open Blender issue/bug, that limits the usefulness of Baking Decals right now" is SEARCH (search summary of that page and the Superhive, Blender Market, Bazaar listings, which mark baking not recommended). The issue is not named; no source found saying it is fixed in 2.17. Listing: v2.17 supports Blender 4.3 to 5.2 (SEARCH). +- Material matching (FETCHED, match_material, shortcut DV): Simple, Subset, Panel decals, not Info. Source material must end in a Principled BSDF; nodes feeding it are ignored, "simple, parameter-based materials work best". Up to three material components per decal; Re-Apply and asset loaders match only Material and Material 2. Trim sheet materials matchable only if the sheet has no Color, Metallic or Roughness map. Blender-side only. +- Transfer UVs (FETCHED, transfer_uvs): creates a second UV channel on the decal mesh, copies the parent's UVs into it, copies the parent's image textures into the decal material (only UV-mapped image textures wired directly into a Principled BSDF; generated-coordinate parents use Init Generated Coords). Can use the parent's normal map and apply parallax to the transferred textures; works properly "only when the decal's and parent's UV spaces face the same way", which the page says is rarely the case. Page does not say whether this second UV channel is meant for export. +- Parallax (FETCHED, docs/assets): Simple, Subset, Panel decals (Panel inconsistent on the page) use parallax to offset UVs; view-angle dependent; depth into the surface works better than above; one depth level better than several; square decals better than elongated; mirrored decals need flipped UVs; Eevee flicker when a decal sits too close to the surface (fix: Displace modifier height or viewport clip start). Page does not name the height map or its channel. +- Decal types (FETCHED): Simple = normal + parallax, one material component; Subset = normal + parallax, two; Panel = normal, up to three; Info = colour. +- Not found: any documented export path of decal height into a forward hull shader; the atlas docs' only forward answer is URP trim sheets with manual material matching. + +## 2. Shipped-game practice +- Star Citizen (SEARCH, Polycount/Unreal forum threads; no primary talk found): community accounts of floating mesh decals blended over the base material; a secondary blend shader driven by vertex alpha for subtle wear in occluded areas (attributed to an SC developer post); POM on decals is hearsay; decals need an offset to avoid z-fighting; ships too large to bake from one high-poly. Whitepaper link on the Polycount thread not retrieved (polycount.com/discussion/comment/2585025 returned 403). Treat as unconfirmed. +- Unreal mesh decals (SEARCH, forum): POM works on decal actors but not mesh decals per one report; opacity tied to all channels so normal maps get affected; metalness/AO hard on mesh decals. +- Doom 2016 (SEARCH, DF interview, 80.lv, id Tech 6 wiki): opaque geometry and decals use clustered-forward shading; frustum grid of lights, probes and decals looked up in the forward pixel shader; 4000-decal in-view limit; depth prepass + equal test; decals are projected volumes in the cluster structure, not mesh decals. Doom Eternal course notes (advances.realtimerendering.com/s2020/RenderingDoomEternal.pdf, listed, not opened): fully forward, hybrid cluster+tile lists. +- Godot decal docs (SEARCH): a normal-only decal uses the albedo alpha to decide where the surface normal is overridden. Bevy clustered decals (SEARCH, commit): normal maps combined with Whiteout blending (SIGGRAPH 2007), chosen because it is commutative and associative unlike RNM. Both are projected decals, not mesh decals. +- Trim sheets vs decal sheets (SEARCH, Polycount forum answer): trim sheet = textures side by side in one bitmap; decal sheet = same layout overlaid on another texture via alpha edges or buffered rendering (deferred/stencil). Trim sheets suit repeated machinery/pipes. +- Insomniac/Ratchet trim-sheet talks, Halo, Destiny, Titanfall mesh-decal talks: not found (searches returned a members-only GDC lighting talk and a fan "ultimate trim" article on 80.lv). Polycount wiki decals / trim sheet pages: not retrieved. Destiny/Halo/Titanfall technique details: KNOWLEDGE only, unverified, not stated here. + +## 3. Parallax techniques +- SEARCH (Wikipedia, Tatarchuk SI3D06 PDF advances.realtimerendering.com/s2006/Tatarchuk-POM.pdf, listed not opened): POM first published 2005 (Brawley and Tatarchuk, ShaderX3); ray-marches a heightfield per fragment; "substantial GPU time", fragment-bound; changes apparent surface not the silhouette, so a flat outline shows at glancing angles; earlier methods aliased at grazing angles, Tatarchuk's adds adaptive sampling and refined intersection; prism POM (Dachsbacher and Tatarchuk 2007) addresses silhouettes; sensitive to fragment-vs-face normal variation; multi-pass use degrades from height mismatch. Step counts not surfaced. +- KNOWLEDGE (unverified): simple parallax mapping with offset limiting costs one extra height sample and a view-vector offset; steep/relief/POM variants take N linear steps (commonly 8-32) plus refinement; all need a tangent-space view vector; offset UVs can leave a decal's alpha/UV island at its edge. +- Alternatives named in sources: normal-map-only lines (Godot normal-only decal; DECALmachine Panel/Simple decals are normal-mapped); Unreal Bump Offset as cheaper than POM (FETCHED, DECALmachine atlas page); real geometry insets ("limited use of actual geometry" for silhouettes, SEARCH). + +## 4. Layering tiling material + global wear masks in built-in +- Unity Standard detail maps and detail mask: see section 5. +- Surface-shader extension pattern: GlowFade (PROJECT) shows surf function, extra samplers, Input struct fields. KNOWLEDGE (unverified): `uv2_Name` in Input reads UV1; `viewDir` and `worldPos` are available Input members. +- Height-blended material layers, per-ship curvature/AO mask packed RGB on UV1: no source consulted this session. KNOWLEDGE (unverified): mask-driven lerp of albedo/smoothness/normal with optional height-based contrast; mask on a unique non-overlapping UV channel because tiling UV0 repeats. +- Hand-retopologised hulls with deliberate seams: no source consulted on seam handling for tiling materials or triplanar alternatives. + +## Gaps for Self +- Which camera runs deferred in ARPG.unity:30582 and whether gameplay uses it. +- Shader assigned to the 12 PBR .mat files; sampler use in Volumetric.cginc. +- Primary sources not opened: Tatarchuk PDF, Doom Eternal PDF, Unity RenderingCommandBuffers project, SC whitepaper, identity of the DECALmachine Blender bug.