wave8-dynamic-buffer-invalidation

DynamicBuffer Invalidation After Structural Changes

Intent

Prevent unsafe access to DynamicBuffer references after structural changes have invalidated the underlying chunk memory pointer.

Use When

• Any system reads a DynamicBuffer reference and then performs structural changes (AddComponent, RemoveComponent, DestroyEntity, CreateEntity) on any entity in the same frame

Avoid When

• No structural changes occur in the system — buffer references are stable within a single structural-change-free frame

Senior Pattern

// WRONG — structural change invalidates the buffer reference:
var buffer = SystemAPI.GetBuffer<WaypointElement>(entity);
EntityManager.AddComponent<DeadTag>(entity);   // structural change — buffer pointer now invalid
var count = buffer.Length;                      // undefined behavior, potential crash

// CORRECT — read buffer contents before structural change:
var buffer = SystemAPI.GetBuffer<WaypointElement>(entity);
var waypointCount = buffer.Length;             // read before structural change
var lastWaypoint = waypointCount > 0 ? buffer[waypointCount - 1] : default;

// Then defer structural change via ECB:
var ecb = new EntityCommandBuffer(Allocator.Temp);
ecb.AddComponent<DeadTag>(entity);             // deferred — buffer still valid until Playback
ecb.Playback(EntityManager);
ecb.Dispose();
// After Playback: buffer reference is invalid — do not access

// CORRECT alternative — re-fetch after structural change:
EntityManager.AddComponent<DeadTag>(entity);                      // structural change
var freshBuffer = SystemAPI.GetBuffer<WaypointElement>(entity);   // re-fetch

Anti-Patterns

• Storing a DynamicBuffer reference in a field and reading it across system updates — invalid after any structural change.
• Calling EntityManager.GetBuffer and then EntityManager.AddComponent in the same method without re-fetching — pointer invalidation.
• Caching buffer references in NativeArray fields between frames — never valid across structural changes.
• Reading a buffer reference after ECB.Playback in the same method — Playback is a structural change; the reference is invalid after it.