Game.Common.RandomLocalizationIndex
Assembly:
Namespace: Game.Common
Type: struct
Base: IBufferElementData, ISerializable
Summary: RandomLocalizationIndex is a small buffer element used to store a randomized selection index for a localization group (for example, selecting one of several localized strings or variants for a prefab). It includes a sentinel value (kNone) for "no selection", utilities to generate or validate indices for an entire DynamicBuffer based on corresponding LocalizationCount entries, and simple serialization support for Colossal's serializer. The struct is marked with InternalBufferCapacity(1), which sets a default internal storage optimization for the Entity buffer.
Fields
-
public static readonly RandomLocalizationIndex kNone
Represents a sentinel "none" value. Constructed as new RandomLocalizationIndex(-1). Use this to mark an invalid or uninitialized index. -
public int m_Index
The actual selected index for the localization entry. Negative values (typically -1) indicate no valid selection.
Properties
- None.
This struct exposes its only data as a public field (m_Index) rather than properties.
Constructors
public RandomLocalizationIndex(int index)
Create a RandomLocalizationIndex with the given index value. Pass -1 to indicate "none".
Methods
-
public static void GenerateRandomIndices(DynamicBuffer<RandomLocalizationIndex> indices, DynamicBuffer<LocalizationCount> counts, ref Random random)
Populate the provided indices buffer so that for each entry i, indices[i].m_Index is set to a random integer in [0, counts[i].m_Count) if counts[i].m_Count > 0, otherwise -1. The indices buffer is resized to match counts.Length. Uses Unity.Mathematics.Random to produce deterministic random values when seeded externally. -
public static void EnsureValidRandomIndices(DynamicBuffer<RandomLocalizationIndex> indices, DynamicBuffer<LocalizationCount> counts, ref Random random)
Ensure the indices buffer is valid relative to counts. If the buffers differ in length, GenerateRandomIndices is called to rebuild indices. If lengths match, any index out of the valid range (< 0 or >= count) is replaced with a newly generated random valid index (or -1 if count is 0). This is useful to repair indices after counts change (for example when localization data is updated). -
public void Serialize<TWriter>(TWriter writer) where TWriter : IWriter
Writes m_Index into the writer. Intended for use with Colossal.Serialization.Entities writer implementations. -
public void Deserialize<TReader>(TReader reader) where TReader : IReader
Reads m_Index from the reader. Intended for use with Colossal.Serialization.Entities reader implementations.
Usage Example
// Example usage in a ComponentSystem or SystemBase:
// Assume `entity` has two DynamicBuffers attached: LocalizationCount and RandomLocalizationIndex.
protected override void OnCreate()
{
base.OnCreate();
// Seeded random for deterministic behavior across loads/runs (pick any uint seed).
var random = new Unity.Mathematics.Random(123456u);
// Acquire buffers for a given entity (replace `entity` with your actual Entity).
var counts = EntityManager.GetBuffer<LocalizationCount>(entity);
var indices = EntityManager.GetBuffer<RandomLocalizationIndex>(entity);
// Generate random indices to pick a localization entry for each count.
RandomLocalizationIndex.GenerateRandomIndices(indices, counts, ref random);
// Later, if counts may have changed, ensure indices are still valid:
RandomLocalizationIndex.EnsureValidRandomIndices(indices, counts, ref random);
}
Notes:
- LocalizationCount is expected to be a buffer element with an int m_Count field indicating how many localized variants exist for that category.
- Because RandomLocalizationIndex is an IBufferElementData, use DynamicBuffer