CodexBot: Link Btrieve explanation at first mention

2026-10-18T17:53:41Z

Link Btrieve explanation at first mention

New page

''Galactic Empire'' uses C structures both as live state and as the bytes passed to [[Btrieve]]. A field's type, order, and offset can therefore be part of the saved-game format. The principal definitions are in <code>GEMAIN.H</code>; the 16-bit ge-next and 32-bit V10 ports must be read as distinct layouts, not as structures whose bytes can be copied between platforms.

== Persistent records ==
The game has separate user, ship, planet-family, and (in standard ge-next) mail databases. The functions <code>geudb()</code>, <code>gepdb()</code>, and <code>gesdb()</code> select the corresponding Btrieve file and key. A Btrieve file is opened with the compiled <code>sizeof</code> its record structure, so adding a field without removing or adjusting filler is not merely a source-code change.

{| class="wikitable"
! Record !! Database role !! Classic structure !! Classic Btrieve record !! 16-bit ge-next 0.3 structure / record !! Elwynor V10 structure / record !! ge-next32 structure / record
|-
| <code>WARUSR</code> || One persistent player || 255 bytes || 246 bytes || 246 bytes || 256 bytes || 256 bytes
|-
| <code>WARSHP</code> || One persistent ship || 514 bytes || 501 bytes || 501 bytes || 512 bytes || 512 bytes
|-
| <code>GALSECT</code> || Sector index || 512 bytes || 493 bytes || 493 bytes || 512 bytes || 512 bytes
|-
| <code>GALPLNT</code> || Planet body || 512 bytes || 493 bytes || 493 bytes || 512 bytes || 512 bytes
|-
| <code>GALWORM</code> || Wormhole body || 512 bytes || 493 bytes || 493 bytes || 512 bytes || 512 bytes
|}

The shipped classic <code>MBMGEUSR.NEW</code>, <code>MBMGESHP.NEW</code>, and <code>MBMGEPLT.NEW</code> Btrieve templates declare fixed record lengths of '''246''', '''501''', and '''493''' bytes respectively. The corresponding classic <code>.DAT</code> files have the same lengths. These are the actual allotted ''logical record'' lengths, not the Btrieve page size or physical slot size. The planet database uses 493 bytes for each of its three record types.

Classic's <code>GEMAIN.H</code> uses filler expressions written around nominal 256-byte user and 512-byte ship/planet targets. Summing its members under the byte-packed 16-bit layout instead gives the classic structure sizes shown in the table: the user structure is 255 bytes, not 256, and the ship structure is 514, not 512. These are calculated structure sizes, distinct from the fixed record lengths read from the shipped Btrieve templates. Classic opens each Btrieve file with <code>sizeof</code> the compiled structure; the file's own fixed-length definition is a separate constraint. ge-next's 16-bit 0.3 structures use explicit filler sized to the real 246/501/493-byte records rather than perpetuating the misleading classic arithmetic.

The shipped Elwynor V10 and ge-next32 Btrieve files confirm 256-byte user records and 512-byte ship and planet-family records, matching their respective structures; ge-next32 also checks all five structure sizes at compile time. Equal lengths do not imply compatible layouts: Elwynor's port and ge-next32 arrange or use fields differently, so their database records should not be exchanged without conversion. A 16-bit record is not a truncated 32-bit record either: member order, alignment, and some compatibility slots differ. In particular, 0.3's reordered records are not compatible with pre-0.3 saved games; the 0.3 release notes require a reset.

