add non ready player sanitization for player variables

Author: Elektryk-Andrzej

Code/VariableSystem/Variables/PlayerVariable.cs

@@ -6,11 +6,39 @@ namespace SER.Code.VariableSystem.Variables;
 
 public class PlayerVariable(string name, PlayerValue value) : Variable<PlayerValue>
 {
+    private PlayerValue _value = value;
+
     public override string Name => name;
     public override string FriendlyName => "player variable";
-    public override PlayerValue Value => value;
+    public override PlayerValue Value
+    {
+        get
+        {
+            var sanitizedValue = RetainReadyPlayers(_value);
+            if (!ReferenceEquals(sanitizedValue, _value))
+            {
+                _value = sanitizedValue;
+            }
+
+            return _value;
+        }
+    }
+
     public Player[] Players => Value.Players;
+
+    protected static PlayerValue RetainReadyPlayers(PlayerValue playerValue)
+    {
+        var players = playerValue.Players;
+        var readyPlayers = Player.ReadyList.ToArray();
+        var retainedPlayers = players
+            .Where(player => readyPlayers.Any(readyPlayer => ReferenceEquals(readyPlayer, player)))
+            .ToArray();
+
+        return retainedPlayers.Length == players.Length
+            ? playerValue
+            : new PlayerValue(retainedPlayers);
+    }
 
     [UsedImplicitly]
     public PlayerVariable() : this("temp", null!) {}
-}
+}

Code/VariableSystem/Variables/PredefinedPlayerVariable.cs

@@ -6,9 +6,9 @@ namespace SER.Code.VariableSystem.Variables;
 public class PredefinedPlayerVariable(string name, Func<List<Player>> value, string category) 
     : PlayerVariable(name, null!)
 {
-    public override PlayerValue Value => new(value());
+    public override PlayerValue Value => RetainReadyPlayers(new(value()));
     public string Category => category;
 
     [UsedImplicitly]
     public PredefinedPlayerVariable() : this("temp", null!, "temp") {}
-}
+}

docs/language/variables-and-properties.md

@@ -26,6 +26,22 @@ Predefined variables such as `@all`, `@alivePlayers`, and `@scpPlayers` are
 provided by SER. Event and command flags can inject additional local variables.
 Run `serhelp variables` for the current predefined list.
 
+## Player variable readiness
+
+Every read of a player variable checks its entries against LabAPI's
+`Player.ReadyList`. Entries which are not in that list are silently and
+permanently removed before the value reaches a method, property, loop, or
+argument. Ready dummy players remain; unauthenticated players, the host,
+non-ready NPCs, and disconnected wrappers do not. An empty player value is
+valid.
+
+The check compares the current player wrapper itself, not only an account or
+round ID. If somebody disconnects and reconnects, the new player is not restored
+to an older stored variable. Pruning also does not add later joiners or update a
+stored selection after role, team, or zone changes. Reassign a predefined player
+group when a fresh snapshot is required. Predefined groups are generated from
+the current ready-player list each time they are read.
+
 ## Text interpolation
 
 Inside quoted text, wrap a variable or expression in braces:

docs/tutorial/decisions-and-time.md

@@ -80,8 +80,8 @@ wait_until {AmountOf @scpPlayers} is 0
 Broadcast @all 5s "No living SCPs remain."
 ```
 
-After a long wait, remember that players may disconnect and item or room
-references may become invalid. Recheck important state before using it.
+After a long wait, remember that players may disconnect and item, room, or any 
+other references may become invalid.
 
 ## Try one change
 

docs/tutorial/player-targets.md

@@ -56,16 +56,13 @@ Heal @all 20
 ```
 
 Combine player groups with `Join`, `Except`, and `Intersect`. `Intersect` keeps
-only players that appear in every supplied group while preserving the order of
-the first group:
+only players that appear in every supplied argument:
 
 ```ser
-@connectedParticipants = Intersect @eventParticipants @all
+@classDInHcz = Intersect @heavyContainmentPlayers @classDPlayers
 ```
 
-This is useful when a stored group may contain players who have since
-disconnected. Additional players in `@all` are not added because they were not
-in `@eventParticipants`.
+In this case, `@classDInHcz` players are both Class-D and in heavy containment.
 
 Be careful when reading a property such as a name or health value. Those
 questions normally make sense for exactly one player, not a group. We will
@@ -80,4 +77,10 @@ remove the `Damage` line, and change the message.
 You now have methods, triggers, and useful targets—the core of many SER
 scripts. Variables become worthwhile only when you need to remember a result.
 
+## What if a player leaves?
+
+They get removed from the variable. If your `@classDInHcz` variable had three 
+players and one leaves, the variable will contain two players after that.
+Keep that in mind!
+
 Next: [remember values and inspect players](variables-and-properties.md).

docs/tutorial/variables-and-properties.md

@@ -90,8 +90,10 @@ first or use a value which is guaranteed to identify one player:
 $name = @target -> name
 ```
 
-There is still one problem: `@alivePlayers` might be empty. The next lesson
-makes this safe by adding a decision before the property is read.
+There is still one problem: `@alivePlayers` might be empty, and a previously
+selected player might disconnect before the property is read. Automatic cleanup
+prevents a stale player from being used, but the next lesson still checks that
+exactly one player remains before reading the property.
 
 The reference has the full rules for [variable families and properties](../language/variables-and-properties.md).
 It saves the unusual details about visibility and lifetime for when you need

language_specification.md

@@ -44,6 +44,19 @@ but do not create separate access namespaces.
   and removed when the function call finishes. They are not stored in a separate
   lexical environment.
 
+### Player Variable Readiness
+
+Every player-variable read is sanitized against LabAPI's `Player.ReadyList`
+before its value reaches a method, property, loop, or argument. Players which
+are no longer ready are silently and permanently removed, and the variable may
+become empty. Ready dummy players remain; unauthenticated players, the host,
+non-ready NPCs, and disconnected wrappers are removed.
+
+Stored player variables are snapshots: cleanup does not add later joiners or
+re-evaluate role, team, or zone membership. A reconnect creates a new player
+wrapper and does not restore the old entry. Predefined player groups are rebuilt
+from the current ready-player list whenever they are read.
+
 ---
 
 ## 2. Text, Math, & Syntax