Property update modes

NSprites provides several strategies how properties should be synced during OnUpdate.

There is two possible ECS events we interested in:

• data changes
• chunk reordered (entity created / destroyed)

There is three modes provided by PropertyUpdateMode:

• Reactive (default) - sync only those chunks which has changed data or gets reordered
• Static - sync only those chunks which gets reordered
• EachUpdate - sync data every update without any filter

Recommendations

Use Reactive for any data which can be mutated and Static for any immutable data (mutable only at 1st frame before SpriteRenderingSystem.OnUpdate).

EachUpdate is legacy mode from previous state of package, the only reason to use it is when you 100% sure you're updating data just every frame and has no other Reactive or Static properties in particular render, so a little part of calculations can be saved.

⚠️ Reactive and Static synced and allocated per-chunk, so to use this properties entity should have some internal components client which you can add with

EntityManager.AddSpriteRenderComponents(Entity entity, int renderID = 0, bool hasPointerComponents = true)

Such components needed to access right data. Inside shader client should define additional StructuredBuffer<int> _propertyPointers; which provides correct property index. So process should look like:

// ...
#if defined(UNITY_INSTANCING_ENABLED) || defined(UNITY_PROCEDURAL_INSTANCING_ENABLED) || defined(UNITY_STEREO_INSTANCING_ENABLED)
StructuredBuffer<int> _propertyPointers;
StructuredBuffer<float4> _colorBuffer;
#endif
// ...
Varyings UnlitVertex(Attributes attributes, uint instanceID : SV_InstanceID)
{
    // ...
#if defined(UNITY_INSTANCING_ENABLED) || defined(UNITY_PROCEDURAL_INSTANCING_ENABLED) || defined(UNITY_STEREO_INSTANCING_ENABLED)
    int propertyIndex = _propertyPointers[instanceID];
    float4 color = _colors[propertyIndex];
#else
    float4 color = flaot4(0,0,0,0);
#endif
    // ...
}

⚠️ NOTE: EachUpdate mode synced and allocated per-entity, so there is no need to any additional properties in shader, you can access data directly through SV_InstanceID

💡 Tip: All three update modes has theirs code section, so if you don't want system to do unnecessary work you can exclude code section of any update modes using directives:

• NSPRITES_REACTIVE_DISABLE
• NSPRITES_STATIC_DISABLE
• NSPRITES_EACH_UDAPTE_DISABLE

If you use any disabled mode he will be treated as nearest possible enabled mode. There is a table down below illustrates mode convertion if upper one was disabled.

Reactive	Static	EachUpdate
EachUpdate	Reactive	Reactive
Static	EachUpdate	Static