Skip to content

Game.Notifications.IconCommandBuffer

Assembly:
Namespace: Game.Notifications

Type: struct

Base: System.ValueType

Summary:
A lightweight command buffer for enqueuing icon/notification commands (add, remove, update) that can be produced from main thread or jobs. Internally it enqueues Command instances into a provided NativeQueue<Command>.ParallelWriter, so it is intended to be used in multithreaded contexts (jobs) where producers push icon commands to be processed later by the notifications system. The struct also carries a buffer index used to group or order commands.

Fields

  • private NativeQueue<Command>.ParallelWriter m_Commands
    The parallel writer of a native queue where commands are enqueued. This is safe to use from jobs and multiple producers.

  • private int m_BufferIndex
    Index identifying the producer buffer. Used by the sorting/comparison logic to stabilize ordering between commands from different buffers.

  • public enum CommandFlags : byte
    Bit flags describing command kinds and modifiers:

  • Add = 1 — Add command.
  • Remove = 2 — Remove command.
  • Update = 4 — Update command.
  • Temp = 8 — Temporary icon (does not persist).
  • Hidden = 0x10 (16) — Mark icon as hidden.
  • DisallowCluster = 0x20 (32) — Prevent clustering for this icon.
  • All = 0x40 (64) — Apply to all (used in combination, e.g. All | Remove).

Note: Some code paths use combined values (for example 66 == All | Remove) to indicate removing all matches of a given priority.

  • public struct Command : IComparable<Command>
    Represents a single enqueued icon command. Fields:
  • Entity m_Owner — The owner entity that issued the command.
  • Entity m_Prefab — The prefab entity for the icon (may be Entity.Null).
  • Entity m_Target — Optional target entity the icon refers to.
  • float3 m_Location — Optional explicit world location for the icon (used when IconFlags.CustomLocation is set).
  • CommandFlags m_CommandFlags — Flags describing the command type and modifiers.
  • IconPriority m_Priority — Icon priority (enum defined elsewhere).
  • IconClusterLayer m_ClusterLayer — Cluster layer for clustering rules (enum defined elsewhere).
  • IconFlags m_Flags — Additional icon flags (including CustomLocation marker).
  • int m_BufferIndex — Buffer index copied at enqueue time (from IconCommandBuffer.m_BufferIndex).
  • float m_Delay — Optional delay before the icon is shown.

Methods: - int CompareTo(Command other) — Comparison used for ordering commands. Ordering logic: 1. If owner entity indexes differ => order by owner index difference. 2. Else if presence of m_Prefab differs between the two commands => the one with a prefab sorts after/ before (difference of prefab-presence). 3. Else => order by m_BufferIndex difference. This ensures stable ordering by owner, then by whether a prefab is specified, then by buffer index.

Properties

  • This struct exposes no public properties.

Constructors

  • public IconCommandBuffer(NativeQueue<Command>.ParallelWriter commands, int bufferIndex)
    Creates an IconCommandBuffer that will enqueue into the given commands parallel writer and tag commands with bufferIndex. Typical usage is to call queue.AsParallelWriter() and pass it to this constructor before using inside jobs or producer code.

Methods

  • public void Add(Entity owner, Entity prefab, IconPriority priority = IconPriority.Info, IconClusterLayer clusterLayer = IconClusterLayer.Default, IconFlags flags = (IconFlags)0, Entity target = default(Entity), bool isTemp = false, bool isHidden = false, bool disallowCluster = false, float delay = 0f)
    Enqueues an Add command at the owner's current/default location. Behavior:
  • Sets m_CommandFlags to Add plus optional Temp/Hidden/DisallowCluster bits.
  • m_Flags is set to the passed flags with IconFlags.CustomLocation explicitly cleared (since no explicit location is provided).

  • m_Delay is set to delay. Use this overload when you want the icon to be attached to the owner or target entities rather than a custom world location.

  • public void Add(Entity owner, Entity prefab, float3 location, IconPriority priority = IconPriority.Info, IconClusterLayer clusterLayer = IconClusterLayer.Default, IconFlags flags = IconFlags.IgnoreTarget, Entity target = default(Entity), bool isTemp = false, bool isHidden = false, bool disallowCluster = false, float delay = 0f)
    Enqueues an Add command with an explicit world location. Behavior:

  • Sets m_CommandFlags to Add plus optional Temp/Hidden/DisallowCluster bits.
  • Sets m_Location to the provided location.
  • Adds IconFlags.CustomLocation to m_Flags to indicate the icon should be placed at m_Location.

  • Default flags is IconFlags.IgnoreTarget for this overload. Use this overload when the icon should appear at a specific world coordinate rather than being anchored to an entity.

  • public void Remove(Entity owner, Entity prefab, Entity target = default(Entity), IconFlags flags = (IconFlags)0)
    Enqueues a Remove command that attempts to remove icons matching owner + prefab (+ optional target/flags). m_CommandFlags is set to CommandFlags.Remove.

  • public void Remove(Entity owner, IconPriority priority)
    Enqueues a Remove command that is intended to remove all icons of a given priority for the owner. Implementation sets m_CommandFlags to the combined value 66 (which is CommandFlags.All | CommandFlags.Remove) and stores the priority in m_Priority. This instructs the consumer to remove all icons of that priority for the owner.

  • public void Update(Entity owner)
    Enqueues an Update command for the given owner (m_CommandFlags = CommandFlags.Update). This is typically used to request the notifications system to refresh or recompute icons for that owner without adding or removing.

Notes: - All public methods create a Command instance and call m_Commands.Enqueue(...). Because m_Commands is a ParallelWriter, these methods are suitable for use inside jobs if the writer was obtained with queue.AsParallelWriter() and the job scheduling respects safety rules.

Usage Example

// Create a persistent queue (example lifecycle management omitted):
var queue = new NativeQueue<Game.Notifications.IconCommandBuffer.Command>(Allocator.Persistent);

// Producer side (main thread or job):
var writer = queue.AsParallelWriter();
var iconBuffer = new Game.Notifications.IconCommandBuffer(writer, bufferIndex: 0);

// Example entities (ownerEntity, prefabEntity) assumed available:
iconBuffer.Add(ownerEntity, prefabEntity, IconPriority.Info); // attach icon to owner
iconBuffer.Add(ownerEntity, prefabEntity, new float3(10f, 0f, 20f), IconPriority.Warning); // explicit location
iconBuffer.Remove(ownerEntity, prefabEntity); // remove specific prefab icon
iconBuffer.Remove(ownerEntity, IconPriority.Warning); // remove all warning-priority icons for owner
iconBuffer.Update(ownerEntity); // request an update for the owner's icons

// Consumer side (notifications system):
// Dequeue commands from 'queue' and process them on main thread or consumer system.
// Dispose queue when no longer needed.

{{ This document describes Game.Notifications.IconCommandBuffer: a struct for enqueuing icon notification commands into a NativeQueue parallel writer. It summarizes flags, command structure, ordering rules, and usage patterns for both entity-anchored and custom-location icons. Use the provided overloads to control priority, clustering, temporary/hidden state, and delays. }}