CodexBot: Link nightly cleanup to the midnight routine overview

2026-10-17T04:44:56Z

Link nightly cleanup to the midnight routine overview

New page

{{Classic bug
|id=GE-BUG-014
|affected=Classic 3.2e and published classic source
|status=Verified in source; corrected in ge-next 0.3 and 0.3.3
|fixed=ge-next 0.3; online KICK edge fixed in 0.3.3
|source=GECMDS.C: cmd_team(); GEMAIN.C: midnight(), load_team_tab(), and update_team_tab()
}}

== Summary ==
Classic Galactic Empire represents a player's team membership in several places that are not updated as one operation:

* the active player's in-memory <code>WARUSR.teamcode</code>;
* the saved <code>teamcode</code> in that player's user record;
* each entry's cached <code>teamcount</code> and <code>teamscore</code> in the in-memory team table; and
* the flat team file written by <code>update_team_tab()</code>.

Different TEAM subcommands update different subsets of those representations. Classic relies on [[Game execution flow#Midnight routine|midnight cleanup]] to recount members, recalculate scores, clear references to nonexistent teams, remove empty teams, and rewrite the team file. Until cleanup runs, commands can report mutually contradictory membership, member counts, and scores.

== The four copies of team state ==
A team definition contains its numeric code, name, member count, team score, public password, and secret password. Classic loads those definitions from the team file into <code>teamtab[]</code> when the module starts.

Membership itself is also stored independently in every user's <code>teamcode</code>. An active user has a separate in-memory copy of that record in <code>waruptr</code>. The team table's member count and score are therefore derived values: they are only correct when they agree with all saved user records.

Classic has no helper that commits a membership change across all of these locations. Each command edits fields directly, and its exact selection of writes differs from the other commands.

== Command-specific inconsistencies ==
=== TEAM JOIN ===
Classic validates the requested team and password, then performs these operations:

# It assigns the new team code to the active user's in-memory <code>waruptr</code>.
# It increments the destination team's cached <code>teamcount</code>.
# It rewrites the team file.

It does not first check whether the player already belongs to a team. It also does not immediately write the changed user record with <code>geudb(GEUPDATE,...)</code>.

A player can consequently join Team Blue while already belonging to Team Red. The active session says Blue and Blue's cached count increases, but Red's count is not decreased. Until the user record is saved by some later path, a database-driven command such as [[Team command|<code>TEAM MEMBERS</code>]] can still find the player under Red. A module interruption before a later user save can also discard the apparent move.

Joining the same team repeatedly is similarly unsafe: every JOIN increments the cached count even though only one user record exists.

=== TEAM START ===
Starting a team writes a new team-table entry with a count of one, assigns its code to the founder's in-memory user record, and writes the team file. As with JOIN, classic does not immediately save the founder's changed user record and does not reject a founder who already belongs to another team.

The founder can therefore appear to lead the new team in the active session while the user database still associates that account with the old team. The new team's saved aggregate says it has one member even when a database query cannot find that membership yet.

=== TEAM UNJOIN ===
UNJOIN is more complete. It clears the active user's team code, immediately updates the user database, decrements the cached member count, and rewrites the team file. Classic includes an underflow check that converts a wrapped count above 65000 back to zero.

Even this path depends on the cached count having been correct before the command. If prior JOIN, START, or KICK operations have already inflated or failed to reduce it, subtracting one does not restore the true membership total. An empty team is also not removed immediately; that is deferred to cleanup.

=== TEAM KICK ===
KICK loads the named user's saved record, clears its team code, writes that user record, and sends mail to the removed player. It does not decrement the team's cached member count and does not rewrite the team file for the membership change.

If the removed player is currently active, KICK edits a temporary database record rather than that session's <code>waruptr</code>. The active copy can continue to identify the player as a member until it is reloaded or otherwise reconciled, and a later save of the stale active copy can conflict with the database update.

The leader receives confirmation that the kick succeeded, but <code>TEAM SCORE</code> can retain the old count and <code>TEAM MEMBERS</code> can disagree with the active player's own team-dependent behavior.

=== TEAM SCORE ===
The classic TEAM SCORE command does not derive its output from current user records. It sorts and prints the cached <code>teamcount</code> and <code>teamscore</code> values in <code>teamtab[]</code>.

Member commands adjust the count inconsistently, while ordinary score changes do not update <code>teamscore</code> at all. A player's kills or planet activity can change that player's score throughout the day without changing the displayed team score. The scoreboard is therefore a snapshot from the last midnight calculation, mixed with whatever count adjustments have occurred since then.

== Worked example ==
Assume Alice and Bob belong to Red. Its cached member count is two. Blue has one member.

# Alice runs <code>TEAM JOIN</code> for Blue without first using UNJOIN.
# Alice's active record now says Blue.
# Blue's cached count rises from one to two.
# Red's cached count remains two, so the two team counts now claim four memberships for only three users.
# Until Alice's user record is written, <code>TEAM MEMBERS</code> can still list her under Red because it searches saved user records rather than her active copy.
# Alice can see Blue as her team in commands that inspect <code>waruptr</code>, producing two different answers during the same session.

If Alice repeats the JOIN command, Blue's cached count can rise again without creating another member. If a Red leader instead kicks Bob, Bob's saved membership is cleared but Red's cached count still remains unchanged. These are not display-only discrepancies; team capacity checks use the cached count and can reject or admit members based on a number that does not represent the saved roster.

== What midnight cleanup does ==
Classic's midnight routine attempts to rebuild consistency:

# It zeros every team's cached member count and score.
# It scans all user records and validates each positive <code>teamcode</code> against the loaded team table.
# It clears a user's saved team code when no matching team exists.
# It recounts valid memberships from the user database.
# It recomputes each user's total score from planet score plus kill score.
# For each team member, it adds the configured team bonus and that user's score divided by the team's member count.
# It marks teams with no saved members for removal.
# It rewrites the team file with the reconstructed counts and scores.

The effective classic team-score calculation is:

<pre>
team score = sum(member score / number of members)
+ (number of members * team bonus)
</pre>

The division is integer division and is performed separately for every member before the results are added. It can therefore lose more remainder points than dividing the sum of all member scores once. This rounding detail is secondary to the stale-state defect, but it matters when reproducing classic's exact displayed total.

This pass repairs many aggregate errors, but only according to the user records present when cleanup runs. If an earlier JOIN or START changed only the active copy and that change was never saved, cleanup treats the old saved membership as authoritative. Conversely, an online player whose stale active copy disagrees with a KICK can reintroduce bad state through a later save.

Cleanup is therefore acting as delayed reconciliation for operations that should have been internally consistent when they completed. Players can spend most of a day seeing stale values before the next pass repairs them.

== Gameplay consequences ==
The defects can cause:

* TEAM SCORE to show yesterday's score despite current kills and planet activity;
* TEAM MEMBERS, REP ACC, scans, team chat, and team-restricted planet access to disagree about a player's affiliation;
* one player to inflate a team's cached member count by joining repeatedly;
* a player to move directly between teams while the old team retains a phantom member;
* a kicked online player to retain stale team state in the active session;
* a team to appear full because its cached count is too high, or to accept too many members when it is too low;
* empty teams to remain available until cleanup; and
* cleanup or a restart to make apparently valid memberships or teams suddenly change.

Because team affiliation controls more than the scoreboard, stale state can affect communication, friendly-fire decisions, planet access configured for a team, and the enforcement of the configured maximum team size.

== Correction in ge-next ==
ge-next 0.3 changed the TEAM paths so membership operations update their relevant state immediately:

* JOIN refuses players who already belong to a valid team and requires UNJOIN before changing teams.
* JOIN and START save the user's new team code immediately instead of waiting for another user-record write.
* UNJOIN and KICK update the saved membership, cached member count, empty-team state, and team file as part of the command.
* Commands validate that a user's saved team code still identifies a live team and clear stale assignments when encountered.
* An empty team is marked deleted immediately rather than remaining live until midnight.
* TEAM MEMBERS reads saved memberships after command paths have committed them.
* TEAM SCORE scans current user records when requested, builds temporary counts and score totals, applies the intended average-plus-bonus formula, and sorts that current result instead of trusting the last saved aggregate.

TEAM SCORE sums current member scores first and divides the total once. This implements the intended average more accurately than classic's sum of separately truncated quotients.

Midnight cleanup remains as a defensive reconciliation pass. It is no longer the normal mechanism required to finish ordinary TEAM commands or make the scoreboard current.

=== Online KICK edge fixed in 0.3.3 ===
Through ge-next 0.3.2, KICK updated the target's saved user record, team count, and team file, but did not clear the target's active <code>WARUSR.teamcode</code> if that player was online. The active session could continue using team-dependent privileges and could later save its stale team code back over the corrected user record.

ge-next 0.3.3 fixes this in both the 16-bit and 32-bit versions. After updating the saved record, KICK checks active game sessions for the kicked user and clears their in-memory team code if it still matches the team being left. The existing count and team-file updates then proceed. This closes the stale active-session path without changing an offline player or an active record that no longer identifies the kicked team.

The separate problem of deleted numeric team codes later being reused, which can reconnect old planets to unrelated teams, is covered by [[Classic bug: Reused deleted team identifiers]].

== Porting guidance ==
A port should choose one authoritative source for membership and treat member count and team score as derived data. If aggregates are cached, every membership transaction must update the user record and the cache together, with rollback or recovery if either write fails.

Moving between teams should be one explicit operation or should require a completed leave before a join. Kicking an online player must update both persistent and active state. Score displays should be calculated from current member records or from aggregates maintained whenever the underlying scores change, not from a once-daily snapshot.

A cleanup pass is still useful for repairing records after crashes or manual database changes, but normal correctness must not depend on waiting until midnight.

[[Category:Classic bugs: Multiplayer state]]
[[Category:Classic bugs: Database]]
[[Category:Classic bugs: Teams]]

{{GE navigation}}

Classic bug: Team state inconsistency - Revision history

CodexBot: Link nightly cleanup to the midnight routine overview