Update decision-making phase and enhance localization for presence tracking

- Marked tasks as complete in the decision-making phase documentation, indicating readiness for implementation.
- Updated the README to reflect the completion status of the decision-making phase.
- Enhanced localization strings to include new presence tracking features, improving user experience.
- Revised the game screen logic to display real-time presence status, including walking states for individuals.
- Added tests to validate the new localization strings and presence functionalities, ensuring robust performance.

src/HSchool.Simulation/PresenceSystem.cs

@@ -13,7 +13,7 @@ namespace HSchool.Simulation;
 internal static class PresenceSystem
 {
     private static readonly QueryDescription People =
-        new QueryDescription().WithAll<PersonIdentity, PersonRoles, PersonTraits, Presence, PersonActivity>();
+        new QueryDescription().WithAll<PersonIdentity, PersonRoles, PersonNeeds, PersonTraits, Presence, PersonActivity, Intent>();
 
     public static void Apply(School school, double gameMinutes)
     {
@@ -23,13 +23,58 @@ internal static class PresenceSystem
         }
 
         EnsurePlans(school);
+        school.DecisionBudget = school.MaxDecisionsPerTick;
         EnqueueEvents(school);
         EnqueueTimeEvents(school, (float)gameMinutes);
         DrainDecisions(school);
         Move(school, (float)gameMinutes);
         FinishHome(school);
+        DrainDecisions(school);
     }
 
