encounter-system/Runtime/QuestProgress.cs

using System;
using System.Collections.Generic;

namespace Jovian.EncounterSystem {
    /// <summary>
    /// Tracks which <see cref="QuestKind"/> encounters the party has resolved and gates any quest
    /// encounter whose predecessor hasn't fired yet. Consumers use <see cref="IsGated"/> to exclude
    /// blocked encounters from rolls, and <see cref="OnEncounterTriggered"/> to mark progress.
    /// </summary>
    /// <remarks>
    /// Gating rule: encounter <c>E</c> is gated iff some other quest encounter <c>P</c> has
    /// <c>P.nextEncounter == E</c> and <c>P</c> hasn't been resolved yet. Build the predecessor map
    /// once in <c>IndexQuests</c>; rolling and advancement are both O(1).
    /// </remarks>
    public class QuestProgress {
        private readonly HashSet<string> resolvedIds = new();
        private readonly Dictionary<string, IEncounter> predecessorOf = new();

        /// <summary>Fires when a root quest encounter (no predecessor) is resolved.</summary>
        public event Action<IEncounter> QuestStarted;

        /// <summary>Fires when a chained quest encounter is resolved. Args: (previous, current).</summary>
        public event Action<IEncounter, IEncounter> QuestAdvanced;

        /// <summary>Fires when a quest encounter with no <c>nextEncounter</c> is resolved.</summary>
        public event Action<IEncounter> QuestCompleted;

        /// <summary>Snapshot of every quest encounter id the party has resolved. Save this in the save file.</summary>
        public IReadOnlyCollection<string> ResolvedIds => resolvedIds;

        /// <summary>Construct and index the quest graph from the given collection.</summary>
        /// <param name="encountersCollection">The collection whose tables will be walked for quest chains.</param>
        public QuestProgress(EncountersCollection encountersCollection) {
            IndexQuests(encountersCollection);
        }

        /// <summary>Returns <c>true</c> if the encounter is currently blocked because its quest
        /// predecessor hasn't been resolved yet.</summary>
        public bool IsGated(IEncounter encounter) {
            var id = encounter?.EncounterDefinition?.internalId;
            if(string.IsNullOrEmpty(id)) {
                return false;
            }

            if(!predecessorOf.TryGetValue(id, out var predecessor)) {
                return false;
            }

            return !resolvedIds.Contains(predecessor.EncounterDefinition.internalId);
        }

        /// <summary>Inform the progress service that an encounter was just shown to the party.
        /// Non-quest encounters and already-resolved ones are no-ops. Fires one or two of the
        /// <see cref="QuestStarted"/>/<see cref="QuestAdvanced"/>/<see cref="QuestCompleted"/> events.</summary>
        public void OnEncounterTriggered(IEncounter encounter) {
            if(encounter?.Kind is not QuestKind questKind) {
                return;
            }

            var id = encounter.EncounterDefinition?.internalId;
            if(string.IsNullOrEmpty(id) || !resolvedIds.Add(id)) {
                return;
            }

            var next = questKind.nextEncounter.Resolve();
            var hasPredecessor = predecessorOf.TryGetValue(id, out var predecessor);

            if(!hasPredecessor) {
                QuestStarted?.Invoke(encounter);
            }
            else {
                QuestAdvanced?.Invoke(predecessor, encounter);
            }

            if(next == null) {
                QuestCompleted?.Invoke(encounter);
            }
        }

        /// <summary>Restore resolved quest ids from save data. Call after construction, before the
        /// first <see cref="OnEncounterTriggered"/>.</summary>
        public void LoadResolvedIds(IEnumerable<string> ids) {
            resolvedIds.Clear();
            if(ids == null) {
                return;
            }

            foreach(var id in ids) {
                if(!string.IsNullOrEmpty(id)) {
                    resolvedIds.Add(id);
                }
            }
        }

        private void IndexQuests(EncountersCollection collection) {
            if(collection?.encounterTables == null) {
                return;
            }

            foreach(var table in collection.encounterTables) {
                if(table?.encounters == null) {
                    continue;
                }

                foreach(var encounter in table.encounters) {
                    if(encounter?.Kind is not QuestKind questKind) {
                        continue;
                    }

                    var next = questKind.nextEncounter.Resolve();
                    if(next == null) {
                        continue;
                    }

                    var nextId = next.EncounterDefinition?.internalId;
                    if(!string.IsNullOrEmpty(nextId)) {
                        predecessorOf[nextId] = encounter;
                    }
                }
            }
        }
    }
}