View source for MajorBBS integration

'''Galactic Empire''' (GE) is a MajorBBS module, not a standalone server. MajorBBS loads the game, routes users' input to it, supplies channel and account information, runs its scheduled callbacks, formats and sends its output, and provides database services. Understanding that boundary is useful when reading GE's source or porting it to another host.

== Loading and registration ==
The 16-bit source supports two MajorBBS integration paths:
* '''MajorBBS 5.x:''' GE is linked into the BBS and enters its common startup routine, <code>iniwara()</code>, through <code>iniwar()</code>.
* '''MajorBBS 6.x (Phar Lap):''' The BBS loads GE as a DLL and calls its exported <code>init__galemp()</code> initializer. That initializer reads the module description from the game's MDF file, calls <code>iniwara()</code>, then passes GE's <code>struct module</code> to <code>register_module()</code>. The returned module state code is stored in <code>gestt</code>.

The MDF supplies the name used by the BBS Menu Tree. GE uses <code>gmdnam()</code> to copy that name into the module registration block; the developer's guide warns that a mismatch between the registered description and the MDF name makes the module inaccessible through the menu. Registration by itself does not put the game in a user's menu: the sysop must also link the module into the Menu Tree. Classic names its module block <code>mbmge</code>. ge-next uses <code>mpoge</code>, while ge-arena uses <code>mpoga</code>; those builds also have separate MDF and resource files so they can run alongside classic and one another.

Common startup in <code>iniwara()</code> opens the compiled message bank, reads configuration options, opens [[Btrieve]] files, loads ship classes and other game data, allocates in-memory tables, and starts recurring work with <code>rtkick()</code>. The 5.x and 6.x routes differ in how the host reaches GE, not in the main game initialization they perform.

== The module interface ==
MajorBBS's <code>struct module</code> contains a description and nine callback slots. GE fills them as follows in its 6.x registration block (the 5.x build uses corresponding host entry points):

{| class="wikitable"
! Host event !! GE routine !! Purpose
|-
| Supplemental logon || <code>gelogon()</code> || Optional GE message while a user logs on to the BBS.
|-
| Module input || <code>galemp()</code> || Handles menu selections, prompts, and gameplay commands while the user is in GE.
|-
| Status input || <code>stshdlr()</code> || Handles host status input while GE is selected.
|-
| Injected-other input || <code>NULL</code> || GE does not install a special <code>injoth</code> handler.
|-
| Supplemental logoff || <code>pwarlof()</code> || Receives the BBS logoff event. In ge-next, it also clears the session's <code>DATA</code> state.
|-
| Carrier loss / hangup || <code>pwarhup()</code> || Handles an abrupt disconnect, including any needed ship cleanup.
|-
| Midnight cleanup || <code>pgemidnight()</code> || Runs GE's daily maintenance work.
|-
| Account deletion || <code>pgedelete()</code> || Removes that user's GE records when the BBS deletes the account.
|-
| System shutdown || <code>pclswar()</code> || Closes GE resources as the BBS shuts down.
|}

The logon, logoff, hangup, midnight, deletion, and shutdown hooks are host lifecycle events, not commands the player types. The main input callback is different: MajorBBS calls it when a user selects GE and after subsequent input lines. Returning zero leaves the module and returns the user to the parent menu.

== Channels and input state ==
For user-facing callbacks, MajorBBS supplies globals including <code>usrnum</code> (the current channel), <code>usrptr</code> (its live user state), and <code>usaptr</code> (account information). <code>usrptr->state</code> identifies the selected module; <code>usrptr->substt</code> identifies the current prompt or input substate within that module. GE's <code>galemp()</code> uses <code>substt</code> to dispatch to the appropriate menu or gameplay handler. It also establishes pointers to the current channel's GE ship and user entries through <code>warshpoff(usrnum)</code> and <code>warusroff(usrnum)</code>.

A channel number is a live connection slot, not a permanent player identity. Slots can be reused after a user disconnects; persistent GE records are keyed separately. GE also uses globals as working storage for the current callback. That is ordinary in the single-threaded MajorBBS execution model, but a port cannot treat those globals as independent per-user state or assume a pointer remains valid for a different callback.

== Timed and lifecycle work ==
During startup, GE schedules recurring callbacks with <code>rtkick()</code>. Those callbacks process ship movement, automatic systems, Cybertrons and other NPC activity, and planetary updates at different intervals. The 5.x and 6.x builds use different callback wrappers where their required function signatures differ. A callback schedules its next run; the host is not executing a separate GE thread. See [[Game timing]] and [[Game execution flow]] for the full sequence.

The BBS calls GE's registered [[Game execution flow#Midnight routine|midnight routine]] for daily game maintenance. Separately, when the BBS disconnects users for its own cleanup, it calls GE's hangup routine. Classic GE treats that hangup like an ordinary disconnect, so a ship still engaged in combat can be lost. MajorBBS provides <code>rsmodes</code> to indicate that a channel is being reset. ge-next checks it on the hangup path and, when the BBS is disconnecting a combat-locked user for cleanup, saves the ship instead of destroying it.

== Output and message resources ==
GE's MSG source is compiled into MCV resource files. <code>opnmsg()</code> opens a bank, <code>setmbk()</code> selects it, and <code>prfmsg()</code> formats a named message into the host's <code>prfbuf</code>. <code>outprf()</code> sends the formatted text to a channel; <code>clrprf()</code> discards it. The buffer and its write pointer are shared formatting state, '''not one independent PRF buffer per channel'''. GE must select the right bank and explicitly send, reuse, or clear the buffer as it delivers messages to different users. A careless clear or send can hide a message or deliver it to the wrong audience. See [[Configuring Galactic Empire]].

== Persistent data ==
GE stores users, ships, sectors and planets, and other game records through the host's Btrieve API. Startup opens the files with the expected record sizes; later operations select a file and use its position block, data buffer, key, operation, and key number. The in-memory channel tables are separate from those persistent records. A port or emulator must preserve the relevant Btrieve key and update behavior, not merely the visible data fields. See [[Data structures]] and [[MBBSEmu]].

== See also ==
* [[Game execution flow]]
* [[Game timing]]
* [[Source code]]
* [[Porting Galactic Empire]]

== Source ==
* [https://download.mbbsemu.com/docs/MajorBBS_Developers_Guide_Rev_6.2_Jan_1994.pdf ''The Major BBS Developer's Guide'', revision 6.2 (January 1994)], particularly the chapters on module initialization, <code>register_module()</code>, user state, and PRF output.

{{GE navigation}}
[[Category:Development]]
[[Category:Platforms]]