Skip to content

t1k:unity:dots-rendering:graphics

FieldValue
Moduledots-rendering
Version3.32.3
Efforthigh
Tools—

Keywords: DOTS, GPU, graphics, rendering

/t1k:unity:dots-rendering:graphics

  • DOTS — Data-Oriented Technology Stack
  • ECS — Entity Component System
  • ECB — EntityCommandBuffer
  • LOD — Level of Detail

Reference guide for the com.unity.entities.graphics package (v1.4.18 for Unity 6). To render ECS entities, use SRP Batcher-compatible batch rendering, material property overrides, LOD baking, and runtime spawn patterns as documented in the reference files below.

Render Pipeline: URP ONLY — This project exclusively uses URP (Universal Render Pipeline). All materials, shaders, and rendering features must target URP. Never use Built-in RP or HDRP materials/shaders.

Prerequisite: t1k-unity-dots-core-ecs skill (ISystem, Baker, SystemAPI, ECB patterns).

  • Rendering entities using ECS (RenderMesh, RenderMeshArray, MaterialMeshInfo)
  • Setting up visual components during baking (authoring to Baker)
  • Overriding material properties per-entity at runtime
  • Spawning many rendered entities at runtime (bullets, particles, crowds)
  • LOD groups in ECS scenes
  • Enabling/disabling rendering of entities
  • Mesh deformation (skinned meshes, blend shapes)
  • Debugging missing renders or black entity meshes
TopicReference File
Package setup, component roles, namespaces, baking, RenderBounds, RenderFilterSettings, debug checklistrendering-setup-guide.md (references/rendering-setup-guide.md)
MaterialProperty attribute, per-entity overrides, color animation, flash patternmaterial-overrides-guide.md (references/material-overrides-guide.md)
LOD group baking, LOD crossfade, mesh deformation, blend shapes, skinninglod-deformation-guide.md (references/lod-deformation-guide.md)
Runtime spawning, prefab-based spawning, mesh/material swap, enable/disable, poolingruntime-patterns-guide.md (references/runtime-patterns-guide.md)
  • Minimize RenderMeshArray (shared component) changes — each unique RenderMeshArray creates a new archetype chunk, fragmenting memory
  • Swap mesh/material via MaterialMeshInfo indices — cheap index update vs replacing entire RenderMeshArray
  • Use DisableRendering tag to hide entities — avoids structural change of destroying/recreating
  • Batch spawn with IJobParallelFor + ECB — never spawn in a main-thread loop
  • Use [MaterialProperty] overrides sparingly — each unique override component type adds to the archetype. Group commonly-toggled properties
  • Prefer LOD baking for distant entities — reduces draw calls and vertex processing
  • Namespace: [YourProject].Rendering
  • To render an entity, it must have LocalToWorld, RenderMeshArray, MaterialMeshInfo, and RenderBounds
  • To share mesh/material data across entities, use RenderMeshArray as ISharedComponentData
  • To override a material property per-entity, declare an IComponentData struct with [MaterialProperty("_ShaderPropName")]
  • To hide an entity without destroying it, add DisableRendering tag; remove to show
  • To swap mesh or material cheaply, update MaterialMeshInfo indices — avoid replacing RenderMeshArray
  • To bake standard rendering, place a GameObject with MeshRenderer and MeshFilter in a SubScene
  • To spawn many entities efficiently, create a prototype entity then clone with a Burst IJobParallelFor via ECB
  • For ShaderGraph material properties, use the Reference name (not Display Name) in [MaterialProperty]