=== WARUSR: player account ===
<code>userid</code> is the identity key. <code>score</code> is a roster-sorting key; <code>teamcode</code> is another indexed key. Standard ge-next also stores cash, ship counts and highest assigned ship number, total and player-only kills, planet count, separate kill/planet score components, population, 30 option bytes, and eight faction-relation bytes. Its <code>score</code> is the cumulative game score, while the kill and planet components describe where it came from. See [[Scoring and rosters]] and [[Droids#Factions and distress in ge-next|factions]].

Classic reserved a 40-byte <code>waste</code> area and retained a <code>debt</code> field from an apparent earlier or unfinished credit system. The [[GEREADME.DOC#05/09/89_Release_2.0d|2.0d release notes]] say the debt line was removed from REPORT ACCOUNT, and 3.2e still includes an unused message about a bank limiting cash advances because of outstanding debt. The field is initialized to zero, but the surviving 3.2e code does not appear to incur or repay player debt. Not every odd-looking field was dead: <code>rospos</code> was assigned during roster processing, displayed in reports, and used in kill-bonus calculation. ge-next eventually removed the unused space and the obsolete stored roster-position field, replacing its behavior with a roster lookup. A block of <code>key_filler</code> in the 16-bit 0.3 structure deliberately keeps <code>teamcode</code> at its required Btrieve key offset. A developer must not remove that block merely because it has no gameplay value.

In ge-arena, the same persistent user-record family retains account settings and stores an <code>arena_wins[]</code> count for each mode. Its <code>score</code> is repurposed as total arena wins for roster sorting; per-match kills, deaths, time, bases, and mode score live in <code>ARENAPLAYER</code>, not in permanent ship records. The win array takes bytes from reserved filler so that the arena variant keeps the same record length within its architecture. Arena and standard-game databases are separate and should not be interchanged.

=== WARSHP: ship state ===
A ship record begins with its owner ID and <code>shipno</code>, followed by name, class, status, coordinates, heading and target heading, speed and target speed, damage, flux energy, phaser and shield state, cloak state, and live control damage. It also holds the current lock, last attacker, ship kill counts, inventory, repair and combat timers, deployed decoy references, and incoming torpedo/missile tracking. The <code>ltorps[]</code> and <code>lmissl[]</code> arrays are ordnance pursuing ''this'' ship, not a list of everything this ship has fired. Later fields include upgrade bits, jamming, weapon throttles, overspeed accumulation, and state used by Cybertrons and other NPCs. Some fields are explicitly user-only or NPC-only even though they share the same record format.

The live ship slot or MajorBBS channel is not the same thing as persistent <code>shipno</code>. A slot can be reused; it must not be treated as a stable player identity in delayed combat state. See [[Ship slot]] and [[Ship number]]. Standard ge-next stores player and NPC ship records in the ship database; ge-arena uses disposable match ships, while its persistent user records remain. ge-arena's <code>damage_notice</code> byte for Cyber-Base warning thresholds consumes one byte of the 16-bit ship filler rather than increasing <code>WARSHP</code>.

Classic carried fields associated with abandoned or partial ideas, including <code>train</code> and an <code>emulate</code> flag in the original header. The 0.2.6 line still retained the old field ordering, a 35-character ship-name array, and several fields added into legacy spare space. Before RC2, the ship-name array was brought into line with its actual usable length. In 0.3 RC2, <code>status</code>, <code>coord</code>, movement values, combat state, equipment, and NPC state were regrouped, and unused/redundant members were removed. The new field order makes the record easier to audit but changes offsets, which is why old databases cannot be opened as though they were 0.3 records.

=== Sector, planet, and wormhole ===
<code>GALSECT</code>, <code>GALPLNT</code>, and <code>GALWORM</code> are different records in the ''same'' planet database. Each begins with <code>xsect</code>, <code>ysect</code>, <code>plnum</code>, and <code>type</code>, allowing a shared sector/number key. The sector index has <code>plnum == 0</code> and contains <code>numplan</code> plus up to nine <code>PLNTCOORD</code> entries identifying the type and position of each body. Planets and wormholes use numbered body records; their filler makes every record in this Btrieve file the same length. <code>PKEY</code> is the small lookup key used to address these records, not another stored body format. See [[Sector]] and [[Wormholes]].

A <code>GALPLNT</code> record holds its coordinates, owner, name, environment and resource ratings, cash and tax, tax rate, trade password, fourteen <code>ITEM</code> entries, beacon, spy owner, team code, and update bookkeeping. Each <code>ITEM</code> has quantity, production rate, allied-sales flag, reserve, allied markup, and amount sold to allies. An unowned planet still has a full planet record; ownership does not determine whether the record exists. Standard ge-next uses <code>timestamp</code> and <code>plantimesave</code> to schedule and resume production, and stores the nebula seed in Zygor's <code>nebseed</code> field. ge-arena leaves its nebula seed in memory; its planet filler instead contains shield/phaser boosts and flags for upgrades or maintenance, alongside the normal item fields. See [[Planetary production]], [[Zygor]], and [[Nebulas]].

<code>GALWORM</code> stores entrance coordinates, a destination coordinate, visibility flag, and optional name. It has no planet economy or owner. Both planet and wormhole records share the sector key prefix and fixed-size database slot, but their remaining bytes mean different things. Blindly interpreting a wormhole as <code>GALPLNT</code> would turn destination and padding bytes into bogus planet fields.

=== Mail ===
Standard 16-bit ge-next opens its mail database using <code>sizeof(MESSAGE) + GEMSGSIZ</code>, documented as a 1000-byte packed record. <code>MESSAGE</code> is a MajorBBS-style message header and text envelope; <code>MAIL</code> and <code>MAILSTAT</code> are GE's ''payload formats'' placed inside that text, not independent 1000-byte Btrieve records. A normal delayed report can carry a template ID, class, recipient, names, coordinates, and numeric parameters; a production-status report uses <code>MAILSTAT</code> to carry a planet snapshot. The 32-bit port wraps the V10 message header and a fixed GE text payload in <code>GEMESSAGE</code>, and opens the database using <code>sizeof(GEMESSAGE)</code>. ge-arena does not use the mail database. See [[Classic bug: Rejected mail leaks into output]].

The published classic GE source includes <code>message.h</code> but does not provide the file. GE's private mail database uses a message structure modeled on the MajorBBS mail header; classic could also route reports to a player's MajorBBS mailbox. The classic release notes describe GE mail as the older path and say that a later release made the personal mailbox the default while retaining GE mail through <code>USEGEMSG</code>. The distributed 3.2e <code>MBMGEMSG.MSG</code>, however, sets <code>USEGEMSG</code> to <code>YES</code>, selecting GE mail. The notes do not establish why the GE database adopted this structure or when the two delivery paths first appeared. Early ge-next reconstructed <code>MESSAGE.H</code> from MajorBBS <code>GME.H</code> to restore the missing definition. It subsequently removed the MajorBBS-mail delivery option and kept GE mail, then folded the reconstructed <code>MESSAGE</code> definition directly into <code>GEMAIN.H</code>.

=== Teams ===
<code>TEAM</code> is a fixed-width team entry containing the code, name, member count, deletion date, password, and secret. Standard ge-next loads and saves its team table to <code>MPOGETEA.DAT</code> as a separate text-backed table, not as a Btrieve planet/user/ship record. ge-arena does not use that file; any future arena teams are intended to be match-local. User and planet <code>teamcode</code> fields still exist in their record layouts. See [[Teams]].

== Live tables and workspaces ==
{| class="wikitable"
! Type !! Lifetime and purpose
|-
| <code>COORD</code> || Two floating-point world coordinates. <code>coord1()</code> derives a sector; <code>coord2()</code> derives the within-sector position.
|-
| <code>PLANETAB</code> || One ship/channel's cached nearby planets and wormholes. It is refreshed as sectors change; stale or cross-user cache use can produce incorrect gravity/orbit behavior. See [[Classic bug: Cross-user planet cache corruption]].
|-
| <code>SCANTAB</code> / <code>SHIPTAB</code> || Per-user scan contacts, assigned letters, distances, and headings. This is a bounded display/index table, not a persistent roster of all ships. See [[Scantab]].
|-
| <code>MINE</code> || Global active-mine slot: owner marker, timer, and location. Ownerless and unused are distinct markers in ge-next.
|-
| <code>TORPEDO</code> / <code>MISSILE</code> || Compact incoming-projectile entries in <code>WARSHP</code>, including the firing ship slot, distance to impact, and for missiles remaining energy.
|-
| <code>SHIP</code> || Loaded ship-class settings and NPC function hooks; configured from the ship-class MSG file, not a user ship record. ge-arena adds per-mode class and starting-loadout fields to this in-memory configuration.
|-
| <code>S00</code> / <code>WORMTAB</code> || Predefined neutral-zone body descriptions and temporary wormhole-pair construction data.
|-
| <code>ENTRYTAB</code> || Per-channel throttling/timing state for ship-entry announcements.
|-
| <code>ARENAPLAYER</code> || ge-arena-only live player state: lobby readiness, match state, selected ship, respawn delay, kills/deaths, and mode score. It is reset independently of persistent arena wins.
|}

The game also uses globals such as <code>warsptr</code>, <code>waruptr</code>, <code>plptr</code>, and temporary record buffers as shared workspaces. These are intentional in the synchronous MajorBBS execution model; they are not independent copies for concurrent requests. A port that introduces concurrent handlers must isolate or serialize access to them.

== How the layout evolved ==
* '''Classic 3.2e:''' The large records contained reserved filler and some fields with little or abandoned gameplay use, such as <code>WARUSR.waste</code>, user/planet debt, and <code>GALPLNT.technology</code>. Others that look obscure, such as <code>rospos</code>, were active. Classic packed multiple planetary body types into a shared fixed-length database, and relied on compile-time structure sizes and key offsets.
* '''ge-next 0.1:''' The first compiled ge-next release fixed cash/tax overflow behavior and several planetary and ship calculations while remaining broadly close to classic's storage scheme. These fixes should not be confused with 0.3's later wholesale layout change.
* '''ge-next 0.2 and 0.2.6:''' The NPC and planet-update overhaul added faction relation bytes to <code>WARUSR</code>, repurposed ship state for new NPC behavior, and replaced the planet's unused debt field with update timing. Subsequent pre-0.3 work added separate user-kill counts, a nebula seed, lock and entry state, and upgrade/overspeed fields, largely by using space in the legacy-shaped records. The 0.2.6 header still shows classic-style ordering and reserved areas.
* '''ge-next 0.3 RC2 onward:''' The broad restructuring removed obsolete fields, grouped related data, normalized types and names, assigned explicit offsets in comments, and recalculated filler. A separate 0.3 fix corrected <code>GALPLNT</code>'s filler after its actual item-array size was verified. Compatibility with earlier saved games was deliberately broken; resetting the databases was required. Later arena builds consume reserved bytes for arena wins, powerups, and NPC notices without changing each build's fixed record length.

The source comments documenting offsets are an audit aid, not a substitute for checking <code>sizeof</code> and actual Btrieve key definitions. The V10 port uses fixed-width <code>SHORT</code>, <code>USHORT</code>, and <code>ULONG</code> fields where appropriate and compile-time size assertions for the major records. Copying a 16-bit <code>.DAT</code> file to the 32-bit port is not a record conversion; it requires a deliberate field-by-field migration, including key layout, signedness, and reserved bytes.

== See also ==
* [[Source code]]
* [[Classic bug database]]
* [[Porting Galactic Empire]]
* [[Integer and storage assumptions]]

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

Data structures - Revision history

CodexBot: Link Btrieve explanation at first mention