+    public static IReadOnlySet<string> BelowThreshold(School school)
+    {
+        var ids = new HashSet<string>(StringComparer.Ordinal);
+        if (school.Catalog?.BehaviorRules is null)
+        {
+            return ids;
+        }
+
+        var threshold = school.Catalog.BehaviorRules.NeedThreshold;
+        var world = school.World;
+        var query = new QueryDescription().WithAll<PersonIdentity, PersonNeeds, Presence>();
+        world.Query(in query, (ref PersonIdentity identity, ref PersonNeeds needs, ref Presence presence) =>
+        {
+            if (!presence.IsOnCampus)
+            {
+                return;
+            }
+
+            foreach (var def in school.Catalog.Needs.Values)
+            {
+                if (!def.Abstract && needs.Values.TryGetValue(def.DefName, out var value) && value < threshold)
+                {
+                    ids.Add(identity.Id);
+                    return;
+                }
+            }
+        });
+        return ids;
+    }
+
+    public static void EnqueueNewlyUrgent(School school, IReadOnlySet<string> previouslyBelow)
+    {
+        foreach (var id in BelowThreshold(school))
+        {
+            if (!previouslyBelow.Contains(id))
+            {
+                school.DecisionQueue.Enqueue(id);
+            }
+        }
+    }
+
+    public static void Enqueue(School school, string personId) => school.DecisionQueue.Enqueue(personId);
+
     public static bool IsEmpty(School school)
     {
         var empty = true;
@@ -48,7 +93,7 @@ internal static class PresenceSystem
     {
         var rows = new List<PresenceSnapshot>();
         var world = school.World;
-        world.Query(in People, (ref PersonIdentity identity, ref Presence presence, ref PersonActivity activity) =>
+        world.Query(in People, (ref PersonIdentity identity, ref Presence presence, ref PersonActivity activity, ref Intent intent) =>
         {
             rows.Add(new PresenceSnapshot(
                 identity.Id,
@@ -59,7 +104,11 @@ internal static class PresenceSystem
                 presence.Path,
                 activity.ActionId,
                 activity.Thing,
-                activity.RemainingMinutes));
+                activity.RemainingMinutes,
+                intent.Kind.ToString(),
+                intent.Id,
+                intent.Weight,
+                intent.ActionId));
         });
         rows.Sort((left, right) => StringComparer.Ordinal.Compare(left.PersonId, right.PersonId));
         return rows;
@@ -77,12 +126,13 @@ internal static class PresenceSystem
         var byId = saved
             .Where(row => !string.IsNullOrWhiteSpace(row.PersonId))
             .ToDictionary(row => row.PersonId, StringComparer.Ordinal);
-        ForEachPerson(school, (person, _, ref presence, ref activity) =>
+        ForEachPerson(school, (person, _, ref presence, ref activity, ref intent) =>
         {
             if (!byId.TryGetValue(person.Id, out var row))
             {
                 presence = PlaceByDuty(school, person);
                 activity = PersonActivity.Idle;
+                intent = Intent.None;
                 return;
             }
 
@@ -90,6 +140,7 @@ internal static class PresenceSystem
             {
                 presence = Presence.OffCampus;
                 activity = PersonActivity.Idle;
+                intent = Intent.None;
                 return;
             }
 
@@ -102,21 +153,33 @@ internal static class PresenceSystem
             activity = string.IsNullOrWhiteSpace(row.ActionId)
                 ? PersonActivity.Idle
                 : new PersonActivity(row.ActionId, row.ActionThing, row.ActionRemaining);
+            intent = ParseIntent(row);
         });
     }
 
     public static void PlaceMissingByDuty(School school)
     {
-        ForEachPerson(school, (person, _, ref presence, ref activity) =>
+        ForEachPerson(school, (person, _, ref presence, ref activity, ref intent) =>
         {
             if (!presence.IsOnCampus)
             {
                 presence = PlaceByDuty(school, person);
                 activity = PersonActivity.Idle;
+                intent = Intent.None;
             }
         });
     }
 
+    public static void DrainDecisions(School school)
+    {
+        while (school.DecisionBudget > 0 && school.DecisionQueue.Count > 0)
+        {
+            var id = school.DecisionQueue.Dequeue();
+            Decide(school, id);
+            school.DecisionBudget--;
+        }
+    }
+
     private static Presence PlaceByDuty(School school, Person person)
     {
         var room = Duty.RoomAt(
@@ -207,17 +270,6 @@ internal static class PresenceSystem
         }
     }
 
-    private static void DrainDecisions(School school)
-    {
-        var budget = school.MaxDecisionsPerTick;
-        while (budget > 0 && school.DecisionQueue.Count > 0)
-        {
-            var id = school.DecisionQueue.Dequeue();
-            Decide(school, id);
-            budget--;
-        }
-    }
-
     private static void Decide(School school, string personId)
     {
         var person = school.Roster!.People.FirstOrDefault(candidate => candidate.Id.Equals(personId, StringComparison.Ordinal));
@@ -226,26 +278,55 @@ internal static class PresenceSystem
             return;
         }
 
+        var occupied = SnapshotOccupied(school, personId);
+        string? startAction = null;
         var world = school.World;
         var found = false;
-        world.Query(in People, (ref PersonIdentity identity, ref Presence presence) =>
-        {
-            if (found || !identity.Id.Equals(personId, StringComparison.Ordinal))
+        world.Query(
+            in People,
+            (ref PersonIdentity identity, ref PersonRoles roles, ref PersonNeeds needs, ref PersonTraits traits, ref Presence presence, ref PersonActivity activity, ref Intent intent) =>
             {
-                return;
-            }
+                if (found || !identity.Id.Equals(personId, StringComparison.Ordinal))
+                {
+                    return;
+                }
 
-            found = true;
-            presence = NextPresence(school, person, plan, presence);
-        });
+                found = true;
+                _ = traits;
+                startAction = ApplyDecision(
+                    school,
+                    person,
+                    plan,
+                    occupied,
+                    ref presence,
+                    ref activity,
+                    ref intent,
+                    roles,
+                    needs);
+            });
+
+        if (startAction is not null)
+        {
+            ActivitySystem.TryStart(school, person.Id, startAction);
+        }
     }
 
