Skip to content

Game.Events.IEventJournalSystem

Assembly:
Assembly-CSharp

Namespace:
Game.Events

Type:
Interface

Base:
N/A (interface)

Summary:
IEventJournalSystem exposes read and query access to the game's event journal (the runtime list of active/past game events). It provides access to the list of journal entries, the available event prefabs, notification callbacks for changes, and helper methods to query per-entry metadata and dynamic buffers (event data and city effects). This interface is intended to be used by systems or managers that need to inspect or react to game events (for UI, save/load, analytics, or gameplay logic).

Fields

  • This interface declares no fields. {{ The interface only exposes properties, actions and methods; there are no private/public fields to document. }}

Properties

  • public Unity.Collections.NativeList<Unity.Entities.Entity> eventJournal { get; }
    {{ Returns a NativeList of Entities representing current journal entries. Each Entity in this list identifies an event journal entry entity. The returned NativeList is a snapshot view provided by the implementing system — do not assume it remains valid across frames or after structural changes to the EntityManager. Access this on the main thread or inside an ECS system context; if you need to retain data long-term, copy out the data you need. }}

  • public System.Collections.Generic.IEnumerable<Game.Prefabs.JournalEventComponent> eventPrefabs { get; }
    {{ Enumerates the event prefabs (JournalEventComponent) available/registered with the event system. Useful for listing possible event types or reading prefab-level default data. Enumeration cost depends on implementation; if used frequently, cache results as needed. }}

  • public System.Action<Unity.Entities.Entity> eventEventDataChanged { get; set; }
    {{ Optional callback/action invoked by the implementing system when the event data for a specific journal Entity changes. The argument is the journal entry Entity whose dynamic EventJournalData buffer was modified. Subscribe to receive notifications for data updates (e.g., to refresh UI). Remember to unsubscribe when no longer needed to avoid leaks. }}

  • public System.Action eventEntryAdded { get; set; }
    {{ Optional callback/action invoked when a new event entry is added to the journal. No arguments are provided; after this callback fires, read eventJournal (or call GetInfo/GetPrefab on new entries) to find the new entry. As with other delegates, unsubscribe when appropriate. }}

Constructors

  • Interfaces do not define constructors. {{ Implementations will provide construction/initialization. Consumers obtain a concrete instance from the game's systems/service locator or through dependency injection provided by the modding environment. }}

Methods

  • EventJournalEntry GetInfo(Unity.Entities.Entity journalEntity) : System.ValueType (EventJournalEntry)
    {{ Returns the EventJournalEntry structure (metadata) associated with the given journal Entity. Use this to read immutable/summary fields for an entry (timestamps, state, identifiers, etc.). If the Entity is not a valid journal entry, behavior depends on implementation (likely returns a default struct). Validate the entity beforehand (e.g., check membership in the event journal or that it has expected components). }}

  • Unity.Entities.Entity GetPrefab(Unity.Entities.Entity journalEntity) : Unity.Entities.Entity
    {{ Returns the prefab Entity (the event definition) associated with the specified journal entry. This prefab can be used to inspect prefab-level JournalEventComponent data or other prefab components. If none is associated or the journalEntity is invalid, the returned Entity may be Entity.Null — check for that. }}

  • bool TryGetData(Unity.Entities.Entity journalEntity, out Unity.Entities.DynamicBuffer<Game.Events.EventJournalData> data)
    {{ Attempts to retrieve the DynamicBuffer for the specified journal entry. If the journal entity has per-entry event data, the method returns true and populates 'data'. If the buffer does not exist or the entity is invalid, returns false and 'data' should not be used. This pattern avoids exceptions and is suitable for safe buffer queries. Note: DynamicBuffer references are only valid while the underlying EntityManager/world state remains unchanged. }}

  • bool TryGetCityEffects(Unity.Entities.Entity journalEntity, out Unity.Entities.DynamicBuffer<Game.Events.EventJournalCityEffect> data)
    {{ Attempts to retrieve the DynamicBuffer for the specified journal entry. Returns true and sets 'data' when city-effect entries exist for that journal entry; otherwise returns false. Use this to read per-city effects attached to an event entry (for example to apply or display city-specific modifiers). As with other DynamicBuffers, respect ECS access rules and do not hold the buffer reference across structural changes or between frames. }}

Usage Example

// Example consumer inside a SystemBase or other class that has access to the World
// This assumes you obtain an instance of IEventJournalSystem from your environment.
// Adjust retrieval method to how your mod/game exposes systems.

IEventJournalSystem journal = /* obtain instance from game/system locator */ null;

// Subscribe to be notified when a new entry is added
journal.eventEntryAdded += () =>
{
    // Iterate current journal entries and process new ones
    foreach (var entryEntity in journal.eventJournal)
    {
        // Get metadata
        var info = journal.GetInfo(entryEntity);

        // Get associated prefab
        var prefab = journal.GetPrefab(entryEntity);

        // Try to get per-entry data buffer
        if (journal.TryGetData(entryEntity, out var dataBuffer))
        {
            for (int i = 0; i < dataBuffer.Length; i++)
            {
                var data = dataBuffer[i];
                // read fields from data...
            }
        }

        // Try to get city effects
        if (journal.TryGetCityEffects(entryEntity, out var effects))
        {
            for (int i = 0; i < effects.Length; i++)
            {
                var effect = effects[i];
                // apply/display city effect...
            }
        }
    }
};

// Subscribe to changes on a specific entry (example: respond when its dynamic data changes)
journal.eventEventDataChanged += (Entity changedEntry) =>
{
    var info = journal.GetInfo(changedEntry);
    // Refresh UI or recompute based on changedEntry
};

{{ Notes: - Always access DynamicBuffers and NativeList results in a context where the EntityManager/world is stable (e.g., inside an ECS system update or on the main thread). - Unsubscribe from eventEntryAdded and eventEventDataChanged when the consumer is destroyed or no longer needs updates to avoid retaining references. - The concrete system implementing IEventJournalSystem controls lifetime and allocation semantics for the returned NativeList and buffers — treat them as transient views unless documentation for that implementation states otherwise. }}