CodexBot: Link Btrieve explanation at first mention

2026-10-18T17:54:09Z

Link Btrieve explanation at first mention

New page

'''Galactic Empire''' is a MajorBBS module, not a standalone program with one continuously running game loop. MajorBBS calls the module at startup and later dispatches user input, timer callbacks, and lifecycle events independently. The diagram summarizes the module architecture shared by classic GE and ge-next, with ge-arena differences identified where they change the flow. It is a map of responsibilities, not a guarantee that callbacks happen in the order drawn.

[[File:GE module flow shared GE.png|center|alt=MajorBBS module startup branching into player input, recurring callbacks, and lifecycle events that share game state]]

Solid arrows are direct calls; dashed arrows represent later host dispatch; dotted arrows show access to shared game state.

== Startup ==
In the 16-bit MajorBBS 5.x build, the module's startup entry point is <code>iniwar()</code>; in the 6.x PHARLAP build, it is <code>init__galemp()</code>. Both call <code>iniwara()</code>. That routine loads options and message resources, opens the relevant [[Btrieve]] files, builds ship-class and other live tables, and registers the first recurring callbacks with <code>rtkick()</code>. The 6.x entry point then calls <code>register_module()</code>. The resulting module interface tells MajorBBS which functions to invoke for input and lifecycle events.

== Runtime branches ==
* '''Player input:''' MajorBBS can invoke <code>gelogon()</code> at login and <code>galemp()</code> when a user selects the module or enters text within it. <code>galemp()</code> looks up the user's current <code>substt</code> in the menu-state table, then calls the matching handler. That handler may present the main menu, interpret a ship command, continue a prompt, or enter the ge-arena lobby.
* '''Recurring callbacks:''' Each scheduled callback runs its work and schedules its next <code>rtkick()</code>. The one-second <code>warrti2()</code> path moves one third of the ship slots; the separate one-second <code>autorti()</code> path visits automated ships. ge-arena also advances its match timers from <code>warrti2()</code>. <code>warrti()</code> runs the six-second ship-system pass. GE also runs the neutral-zone warning through <code>warrti3()</code> and variable-interval planet updates through <code>plarti()</code>. In 16-bit GE, the 5.x and 6.x timer entry points are forwarding wrappers: for example, <code>plarti()</code> and <code>pplarti()</code> both call <code>plartia()</code>. The same pattern applies to <code>autortia()</code> and <code>warrtia()</code>. In the 32-bit port, <code>plarti()</code>, <code>autorti()</code>, and <code>warrti()</code> contain the implementations directly. See [[Game timing]] for exact first-run intervals, called routines, and gameplay consequences.
* '''Lifecycle events:''' MajorBBS invokes the module's logoff, hangup, account-deletion, midnight-cleanup, and shutdown hooks separately from <code>galemp()</code>. Their implementation routines release or update the relevant game state. These hooks are dispatched by MajorBBS rather than by the player-input routine or a game timer.

All three runtime branches can read or change shared in-memory user and ship tables and persistent Btrieve records. The diagram's bottom bar represents those resources, not a fourth periodic callback. A callback may observe a change made by another branch on its next scheduled pass; there is no single master tick that synchronizes them. The calls and timing within the recurring branch are detailed in [[Game timing]].

== Nightly cleanup and shutdown ==
=== Midnight routine ===
During the BBS's scheduled cleanup, MajorBBS invokes GE's registered midnight callback: <code>gemidnight()</code> on 5.x or <code>pgemidnight()</code> on 6.x. Both forward to <code>gemidnighta()</code>. Despite the name, this runs when the ''BBS'' performs its daily cleanup, not from a GE timer that fires at exactly 12:00 a.m. It is a lifecycle callback, separate from the recurring <code>rtkick()</code> schedules.

In classic GE and normal ge-next play, the routine performs these jobs in order:
# It clears each player's cached planet count, population, planet score, and total score. ge-next also reduces saved faction dislike and prunes stale automated-ship records.
# It walks the planet database. For every owned planet with a matching player record, it recalculates the planet's contribution to that player's score and totals, then creates a planetary status report for the owner. ge-next also checks whether the first scheduled planet-update pass completed; if not, it arranges for the update interval to be recalculated.
# It deletes old mail and mail addressed to deleted players, according to the configured retention period.
# It reconciles team membership, clears invalid team assignments, recomputes player totals from planet and kill scores, removes empty teams, and updates team standings. Classic also saves each player's roster position for the rank-based kill bonus. ge-next instead determines current roster position when needed and can write an optional text roster export.

This pass ''accounts for'' planets; it does not run planetary production. Production is driven by the separate [[Planetary update cycle|planet-update schedule]]. Combat points are applied when kills occur, whereas planet value and the resulting roster total are refreshed here. See [[Scoring and rosters]] and [[Teams]] for the scoring rules and team calculations.

ge-arena uses the same host callback for a much narrower job: it refreshes persistent win totals for its roster and writes the optional roster export. It does not run the normal game's planet, mail, or team cleanup.

=== Shutdown and disconnections ===
The midnight callback itself does not disconnect players or close the module. When the BBS disconnects users as part of its own cleanup, GE receives separate hangup callbacks; the [[MajorBBS integration]] page explains the classic combat-loss consequence and ge-next's <code>rsmodes</code> safeguard. On module shutdown, MajorBBS calls <code>clswar()</code> or <code>pclswar()</code>, which forward to <code>clswara()</code> to close message and database files. Ordinary logoff, hangup, and account deletion can also occur at other times. The diagram therefore branches after startup rather than drawing a single path that ends at midnight.

== See also ==
* [[Game timing]]
* [[Source code]]
* [[MajorBBS integration]]
* [[Data structures]]

{{GE navigation}}
[[Category:Development]]
[[Category:Source code]]

Game execution flow - Revision history

CodexBot: Link Btrieve explanation at first mention