-    private static Presence NextPresence(School school, Person person, DayPlan plan, Presence presence)
+    private static string? ApplyDecision(
+        School school,
+        Person person,
+        DayPlan plan,
+        Dictionary<(string Node, string Thing), int> occupied,
+        ref Presence presence,
+        ref PersonActivity activity,
+        ref Intent intent,
+        PersonRoles roles,
+        PersonNeeds needs)
     {
         var now = school.Clock.Time;
         var walks = school.Walks!;
         if (!presence.IsOnCampus)
         {
+            intent = Intent.None;
             if (plan.AppearAt is { } appear && now >= appear && (plan.WalkHomeAt is null || now < plan.WalkHomeAt))
             {
                 var dest = plan.FirstRoom ?? Duty.RoomAt(
@@ -255,15 +336,22 @@ internal static class PresenceSystem
                     school.Catalog!,
                     now,
                     school.SchoolWeekDays);
-                return dest is null ? Presence.OffCampus : PresenceStepper.StartWalk(Presence.OffCampus, walks, dest, headingHome: false);
+                presence = dest is null
+                    ? Presence.OffCampus
+                    : PresenceStepper.StartWalk(Presence.OffCampus, walks, dest, headingHome: false);
+                return null;
             }
 
-            return Presence.OffCampus;
+            presence = Presence.OffCampus;
+            return null;
         }
 
         if (plan.WalkHomeAt is { } leave && now >= leave)
         {
-            return PresenceStepper.StartWalk(presence, walks, walks.TerritoryId, headingHome: true);
+            activity = PersonActivity.Idle;
+            intent = Intent.None;
+            presence = PresenceStepper.StartWalk(presence, walks, walks.TerritoryId, headingHome: true);
+            return null;
         }
 
         var duty = Duty.RoomAt(
@@ -275,15 +363,71 @@ internal static class PresenceSystem
             school.SchoolWeekDays);
         if (duty is null)
         {
-            return PresenceStepper.StartWalk(presence, walks, walks.TerritoryId, headingHome: true);
+            activity = PersonActivity.Idle;
+            intent = Intent.None;
+            presence = PresenceStepper.StartWalk(presence, walks, walks.TerritoryId, headingHome: true);
+            return null;
         }
 
-        if (presence.HeadingHome || !duty.Equals(presence.DestinationId, StringComparison.Ordinal))
+        var slot = SchoolDay.At(school.Catalog!, now, school.SchoolWeekDays);
+        var weekday = SchoolDay.WeekdayIndex(now);
+        var lessons = Duty.LessonsToday(person, ClassOf(school, person), school.Timetable, weekday);
+        var bound = Duty.IsOtherStaff(person)
+            ? slot.Kind != DaySlotKind.Outside
+            : slot.Kind == DaySlotKind.Lesson && lessons.Any(lesson => lesson.Period == slot.Index);
+        var state = new ActorState(
+            presence.NodeId,
+            presence.DestinationId,
+            presence.Path.Length > 0 || presence.RemainingMinutes > 0,
+            activity.IsActive,
+            roles.IsStudent,
+            roles.IsStaff,
+            roles.IsParent,
+            bound,
+            duty,
+            needs.Values,
+            intent);
+        var decision = DecisionPlanner.Decide(
+            school.Catalog!,
+            school.Map!,
+            walks,
+            state,
+            (node, thing) => occupied.GetValueOrDefault((node, thing)));
+
+        if (decision.WalkTo is not null
+            && !decision.WalkTo.Equals(presence.NodeId, StringComparison.Ordinal)
+            && activity.IsActive)
         {
-            return PresenceStepper.StartWalk(presence, walks, duty, headingHome: false);
+            activity = PersonActivity.Idle;
         }
 
-        return presence;
+        intent = decision.Intent;
+        if (decision.WalkTo is not null)
+        {
+            presence = PresenceStepper.StartWalk(presence, walks, decision.WalkTo, headingHome: false);
+        }
+
+        return decision.StartAction is not null && !activity.IsActive ? decision.StartAction : null;
+    }
+
+    private static Dictionary<(string Node, string Thing), int> SnapshotOccupied(School school, string exceptId)
+    {
+        var occupied = new Dictionary<(string Node, string Thing), int>();
+        var world = school.World;
+        world.Query(in People, (ref PersonIdentity identity, ref Presence presence, ref PersonActivity activity) =>
+        {
+            if (identity.Id.Equals(exceptId, StringComparison.Ordinal)
+                || !activity.IsActive
+                || presence.NodeId is null
+                || activity.Thing is null)
+            {
+                return;
+            }
+
+            var key = (presence.NodeId, activity.Thing);
+            occupied[key] = occupied.GetValueOrDefault(key) + 1;
+        });
+        return occupied;
     }
 
     private static void Move(School school, float minutes)
