t1k:unity:rendering:amplify-impostors
| Field | Value |
|---|---|
| Module | rendering |
| Version | 5.39.1 |
| Effort | medium |
| Tools | — |
Keywords: Amplify, impostors, LOD, rendering
How to invoke
Section titled “How to invoke”/t1k:unity:rendering:amplify-impostorsAmplify Impostors
Section titled “Amplify Impostors”Terminology
Section titled “Terminology”- Impostor — A flat billboard that fakes a 3D object from pre-baked multi-angle snapshots
- Octahedron — Impostor type mapping views onto an octahedral UV layout (best quality, recommended)
- HemiOctahedron — Half-octahedron for ground-based objects (trees, buildings) viewed from above
- Spherical — Traditional billboard with parallax depth (simplest, lowest quality)
- Atlas — Texture containing all baked view angles (albedo, normals, specular, emission, depth)
- BakePreset — ScriptableObject defining output textures, compression, and format settings
Skill Purpose
Section titled “Skill Purpose”Reference guide for Amplify Impostors v1.0.3 — a component-based impostor baking tool for Unity 6. Use to replace high-poly models (Synty characters, trees, buildings) with ultra-lightweight billboards for mass-spawned DOTS entities or distant LOD levels.
Render Pipeline: URP ONLY — This project exclusively uses URP (Universal Render Pipeline). All shaders, materials, impostor baking, and rendering must target URP. Never use Built-in RP or HDRP shaders/materials. When baking impostors, always ensure URP shader package is imported (
AmplifyImpostors/Plugins/EditorResources/Shaders/Runtime/URP/).
Key use case in this project: Synty PolygonKnights characters (5 SkinnedMeshRenderers + 50 bones each) are too heavy for DOTS mass spawning. Impostors reduce each unit to 1 quad (~4 tris) with baked appearance.
CRITICAL GOTCHA — URP shader must be imported + applied: Amplify ships URP shaders as
.unitypackagefiles inAmplifyImpostors/Plugins/EditorResources/Shaders/. You MUST import the matching version (e.g.,URP Shaders 17.3.unitypackagefor URP 17.3). After baking, materials default to the non-URP shader (Hidden/Amplify Impostors/Octahedron Impostor) which renders pink/magenta. RunTools/DOTSBattlefield/Fix Impostor Shaders for URPto batch-swap all materials to URP variants.Two material strategies (in
ImpostorMaterialHelper,DOTSBattlefield.Editor):
- MonoBehaviour GameObjects (trees, LODGroups): Use
GetUrpImpostorMaterial()— swaps shader toOctahedron Impostor URP, preserves view-dependent billboard rendering- ECS entities (units in SubScene): Use
LoadOrCreateUrpLitMaterial()— creates standardURP/Litwith alpha cutout. Amplify URP shader is still NOT SRP Batcher / BRG compatible (_AI_ForwardBiascbuffer)
🚨 Amplify’s SRP support table is HARDCODED and caps at URP 17.3
Section titled “🚨 Amplify’s SRP support table is HARDCODED and caps at URP 17.3”Root-caused + fixed 2026-07-31 (Unity 6000.5.6f1 / URP 17.5.0). Full mechanism, verified line numbers, and the fix: urp-version-detection.md (
references/urp-version-detection.md).In
Plugins/Editor/AIPackageManagerHelper.cs,SRPPackageSupport(L73-84) tops out atAI_SRP_17_3 = 170300. On a newer URP,Update()(L284) computes a higher baseline (17.5.0 →170500), the exact-matchTryGetValueat L303 fails,m_packageURPVersionstays at its0initializer (L103), andApplySRP()(L354-360) rewritesAmplifyImpostorsConfig.cgincto#define AI_URP_VERSION 0— i.e. “no SRP detected”.TemplatePostProcessor(L431/L433) re-arms detection on every asset import, so this repeats on every domain reload.⛔ Do NOT fix the
.cginc— it is generated output. Hand-editing it orgit checkout-ing it back does not survive one reload. The fix belongs inAIPackageManagerHelper.Update(): clamp to the newest supported baseline at-or-below the detected one instead of giving up on an exact-match miss. Prefer the clamp over adding anAI_SRP_17_5row — Amplify ships no 17.5 shader set, so a new row would point at the 17.3 GUIDs anyway, and the clamp also survives 17.6 / 18.x.Blast radius is smaller than the churn suggests.
AI_URP_VERSIONis written-but-never-read — no shipped shader branches on it (0 hits across all 40.unitypackagepayloads) — so the reset define is a symptom, not the breakage, and it was never a pink-impostor mechanism; correspondingly the fix changes zero shader bytes. The baker is independent too:AmplifyImpostor.csnever referencesAIPackageManagerHelper, detecting the pipeline itself viaRenderPipelineManager.currentPipeline(L793/L798) and picking the shader by GUID (L64) — broken detection could not misroute a bake. The one real consequence is thatCheckPackageImport(AIImportFlags.URP, …)never ran, so Amplify stopped enforcing that the on-disk URP shader set matches the detected URP; the fix restores that (plus the.cgincstops churning ingit status).Also NOT broken (checked, so nobody re-chases it): all 18 URP/core
ShaderLibraryincludes the Amplify URP shaders depend on (Core.hlsl,Lighting.hlsl,Shadows.hlsl,GBufferOutput.hlsl,LODCrossFade.hlsl,UnityInstancing.hlsl, …) still exist in URP 17.5. No include path moved between 17.3 and 17.5. URP is still returned byClient.Listdespite being abuiltinpackage in 6000.5 (source=BuiltIn) — the builtin-package hypothesis is false.Residual (open, low): the shaders on disk are Amplify’s 17.3 build running on URP 17.5 — Amplify ships no 17.5 set. Variants compile lazily at draw time, so a clean import is not proof; a Play-mode pass confirming LOD1 impostors are not pink/black is the honest close. This is independent of the define and would exist even with a 17.5 row in the table.
When This Skill Triggers
Section titled “When This Skill Triggers”- Creating impostors from Synty or other high-poly models
- Setting up LOD groups with impostor as final LOD level
- Baking impostor atlases (editor workflow or programmatic)
- Configuring impostor atlas resolution, frame count, pixel padding
- Optimizing distant rendering for mass-spawned entities
- Debugging pink/missing impostor shaders (URP shader package)
- Integrating impostors with DOTS Entities Graphics
Quick Reference
Section titled “Quick Reference”| Topic | Reference File |
|---|---|
| Impostor types, baking workflow, parameters, LOD integration | baking-guide.md (references/baking-guide.md) |
| API reference, enums, programmatic baking, editor scripting | api-reference.md (references/api-reference.md) |
| DOTS integration, ECS rendering, GPU instancing, performance | dots-integration.md (references/dots-integration.md) |
| Advanced API patterns, batch baking, custom preset config | api-advanced-guide.md (references/api-advanced-guide.md) |
| URP auto-detection failure on URP > 17.3, blast radius, the clamp fix | urp-version-detection.md (references/urp-version-detection.md) |
Critical Rules
Section titled “Critical Rules”- Import URP shaders first — Before baking, import
AmplifyImpostors/Plugins/EditorResources/Shaders/URP Shaders 17.3.unitypackage. 17.3 is the newest set Amplify ships — on URP 17.5 (Unity 6000.5) it is still the correct package to import, and detection clamps down to it (see the SRP-table gotcha above) - Octahedron is default — Use
ImpostorType.Octahedronfor characters/props. UseHemiOctahedrononly for trees/foliage viewed from above - 8x8 frames at 2048 — Project default (ImpostorBakeConfig). For hero characters, increase to 16x16 for more viewing angles. For mass units, reduce to 1024 resolution to save VRAM
- Run “Fix Impostor Shaders for URP” after baking — Baked materials default to non-URP shader. Menu:
Tools/DOTSBattlefield/Fix Impostor Shaders for URP - Two material strategies — MonoBehaviour:
GetUrpImpostorMaterial()(Amplify URP shader). ECS entities:LoadOrCreateUrpLitMaterial()(standard URP/Lit, SRP Batcher safe) - LODGroup integration — Use
LODReplacement.ReplaceLastto auto-insert impostor as final LOD - Bake from prefab — Add
AmplifyImpostorcomponent to prefab, set renderers, bake. Output:.asset+ textures - Linux baking works — Fixed in v1.0.1 (GLCore fix)
Performance Guidelines
Section titled “Performance Guidelines”| Scenario | Recommendation |
|---|---|
| Mass units (100+) | 8x8 frames, 1024 atlas, Octahedron |
| Distant trees/foliage | 16x16 frames, 2048 atlas, HemiOctahedron |
| Hero characters (close-up) | 16x16 frames, 2048 atlas, Octahedron |
| Buildings/static props | 8x8 frames, 2048 atlas, Octahedron |
See also. This table is keyed by bake scenario;
t1k:unity:optimize:assets’s pinned contract records these frame/atlas/projection combinations as having no v1 consumer, so they are not duplicated intobudgets.json.
Hard rules
Section titled “Hard rules”- Synty characters need T-pose bake: Animated characters should be in bind pose when baking. Disable Animator before bake
- SubScene baking: Impostor GameObjects (MeshFilter + MeshRenderer + impostor material) bake cleanly into ECS entities via SubScene. No SkinnedMeshRenderer = no bone overhead
- Multiple materials: If source has multiple materials, all are baked into single atlas. No material sorting needed
- Pixel padding: Keep at 32 (project default in ImpostorBakeConfig). Lower values (e.g. 16) cause atlas frame bleeding — visible as noise/artifacts around impostor edges, especially at distance where mipmaps kick in
- Shadow artifacts: Use Forward Bias slider (v1.0.0+) to fix self-shadowing issues
- Dithering crossfade: Supported for smooth LOD transitions — enable in LODGroup settings
- Custom shader property mapping (CRITICAL — Synty): Synty materials use
Synty/Generic_Basicshader with_Albedo_Mapproperty. Amplify’s baking shader expects_BaseMap/_MainTex. Fix:ImpostorBatchBaker.NormalizeMaterialsForBaking()temporarily swaps renderers toURP/Litwith correct texture mappings (_Albedo_Map→_BaseMap,_Normal_Map→_BumpMap) beforeRenderAllDeferredGroups(), then restores originals - URP Forward+ GBuffer fallback (CRITICAL — double-lit impostors): URP/Lit in Forward/Forward+ mode has NO GBuffer pass (only 8 passes: ForwardLit, ShadowCaster, DepthOnly, etc.). Amplify’s
RenderAllDeferredGroups()searches for “DEFERRED”/“GBuffer” → falls back to pass 0 (ForwardLit), which bakes FULLY LIT colors into the atlas → bright/washed-out impostors at runtime (double-lighting). Fix: Custom bake shaderAssets/AmplifyImpostors/Plugins/EditorResources/Shaders/Baking/ImpostorBakeGBuffer.shaderoutputs raw material properties to 5 MRT targets (albedo, normalWS, specular, occlusion, emission + SV_Depth), bypassing URP lighting entirely.ImpostorBatchBaker.EnsurePresetWithBakeShader()loads global BakePreset and assignsHidden/Impostors/Baking/GBufferBakebefore baking.RestorePresetBakeShader()nulls it after. TheTools/DOTSBattlefield/Bake All Impostorsmenu item handles this automatically - “Resize Textures?” dialog spam: Amplify shows
EditorUtility.DisplayDialogfor each impostor when resolution changes. Fix:ImpostorBatchBakersetsEditorPrefs.SetInt("IMPOSTORS_GLOBALTEXIMPORT", 1)before baking (1 = always resize), restores original value after. This EditorPref controls the behavior inAmplifyImpostor.cs:1177 - LOD threshold tuning: Small objects (walls ~4m, obstacles ~1-3m) need very low LOD0 transition values. At
0.10f(10% screen height), these objects are almost always below threshold → impostor shown at close range. Recommended:0.02ffor LOD0 (switches to impostor when < 2% screen height),0.005ffor LOD1 cull. Large trees can use0.15f/0.01f - Bake leftover cleanup (AUTOMATIC):
RenderAllDeferredGroups()creates temporary “Impostor” GameObjects at scene root during baking.ImpostorBatchBaker.CleanupLeftoverImpostorObjects()auto-deletes them after batch baking completes — no manual cleanup needed
Visual change notice
Section titled “Visual change notice”A visible change made with this skill (UI, sprites, 3D, shaders, VFX, animation, lighting, scene layout; audio excluded) follows core rule visual-change-discord-notice:
- Capture OLD before the first edit and NEW after the last (screen:
ScreenCapturein Play mode pert1k-unity-editor-cli, windowed or Xvfb only because rendering is needed; 3D, shader, VFX: same-scene frame grab; 2D asset: the file). - Return the paths and a draft Discord post to the orchestrator, which posts; the PR links the post or carries
visual-notice-waiver: <reason>. Logic only: “no visible change”. No capture: “screenshots pending:”, never a fake image.