For 2D games: quad meshes (XZ-plane) + URP/Unlit materials + [MaterialProperty] overrides (SpriteSheetUV -> _BaseMap_ST, SpriteColor -> _BaseColor). Shader choice depends on whether UV is driven per entity (see Critical Gotcha 8 — getting this wrong fails silently): a single-frame sprite with only _BaseColor overridden works fine on stock Universal Render Pipeline/Unlit, but a sprite SHEET needs DOTSCore/SpriteSheetUnlit or DOTSRPG/BillboardSprite — stock URP Unlit cannot DOTS-instance _BaseMap_ST. Full quad-mesh code, component definitions, and material setup steps: references/2d-sprite-rendering.md.


  1. ⚠️ ChunkWorldRenderBounds NaN = invisible entities — If ChunkWorldRenderBounds gets corrupted with NaN/garbage values, ALL entities in the affected chunk become invisible due to frustum culling. Root causes: (a) Baking lightmaps with SubScene CLOSED — per Entities Graphics 1.4 changelog: “You will need to bake with subscenes open.” (b) Mixed/Baked light mode on directional light — use Realtime mode for DOTS scenes. Fix: Set light to Realtime → bake_clear → delete SubScene file → re-run scene setup → rename Library/EntityScenes/ aside (Editor closed) → Play. See t1k-unity-rendering-light-baking and t1k-unity-rendering-shadow-optimization skills.

  2. ⚠️ LODGroup + Amplify Impostor = invisible entities (ALL platforms) — Amplify Impostor URP shader is NOT SRP Batcher / BRG compatible. DOTS Entities Graphics uses BRG → impostor LOD1 renders nothing on ANY platform. If LOD0 transition is too high (e.g., 0.15f), LOD1 is the only active LOD → entities invisible. Symptom: Health bars visible but meshes gone, 0 draw calls in stats. Fix: Use ImpostorMaterialHelper.LoadOrCreateUrpLitMaterial() for ECS entities (standard URP/Lit from atlas), or set LOD0 transition to 0.01f. See t1k-unity-rendering-amplify-impostors skill.

  3. Temp-camera screenshots bypass frustum culling — a screenshot from a custom viewpoint uses a temp camera that doesn’t follow normal frustum culling. Entities may appear in such screenshots but be invisible in Game view. Always verify rendering via a Game view capture (the t1k unity facade has no screenshot verb: capture manually, or call ScreenCapture.CaptureScreenshot through t1k unity eval in Play mode, unverified live).

  4. t1k unity dots query_entities requires fully-qualified type names — Use [YourNamespace].YourTagComponent not YourTagComponent, Unity.Transforms.LocalTransform not LocalTransform.

  5. ⚠️ Transparent materials = per-entity draw calls (CRITICAL) — URP entities with _SURFACE_TYPE_TRANSPARENT (alpha blend) automatically get DepthSorted_Tag from Entities Graphics, forcing per-entity back-to-front rendering that defeats BOTH SRP Batcher and GPU instancing. Result: 1 draw call per entity (600 units = 600 draw calls). Fix: Use AlphaTest (cutout) instead — set _Surface=0 (Opaque), _AlphaClip=1, _Cutoff=0.5, keyword _ALPHATEST_ON, RenderQueue=AlphaTest(2450). Only use Transparent for genuinely semi-transparent effects (particles, AoE blasts). BattleDemo2D: 608→28 batches after this fix.

  6. ⚠️ Side-view Z-fighting between cutout quads (CRITICAL) — When a side-view camera looks along +Z and all unit quads sit at their navigation Z positions (0-20 range), quads at similar Z depths Z-fight because the depth buffer cannot resolve sub-unit differences at camera distance ~100. The SideViewTransformSystem maps Z→Y for visual placement but must ALSO compress Z via DepthSpread multiplier (default 0.1) to prevent flickering. Root cause: AlphaTest materials use opaque Z-buffer sorting with _ZWrite=1; transparencySortAxis only affects the Transparent queue. Fix: SideViewConfig.DepthSpread (default 0.1) compresses Z range from ~20 to ~2, giving the depth buffer enough precision to separate overlapping quads. Relative depth order is preserved. Set to 0 to disable (will cause flickering).

  7. ⚠️ BillboardSprite shader: _LightDirection / _LightPosition undeclared on glcore (Linux OpenGL Core) — The BillboardSprite.shader shadow pass #includes Shadows.hlsl but NOT ShadowCasterPass.hlsl. On glcore, _LightDirection and _LightPosition are declared inside ShadowCasterPass.hlsl, not Shadows.hlsl. Result: shader compilation fails on Linux with undeclared identifier '_LightDirection'. Vulkan is unaffected. Fix: Add explicit declarations before the CBUFFER in the shadow-pass HLSL block: float3 _LightDirection; float3 _LightPosition;. Apply to com.the1studio.dots-core/Runtime/Rendering/BillboardSprite.shader. Verified on Unity 6000.3.9f1 / glcore (Linux). Re-apply after any fresh import of the submodule.

  8. ⚠️ A [MaterialProperty] the shader doesn’t DOTS-instance is SILENTLY DROPPED — no error, ever (CRITICAL) — Entities Graphics builds its override set from the ECS archetype plus the [MaterialProperty] registry and never consults the shader (GraphicsArchetype.AddOverrideForType matches on TypeIndex alone). An undeclared NameID is bound to the batch and discarded: the ECS write is verifiably correct, the console is clean, and the GPU renders the material’s default for every instance. The concrete trap: stock Universal Render Pipeline/Unlit DOTS-instances ONLY _BaseColor and _Cutoff. _BaseMap_ST sits in CBUFFER(UnityPerMaterial) and is not in its UNITY_DOTS_INSTANCING_START(MaterialPropertyMetadata) block (UnlitInput.hlsl:8-37, URP 17.5), and no URP shader instances it — so SpriteSheetUV on a URP-Unlit material is inert and every entity shows the same frame forever. Note “stock URP Unlit honours _BaseMap_ST via TRANSFORM_TEX” is true on the SRP Batcher path and irrelevant under DOTS_INSTANCING_ON, where the same call reads the per-material value — do not let that reasoning close the investigation. Fix: use DOTSCore/SpriteSheetUnlit (non-billboard) or DOTSRPG/BillboardSprite; both declare all three. Detect: DOTSCore.Editor.DotsInstancedPropertyUtility.DeclaresDotsInstancedProperty(shader, "_BaseMap_ST", out reason) — scans the shader source + transitive #includes; assert it in an EditMode test, because no runtime signal exists. Symptom to recognise: “the sprite never changes” while entity inspection shows the correct UV — the write happened, the read never did. TinyTerraces crops shipped this way.

  • MaterialMeshInfo.IEnableable semantics in v1.4+: per-material-slot or whole entity?
  • Unity 6 embedded Entities Graphics (v6.x): API diff vs 1.4.x (RenderMesh struct removal status)
  • GPU instancing interaction with material property override components when same material is shared across multiple RenderMeshArrays
  • Official stance on WorldRenderBounds being manually writable or strictly system-managed

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: ScreenCapture in Play mode per t1k-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.