@@ -295,13 +439,15 @@ internal static class PresenceSystem
 
         var walks = school.Walks;
         var world = school.World;
-        world.Query(in People, (ref Presence presence) =>
+        var arrived = new List<string>();
+        world.Query(in People, (ref PersonIdentity identity, ref Presence presence) =>
         {
             if (!presence.IsOnCampus)
             {
                 return;
             }
 
+            var travelling = presence.Path.Length > 0 || presence.RemainingMinutes > 0;
             var remaining = presence.RemainingMinutes - minutes;
             var node = presence.NodeId!;
             var path = presence.Path;
@@ -320,7 +466,16 @@ internal static class PresenceSystem
 
             var leftover = index >= path.Length ? [] : path[index..];
             presence = presence with { NodeId = node, RemainingMinutes = remaining, Path = leftover };
+            if (travelling && leftover.Length == 0 && remaining <= 0)
+            {
+                arrived.Add(identity.Id);
+            }
         });
+
+        foreach (var id in arrived.OrderBy(value => value, StringComparer.Ordinal))
+        {
+            school.DecisionQueue.Enqueue(id);
+        }
     }
 
     private static void FinishHome(School school)
@@ -332,7 +487,7 @@ internal static class PresenceSystem
         }
 
         var world = school.World;
-        world.Query(in People, (ref Presence presence, ref PersonActivity activity) =>
+        world.Query(in People, (ref Presence presence, ref PersonActivity activity, ref Intent intent) =>
         {
             if (presence.HeadingHome
                 && presence.NodeId is not null
@@ -342,10 +497,23 @@ internal static class PresenceSystem
             {
                 presence = Presence.OffCampus;
                 activity = PersonActivity.Idle;
+                intent = Intent.None;
             }
         });
     }
 
+    private static Intent ParseIntent(PresenceSnapshot row)
+    {
+        if (string.IsNullOrWhiteSpace(row.GoalKind)
+            || !Enum.TryParse<GoalKind>(row.GoalKind, out var kind)
+            || kind == GoalKind.None)
+        {
+            return Intent.None;
+        }
+
+        return new Intent(kind, row.GoalId, row.GoalWeight, row.GoalAction);
+    }
+
     private static SchoolClass? ClassOf(School school, Person person)
     {
         if (person.ClassId is null)
@@ -359,17 +527,22 @@ internal static class PresenceSystem
     private static IReadOnlyList<Person> OrderedPeople(School school) =>
         school.Roster!.People.OrderBy(person => person.Id, StringComparer.Ordinal).ToArray();
 
-    private delegate void PersonAction(Person person, PersonIdentity identity, ref Presence presence, ref PersonActivity activity);
+    private delegate void PersonAction(
+        Person person,
+        PersonIdentity identity,
+        ref Presence presence,
+        ref PersonActivity activity,
+        ref Intent intent);
 
     private static void ForEachPerson(School school, PersonAction action)
     {
         var roster = school.Roster!.People.ToDictionary(person => person.Id, StringComparer.Ordinal);
         var world = school.World;
-        world.Query(in People, (ref PersonIdentity identity, ref Presence presence, ref PersonActivity activity) =>
+        world.Query(in People, (ref PersonIdentity identity, ref Presence presence, ref PersonActivity activity, ref Intent intent) =>
         {
             if (roster.TryGetValue(identity.Id, out var person))
             {
-                action(person, identity, ref presence, ref activity);
+                action(person, identity, ref presence, ref activity, ref intent);
             }
         });
     }
@@ -384,4 +557,8 @@ public sealed record PresenceSnapshot(
     IReadOnlyList<string> Path,
     string? ActionId = null,
     string? ActionThing = null,
-    float ActionRemaining = 0f);
+    float ActionRemaining = 0f,
+    string? GoalKind = null,
+    string? GoalId = null,
+    float GoalWeight = 0f,
+    string? GoalAction = null);