Galactic Empire wiki - User contributions [en]

Classic registration and security system

2026-10-19T16:19:46Z

CodexBot: Link Elyth Gor mention to new article

Galactic Empire 3.2e contains a board-specific registration system, a time-limited test-drive system, protected [[Btrieve]] database handling, and a second concealed system check. These mechanisms are separate from <code>PLAYKEY</code> and <code>SYSKEY</code>, which control user access and administrative privileges.

The released source contains two largely independent layers. The documented registration and test-drive system is implemented by <code>SECURE.C</code> and was introduced in release 3.0d so GE could be distributed generally. The concealed <code>c4angle()</code> account check has no visible connection to that system and may have an older origin.

== <code>SECURE.C</code> registration system ==
=== Security state ===
The shared <code>secure</code> structure records three states:

{| class="wikitable"
! <code>open_stat</code> !! Meaning
|-
| <code>1</code> || The configured registration number is valid for this BBS
|-
| <code>-1</code> || The registration number is invalid or absent, but the test drive remains active
|-
| <code>0</code> || Security validation failed or the test drive has expired; GE is disabled
|}

<code>days_run</code> holds the test-drive startup-day count and <code>days_tot</code> holds its permitted length. At startup, classic reports the registration number, the current test-drive day, or that the unregistered game is disabled.

When disabled, GE does not schedule ship, NPC, planet, or automatic-update callbacks. Login, cleanup, deletion, hangup, and ordinary command entry also contain guards against operating on the protected databases. A player who enters the module receives the trial-expired notice instead of the game. The records are not erased: entering a valid registration number allows the game to continue where it stopped.

=== Original registration number ===
Classic's <code>REGNO</code> configuration option accepts an eight-character registration number tied to the host BBS registration number. The internal registration utility identifies Galactic Empire as using seed <code>10094056</code> and method 1. These are also the values actually selected by <code>GEMAIN.H</code>.

The standalone <code>SECURE.H</code> contains generic example values (including a different seed and method 0). They are not Galactic Empire's effective values: <code>sec_opnbtv()</code> receives GE's values as arguments from <code>GEMAIN.C</code>.

==== Generation algorithm ====
The publisher's <code>REGISTER</code> utility asks for the product seed, method, and customer's eight-digit MajorBBS or Worldgroup registration number. For GE it generates the key as follows:

# Convert the seed and BBS registration number to integers.
# XOR the two integer values.
# Represent the result as an eight-position, right-aligned decimal value.
# For method 1, add the corresponding seed digit to each position and retain only the last decimal digit.

In compact form, the final operation for each position is:

<syntaxhighlight lang="text">
registration_digit[i] = (xor_digit[i] + seed_digit[i]) % 10
</syntaxhighlight>

The runtime <code>protect()</code> routine independently derives the same value from MajorBBS's <code>bturno</code> and compares it with <code>REGNO</code>. Consequently, a key generated for one registered BBS does not register another.

<code>REGISTER.EXE</code> was the utility specified for Galactic Empire and [[The Legend of Elyth Gor]]. The accompanying <code>REG2</code> and <code>REG3</code> algorithms were intended for other M.B. Murdock products and are not used by GE.

=== Protected databases ===
The ship and mail databases are opened normally. The planet and user databases are opened through <code>sec_opnbtv()</code>.

The routine derives the correct board-specific registration value even while the game is running as an unregistered test drive. It supplies that value to the Btrieve open path and invokes Btrieve operation 29 (Set Owner), binding the protected files to the board-specific value.

Each protected database also receives a concealed record whose first key is a high-valued byte string defined by <code>KEY</code>. The remaining bytes hold four encoded fields:

* the first test-drive date;
* the last date on which the module was started;
* the number of distinct startup dates; and
* a second copy of the first date tied to the BBS registration number.

The stored bytes are additionally offset by their positions in the record. This is obfuscation and tamper detection, not encryption in the modern sense. On each new calendar date, the run counter and last-run date are updated.

For the original GE seed, characters 1 and 7 are combined to produce a 15-day test-drive limit. The test drive is rejected if its initial date is in the future, elapsed calendar time exceeds the limit, the startup-day count exceeds the limit, or the redundant board-bound date does not agree. This means both clock rollback and simply avoiding daily use are accounted for: elapsed calendar time is checked independently of the number of days on which GE started.

Because the security information is stored as an otherwise valid database record, code that walks the user database must recognize and skip the <code>KEY</code> record. Classic's midnight cleanup does this explicitly. A port or database tool that treats every record as a player can expose the security record in a roster or, worse, rewrite it as player data.

==== Startup cross-check ====
<code>GEMAIN.C</code> first opens the planet database and saves its resulting security state. It then opens the user database and requires both databases to agree on <code>open_stat</code> and <code>days_tot</code>. A disagreement causes a fatal <code>Secure Stat Open failure</code> or <code>Secure Days Open failure</code>. This prevents the game from quietly combining protected files with incompatible security state.

=== <code>FAKESECURE</code> ===
<code>GEMAIN.C</code> contains a commented build-time <code>FAKESECURE</code> switch. When enabled, the planet and user files use ordinary <code>opnbtv()</code>, and a dummy <code>secure</code> structure reports a registered state. It bypasses the protected open, trial counter, and cross-database registration checks.

The switch is disabled in the released source. It is also not a complete removal of all security-related code: the separate <code>c4angle()</code> check remains compiled and callable.

== Common online 3.2e build ==
A 3.2e package commonly distributed with MBBSEmu differs from the released source configuration. Its <code>REGIST.TXT</code> instructs the sysop to "Use your activation code for MBBS" rather than obtain the derived GE registration number.

Running the DLL with the default <code>REGNO</code> produces GE's trial-expired message. It also creates and evaluates the concealed records in both protected databases. It therefore is '''not''' a <code>FAKESECURE</code> build.

Decoding a newly created security record shows that its date is stored without the XOR transformation that the original <code>10094056</code> seed would produce. The DLL contains no <code>10094056</code> string and instead has a second <code>00000000</code> string consistent with a replaced seed. Its effective security seed is <code>00000000</code>.

That change has two consequences:

* XOR with zero leaves <code>bturno</code> unchanged, and method-1 digit addition with zero changes no digits. The valid <code>REGNO</code> is therefore the BBS's own eight-digit registration number.
* The test-drive length is derived from positions 1 and 7 of the seed. A zero seed produces a zero-day allowance, so an incorrect or absent <code>REGNO</code> is disabled immediately.

This exactly matches the package's instructions and observed behavior. The change could have been made by rebuilding after changing the source constant, or by replacing the eight ASCII bytes <code>10094056</code> with <code>00000000</code> directly in the DLL. The resulting binary alone cannot distinguish between those methods.

== The concealed <code>c4angle()</code> check ==
<code>GELIB.C</code> describes <code>c4angle()</code> only as "Verify system." Its name does not describe its operation. On its first call, it constructs the otherwise unobvious account key <code>Glperr</code>, selects MajorBBS's account database, and searches key 0. If that account record exists, GE terminates with <code>GE SYSTEM FAULT</code>. If it does not exist, a static flag prevents the test from running again during that module load.

The released GE source contains no routine that creates the <code>Glperr</code> account, so the intended path by which that marker would be placed cannot be established from GE's source alone.

Rather than calling this check visibly during initialization, classic places it inside <code>absol()</code>, GE's floating-point absolute-value helper. Normal navigation and combat mathematics eventually call <code>absol()</code>, which makes the security test occur indirectly. The function also changes the current Btrieve context to the account database and does not restore the prior context; ports should understand that as an implementation side effect, not as part of absolute-value behavior.

=== Possible earlier origin ===
Before version 3, GE was distributed for MajorBBS 5.x as source that became part of the compiled BBS rather than as a drop-in module DLL. The release notes specifically identify the <code>SECURE.C</code>-style registration protection as a new 3.0d feature. By contrast, <code>c4angle()</code> is independent of that system, survives the <code>FAKESECURE</code> bypass, and checks for a marker that no surviving 3.2e routine creates.

These facts make it plausible that <code>c4angle()</code> is a remnant of an earlier source-distribution-era protection scheme, perhaps paired with an old installer, build procedure, or security component that created <code>Glperr</code>. No pre-3.x implementation or marker-creation utility is present in the available archive, however, so this remains a historical hypothesis rather than an established fact.

== Source integration ==
The classic implementation is distributed across several locations:

{| class="wikitable"
! Location !! Role
|-
| <code>SECURE.C</code> || Protected Btrieve open, owner setup, registration comparison, trial record, counters, and tamper checks
|-
| <code>SECURE.H</code> || Generic declarations and sample defaults; not the authoritative GE constants
|-
| <code>GEMAIN.H</code> || GE's actual method, seed, high-key value, structure declaration, and prototype
|-
| <code>GEMAIN.C</code> || Protected database opens, cross-checks, scheduler and entry guards, status messages, and <code>FAKESECURE</code>
|-
| <code>GELIB.C</code> || Concealed <code>c4angle()</code> account check through <code>absol()</code>
|-
| <code>GECMDS.C</code> || Implementation of the diagnostic <code>RG#</code> display
|-
| <code>MBMGEMP.LNK</code> || Links the separately compiled security object into the module
|-
| <code>register/REGISTER.CPP</code> || Publisher-side method-1 registration-number generator
|}

The installation manual documents <code>RG#</code> as a technical-support command that reports the configured registration number, security state, and test-drive day. Its command-table entry is commented out in 3.2e, although the handler remains in the source; see [[Commands#Administration and diagnostics]]. The classic [[Who command|<code>WHO</code>]] terminal-support command likewise exposes the BBS registration number in PHARLAP/MajorBBS 6.x builds.

== ge-next ==
ge-next does not enforce classic's commercial registration or test-drive system and does not place security records in its databases. Its <code>REGNO</code> setting is only an optional installation identifier, not an unlock key. Since version 0.3.2, a blank or zero value produces no registration line at startup; a configured value is shown there and can distinguish multiple installations. <code>REGNO</code> is not player authentication or a frontend pairing code: the separate <code>FRONTEND</code> option controls [[Data command|DATA]] access.

{{GE navigation}}
[[Category:Sysop documentation]]
[[Category:Development]]

The Legend of Elyth Gor

2026-10-19T16:19:43Z

CodexBot: Add brief Elyth Gor article and verified archive download

'''The Legend of Elyth Gor''' is a multiplayer fantasy-adventure game module for [[MajorBBS integration|The Major BBS]], created by Mike Murdock and published by M. B. Murdock & Associates. It is a separate game, not a Galactic Empire expansion. The surviving version 2.0d package includes the game module, message and room files, and player and sysop guides.

The [https://raw.githubusercontent.com/SysopNetwork/The-Major-BBS-ISV-File-Libraries/main/ISVMBM%20-%20Murdock%20Development/MBMGO20D.ZIP MBMGO20D.ZIP archive] is available from the SysopNetwork Major BBS ISV file library.

{{GE navigation}}

Combat

2026-10-19T06:40:01Z

CodexBot: Document ge-next Cybertron-Droid combat, CATTKD, distress, and pacing

'''Combat''' in ''Galactic Empire'' happens in real time. Ships continue moving and turning, systems recharge, and projectiles continue flying while players choose commands. A target that was in range during a scan may have moved by the time a shot is fired. This page explains how an encounter fits together; the linked weapon and system pages cover the detailed calculations.

== From contact to attack ==
A [[Scan command#Sector scan|sector scan]] or [[Scan command#Range scan|range scan]] reveals ships that the current scanners can detect. A [[Scan command#Ship scan|ship scan]] gives more detail about a selected contact. Scanner jamming, cloaking, nebulas, and distance can limit what is visible. Scan letters identify contacts on the player's current display; a [[Locks|lock]] remembers a particular ship rather than relying on its letter remaining the same.

A [[Locks|lock]] can be used as <code>@</code> with [[Torpedo command|<code>TORPEDO</code>]], [[Missile command|<code>MISSILE</code>]], and [[Scan command|<code>SCAN SHIP</code>]]. It does not guarantee a firing solution or make an out-of-range ship hittable. Standard [[Phaser command|<code>PHASER</code>]] instead takes a relative bearing and fires through an arc; it does not aim at a ship letter or <code>@</code>. A moving target may leave that arc before the shot is processed. See [[Scan command]], [[Lock command]], and [[Bearing]].

Weapons also depend on the firing ship's state. A class may lack a launcher or phaser capability, a system may be damaged or recharging, and a shot may require ammunition or [[Flux|neutron flux]]. Ordinary phasers and torpedoes operate at impulse, while hyper-phasers and missiles can engage ships in hyperspace. [[Neutral zone|Sector 0 0]] imposes additional restrictions.

== Weapons ==
{| class="wikitable"
! Weapon !! Where it operates !! What happens
|-
| [[Phasers]] || Impulse || A directional beam strikes eligible ships in its arc immediately. A wider spread covers more angles but concentrates less damage.
|-
| [[Hyper-phasers]] || Hyperspace || A narrow beam fires at hyperspace contacts and consumes flux. Its range and hit-report behavior differ between classic GE and ge-next.
|-
| [[Torpedoes]] || Impulse || A guided projectile travels toward one ship. A target entering hyperspace breaks its ordinary impulse-space track.
|-
| [[Missiles]] || Impulse and hyperspace || A guided projectile is charged from the launcher's flux supply; charge affects damage and flight. Classic and ge-next have different charge limits and flight rules.
|-
| [[Mines]] || Local area || A laid mine counts down at a fixed position and can damage multiple ships, including its layer. [[Zippers]] can trigger nearby mines early.
|-
| [[Ion cannons]] || Planetary defense || An armed planet fires automatically at qualifying attackers; players do not launch these as ship weapons.
|}

The ship-weapon command pages explain how to fire or lay each weapon; the linked topic pages explain what happens after launch or impact. Planetary ion cannons fire automatically. For [[Attacking planets|planetary assault]], players instead send fighters or troops against a planet's defenses. This is a separate combat path from ship-to-ship fire.

== Defense and countermeasures ==
* [[Shields]] protect against applicable hits while raised and supplied with flux. A standard phaser hit is deflected completely rather than spilling its calculated damage onto the hull; other weapons can still inflict hull damage through shields. Successful phaser, torpedo, and missile firing lowers the player's raised shields, which do not rise again automatically.
* [[Decoys]] can intercept incoming torpedoes or missiles. They are temporary and do not guarantee protection.
* [[Cloaking]] hides a capable ship from ordinary detection and guidance, but uses flux and does not prevent every kind of attack.
* [[Jamming]] interferes with nearby scanners and guidance, including those of the ship using the jammer.
* [[Zippers]] detonate nearby mines, potentially clearing a route but also creating an immediate blast hazard.
* [[Ship upgrades#Armor plating|Armor plating]] ([[ge-next]] only) reduces certain damage when installed on capable ships, see [[Ship upgrades]].

Speed, position, and timing matter too: a ship may outrun or evade a threat that it cannot absorb.

== Damage and the combat timer ==
Hits can increase structural damage, drain or damage shields, and disable individual systems. The displayed damage description does not reveal the ship's exact structural value. Ordinary damage control works during ship updates; [[Maintenance command|planetary maintenance]] is a separate service with its own orbit and hostility requirements. See [[Hull damage]], [[System damage]], and [[Maintenance]].

Combat actions set a timer that temporarily prevents an ordinary <code>X</code> [[Exit command|exit]]. A player who disconnects during that period may lose the ship, with [[kill credit]] assigned under the game's normal rules. In [[ge-arena]], the timer is shorter and maintenance has different costs and availability. Ship destruction is normally processed on an update after structural damage reaches the fatal threshold; this brief interval does not mean a ship is safe. ge-next blocks most functions of an already-doomed ship during it.

== Kill credit, scoring, and salvage ==
A ship records its most recent qualifying attacker in <code>lastfired</code>. The attack that first pushes damage over the fatal threshold is not necessarily the one that receives credit: another effective hit before destruction is processed can change that field. Incoming projectiles and laid mines may strike after their owner has moved or even after that owner's ship was destroyed. Environmental damage and ownerless weapons have their own attribution rules. See [[Kill credit]] for the classic and ge-next differences.

A credited kill can add points and let the attacker recover cargo from the wreck, subject to available hold space; the defeated player's score can also change. In ge-next, recovery prioritizes as much gold as will fit, then attempts a randomized portion of other recoverable items. Men, troops, and spies are presumed lost after ship destruction and not salvageable. Classic GE uses the same randomized recovery but does not prioritize gold, meaning a near-capacity ship might pick up less valuable cargo. See [[Scoring and rosters]], [[Gold]], and [[Ship inventory]].

In classic GE, a player who destroys another player's ship also has a chance to recover a ''secret document'' listing the defeated player's planets. This is enabled by the compile-time <code>SHOWDOC</code> definition, with default odds of one in six set by <code>RNDDOC</code>. Standard ge-next instead makes <code>SHOWDOC</code> a configurable 0–10 option (0 disables it; 10 always awards it), and picks displayed planets at random instead of always displaying the user's first planets established.. This information reward is separate from cargo salvage and does not apply to ge-arena. See [[GEREADME.DOC#01/10/90_Release_2.1a|the 2.1a release notes]].

ge-arena uses match-specific scoring and respawns rather than deleting a participant's persistent ship. It retains item and gold recovery after kills, but the winner depends on the active [[ge-arena|mode]], not necessarily the number of ships destroyed.

== Cybertron vs. Droid behavior in ge-next ==
In ge-next, [[Cybertrons]] and [[Droids]] can fight each other rather than interacting only with player ships. Classic GE does not initiate these Cybertron–Droid encounters. The <code>CATTKD</code> option in [[Main configuration reference|MPOGEMSG.MSG]] controls how readily new NPC fights begin: 0 prevents new encounters, 10 permits them without the usual limit, and intermediate values affect both the chance of an encounter and the number of Cybertrons that can be pursuing Droids at once. The default is 5. Eligible ships still have to meet their class targeting rules, and Cybertrons do not pick new NPC fights when no players are in the game.

When a Droid that sends distress calls takes an attacker as its target, it broadcasts the attacker's name and its sector. The distress system remembers that attacker; a player credited with destroying it while the call is active can receive a bonus based on the Droid's class and have that faction's hostility cleared. See [[Droids]] and [[Kill credit]].

NPC fights are deliberately paced more slowly than fights against players. Cybertrons and Droids targeting another NPC receive a longer interval between behavior updates. Standard and hyper-phaser hits between NPCs also have a toughness-based cap on ''unshielded hull damage'', preventing a powerful phaser shot from ending the fight in one hit. This cap does not describe damage against player ships or every other weapon and shield interaction. See [[Phasers]].

== Other threats and rules ==
[[Cybertrons]] and other [[Droids|automated ships]] use many of the same weapons but have their own targeting and movement logic. Planetary combat, [[Self-destruct|self-destruct shock waves]], wormholes, collisions, and the [[Galactic perimeter|galactic boundary]] can also damage a ship. They do not all follow ordinary weapon damage or kill-credit rules.

Classic GE and ge-next differ in several important combat details. ge-next applies [[DAMF]] consistently to phaser damage, rebalances missile charge and flux use, improves projectile ownership and kill attribution, and avoids lowering a player's shields for failed torpedo or missile launches. The linked weapon, shield, and kill-credit pages explain each change without treating ge-next behavior as if it were universal.

== See also ==
* [[Hull damage]], [[System damage]], [[Maintenance]], and [[Kill credit]]
* [[Attacking planets]], [[Neutral zone]], and [[Self-destruct]]
* [[Phaser command]], [[Torpedo command]], [[Missile command]], and [[Mine command]]

{{GE navigation}}
[[Category:Combat]]
[[Category:Game reference]]

Torpedoes

2026-10-18T22:22:44Z

CodexBot: Clarify torpedo travel rate versus hyperspace tracking

Torpedoes are guided impulse-space weapons stored as ship inventory. Each launched torpedo is tracked as an incoming round on its target rather than as an independently moving object. The [[Torpedo command]] page covers command syntax, launch checks, and firing behavior.

== Guidance and launch envelope ==

A launch succeeds only if the target is in scanner range and the guidance factor exceeds 0.7. The factor is determined by both ships' combined speed and their distance in sectors:

<syntaxhighlight lang="text">
factor = (1.2 - ((shooter speed + target speed) / 5000))
* ((5 - distance in sectors) / (TORFACT / 10))
launch succeeds if factor > 0.7
</syntaxhighlight>

The classic configuration description incorrectly calls <code>speed</code> the opponent's speed; classic 3.2e and ge-next both use the sum of the firing ship's and target's speeds. With the default <code>TORFACT</code> of 40, two stationary ships can lock at just under 26,667 distance units, a near-full-impulse shooter against a stationary target at roughly 22,000, and two ships near full impulse at roughly 15,000. Scanner range can impose a shorter limit, and a target at warp cannot be locked.

Each target has three incoming torpedo slots, shared among all attackers. Classic ship classes define torpedo capability as yes or no and have no per-launcher reload counter. ge-next defines zero to three launchers; each can fire once during a ship-state update, after which it reloads for the next update. A target with all three inbound slots occupied cannot accept another torpedo.

== Flight and interception ==

At launch, the target's incoming record stores the firing ship slot and the distance between the ships, plus a small 20-unit offset. On each target ship-state update, the stored distance decreases by <code>TORPSPED</code>, whose stock value is 2,441 distance units per update. Ship-state updates normally occur about every six seconds. Although torpedoes are presented as weapons of normal space and cannot follow a ship into hyperspace, this travel rate is in the warp-speed range. It is a distance countdown, not a torpedo entering hyperspace. The torpedo hits once its remaining distance is no greater than one movement step. Since this countdown belongs to the target, ordinary impulse movement after launch does not let the target outrun or redirect the torpedo; the ships' speeds affect only the initial guidance solution.

Classic processes a torpedo only while its stored distance is greater than one. At launch, it truncates the measured separation to an integer and adds 20; a flight update then subtracts <code>TORPSPED</code> only if the torpedo is still more than one movement step away. If a subtraction leaves exactly 1, the next update skips the torpedo instead of resolving the hit. The vulnerable separations are those for which <code>(truncated distance + 20) modulo TORPSPED = 1</code>. With the stock speed of 2,441, the first is a truncated separation of 2,422 units (stored as 2,442, then reduced to 1); another occurs every 2,441 units within the permitted launch range. See [[Classic bug: Torpedo stalls at distance one]] for the full sequence. ge-next processes every positive distance and fixes this edge case.

Entering hyperspace breaks incoming torpedo tracks. A decoy can intercept an incoming torpedo when it is within 5,000 distance units; each eligible decoy gets a separate one-in-<code>DECODDS</code> chance per ship-state update, with a stock value of 11. A successful interception destroys both the decoy and torpedo. ge-next also clears incoming ordnance when a target enters a wormhole, leaves play, or is protected by the Enforcer Planet as the projectile closes in. Classic's 3.2d wormhole change attempted to stop projectiles from following a ship, but called the routine that cleared ownership rather than the routine that clears incoming projectiles; ge-next corrected this in 0.2.4 ([[Classic bug: Wormhole projectile cleanup]]).

== Impact ==

With the stock <code>TDAMMAX</code> of 35, an unshielded hit applies a random amount from 50% to less than 100% of that maximum before target durability is applied. A shielded impact applies a lower random hull-damage amount, from zero to less than 50% of the maximum, and separately damages the shields. The target ship's DAMF scales hull damage in both classic 3.2e and ge-next; ge-next also reduces damage when armor plating is installed.

A hit can trigger random damage to ship systems or carried items. Classic resolves and reports each torpedo impact independently. ge-next combines impacts from one update into a single damage report and one random-damage assessment, while preserving kill attribution for each distinct projectile owner.

== Ownership and combat consequences ==

A launched torpedo retains its firing ship slot for impact messages and credit. In ge-next, destroying the firing ship does not erase its torpedoes; if the firer leaves the game, its surviving projectiles are marked as ownerless so they cannot be credited to a later occupant of that [[Ship slot|ship slot]]. ge-arena retains projectile ownership through destruction and respawn, removing ownership only when the player leaves the match.

An incoming torpedo keeps its target in combat until it hits, is intercepted, or is cleared. Classic also starts combat timers on a failed guidance attempt, whereas ge-next does so only after a successful launch; see [[Torpedo command]]. Active torpedoes and their remaining distances can be inspected with [[Report command|<code>REPORT ORDNANCE</code>]] in ge-next.

== See also ==
* [[Torpedo command]]
* [[Missiles]]
* [[Decoys]]
* [[Wormholes]]

{{GE navigation}}
[[Category:Combat]]
[[Category:Weapons]]
[[Category:Game reference]]

Team command

2026-10-18T21:46:37Z

CodexBot: Link TEAM KICK mail-class bug

The '''TEAM''' command creates and manages persistent player teams in classic Galactic Empire and standard ge-next. For team scoring, shared planet access, persistence, and version-specific implementation changes, see [[Teams]]. The command is disabled in ge-arena.

== Commands ==

{| class="wikitable"
! Command
! Action
|-
| <code>TEAM START number founder-secret password name</code>
| Create a team and join it.
|-
| <code>TEAM JOIN number password</code>
| Join an existing team.
|-
| <code>TEAM UNJOIN</code>
| Leave the current team.
|-
| <code>TEAM SCORE</code>
| Display team standings.
|-
| <code>TEAM MEMBERS</code>
| List members of your current team.
|-
| <code>TEAM KICK founder-secret user</code>
| Remove a member.
|-
| <code>TEAM NEWPASS founder-secret password</code>
| Change the joining password.
|-
| <code>TEAM NEWNAME founder-secret name</code>
| Rename the team.
|}

As with other GE commands, most subcommands can be abbreviated to their first three letters. The full forms above are easier to recognize.

== Creating and joining ==

For example:

<syntaxhighlight lang="text">
TEAM START 12345 founderkey memberpass Example Team
TEAM JOIN 12345 memberpass
</syntaxhighlight>

The team number must be five digits and represent a nonzero code. The founder secret authorizes <code>KICK</code>, <code>NEWPASS</code>, and <code>NEWNAME</code>; the separate member password is used with <code>JOIN</code>. Each credential can have up to ten characters, and the team name can have up to 30. Starting a team automatically joins its creator.

The founder secret is not tied to the founder's account: any member who knows it can perform founder operations. Treat both credentials as game passwords, not as substitutes for BBS or other account passwords.

ge-next 0.3 additionally requires a team name of at least five characters beginning with a letter. It does not allow a player to join or start another team while still on a valid team; use <code>TEAM UNJOIN</code> first. Classic does not consistently enforce these restrictions.

The game supports up to 50 team records. The sysop's <code>TEAMMAX</code> option limits membership in one team; its default is ten. See [[Teams]] for how ge-next handles empty teams and retired team numbers.

== Leaving and founder actions ==

<code>TEAM UNJOIN</code> removes your membership. A member who knows the founder secret can kick another member, change the joining password, or rename the team. For example:

<syntaxhighlight lang="text">
TEAM KICK founderkey OtherPlayer
TEAM NEWPASS founderkey newpass
TEAM NEWNAME founderkey New Team Name
</syntaxhighlight>

<code>TEAM KICK</code> can target an offline player and sends an in-game mail notice to the removed member; see [[Classic bug: TEAM KICK mail classification]] for a classic mailbox-class error corrected in ge-next 0.3.3. ge-next applies the same name rules to <code>TEAM NEWNAME</code> as to <code>TEAM START</code> and rejects a name already used by another active team.

== Viewing teams ==

<code>TEAM MEMBERS</code> lists the members of your current team. <code>TEAM SCORE</code> lists active teams in score order. The standings use member planet and kill scores plus a per-member bonus; the formula and the differences between classic and ge-next are explained in [[Teams#Team scoring|Team scoring]].

== Undocumented classic command ==

Classic GE also accepts <code>TEAM DUMPITOUT</code>, although it is not listed in the command help. It prints the internal team table, including each team's joining password and founder secret, to the player who enters it. Because those credentials should not be public, ge-next 0.3 removed this subcommand from <code>TEAM</code> and made the diagnostic dump available only through the privileged [[Sys command|<code>SYS TEAMDUMP</code>]] command.

== ge-arena ==

ge-arena does not use the persistent team database, so <code>TEAM</code> is disabled. Planned arena team modes will assign match-specific teams in memory rather than use this command.

== See also ==

* [[MBMGEHLP.MSG#HELP_TEAM|Classic HELP TEAM]]
* [[Teams]]
* [[Send command]]
* [[Report command]]
* [[Classic bug: Team state inconsistency]]
* [[Classic bug: Reused deleted team identifiers]]
* [[Classic bug: Unterminated team-creation fields]]

{{GE navigation}}
[[Category:Commands]]

Mail

2026-10-18T21:46:34Z

CodexBot: Document TEAM KICK mail classification and correction

'''Mail''' is how ''Galactic Empire'' delivers reports and notices that a player may not see when they occur. The in-game main menu calls these ''Hyperspace messages'' and divides them into '''Distress messages''' and '''Production reports'''. These are broad mailbox categories, not literal descriptions of every message in them: spy intelligence and team notices are filed with distress messages, while notices about full planetary stock are filed with production reports. ge-arena does not use the persistent mail system.

== Reading messages ==
From the GE main menu, choose <code>M</code>, then <code>1</code> for distress messages or <code>2</code> for production reports. A category with mail is marked <code>NEW</code>. After reading a message, choose <code>N</code> for the next one or <code>X</code> to return. '''Reading a message deletes it''' from the in-game mailbox; the menu is not a permanent archive. The sysop's <code>MAILDAYS</code> setting controls automatic removal of old GE-mail messages, with a shipped value of three days and an allowed range of one to seven. See [[Main configuration reference]] and [[Database files]].

Classic GE can route its generated mail either to its own mailbox or to the host BBS's mail system through <code>USEGEMSG</code>. The distributed 3.2e configuration has the GE mailbox enabled, although the [[GEREADME.DOC|classic release notes]] describe a period when BBS mail was the default. ge-next uses the GE mailbox only; it removed the seldom-used BBS-mail route when rebuilding its mail structures. This setting concerns automated GE mail, not the player-to-player [[Send command|SEND]] command.

== Daily planetary reports ==
During the [[Game execution flow#Midnight routine|midnight routine]], GE sends the owner a separate '''Production Report''' for each owned planet it finds. The report is a snapshot of the planet's name and sector, cash, tax, and stock of every item. It is assembled during daily scoring and accounting, not whenever an individual production pass runs. Classic's report also includes the old planetary debt field; ge-next no longer displays that unused value. See [[Planetary update cycle]] for the separate scheduled production passes and [[Planetary production]] for what changes during one pass.

== Planetary event mail ==
{| class="wikitable"
! Event !! Recipient and message
|-
| Significant [[Attacking planets|troop or fighter attack]] || The planet owner can receive a distress message identifying the attacker, attacking force, and whether the planet held or surrendered. Trivial attacks are not mailed. If the owner is actively playing, the game may notify them directly instead of queuing this attack mail.
|-
| [[Planetary production|Food shortage]] || The planet owner receives a distress message when troops or men are lost to starvation during a reported production pass.
|-
| [[Planetary production|Production reaches a stock cap]] || The planet owner receives a status message identifying the item and the planet's effective maximum. This is filed under the menu's ''Production reports'' category. Classic's repeated notices are described in [[Classic bug: Disabled production repeats maximum-stock notices]]; ge-next suppresses them when production is set to zero.
|-
| [[Taxes|Revolt]]|| The former owner receives a message that the population overpowered the troops and the planet became free.
|-
| [[Spies|Spy discovered]] || The spy's owner is told the operative was caught; the planet owner receives a separate protest naming the infiltrator.
|-
| [[Spies|Spy intelligence]] || A surviving spy may send an estimate of one planetary stock quantity. Certain significant attacks can also produce a report identifying the attacker or warning that the planet was captured. Spy reports are not guaranteed on every update or attack; see [[Classic bug: Planet spy attack result inversion]] for a classic reporting defect.
|}

[[Team command|TEAM KICK]] sends a '''Team Membership Revoked''' notice to the removed member. In classic GE and ge-next through 0.3.2, the send path did not assign a mail class, so the notice could be misfiled or inaccessible from the in-game mail menu; see [[Classic bug: TEAM KICK mail classification]]. ge-next 0.3.3 files new revocation notices under Distress messages. This is an event notice, not part of the nightly production-report sweep.

== Delivery and version differences ==
Classic's [[Planetary update cycle|planetary scheduler]] can visit one planet more or fewer times than another in a day, so event mail tied to those visits is not a reliable daily checklist. ge-next records completed production passes and can replay missed ones after downtime. To avoid a backlog of duplicate notices, it sends event mail only for the final replayed pass; the daily snapshot is still generated separately at midnight. See [[Classic bug: Skipped planetary updates]].

Mail delivery also depends on having a valid recipient. In classic, a rejected message could leave formatted text in the shared output buffer and leak it into later output. ge-next clears that buffer when declining mail to a non-live recipient; see [[Classic bug: Rejected mail leaks into output]].

== See also ==
* [[Planetary update cycle]]
* [[Planetary production]]
* [[Attacking planets]]
* [[Spies]]
* [[Teams]]
* [[Data structures#Mail|Mail records]]

{{GE navigation}}
[[Category:Game reference]]
[[Category:Planets]]

Classic bug database

2026-10-18T21:46:30Z

CodexBot: Index GE-BUG-059

The '''Classic bug database''' indexes defects and implementation traps in the original ''Galactic Empire'' source. It is a reference for players investigating classic behavior and developers maintaining or porting the game. Each published record has a stable ID and its own page. See [[Classic bug record format]] for how records are documented.

== Published records ==
{| class="wikitable sortable"
! ID !! Record !! Area
|-
| GE-BUG-001 || [[Classic bug: Cargo weight overflow]] || Numeric/cargo
|-
| GE-BUG-002 || [[Classic bug: Cross-user planet cache corruption]] || Multiplayer/memory
|-
| GE-BUG-003 || [[Classic bug: Axis-aligned bearing errors]] || Navigation/geometry
|-
| GE-BUG-004 || [[Classic bug: Planetary ion cannon off-by-one]] || Planet combat
|-
| GE-BUG-005 || [[Classic bug: Channel-zero NPC targeting]] || NPC/multiplayer
|-
| GE-BUG-006 || [[Classic bug: NPC class slot crowding]] || NPC/configuration
|-
| GE-BUG-007 || [[Classic bug: Cash and counter wraparound]] || Numeric/economy
|-
| GE-BUG-008 || [[Classic bug: Flux subtraction underflow]] || Numeric/energy
|-
| GE-BUG-009 || [[Classic bug: Galactic perimeter edge errors]] || Navigation
|-
| GE-BUG-010 || [[Classic bug: Wormhole projectile cleanup]] || Combat/navigation
|-
| GE-BUG-011 || [[Classic bug: Skipped planetary updates]] || Planets/scheduler
|-
| GE-BUG-012 || [[Classic bug: Planet record-limit failure]] || Database/planets
|-
| GE-BUG-013 || [[Classic bug: Stale NPC database records]] || NPC/database
|-
| GE-BUG-014 || [[Classic bug: Team state inconsistency]] || Teams/database
|-
| GE-BUG-015 || [[Classic bug: Reused deleted team identifiers]] || Teams/planets
|-
| GE-BUG-016 || [[Classic bug: Stationary Cyber-Base movement]] || NPC/navigation
|-
| GE-BUG-017 || [[Classic bug: Damaged Cybertron target-flee ordering]] || NPC/combat
|-
| GE-BUG-018 || [[Classic bug: NPC speed exceeds class limits]] || NPC/navigation
|-
| GE-BUG-019 || [[Classic bug: Planet-owner PRICE display]] || Economy/display
|-
| GE-BUG-020 || [[Classic bug: Stale scantab and lock state]] || Sensors/multiplayer
|-
| GE-BUG-021 || [[Classic bug: Torpedo stalls at distance one]] || Combat
|-
| GE-BUG-022 || [[Classic bug: Ship-selection output overflow]] || Memory/UI
|-
| GE-BUG-023 || [[Classic bug: Phaser spread bias]] || Combat/numeric
|-
| GE-BUG-024 || [[Classic bug: Men do not consume food]] || Planets/economy
|-
| GE-BUG-025 || [[Classic bug: Phaser durability uses cargo capacity]] || Combat/balance
|-
| GE-BUG-026 || [[Classic bug: Damaged warp overrides requested speed]] || Navigation
|-
| GE-BUG-027 || [[Classic bug: Fixed-width display column overflow]] || User interface/configuration
|-
| GE-BUG-028 || [[Classic bug: Invalid WARP heading reports helm damage]] || Navigation/user interface
|-
| GE-BUG-029 || [[Classic bug: Planet spy attack result inversion]] || Planet combat/spies
|-
| GE-BUG-030 || [[Classic bug: Empty-planet troop conquest]] || Planet combat
|-
| GE-BUG-031 || [[Classic bug: Extended BUY token executes PRICE]] || Commands/economy
|-
| GE-BUG-032 || [[Classic bug: Planet name limit off by one]] || Planets/user interface
|-
| GE-BUG-033 || [[Classic bug: Revolt troop losses are reversed]] || Planets/user interface
|-
| GE-BUG-034 || [[Classic bug: Disabled production repeats maximum-stock notices]] || Planets/user interface
|-
| GE-BUG-035 || [[Classic bug: Attacking troop surrender overwrite]] || Planet combat
|-
| GE-BUG-036 || [[Classic bug: SYS GOTO desynchronizes warp state]] || Navigation/administration
|-
| GE-BUG-037 || [[Classic bug: Planet troop anti-fighter probability]] || Planet combat/numeric
|-
| GE-BUG-038 || [[Classic bug: Planet trade-password terminator overrun]] || Planets/memory
|-
| GE-BUG-039 || [[Classic bug: Unterminated team-creation fields]] || Teams/memory
|-
| GE-BUG-040 || [[Classic bug: Planetary troop fire requires defending fighters]] || Planet combat
|-
| GE-BUG-041 || [[Classic bug: HELP index omits gameplay commands]] || Documentation/user interface
|-
| GE-BUG-042 || [[Classic bug: Messages leak ANSI color and intensity]] || Documentation/user interface
|-
| GE-BUG-043 || [[Classic bug: Optional menu text file is never closed]] || Resource management/user interface
|-
| GE-BUG-044 || [[Classic bug: Maintenance omits cloak repair]] || Ships/maintenance
|-
| GE-BUG-045 || [[Classic bug: MAXPLSE is off by one]] || Configuration/sector generation
|-
| GE-BUG-046 || [[Classic bug: Reports list nonexistent phasers and shields]] || Ships/user interface/configuration
|-
| GE-BUG-047 || [[Classic bug: REP SYS omits damaged systems]] || Ships/combat/user interface
|-
| GE-BUG-048 || [[Classic bug: SHIELD DOWN bypasses shield repair]] || Ships/combat
|-
| GE-BUG-049 || [[Classic bug: Replacement systems retain old charge]] || Ships/economy
|-
| GE-BUG-050 || [[Classic bug: Planet conquest bypasses ownership limit]] || Planets/configuration
|-
| GE-BUG-051 || [[Classic bug: Negative missile charge]] || Combat/numeric
|-
| GE-BUG-052 || [[Classic bug: NPC zipper uses another ship's scanner range]] || NPC/combat
|-
| GE-BUG-053 || [[Classic bug: Self-destruct abort omits count-10 all-clear]] || Combat/notifications
|-
| GE-BUG-054 || [[Classic bug: Rejected mail leaks into output]] || Planets/mail/user interface
|-
| GE-BUG-055 || [[Classic bug: Filtered broadcast suppresses later recipients]] || Multiplayer/messages
|-
| GE-BUG-056 || [[Classic bug: Team maintenance password bypass]] || Teams/planets
|-
| GE-BUG-057 || [[Classic bug: Droid phasers fire straight ahead]] || NPC/combat
|-
| GE-BUG-058 || [[Classic bug: CYBGOLD zero crashes Cybertron creation]] || NPC/configuration
|-
| GE-BUG-059 || [[Classic bug: TEAM KICK mail classification]] || Teams/mail
|}

== Porting and modernization cautions ==
These are intentional features, design limitations, or integration assumptions in classic GE rather than additional numbered bugs. A port should decide explicitly whether to preserve or change them.

=== Exposed team diagnostics ===
The undocumented <code>TEAM DUMPITOUT</code> command prints the team table, including joining passwords and founder secrets, to any player who invokes it. This is a serious information-disclosure risk even though the command does what its diagnostic implementation asks it to do. A modern port should remove it from ordinary player access or restrict it to administrators, as ge-next did with <code>SYS TEAMDUMP</code>. See [[Team command#Undocumented classic command|Team command]] and [[Sys command]].

=== Frontend data access ===
Classic <code>DATA</code> is a documented frontend interface, not merely an accidental debug command. Its published, hardcoded access word does not authenticate a client, and its responses include raw combat state and precise scan information that ordinary commands may conceal. Retaining frontend support need not mean retaining those disclosures: define which information a frontend is allowed to receive and enforce the same gameplay checks as other commands. See [[Data command]] and [[GECP]].

=== NPC behavior tied to class names ===
Classic selects several Droid behavior routines by matching configured ship-class names. Renaming one of those classes in the ship configuration can silently remove its special behavior even when its other settings are unchanged. This is a configuration constraint rather than a broken default installation; a port can use a separate behavior identifier instead. See [[Droids#Classic Galactic Empire|Droids]] and [[Ship class configuration]].

=== Flux-pod loading conventions ===
Classic checks for automatic pod loading periodically and only below a fixed active-flux threshold, not whenever an action needs more energy. A ship can therefore fail to fire, cloak, or maintain warp despite carrying spare pods. Some of these outcomes are consequences of the original loading design, distinct from the arithmetic fault catalogued as [[Classic bug: Flux subtraction underflow]]. See [[Flux#Why spare pods can fail in classic|Flux]] and [[Flux command]].

=== Registration and database assumptions ===
Classic stores registration and trial information in concealed records inside its Btrieve files. A port, roster tool, or database converter must distinguish those records from player and planet records; it should also decide how to handle the original board-bound registration mechanism rather than assuming every record is gameplay data. See [[Classic registration and security system]] and [[Database files]].

=== Shared host output state ===
MajorBBS's PRF output buffer is shared working state, not a separate buffer for each connected player. A port or emulator that changes when messages are formatted, cleared, or sent can alter who sees a message even when GE's calls appear unchanged. See [[MajorBBS integration#Output and message resources|MajorBBS integration]] and [[Classic bug: Filtered broadcast suppresses later recipients]] for a separate GE-side defect involving multi-recipient delivery.

== See also ==
* [[Classic bug record format]]
* [[Source code]]
* [[Classic Galactic Empire]]

{{GE navigation}}
[[Category:Classic bugs]]
[[Category:Development]]

Classic bug: TEAM KICK mail classification

2026-10-18T21:46:27Z

CodexBot: Document inherited TEAM KICK mail-class bug and ge-next 0.3.3 fix

{{Classic bug
|id=GE-BUG-059
|affected=Classic 3.2e and ge-next through 0.3.2
|status=Verified in source; corrected in ge-next 0.3.3
|fixed=ge-next 0.3.3 (16-bit and 32-bit)
|source=GECMDS.C: cmd_team(); GEFUNCS.C: sendit(), mailscan(), mailread()
}}

== Summary ==
When <code>TEAM KICK</code> removes a member, it composes a ''Team Membership Revoked'' mail notice but does not set the notice's mail class. In classic GE and ge-next through 0.3.2, the notice inherits whatever class was last stored in the shared <code>mail</code> workspace. It may be filed under Distress messages, misfiled under Production reports, or left in a class that the in-game menu cannot open.

== Symptoms and reproduction ==
# Use the in-game GE mailbox, with an existing team and another player who can be removed from it.
# Before any event has assigned a class to the shared <code>mail</code> workspace, use <code>TEAM KICK</code> to remove that player.
# The removed player's main menu can indicate that a message is waiting, while the mail menu shows neither Distress messages nor Production reports as available.

The initial global <code>mail</code> workspace has class zero. If an earlier event set it to class 1, the notice appears under Distress messages. If a production report or stock-cap notice left it at class 3, the team notice appears under Production reports. The behavior therefore depends on previous activity during that module run, not on the team action itself. It does not mean the kick or the team's saved membership failed.

Classic 3.2e also has a <code>USEGEMSG</code> option. When mail is routed to the host BBS mailbox instead of GE's own mailbox, this particular two-category menu problem does not apply. The distributed classic configuration enables GE mail. ge-next uses only GE mail, so both its 16-bit and 32-bit standard-game builds inherited the problem. ge-arena disables persistent <code>TEAM</code> and is unaffected.

== Cause ==
<code>cmd_team()</code> sets <code>mail.userid</code> and <code>mail.topic</code>, then calls <code>sendit()</code> without assigning <code>mail.class</code> (classic) or <code>mail.mailclass</code> (ge-next). <code>sendit()</code> copies that field to the stored message's flags. The GE mail menu searches only class 1 for Distress messages and class 3 for Production reports. Its initial any-mail check searches by recipient alone, so a class-zero notice can make the main menu show mail waiting without providing a readable category.

== Correction in ge-next 0.3.3 ==
The 16-bit and 32-bit ge-next <code>TEAM KICK</code> paths now set <code>mail.mailclass = MAIL_CLASS_DISTRESS</code> immediately before <code>sendit()</code>. A newly generated revocation notice is thus placed in the Distress messages category regardless of what previously used the workspace. This is a classification fix; it does not change team membership or rewrite mail records already stored with an incorrect class.

== See also ==
* [[Mail]]
* [[Team command]]
* [[Teams]]
* [[Classic bug: Team state inconsistency]]

[[Category:Classic bugs: Multiplayer state]]
[[Category:Classic bugs: User interface]]

{{GE navigation}}

Game reference

2026-10-18T21:39:18Z

CodexBot: Link Mail from game reference

The game reference documents observable rules and mechanics. Articles should state which version they describe whenever behavior differs.

== Systems ==
* [[Navigation and scanning]]
* [[Combat]]
* [[Hull damage]]
* [[System damage]]
* [[Maintenance]]
* [[Economy and cargo]]
* [[Planets]]
* [[Mail]]
* [[Scoring and rosters]]
* [[Teams]]

== Objects and actors ==
* [[Ships]]
* [[Ship upgrades]] (ge-next only)
* [[Items]]
* [[Cybertrons]]
* [[Droids]] (other NPCs)
* [[Wormholes]]

== Reference ==
* [[Commands]]
* [[Glossary]]
* [[Game timing]]
* [[Coordinate system]]

{{GE navigation}}
[[Category:Game reference]]

Maintenance command

2026-10-18T21:04:09Z

CodexBot: Explain team maintenance bypass before 0.3.3 fix

The '''MAINTENANCE''' command hires a planetary maintenance crew to repair the current ship while it remains in orbit. The command may be abbreviated to <code>MAI</code>.

== Syntax ==

<syntaxhighlight lang="text">
MAINTENANCE [password]
</syntaxhighlight>

An ordinary planet trade password must be supplied directly after the command; the game does not open a separate password prompt. The special password <code>team</code> is intended to limit access to members of the planet owner's team. Classic GE and ge-next through 0.3.2 instead treat it as a literal word in <code>MAINTENANCE</code>: a nonmember can enter <code>MAINT team</code> and receive service despite the team restriction. See [[Classic bug: Team maintenance password bypass]]. Since ge-next 0.3.3, the command checks membership instead; a team member can request maintenance without supplying a password, and a nonmember cannot bypass the restriction by entering <code>team</code>.

== Where maintenance is available ==

The ship must be in stationary orbit. In sector 0 0, Zygor and Tahanian Station provide maintenance for 2,500 cash. The Enforcer Planet does not provide repair service.

Outside the [[Neutral zone|neutral zone]], a claimed planet establishes a repair facility when it has at least 25,000 men. Service there costs 200 cash. The facility does not have to belong to the player requesting repairs. Ordinary trade passwords must be supplied if set; access to a team-restricted planet differs by game version as explained below.

The complete fee is charged when maintenance begins. There is no partial refund if the work is interrupted.

== Restrictions ==

Maintenance will not begin while the ship is considered engaged in hostilities. Weapon fire and damaging another ship set a combat timer used by several game systems; maintenance crews refuse service until that timer has expired.

If a ship becomes hostile or is attacked after maintenance begins, the crew stops work. Leaving orbit also cancels maintenance. The ship keeps whatever repair progress has already occurred, but must pay again to restart the job.

Classic lowers and completely discharges shields when maintenance finishes, regardless of whether the shields were damaged, down, or operating normally. It does not repair cloak damage at all. ge-next leaves undamaged shields alone and includes cloak damage in maintenance, but a cloaked ship cannot begin maintenance unless the ship's owner also owns the planet.

Issuing <code>MAINTENANCE</code> again while work is already underway does not restart the job or charge another fee in ge-next. Classic does not have this guard: repeating the command charges the fee again and replaces its repair counter.

== Classic Galactic Empire ==

Classic bases maintenance duration only on structural damage:

<syntaxhighlight lang="c">
warsptr->repair = (unsigned)(warsptr->damage / 3.0) + 1;
</syntaxhighlight>

The resulting number is displayed as "[[Centock|centocks]]." Maintenance is actually processed by the ship-state update, which normally runs every six seconds. The displayed count is therefore neither a real-world number of seconds nor a complete count of all work required.

Each maintenance update removes three points of structural damage. Individual system damage does not lengthen the estimate. When the hull-derived counter reaches its completion threshold, classic immediately resets the hull and a fixed list of systems, then announces that all maintenance is complete.

This has several consequences:

* Damaged systems are not repaired progressively; most remain unavailable until the final update.
* System damage alone does not produce a longer maintenance time.
* The cloaking device is omitted from the final reset and can remain damaged after the completion announcement. See [[Classic bug: Maintenance omits cloak repair]].
* Shields are lowered and completely discharged regardless of whether they were damaged or operating normally.
* An undamaged ship can still pay for maintenance. On the next update, the completion block runs and can unnecessarily change its shield state.

The classic help describes service at the player's own planet or Zygor, but the actual command is less restrictive: any claimed planet with at least 25,000 men can provide service if its password requirements are met. Classic checks even the special planet password <code>team</code> as literal text, so <code>MAINT team</code> passes that check for a nonmember. See [[Classic bug: Team maintenance password bypass]].

== ge-next ==

ge-next 0.3.3 corrects the [[Classic bug: Team maintenance password bypass|team-password bypass]] described above, matching the [[Buy command|BUY]] membership rule. It validates old team references on the planet before applying that rule. Ordinary passwords are unchanged.

ge-next first checks whether the ship has anything that requires repair. An undamaged ship is told that maintenance is unnecessary and is not charged.

During paid maintenance, every six-second ship-state update performs work in three areas concurrently:

* structural damage is reduced by 3 points;
* damaged shields receive five normal shield-repair steps; and
* five system-repair steps are applied in priority order.

The system order begins with helm and tactical systems, followed by phasers, torpedo and missile fire control, cloak, jammer, decoy, zipper and mine launchers, and finally warp or overspeed damage. A badly damaged system may consume several steps before work advances to the next system. Messages are shown as individual systems return to service.

The completion estimate is calculated from the outstanding hull, shield, and system work. These categories progress together, so ge-next uses whichever category will take the most update ticks and converts that result to real seconds:

<syntaxhighlight lang="text">
ETA = max(hull ticks, shield ticks, system ticks) * 6 seconds
</syntaxhighlight>

The initial maintenance message and [[Report command|<code>REPORT SYSTEMS</code>]] therefore show a real-time estimate rather than classic's centock counter. The estimate may change if the ship suffers more damage or maintenance is interrupted.

ge-next does not announce completion until structural damage, damaged shields, cloak damage, and all other applicable system damage have been cleared. Undamaged shields are left alone, preserving both their operating state and charge. An operational cloak is likewise left in its existing state, although a cloaked ship can only begin maintenance at a planet owned by the same player.

Ships also perform slow passive repairs without hiring a maintenance crew. Paid maintenance replaces those normal rates with the faster rates above. The enhanced damage-control upgrade improves passive repair and exposes additional repair-time information, but paid maintenance already uses its own faster rates.

== ge-arena ==

ge-arena planets may generate either a '''maintenance depot''' or an '''instant maintenance''' pickup.

At a maintenance depot, <code>MAINTENANCE</code> starts the same progressive repair process used by ge-next. Arena maintenance costs no cash and does not use planet population or trade passwords. It still cannot begin during the arena combat-lock period, and leaving orbit or renewed hostility interrupts the work.

The standard ge-next hostility lock uses <code>FIRETICKS</code> 10, normally about 60 seconds across six-second ship-state updates. ge-arena reduces this to 4 ticks, normally about 24 seconds. This keeps a player from repairing during active combat without imposing a one-minute wait in a 15-minute arena match. Some less severe hostile actions use fractions of these values, so the exact remaining wait can be shorter.

Instant maintenance is collected with [[Transfer command|<code>TRANSFER UP</code>]], not <code>MAINTENANCE</code>. It repairs all hull and system damage immediately. If the ship does not need repair, the pickup remains on the planet rather than being consumed.

== Comparison ==

{| class="wikitable"
! Behavior
! Classic Galactic Empire
! ge-next
|-
| Standard fees
| 2,500 credits at Zygor or Tahanian Station; 200 elsewhere
| Same
|-
| Planet population required outside sector 0 0
| 25,000 men
| Same
|-
| Duration display
| Hull-derived centocks
| Calculated real-world seconds
|-
| Systems repaired progressively
| No
| Yes
|-
| All applicable damaged systems included
| No
| Yes
|-
| Undamaged ship refused without charge
| No
| Yes
|-
| Repeating the command during maintenance refused without charge
| No
| Yes
|-
| <code>team</code> restricts maintenance by membership
| No; literal <code>MAINT team</code> passes the password check
| Yes, since 0.3.3
|-
| Visiting cloaked ship refused
| No
| Yes, unless the ship owner owns the planet
|}

== See also ==

* [[MBMGEHLP.MSG#HELP_MAINT|Classic HELP MAINT]]
* [[Maintenance]]
* [[Report command]]
* [[Orbit command]]
* [[Classic bug: Maintenance omits cloak repair]]
* [[Classic bug: Team maintenance password bypass]]

{{GE navigation}}
[[Category:Commands]]
[[Category:Ships]]

Flux

2026-10-18T18:51:49Z

CodexBot: Clarify classic rotation flux charge and ge-next rationale

'''Neutron flux''' is the energy in a ship's active pile. Propulsion and several ship systems spend this charge; a carried [[Flux pod]] is a separate inventory item that can replace it. The active pile holds up to 65,000 energy units. [[Report command|<code>REPORT SYSTEMS</code>]] shows its current charge, while <code>REPORT INVENTORY</code> shows how many pods remain.

== Energy use ==
These are stock costs; a configured cloak cost or missile charge can differ. A movement update and a ship-state update are different parts of the game loop, so costs in different rows need not be charged at the same instant.

{| class="wikitable"
! System or action !! Classic GE 3.2e !! ge-next
|-
| [[Rotate command|ROTATE command]] || 30 when its energy check succeeds; <code>useenergy()</code> also requires 500 energy to remain afterward. || No separate rotation charge.
|-
| Impulse movement || No ordinary movement-energy charge at impulse speed. || 1 per powered movement update.
|-
| Warp acceleration || 120 for a charged acceleration step. || 120 for a warp-range acceleration step; entering hyperspace also reserves enough flux for the accompanying movement check.
|-
| Warp movement || 10 per movement update only above warp 1.00; at exactly 1.00 the classic code skips this charge. The requested speed is cut when the active pile falls below 3,000 during a charged movement update. || 10 plus the whole-number warp speed per powered movement update: 11 at warp 1, 20 at warp 10.
|-
| Standard phaser firing || Spends stored phaser charge, not flux directly. || Same; the later recharge spends flux.
|-
| Phaser recharge || 57 per ship-state update while a working phaser is below full charge; the classic <code>useenergy()</code> check requires 500 more than the cost. || 57 per recharge update, checked against available active charge or a pod.
|-
| Hyper-phaser firing || Spends 5,000 but requires at least 6,000 active energy before firing. || Spends 5,000; the shared loader checks that amount first.
|-
| Missile launch || Uses charged missile energy divided by <code>MISENGFC</code>, stock 100: a 50,000-energy missile costs 500 flux. || Uses the entire selected 2,000–20,000-energy charge as flux.
|-
| Raised shields || Normally 100 times the installed shield Mark per ship-state update: Mark-5 costs 500. || The same Mark-based upkeep, but checked against available active charge or a pod before charging.
|-
| Cloak upkeep || <code>CLENGUSE</code> per ship-state update, stock 7,500. || <code>CLENGUSE</code> per ship-state update, stock 5,000; the shared loader checks for a pod first.
|}

Classic charges for issuing <code>ROTATE</code>, not for the physical turn performed later. <code>IMPULSE</code> and <code>WARP</code> can set a new heading without paying that 30-unit charge, and the subsequent turn also costs no flux. Conversely, <code>ROTATE</code> can charge even when the requested heading is unchanged; in its absolute-heading path, it charges before rejecting an out-of-range value such as <code>ROTATE @360</code>. This command-dependent inconsistency was one reason ge-next removed the separate rotation charge.

Background recharge adds one unit per ship-state update in classic and two in ge-next. This is far slower than the main costs of combat or warp travel. The costs above describe normal player use. In both classic GE and ge-next, an active Cybertron or Droid has its flux set back to 50,000 at the end of each AI behavior callback, rather than depending on carried pods to remain powered. These ships still carry flux pods as inventory and potential salvage; the shared energy check can occasionally consume one between AI callbacks, but the recurring reset keeps an NPC from staying powerless merely because it has run out of pods.

== Why spare pods can fail in classic ==
Classic checks for automatic pod loading once near the start of each ship-state pass, and only if active flux is ''below'' 5,000. Other energy-using routines do not call that loader when an action needs more charge. The timing and thresholds can therefore disagree:

* At 5,500 flux, a ship with spare pods cannot fire its hyper-phaser: firing requires 6,000, but the periodic loader will not load a pod until the pile falls below 5,000.
* At 6,000 flux, a successful hyper-phaser shot spends 5,000 and leaves 1,000. If the next movement update runs before the pod-loading status pass, the ship can lose its requested warp speed because its charge is below the 3,000 movement threshold, despite having pods aboard.
* With 8,000 flux and raised Mark-6 shields, the classic status pass skips pod loading, then shield upkeep takes 600. Cloak upkeep later in that pass requires the stock 7,500 and shuts off the cloak at 7,400, although a spare pod is present.
* An immediate rotation or a phaser recharge attempt can also fail or stall at low charge between periodic checks. The pod will not be considered until a later status pass.

Classic can also subtract flux unsafely in some paths when no pod is available; see [[Classic bug: Flux subtraction underflow]]. These are separate arithmetic faults from the missed-reload cases above.

== ge-next loading ==
Since ge-next 0.2, <code>fluxstat()</code> receives the amount an operation needs. If the active pile cannot cover it, the routine consumes one available pod and replaces the pile with 65,000 units ''before'' the operation proceeds. Movement, phaser recharge, hyper-phaser and missile firing, and shield/cloak upkeep use this shared check. The remaining energy in the old pile is not added to the replacement charge. If there is no pod, the system follows its insufficient-power path instead. This eliminates the classic timing gaps above and makes the manual [[Flux command|FLUX command]] unnecessary for normal operation.

== See also ==
* [[Flux pod]]
* [[Flux command]]
* [[Warp travel]]
* [[Hyper-phasers]]
* [[Missiles]]
* [[Shields]]
* [[Cloaking]]

{{GE navigation}}
[[Category:Game reference]]
[[Category:Ships]]

Lydorian Garbage Scow

2026-10-18T18:37:58Z

CodexBot: Distinguish defined and reachable classic Scow hails

The '''Lydorian Garbage Scow''' is the smallest, least aggressive [[Droids|Droid]] in both classic ''Galactic Empire'' and ge-next. Its low point value and central starting area make it an early encounter rather than a serious combatant.

== Classic GE ==
The stock class is '''NCC Lx4''', with Mark-1 shields and phasers, a 25,000-distance-unit scanner, and a five-point kill value. Its class table lists warp 1 and several secondary-system permissions, but its dedicated behavior does not use those weapons or enter ordinary warp travel. It can carry some supplies, but carrying them does not mean its AI uses them.

The Scow notices and occasionally hails a player within its scanner range. It raises shields while moving at impulse speed. If jammed, it requests a near-warp impulse speed and holds course for a while. Even when attacked, the classic routine has no retaliatory shot, target pursuit, or damage-triggered retreat. Its installed phaser is therefore not a practical threat. See [[Classic NPC ship classes]] for the complete shipped class settings.

== ge-next ==
The stock class becomes '''NCC Lx5''', with no phaser capability, warp 0, Mark-1 maximum shields, and a 20,000-distance-unit scanner. Newly created Scows appear relatively close to the center of the galaxy. They hail visible player ships only when each ship is within the other's scanner range.

The Scow still does not fire. Unlike the classic version, it can respond to an assigned attacker by turning directly away and requesting its maximum impulse speed; it resumes ordinary cruising when the threat is gone. Jamming disrupts that response. At impulse speed it keeps shields raised when they are functional, and an attacked Scow can send a [[Droids#Factions and distress in ge-next|distress call]]. Its avoidance makes it less of a stationary target without turning it into a combat ship. See [[ge-next NPC ship classes]] for its configured limits.

== Hails ==
Classic GE's message file defines five Scow beacons about hazardous cargo, treaty protection, and approach clearance. However, the published 3.2e Scow routine calls <code>droid_annoy()</code> with <code>DRDMSG6</code> as both the first and last message, so only the hazardous-material warning is selected by that code. ge-next uses several rotating beacons and adds wary hails for players disliked by the Lydorians. After an attack, the Scow asks the player to stop or spare a vessel carrying nothing valuable. These are warnings and pleas, not threats backed by Scow weapons. A ge-next distress call is separate from these hails.

== See also ==
* [[Droids]] and [[Droids#Factions and distress in ge-next|faction rules]]
* [[Murdonian Transport]] and [[Vakory Survey Drone]]

{{GE navigation}}
[[Category:NPCs]]
[[Category:Ships]]

Galactic Command Freighter

2026-10-18T18:35:39Z

CodexBot: Summarize class-specific Droid hails

The '''Galactic Command Freighter''' is a ge-next [[Droids|Droid]] belonging to the Zygorian/Galactic Command [[Droids#Factions and distress in ge-next|faction]]. Its distinctive behavior is a supply voyage to [[Zygor]], with defensive combat if that voyage is threatened. There is no corresponding classic Droid class.

== ge-next behavior ==
The stock '''Zygor-''' class has maximum Mark-12 shields, Mark-10 phasers, warp 25, a 150,000-distance-unit scanner, a 500-point kill value, and exceptionally large cargo capacity. A new freighter can carry gold and assorted supplies, and is normally generated within roughly half the galaxy radius on each axis.

Freighters coordinate a recurring trip to sector <code>0 0</code>. Normally one enters the travel-and-resupply sequence at a time, although a freighter with more than 50 hull damage can join it for repair. It steers toward the center, progressively slows, and stops within orbit range of Zygor. While stopped, it repairs hull damage in increments, pauses briefly, replenishes its cargo, then departs and travels outward before another freighter takes the scheduled turn. This is scripted NPC behavior, not a player-operated trade or [[Maintenance command|maintenance]] transaction. The routine even prevents helm damage from derailing its route.

If attacked away from the neutral zone, the freighter steers roughly away and uses defensive phasers and torpedoes against a visible nearby target. It can also release decoys, activate a jammer, or use a zipper when the attacker is near mines and equipment is available. At 33 or more hull damage it tries a faster escape rather than a slower impulse withdrawal. It can send a distress call. Offensive fire is suppressed in the [[neutral zone]], where its Zygor visit takes place. See [[ge-next NPC ship classes]] for the stock equipment and [[Droids#Factions and distress in ge-next|Droid distress]] for rescue consequences.

== Hails ==
Its routine messages are promotional beacons for Zygor's ships and supplies and for Tahanian Station. A player regarded as hostile by Galactic Command receives warnings to keep away instead. When attacked, the Freighter protests and may say the attacker is no longer welcome at Zygor. That line does not itself bar trade: Zygor's actual refusal depends on the player's faction dislike. The Freighter can also send a separate distress call.

== See also ==
* [[Droids]], [[Zygor]], [[Droids#Factions and distress in ge-next|faction rules]], and [[Gold]]
* [[Murdonian Transport]]

{{GE navigation}}
[[Category:NPCs]]
[[Category:Ships]]

Sarten Defense Drone

2026-10-18T18:35:36Z

CodexBot: Summarize class-specific Droid hails

The '''Sarten Defense Drone''' is ge-next's active Sarten patrol ship and a [[Droids|Droid]] rather than a Cybertron. It is not the same class or AI as classic GE's Cybertron-type Sarten Attack Drone. Unlike a civilian transport, this ship can select a target before it is attacked.

== ge-next behavior ==
The stock '''SDDx2''' has maximum Mark-6 shields, Mark-10 phasers, warp 50, a 250,000-distance-unit scanner, and a 100-point kill value. Its acceleration is comparatively low. Newly generated patrols tend to appear farther from the center in sufficiently large galaxies.

An unassigned patrol can choose a nearby player whose Sarten [[Droids#Factions and distress in ge-next|dislike]] exceeds 50, provided that player's class meets the configured minimum and another Defense Drone has not already claimed them. Depending on the Cybertron-attack setting, it can instead select an idle Cybertron. It hails nearby players, but does not need to wait to be damaged before it starts pursuing an eligible target.

The Drone uses fast travel to close large distances, drops toward impulse as it approaches, and makes close combat passes rather than simply stopping on top of a target. It can use phasers and torpedoes at suitable range, lay a mine during a very close pass, then turn away and accelerate. If the target is near mines, it may use a zipper. These attacks depend on range, visibility, stock, reload state, and neutral-zone restrictions. If the target becomes invisible, the pursuit can eventually be abandoned; jamming can disrupt its normal target handling. Its routine does not use the civilian Droid distress-call path. See [[ge-next NPC ship classes]] for full class settings.

== Hails ==
The patrol's routine beacons identify its defensive mission, warn ships not to interfere, and invite help against Cybertrons. To a player with hostile Sarten standing, it sends accusations or warnings instead. If attacked, it responds with condemnations of the player's actions. Unlike civilian Droids, the Defense Drone does not use the distress-call path.

== See also ==
* [[Droids]], [[Droids#Factions and distress in ge-next|faction rules]], [[Mines]], and [[Zippers]]
* [[Sarten Civil Transport]]

{{GE navigation}}
[[Category:NPCs]]
[[Category:Ships]]

Sarten Civil Transport

2026-10-18T18:35:32Z

CodexBot: Summarize class-specific Droid hails

The '''Sarten Civil Transport''' is a ge-next [[Droids|Droid]] introduced with the expanded non-Cybertron population. It belongs to the [[Droids#Factions and distress in ge-next|Sarten faction]] and is a defensive civilian ship, not a dedicated pursuer. It is distinct from classic GE's Sarten Attack Drone and Sarten Obliterator, which were [[Cybertrons|Cybertron-type]] ships rather than Droids.

== ge-next behavior ==
The stock '''SCTx7''' has maximum Mark-8 shields, Mark-6 phasers, warp 10, a 50,000-distance-unit scanner, and a 200-point kill value. New transports start comparatively close to the galactic center and may carry a modest amount of gold. They hail visible player ships when the ships are within mutual scanner range.

If attacked, the transport faces roughly away from the attacker and alternates between impulse evasions and faster cruising; when its target is obscured in a nebula, it can favor impulse maneuvering. It can fire phasers at a visible target within roughly 30,000 distance units. At impulse it may release decoys, and it may jam a nearby attacker when the jammer is stocked and ready. It has no torpedo or missile launchers. Like other non-combat transports, it may issue a distress call, so a player can become involved in a Sarten encounter without having initiated the attack. It does not actively search for disliked players to pursue. See [[ge-next NPC ship classes]] for its configured equipment and [[Droids#Factions and distress in ge-next|Droid distress]] for the broader rescue rules.

== Hails ==
Its approach messages describe civilian passengers, flight from Cybertrons, and a wish for peace with other species. A player disliked by the Sartens instead hears warnings about previous attacks on Sarten vessels. When fired upon, the Transport protests and may say it will summon defense drones; that line is dialogue, not a command that immediately creates a patrol. A separate distress message can ask nearby players for help.

== See also ==
* [[Droids]], [[Droids#Factions and distress in ge-next|faction rules]], [[Decoys]], and [[Jamming]]
* [[Sarten Defense Drone]]

{{GE navigation}}
[[Category:NPCs]]
[[Category:Ships]]

Vakory Survey Drone

2026-10-18T18:35:29Z

CodexBot: Summarize class-specific Droid hails

The '''Vakory Survey Drone''' is the most combat-capable of the three classic ''Galactic Empire'' [[Droids|Droids]]. It surveys and hails rather than proactively hunting players, but an attack can provoke weapons fire and evasive action.

== Classic GE ==
The stock '''Vakory SD-82''' has Mark-1 shields and phasers, warp 4, a 25,000-distance-unit scanner, and a 50-point kill value. It notices nearby player ships and may hail them. Once attacked, it can use standard phasers at impulse or hyper-phasers while both ships are at warp. Its impulse phaser sweep points straight ahead, not necessarily at the attacker; see [[Classic bug: Droid phasers fire straight ahead]].

The classic routine also attempts torpedo fire: it temporarily stocks torpedoes and calls the launcher directly, despite the class table saying ''no'' to torpedo capability. The direct launcher path does not check that class flag. The attempt remains subject to other requirements, including obtaining a lock and a free incoming-torpedo slot. The Drone can vary its speed and heading, accelerate to shake an attached missile, and, above 75 hull damage, try to lay a mine, activate a jammer, and run at its maximum requested speed on a random heading. Thus its retreat is both evasive and hazardous to a pursuer. Its attack/retreat branch also requires a positive <code>lastfired</code> channel, so a channel-zero attacker can fail to trigger it; see [[Classic bug: Channel-zero NPC targeting]]. See [[Classic NPC ship classes]].

== ge-next ==
The stock '''Vakory SD-86''' retains maximum Mark-1 shields and phasers and warp 4, but now has two torpedo launchers and explicit mine and jammer capability. Unlike the centrally concentrated classic Drone, a newly created one can appear throughout the galaxy.

When attacked, it turns roughly away from its attacker. Below 67 hull damage it varies its impulse speed; at or above that threshold it tries to escape faster and may leave a mine. Against a visible nearby target it can fire an aimed phaser or torpedo, and may jam when its equipment is ready. Its torpedo use now follows the configured launcher count, stock, visibility, speed, and neutral-zone rules instead of relying on the classic direct-call quirk. It can send a distress call. Heavy jamming interferes with its normal response. See [[ge-next NPC ship classes]].

== Hails ==
In classic GE, the Drone occasionally announces treaty protection or its automatic defenses, and an attacked Drone may call for help or report the attack to Vakory High Command. ge-next separates routine approach beacons from warnings to players the Vakories regard as hostile and responses to a fresh attack. Its messages present the ship as an unmanned research vessel and warn that its defenses are active. The ge-next distress broadcast is a separate gameplay message, not merely one of these hails.

== See also ==
* [[Droids]], [[Torpedoes]], [[Mines]], and [[Jamming]]
* [[Murdonian Transport]]

{{GE navigation}}
[[Category:NPCs]]
[[Category:Ships]]

Murdonian Transport

2026-10-18T18:35:26Z

CodexBot: Summarize class-specific Droid hails

The '''Murdonian Transport''' is a cargo-carrying [[Droids|Droid]] in classic ''Galactic Empire'' and ge-next. It is not a roaming hunter: an encounter or attack causes it to slow, defend itself, or evade, rather than deliberately seek players to fight.

== Classic GE ==
The stock '''Trans-Gal #2''' has Mark-2 shields, Mark-5 phasers, warp 8, a 25,000-distance-unit scanner, and a 200-point kill value. It may start with a broad assortment of cargo, including goods that it cannot launch as weapons. Its behavior is distinct from the smaller Scow: when a player approaches, it requests an impulse speed, raises shields at impulse, and may hail the player.

After being attacked, it can answer with phasers at impulse or hyper-phasers when both ships are at warp. At impulse, its classic routine fires straight along its current heading rather than aiming at the attacker; see [[Classic bug: Droid phasers fire straight ahead]]. The shot can still hit a ship in that narrow forward arc. It may also change heading and speed unpredictably. If a missile is attached while it is at warp, it requests a drop to impulse. Jamming makes it request maximum warp and hold course. It does not launch the torpedoes or missiles that may be present in its cargo, and it has no explicit hull-damage threshold that triggers a dedicated retreat. See [[Classic NPC ship classes]].

== ge-next ==
The stock '''Trans-Gal #3''' can carry substantially more cargo, with maximum Mark-4 shields and Mark-10 phasers, warp 8, and a 50,000-distance-unit scanner. Its starting inventory may include goods, gold, and weapons as cargo, but the class has no projectile launchers. It commonly cruises until a player comes near, then slows to impulse and hails; when alone, it resumes its route.

When an attacker is assigned, the Transport steers roughly away from the attacker and can fire an aimed standard or hyper-phaser if the target is visible and close enough. At more than 50 hull damage it switches from a modest impulse escape to a faster cruise. It does not fire torpedoes or missiles. It can call for help, and its response is affected by jamming, visibility, and damage to its systems. Its defensive fire is more deliberately aimed than in classic but is still secondary to escaping with its cargo. See [[ge-next NPC ship classes]] and [[Droids#Factions and distress in ge-next|faction rules]].

== Hails ==
Classic's Transport sends occasional warnings about its cargo, clearance, and Murdonian law. When attacked, it may object to the aggression or transmit a plea for assistance; these classic pleas are message text, not ge-next's rescue mechanism. ge-next adds distinct approach beacons, hostile-standing warnings, and attack reactions. They emphasize Murdonian Imperial authority, the civilian passengers, and the Transport's right to defend itself. A ge-next distress broadcast is separate from its ordinary hails.

== See also ==
* [[Droids]] and [[Gold]]
* [[Lydorian Garbage Scow]] and [[Vakory Survey Drone]]

{{GE navigation}}
[[Category:NPCs]]
[[Category:Ships]]

Classic bug: Filtered broadcast suppresses later recipients

2026-10-18T18:24:06Z

CodexBot: Link bug discovery transcript

{{Classic bug
|id=GE-BUG-055
|affected=Classic Galactic Empire 3.2e and published classic source; standard ge-next builds through 0.3.1
|status=Verified in source; reproduced in multiplayer testing before correction
|fixed=ge-next 0.3.2
|source=<code>outprfge()</code>, <code>outwar()</code>, <code>outsect()</code>, and <code>outrange()</code> in <code>GEMAIN.C</code>; <code>cmd_send()</code> in <code>GECMDS.C</code>
}}

== Summary ==
Classic GE can suppress a <code>FILTER</code>-class broadcast for players who have not enabled filtering. When one eligible recipient has <code>SET FILTER ON</code>, rejecting that message clears the shared print buffer. The broadcast continues to higher-numbered user slots, but the text has already been erased. Earlier eligible recipients can receive the message; later ones cannot. This is not an intended effect of the later players' own settings.

== Reproduction ==
# Have three players in GE on user slots 0, 1, and 2. Player 0 is the sender. Player 1 enters <code>SET FILTER ON</code>; player 2 leaves <code>SET FILTER OFF</code>.
# Player 0 tunes one classic A/B/C preset to <code>HAIL</code> and sends a public message with, for example, <code>SEND A test</code>.
# Player 1 correctly does not receive the filtered hail. Player 2 also does not receive it, despite filtering being off.
# If player 1 turns filtering off and the sender repeats the hail, player 2 receives it. A recipient visited ''before'' the filtered player is unaffected.

The same failure pattern can occur for other <code>FILTER</code>-class messages distributed through a sector or scanner-range broadcast. It does not apply to every message: calls marked <code>ALWAYS</code> are not rejected by this setting, and a recipient must otherwise qualify for that particular broadcast.

== Cause ==
Classic broadcast helpers iterate potential recipients in ascending user-slot order, calling <code>outprfge()</code> with the same formatted print buffer. For a <code>FILTER</code> message whose recipient has filtering enabled, <code>outprfge()</code> calls <code>clrprf()</code> rather than sending the text:

<syntaxhighlight lang="c">
if (class == FILTER && warusroff(shpno)->options[MSG_FILTER] == TRUE) {
clrprf();
return;
}
</syntaxhighlight>

That clears the message for the ''whole ongoing broadcast'', not just this recipient. The loop in <code>outwar()</code>, <code>outsect()</code>, or <code>outrange()</code> still visits later eligible slots, but their output calls no longer have the original message to send. A public hail from classic <code>SEND A</code>, <code>SEND B</code>, or <code>SEND C</code> when that preset is set to <code>HAIL</code> uses <code>outwar(FILTER, ...)</code>, making the problem visible in ordinary play.

== Correction in ge-next ==
ge-next 0.3.2 separates individual recipient delivery from buffer cleanup. Its internal <code>sendprfge()</code> decides whether to send to one recipient without clearing a rejected message. The broadcast helpers use that routine for each eligible recipient and call <code>clrprf()</code> only after the broadcast loop finishes. The public <code>outprfge()</code> wrapper still clears after an individual rejected delivery, where no subsequent broadcast recipients depend on the buffer. A recipient's display settings therefore affect only that recipient.

ge-next uses more specific message categories in place of classic's single <code>FILTER</code> switch; that interface change is separate from the shared-buffer correction.

== Discovery transcript ==
[[Discovery transcript: GE-BUG-055|Read the multiplayer observation that revealed the broadcast-filter failure]].

== See also ==
* [[Set command]]
* [[Send command]]
* [[MajorBBS integration]]

[[Category:Classic bugs: Multiplayer state]]
[[Category:Classic bugs: User interface]]

{{GE navigation}}

Classic bug: Phaser spread bias

2026-10-18T18:24:00Z

CodexBot: Link bug discovery transcript

{{Classic bug
|id=GE-BUG-023
|affected=Classic 3.2e and published classic source
|status=Verified mathematically and in source
|fixed=ge-next 0.3
|source=GECMDS.C: firep() and firehp(); GEFUNCS.C: valpcnt() and pdamage(); GELIB.C: smallest()
}}

== Summary ==
Classic converts the phaser's intended firing direction and the direction to each potential target from floating-point angles to unsigned whole degrees by truncating them. Truncation always discards the fractional part instead of rounding to the nearest degree. Near the edge of the beam, this gives the positive-bearing side almost one additional degree of coverage compared with the negative-bearing side.

The phaser does not randomly wander to one side. The bias is deterministic: the same geometry produces the same hit or miss every time.

== Direction and spread ==
The first argument to [[Phaser command|<code>PHASER</code>]] is a relative bearing from -180 through +180:

* negative bearings are to port, or left;
* positive bearings are to starboard, or right; and
* zero is directly ahead.

The optional second argument is called both “spread” and “focus” in classic's interface. It accepts values from 0 through 5. If it is omitted, classic uses 1. Despite the name “focus,” increasing the value widens the beam while reducing its damage.

Classic first converts the requested relative direction into an absolute firing direction:

<syntaxhighlight lang="c">
deg = (unsigned)normal(ptr->heading + (double)ptr->degrees);
</syntaxhighlight>

It independently calculates the true direction from the firing ship to every candidate target and truncates that value as well:

<syntaxhighlight lang="c">
heading = (unsigned)vector(&ptr->coord,&wptr->coord);
</syntaxhighlight>

A target is inside the beam when the shortest angular distance between those two truncated integers is less than the selected spread plus <code>PHABIAS</code>:

<syntaxhighlight lang="c">
#define PHABIAS 2

if (smallest(heading,deg) < ptr->percent + PHABIAS)
/* target is in the beam */
</syntaxhighlight>

<code>smallest()</code> correctly treats angles near 0 and 360 as adjacent. The defect occurs before that comparison, when each floating-point angle is truncated toward the lower whole degree.

== Positive-versus-negative example ==
Consider a stationary ship heading 0 that fires:

<syntaxhighlight lang="text">
PHASER 0 1
</syntaxhighlight>

The firing direction is straight ahead. Spread 1 plus <code>PHABIAS</code> 2 produces this strict test:

<syntaxhighlight lang="c">
angular_difference < 3
</syntaxhighlight>

Now place otherwise identical targets at equal fractional bearings on either side of the centerline.

{| class="wikitable"
! True relative bearing
! Angle used by classic
! <code>smallest()</code> result
! Outcome
|-
| +2.9 degrees
| 2
| 2
| Hit, because 2 is less than 3
|-
| -2.9 degrees
| 357 after normalization and truncation
| 3
| Miss, because 3 is not less than 3
|}

The positive target is nearly three degrees to starboard but is pulled down into the accepted two-degree bucket. The corresponding negative target is represented near 360 degrees; truncating 357.1 to 357 pushes its complementary distance up to three degrees.

For an integral beam center and a threshold <var>W</var>, classic's effective coverage is approximately:

<syntaxhighlight lang="text">
-(W - 1) degrees through just under +W degrees
</syntaxhighlight>

With the default spread of 1, <var>W</var> is 3, so the beam covers roughly -2.0 through just under +3.0 degrees. The exact boundary changes when the ship's own heading has a fractional component, but truncation still quantizes the center and target toward lower absolute angles rather than treating the two sides evenly.

According to classic's own command documentation, positive relative bearings are starboard and negative bearings are port. The arithmetic therefore favors the positive/starboard edge in the straightforward heading-zero example.

== Effect of the spread setting ==
The same one-sided boundary appears at every spread setting. The nominal integer comparison is:

{| class="wikitable"
! Spread
! Test threshold
! Accepted integer differences
|-
| 0
| less than 2
| 0 or 1 degree
|-
| 1
| less than 3
| 0 through 2 degrees
|-
| 2
| less than 4
| 0 through 3 degrees
|-
| 3
| less than 5
| 0 through 4 degrees
|-
| 4
| less than 6
| 0 through 5 degrees
|-
| 5
| less than 7
| 0 through 6 degrees
|}

Spread also feeds into <code>pdamage()</code>. Before range, phaser charge, phaser class, and target durability are applied, classic calculates a focus factor and squares it:

<syntaxhighlight lang="c">
fd = 1 - ((double)foc / 11);
damage_factor = fd * fd;
</syntaxhighlight>

The resulting factors are approximately 1.000, 0.826, 0.669, 0.529, 0.405, and 0.298 for spread values 0 through 5. A wider setting therefore makes a target easier to include in the beam but substantially reduces the damage. The truncation bug alters which targets receive that tradeoff; it does not change the damage formula itself.

== Wraparound is not the cause ==
The example crosses the 0/360 boundary, but <code>smallest()</code> contains the intended complementary-angle logic:

<syntaxhighlight lang="c">
a = abs(a1 - a2);
if (a > 180)
return 360 - a;
return a;
</syntaxhighlight>

The differing outcomes come from converting +2.9 to 2 and -2.9 to 357 before that function runs. The same lower-angle quantization exists away from north; the wraparound example merely makes the positive-versus-negative result easy to see.

== Correction in ge-next ==
ge-next 0.3 rounds both angles to the nearest whole degree before comparing them:

<syntaxhighlight lang="c">
deg = (unsigned)(normal(ptr->heading + (double)ptr->degrees) + 0.5);
heading = (unsigned)(vector(&ptr->coord,&wptr->coord) + 0.5);
</syntaxhighlight>

Under the corrected calculation:

* +2.9 rounds to 3 and misses;
* -2.9 normalizes near 357.1, rounds to 357, and also misses;
* +2.4 rounds to 2 and hits; and
* -2.4 normalizes near 357.6, rounds to 358, and also hits.

The one-degree quantization remains, but its error is centered around each whole degree instead of always falling on the lower side. Standard phasers and hyper-phasers now use the same nearest-degree treatment.

This correction changes only edge-of-beam hit detection. ge-next's other phaser changes, including smoother floating-point damage, preservation of the half-step contribution from even phaser classes, and use of the ship damage factor, are separate corrections documented elsewhere.

== Discovery transcript ==
[[Discovery transcript: GE-BUG-023|Read the original shot observations and the initial interpretation]].

== Porting guidance ==
Keep angular values as floating point through the hit test when practical. Comparing the true shortest angular difference directly against a true beam half-width avoids one-degree buckets entirely. If integer angles are required for compatibility or performance, round both the beam center and target direction by the same rule; do not truncate them.

Tests should place targets at matching positive and negative fractional offsets around the beam center, including offsets near 0/360. Testing only integral bearings will not reveal this defect.

[[Category:Classic bugs: Combat]]
[[Category:Classic bugs: Numeric correctness]]

{{GE navigation}}

Classic bug: Cargo weight overflow

2026-10-18T18:23:57Z

CodexBot: Link bug discovery follow-up

{{Classic bug
|id=GE-BUG-001
|affected=Classic 3.2e and published classic source
|status=Verified in source
|fixed=Initially ge-next 0.1; comprehensively rewritten in ge-next 0.3.1
|source=GEFUNCS.C: chkweight() and calcweight()
}}

== Summary ==
Classic calculates an item's cargo contribution by multiplying its count by its configured weight before dividing by 100. The intermediate multiplication uses 32-bit arithmetic and can wrap even when the later division would produce a representable result.

Because the same calculation is used for inventory reports and capacity checks, this is not merely a display error. A wrapped result can allow a ship to load vastly more cargo than its class permits.

== Symptoms ==
A heavily loaded ship can appear to have little or no cargo weight, accept transfers far beyond its capacity, or reject a transfer whose wrapped arithmetic happens to produce a large result. Once an overflowing inventory exists, later reports and capacity decisions can change abruptly as item counts alter the wrapped remainder.

Corrupted records and sysop testing can reach the condition immediately, but stock classic planet populations are large enough for a player to exploit some item types during ordinary play.

== Exploit example ==
In the stock configuration, 100 men weigh 100 tons, so each man weighs one ton. Suppose an owned planet has at least 42,949,673 men and an empty ship requests:
<pre>
TRANSFER UP 42949673 MEN
</pre>
The true cargo contribution is 42,949,673 tons. Classic evaluates the numerator in 32-bit unsigned arithmetic:
<pre>
42,949,673 × 100 = 4,294,967,300
= 2^32 + 4
wrapped numerator = 4
wrapped cargo weight = 4 / 100 = 0 tons
</pre>
The separate item-count overflow guard still passes because 42,949,673 is well below its limit. The capacity check therefore treats the transfer as adding zero tons and accepts tens of millions of men even on a small ship. [[Report command|<code>REPORT INVENTORY</code>]] repeats the same multiplication and also omits their real weight.

Troops make the exploit directly useful in planetary combat. Stock troops weigh 200 tons per 100. A transfer of 21,474,837 troops really weighs 42,949,674 tons, but:
<pre>
21,474,837 × 200 = 4,294,967,400
= 2^32 + 104
wrapped cargo weight = 104 / 100 = 1 ton
</pre>
A player who accumulates that population on an owned planet can therefore move an enormous invasion force in a ship that classic believes gained only one ton. Similar wrap points exist for every item weight.

These examples follow deterministically from the published source and stock weights. A live classic test would confirm the complete command path and messages, but is not required to establish the arithmetic failure.

== Cause ==
Classic performs the equivalent of:
<pre>
(item_count × item_weight) / 100
</pre>
<code>item_count</code> is an unsigned long and <code>item_weight</code> is a long. Under the target compiler's usual arithmetic conversions, the multiplication is performed as a 32-bit unsigned value. It wraps modulo 2^32 before division can reduce it. Summing multiple already-wrapped item contributions cannot recover the lost high bits.

<code>chkweight()</code> performs this calculation for every item already aboard and again for the proposed addition. <code>calcweight()</code> performs the same calculation for the inventory report. Their agreement therefore makes the incorrect result look internally consistent.

== Fix history ==
=== ge-next 0.1 ===
ge-next 0.1 initially addressed the classic defect by calculating cargo contributions with floating-point arithmetic and by checking item-count addition against the unsigned-long limit before accepting a transfer. ge-next 0.1.1 refined the displayed total by accumulating fractional weight in a <code>double</code> and rounding the final result upward.

This removed the classic 32-bit multiplication wrap for normal game values, but later exact-integer cargo work and extreme inventory testing exposed remaining edge cases involving very large totals, fractional truncation, and intermediate overflow. The cargo system was therefore revisited rather than treating the original 0.1 change as the final implementation.

=== ge-next 0.3.1 ===
ge-next 0.3.1 rewrote the cargo routines with functionally equivalent but architecture-specific implementations.

The 16-bit build cannot rely on an efficient native 64-bit integer. It splits each quantity into complete groups of 100 and a remainder below 100, checks each multiplication against the remaining capacity before performing it, and carries fractional hundredths of a ton between item types. Impossible totals saturate instead of wrapping. Its “room for item” routine uses the same capacity predicate through a binary search, ensuring that displayed weight, transfer checks, and maximum transferable amounts follow one fit rule.

The 32-bit build uses a 64-bit unsigned accumulator measured in hundredths of a ton. It can multiply a 32-bit item count by the configured item weight directly, calculate remaining capacity in one operation, and then apply the same rounding and saturation rules as the 16-bit build.

Both implementations reject item-count addition overflow, combine fractional weight across item types, round any final fractional ton upward for display, and return a saturated maximum for impossible or corrupted inventories.

== Discovery transcript ==
[[Discovery transcript: GE-BUG-001|Read the June 2026 discussion of a later ge-next cargo-calculation failure]].

== Compatibility notes ==
A port should not assume that using a wider accumulator alone resolves every case. It must also reject item-count overflow, define behavior for totals beyond the report type, combine fractional weights consistently, and ensure that reports, capacity checks, loot collection, and “maximum transfer” calculations all use the same rule.

== Verification ==
The classic defect and exploit arithmetic were verified against the published classic source and stock item weights. The ge-next 0.1, 0.1.1, and 0.3.1 implementations were checked against their corresponding source revisions. The 0.3.1 routines were also exercised with inventories near the 32-bit unsigned item-count limit.

[[Category:Classic bugs: Numeric correctness]]

{{GE navigation}}

Discovery transcript: GE-BUG-055

2026-10-18T18:23:54Z

CodexBot: Add broadcast filter discovery excerpt

= Discovery of GE-BUG-055 =

'''Related bug:''' [[Classic bug: Filtered broadcast suppresses later recipients]] 
'''Source:''' Discord <code>#dev</code> discussion, September 3, 2026. Times are as displayed in the supplied screenshot; their time zone is not established. 
'''Editorial note:''' This is a short excerpt from one screenshot. The [[Classic bug: Filtered broadcast suppresses later recipients|bug article]] gives the source-level explanation and distinguishes classic's single filter from ge-next's category-based settings.

== September 3: A hail disappears downstream ==

; 10:50 PM — manicpoporg
: wow, i found an interesting legacy bug
: if message filters (set filter on in classic, or the category-based filters in ge-next) filter out a broadcast message for one user, it also filters it out for all users below that one
: let's say you have users 0, 1, 2 and 3 and user 2 has hails set to off. if user 1 hails user 0 will see it but not 2 (correct) or 3 (incorrect)

[At 11:07 PM, GitHub announced commit <code>4beca4d</code>, whose displayed title begins “remove obsolete mbbsemu mitigations, fix prf/fi...”.]

== Clarification ==

“Below that one” was informal wording. The example shows that the sender's hail reached slot 0, was intentionally suppressed at slot 2, and was then incorrectly absent for slot 3. The affected recipients are those processed ''after'' the filtered slot in the broadcast loop, not lower-numbered slots. Source review showed that rejecting one recipient cleared the shared print buffer used by the remaining recipients. ge-next 0.3.2 changed delivery so each recipient's filter affects only that recipient.

== See also ==
* [[Classic bug: Filtered broadcast suppresses later recipients]]
* [[Set command]]
* [[Send command]]

{{GE navigation}}
[[Category:Classic bugs]]
[[Category:History]]

Discovery transcript: GE-BUG-023

2026-10-18T18:23:51Z

CodexBot: Add phaser spread discovery excerpt

= Discovery of GE-BUG-023 =

'''Related bug:''' [[Classic bug: Phaser spread bias]] 
'''Source:''' Discord <code>#dev</code> discussion, December 4, 2025. Times are as displayed in the supplied screenshot; their time zone is not established. 
'''Editorial note:''' The screenshot captures an initial observation and a same-day fix, not a controlled measurement of both beam edges. The [[Classic bug: Phaser spread bias|bug article]] explains the verified arithmetic.

== December 4: Asymmetric shots ==

; 4:08 PM — manicpoporg
: the phaser spread is biased to the port side
: has anyone noticed this before
: spread 1 phasers hit ships bearing between -3 and +1 of aim
: spread 5 is between -7 and +5

[An attached game-output image shows <code>PHA -3</code> and <code>PHA 0</code> hitting manicpop's ship, while <code>PHA 3</code> produces no hit message. The accompanying note says the target ship's displayed bearing was 0.]

; 4:08 PM — manicpoporg
: that's with a ship bearing 0

[At 4:40 PM, GitHub announced commit <code>7d172f0</code>, “fix phaser spread / round deg and heading.”]

== Interpreting the first observation ==

The three shots made an asymmetry apparent, but “bearing 0” was a displayed whole-degree value, not a record of the target's exact angle. The screenshot therefore does not by itself prove that the port side is favored for every heading and target position, or establish the stated beam boundaries. Later source review identified the underlying issue: classic truncates the firing direction and target direction to whole degrees before comparing them. For the heading-zero geometry worked through in the bug article, that truncation favors the positive/starboard edge. The original “port side” description is retained above as part of the discovery history, not as the final general rule.

== See also ==
* [[Classic bug: Phaser spread bias]]
* [[Phasers]]

{{GE navigation}}
[[Category:Classic bugs]]
[[Category:History]]

Discovery transcript: GE-BUG-001

2026-10-18T18:23:47Z

CodexBot: Add cargo overflow discovery follow-up

= Discovery follow-up for GE-BUG-001 =

'''Related bug:''' [[Classic bug: Cargo weight overflow]] 
'''Source:''' Discord direct message between Oliver and manicpoporg, June 17, 2026. Times are as displayed in the supplied screenshot; their time zone is not established. 
'''Editorial note:''' This is a later ge-next cargo-capacity report, not the original discovery of classic GE's overflow. The screenshot and quoted chat show how an inadequacy in the early ge-next cargo fix was noticed. The [[Classic bug: Cargo weight overflow|bug article]] distinguishes the classic defect from the subsequent fixes.

== June 17: Planetary Transport capacity report ==

[Oliver shared game output from a Planetary Transport. A planet scan showed 217,993 food cases. <code>TRAN UP 217993 FOO</code> was refused with “There is not enough space available for that many items.” The inventory report showed 22,655,938 men, 1,902,680 food cases, other cargo, and a reported total cargo weight of 26,905,885 tons. The output also contained an unrelated “There is no such planet in this sector” message.]

; 4:19 PM — Oliver
: Bug on PT capacity?

; 4:39 PM — manicpoporg
: the weight calculation is overflowing the 32-bit long

; 4:49 PM — Oliver
: Why did that change?

; 5:21 PM — manicpoporg
: i don't know, the weight calculation has gotten too convoluted
: i need to rewrite it and probably have different routines for the 16-bit and 32-bit builds

== What this established ==

The refusal and unusually large inventory exposed a cargo-calculation problem in ge-next after its initial classic-overflow fix. The chat's “32-bit long” diagnosis was an immediate working explanation, not a complete analysis of every arithmetic path. Subsequent review led to architecture-specific cargo implementations in ge-next 0.3.1; the bug article explains those fixes. This screenshot alone does not show that the displayed Planetary Transport inventory was produced by the original classic exploit.

== See also ==
* [[Classic bug: Cargo weight overflow]]
* [[Ship inventory]]

{{GE navigation}}
[[Category:Classic bugs]]
[[Category:History]]

Planetary update cycle

2026-10-18T17:54:11Z

CodexBot: Link Btrieve explanation at first mention

'''Planetary update cycles''' decide ''when'' a planet record is visited and how many production passes are due. The scheduled routine is <code>plartia()</code> in the 16-bit [[Source code|source]]; the 5.x <code>plarti()</code> and 6.x <code>pplarti()</code> callbacks forward to it. The 32-bit implementation is named <code>plarti()</code>. When a colony is due, the routine calls <code>multiply()</code>; [[Planetary production]] explains what that one economic pass does. Neither visiting a planet nor scanning it immediately runs a production pass.

== Classic GE: a continuous database sweep ==
Classic [[MajorBBS integration|MajorBBS]] schedules the next <code>plartia()</code> callback after a variable <code>plantime</code> delay. The <code>PLANTOCK</code> setting specifies the target duration, in minutes, for ''one complete sweep'' of the database; its distributed value of 360 minutes aims for roughly four sweeps a day. It is not a per-planet timer or a guarantee of four updates on each calendar day.

The routine stores a [[Btrieve]] cursor position in memory and advances through the shared sector, planet, and wormhole file. Each invocation examines up to 20 records while seeking its next planet. A callback that finds no planet may therefore do no economic work. A populated planet with an owner is passed to <code>multiply()</code> and <code>check_spy()</code>; empty or unowned planets are skipped. [[Zygor]] and [[Tahanian Station]] also receive special stock resets when their records are encountered, after any applicable ordinary planet processing. See their pages for the resulting classic behavior.

At the end of the file, classic measures approximately how long the sweep took from the number of callbacks and the current delay. It recalculates <code>plantime</code> to bring the ''next'' sweep closer to <code>PLANTOCK</code>, but will not schedule callbacks less than three seconds apart. The cursor then starts over immediately. This feedback cannot enforce an exact number of passes: a planet may be reached three or five times in a day, and the work of walking sector and wormhole records increases as the galaxy is explored. A restart loses the in-memory cursor and timing history; downtime is neither recorded nor replayed. See [[Classic bug: Skipped planetary updates]] for the failure modes and examples.

== ge-next: named daily passes ==
[[ge-next]] 0.2 replaced the continuous-sweep target with <code>PLANUPD</code>, the desired number of passes per day (four by default; the setting allows 1–15). The scheduler walks the planet portion of the database index rather than scanning ordinary sector and wormhole records. It seeks an owned planet with men or troops, or one of the neutral-zone planets, and processes at most one selected planet per callback. It can inspect up to 25 records while looking for the next eligible one. At the end of a pass, it adjusts <code>plantime</code> to aim for the remaining passes to fit within 23 hours, leaving some margin before the day ends. Once the configured passes are complete, it stops applying further production passes that day rather than starting an extra sweep.

[[Zygor]], [[Tahanian Station]], and the [[Enforcer Planet]] take dedicated update paths. Ordinary eligible colonies call <code>multiply()</code> for production and <code>check_spy()</code> for spies. This separates special market restocking from colony food, population, tax, and revolt processing; it also avoids classic's first-update starvation problem at Zygor. The scheduler still records progress on the special planets, but they do not run ordinary colony production.

== Timestamps, restart, and catch-up ==
Every ge-next planet record carries a 32-bit <code>timestamp</code> combining the current game-day number in its upper bits with the pass number in its low four bits. Those four bits can hold the supported 1–15 daily passes. After a planet is processed, its day and pass are written to the database. A restarted or interrupted sweep may encounter the same record again, but the stored marker prevents it from receiving the same production pass twice.

Zygor's record additionally saves the global scheduler's current day/pass marker and calibrated callback interval. On startup, ge-next reads those values to resume today's work if applicable. If no useful interval has been saved, it estimates one from the current record count. A correction in ge-next 0.2.2 clears a stale saved interval after a day in which even the first pass failed to complete; otherwise rapid early database growth could leave the first pass too slow ever to reach its recalibration point.

If an ordinary planet's timestamp shows that it missed passes during an interruption or downtime, the scheduler calculates the number due and calls <code>multiply()</code> repeatedly. This catch-up is limited to recent history: planets behind within the previous seven days can replay missed passes, whereas older records receive one update instead of an unbounded backlog. Intermediate replays suppress repetitive player mail; the final pass may send its normal reports. The timestamp is a record of completed passes, not a promise that all missed work happens immediately when the BBS starts: the scheduler still has to reach that planet's record.

== What this means in play ==
A newly claimed colony will not produce goods until the scheduler reaches it. A change to its work allocation, tax, food stock, or bank affects the next pass that <code>multiply()</code> applies; it does not instantly recalculate existing inventory. After downtime, ge-next may apply several due passes together, so population and stock can change in a burst. Classic instead resumes sweeping from the beginning without knowing which planets were already visited. For the output, food, bank, tax, and revolt calculations within each pass, see [[Planetary production]].

== See also ==
* [[Planetary production]] and [[Colonizing planets]]
* [[Game timing]] and [[Game execution flow]]
* [[Classic bug: Skipped planetary updates]]
* [[Zygor]] and [[Tahanian Station]]

{{GE navigation}}
[[Category:Planets]]
[[Category:Game reference]]

Game execution flow

2026-10-18T17:54:09Z

CodexBot: Link Btrieve explanation at first mention

'''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]]

Classic registration and security system

2026-10-18T17:54:06Z

CodexBot: Link Btrieve explanation at first mention

Galactic Empire 3.2e contains a board-specific registration system, a time-limited test-drive system, protected [[Btrieve]] database handling, and a second concealed system check. These mechanisms are separate from <code>PLAYKEY</code> and <code>SYSKEY</code>, which control user access and administrative privileges.

The released source contains two largely independent layers. The documented registration and test-drive system is implemented by <code>SECURE.C</code> and was introduced in release 3.0d so GE could be distributed generally. The concealed <code>c4angle()</code> account check has no visible connection to that system and may have an older origin.

== <code>SECURE.C</code> registration system ==
=== Security state ===
The shared <code>secure</code> structure records three states:

{| class="wikitable"
! <code>open_stat</code> !! Meaning
|-
| <code>1</code> || The configured registration number is valid for this BBS
|-
| <code>-1</code> || The registration number is invalid or absent, but the test drive remains active
|-
| <code>0</code> || Security validation failed or the test drive has expired; GE is disabled
|}

<code>days_run</code> holds the test-drive startup-day count and <code>days_tot</code> holds its permitted length. At startup, classic reports the registration number, the current test-drive day, or that the unregistered game is disabled.

When disabled, GE does not schedule ship, NPC, planet, or automatic-update callbacks. Login, cleanup, deletion, hangup, and ordinary command entry also contain guards against operating on the protected databases. A player who enters the module receives the trial-expired notice instead of the game. The records are not erased: entering a valid registration number allows the game to continue where it stopped.

=== Original registration number ===
Classic's <code>REGNO</code> configuration option accepts an eight-character registration number tied to the host BBS registration number. The internal registration utility identifies Galactic Empire as using seed <code>10094056</code> and method 1. These are also the values actually selected by <code>GEMAIN.H</code>.

The standalone <code>SECURE.H</code> contains generic example values (including a different seed and method 0). They are not Galactic Empire's effective values: <code>sec_opnbtv()</code> receives GE's values as arguments from <code>GEMAIN.C</code>.

==== Generation algorithm ====
The publisher's <code>REGISTER</code> utility asks for the product seed, method, and customer's eight-digit MajorBBS or Worldgroup registration number. For GE it generates the key as follows:

# Convert the seed and BBS registration number to integers.
# XOR the two integer values.
# Represent the result as an eight-position, right-aligned decimal value.
# For method 1, add the corresponding seed digit to each position and retain only the last decimal digit.

In compact form, the final operation for each position is:

<syntaxhighlight lang="text">
registration_digit[i] = (xor_digit[i] + seed_digit[i]) % 10
</syntaxhighlight>

The runtime <code>protect()</code> routine independently derives the same value from MajorBBS's <code>bturno</code> and compares it with <code>REGNO</code>. Consequently, a key generated for one registered BBS does not register another.

<code>REGISTER.EXE</code> was the utility specified for Galactic Empire and The Legend of Elyth Gor. The accompanying <code>REG2</code> and <code>REG3</code> algorithms were intended for other M.B. Murdock products and are not used by GE.

=== Protected databases ===
The ship and mail databases are opened normally. The planet and user databases are opened through <code>sec_opnbtv()</code>.

The routine derives the correct board-specific registration value even while the game is running as an unregistered test drive. It supplies that value to the Btrieve open path and invokes Btrieve operation 29 (Set Owner), binding the protected files to the board-specific value.

Each protected database also receives a concealed record whose first key is a high-valued byte string defined by <code>KEY</code>. The remaining bytes hold four encoded fields:

* the first test-drive date;
* the last date on which the module was started;
* the number of distinct startup dates; and
* a second copy of the first date tied to the BBS registration number.

The stored bytes are additionally offset by their positions in the record. This is obfuscation and tamper detection, not encryption in the modern sense. On each new calendar date, the run counter and last-run date are updated.

For the original GE seed, characters 1 and 7 are combined to produce a 15-day test-drive limit. The test drive is rejected if its initial date is in the future, elapsed calendar time exceeds the limit, the startup-day count exceeds the limit, or the redundant board-bound date does not agree. This means both clock rollback and simply avoiding daily use are accounted for: elapsed calendar time is checked independently of the number of days on which GE started.

Because the security information is stored as an otherwise valid database record, code that walks the user database must recognize and skip the <code>KEY</code> record. Classic's midnight cleanup does this explicitly. A port or database tool that treats every record as a player can expose the security record in a roster or, worse, rewrite it as player data.

==== Startup cross-check ====
<code>GEMAIN.C</code> first opens the planet database and saves its resulting security state. It then opens the user database and requires both databases to agree on <code>open_stat</code> and <code>days_tot</code>. A disagreement causes a fatal <code>Secure Stat Open failure</code> or <code>Secure Days Open failure</code>. This prevents the game from quietly combining protected files with incompatible security state.

=== <code>FAKESECURE</code> ===
<code>GEMAIN.C</code> contains a commented build-time <code>FAKESECURE</code> switch. When enabled, the planet and user files use ordinary <code>opnbtv()</code>, and a dummy <code>secure</code> structure reports a registered state. It bypasses the protected open, trial counter, and cross-database registration checks.

The switch is disabled in the released source. It is also not a complete removal of all security-related code: the separate <code>c4angle()</code> check remains compiled and callable.

== Common online 3.2e build ==
A 3.2e package commonly distributed with MBBSEmu differs from the released source configuration. Its <code>REGIST.TXT</code> instructs the sysop to "Use your activation code for MBBS" rather than obtain the derived GE registration number.

Running the DLL with the default <code>REGNO</code> produces GE's trial-expired message. It also creates and evaluates the concealed records in both protected databases. It therefore is '''not''' a <code>FAKESECURE</code> build.

Decoding a newly created security record shows that its date is stored without the XOR transformation that the original <code>10094056</code> seed would produce. The DLL contains no <code>10094056</code> string and instead has a second <code>00000000</code> string consistent with a replaced seed. Its effective security seed is <code>00000000</code>.

That change has two consequences:

* XOR with zero leaves <code>bturno</code> unchanged, and method-1 digit addition with zero changes no digits. The valid <code>REGNO</code> is therefore the BBS's own eight-digit registration number.
* The test-drive length is derived from positions 1 and 7 of the seed. A zero seed produces a zero-day allowance, so an incorrect or absent <code>REGNO</code> is disabled immediately.

This exactly matches the package's instructions and observed behavior. The change could have been made by rebuilding after changing the source constant, or by replacing the eight ASCII bytes <code>10094056</code> with <code>00000000</code> directly in the DLL. The resulting binary alone cannot distinguish between those methods.

== The concealed <code>c4angle()</code> check ==
<code>GELIB.C</code> describes <code>c4angle()</code> only as "Verify system." Its name does not describe its operation. On its first call, it constructs the otherwise unobvious account key <code>Glperr</code>, selects MajorBBS's account database, and searches key 0. If that account record exists, GE terminates with <code>GE SYSTEM FAULT</code>. If it does not exist, a static flag prevents the test from running again during that module load.

The released GE source contains no routine that creates the <code>Glperr</code> account, so the intended path by which that marker would be placed cannot be established from GE's source alone.

Rather than calling this check visibly during initialization, classic places it inside <code>absol()</code>, GE's floating-point absolute-value helper. Normal navigation and combat mathematics eventually call <code>absol()</code>, which makes the security test occur indirectly. The function also changes the current Btrieve context to the account database and does not restore the prior context; ports should understand that as an implementation side effect, not as part of absolute-value behavior.

=== Possible earlier origin ===
Before version 3, GE was distributed for MajorBBS 5.x as source that became part of the compiled BBS rather than as a drop-in module DLL. The release notes specifically identify the <code>SECURE.C</code>-style registration protection as a new 3.0d feature. By contrast, <code>c4angle()</code> is independent of that system, survives the <code>FAKESECURE</code> bypass, and checks for a marker that no surviving 3.2e routine creates.

These facts make it plausible that <code>c4angle()</code> is a remnant of an earlier source-distribution-era protection scheme, perhaps paired with an old installer, build procedure, or security component that created <code>Glperr</code>. No pre-3.x implementation or marker-creation utility is present in the available archive, however, so this remains a historical hypothesis rather than an established fact.

== Source integration ==
The classic implementation is distributed across several locations:

{| class="wikitable"
! Location !! Role
|-
| <code>SECURE.C</code> || Protected Btrieve open, owner setup, registration comparison, trial record, counters, and tamper checks
|-
| <code>SECURE.H</code> || Generic declarations and sample defaults; not the authoritative GE constants
|-
| <code>GEMAIN.H</code> || GE's actual method, seed, high-key value, structure declaration, and prototype
|-
| <code>GEMAIN.C</code> || Protected database opens, cross-checks, scheduler and entry guards, status messages, and <code>FAKESECURE</code>
|-
| <code>GELIB.C</code> || Concealed <code>c4angle()</code> account check through <code>absol()</code>
|-
| <code>GECMDS.C</code> || Implementation of the diagnostic <code>RG#</code> display
|-
| <code>MBMGEMP.LNK</code> || Links the separately compiled security object into the module
|-
| <code>register/REGISTER.CPP</code> || Publisher-side method-1 registration-number generator
|}

The installation manual documents <code>RG#</code> as a technical-support command that reports the configured registration number, security state, and test-drive day. Its command-table entry is commented out in 3.2e, although the handler remains in the source; see [[Commands#Administration and diagnostics]]. The classic [[Who command|<code>WHO</code>]] terminal-support command likewise exposes the BBS registration number in PHARLAP/MajorBBS 6.x builds.

== ge-next ==
ge-next does not enforce classic's commercial registration or test-drive system and does not place security records in its databases. Its <code>REGNO</code> setting is only an optional installation identifier, not an unlock key. Since version 0.3.2, a blank or zero value produces no registration line at startup; a configured value is shown there and can distinguish multiple installations. <code>REGNO</code> is not player authentication or a frontend pairing code: the separate <code>FRONTEND</code> option controls [[Data command|DATA]] access.

{{GE navigation}}
[[Category:Sysop documentation]]
[[Category:Development]]

Classic bug: Skipped planetary updates

2026-10-18T17:54:05Z

CodexBot: Link Btrieve explanation at first mention

{{Classic bug
|id=GE-BUG-011
|affected=Classic 3.2e and published classic source
|status=Verified through source analysis and long-running games
|fixed=ge-next 0.2; startup calibration refined in 0.2.2
|source=Classic GEMAIN.C: plartia(); ge-next GEMAIN.C: plartia()
}}

== Summary ==
Classic Galactic Empire does not record when an individual planet was last updated. Instead, one process-local cursor continuously sweeps through the entire planet database and updates planets as it encounters them. The routine tries to adjust its own callback interval so that one sweep takes the number of minutes configured by <code>PLANTOCK</code>.

This makes the configured period only a target for a complete database sweep, not a guarantee that every planet receives a fixed number of updates in a calendar day. With the recommended six-hour setting, some planets can receive three updates in a day while others receive five. Interrupted sweeps, server downtime, and restarts can make the difference more pronounced. As the database grows, the scheduler also spends increasing amounts of time walking [[Sector|sector]] and wormhole records that cannot receive economic updates.

== Classic scheduling model ==
Classic describes <code>PLANTOCK</code> as the amount of time in which to update all planets. Its default of 360 minutes is intended to produce four updates per day. The implementation does not divide the day into four named update periods, however. It continuously repeats this process:

# Start at the beginning of the shared sector/planet/wormhole database.
# Run <code>plartia()</code> after the current <code>plantime</code> delay.
# Examine records until one planet is found or 20 records have been examined.
# If a planet was found, update at most that one planet.
# Save the [[Btrieve]] absolute position in the process-local <code>fpos</code> variable and schedule another callback.
# At end of file, measure how long the sweep took, adjust <code>plantime</code>, reset the cursor, and immediately begin another sweep.

The updater therefore normally handles no more than one planet per callback. It may handle no planet at all: <code>MAXTIC</code> limits one invocation to 20 database records, so an invocation that encounters 20 sector or wormhole records merely advances the cursor.

Only an owned planet with population is passed to the normal economic <code>multiply()</code> routine. The neutral-zone planets receive their own special replenishment treatment. Empty and unowned planets do not receive an economic update, but the scheduler still has to find and inspect their records.

=== Adaptive timing ===
Classic starts with a delay of approximately 55 seconds between callbacks. At the end of a sweep it calculates approximately:

<pre>
measured sweep time = callback count * current callback delay
new callback delay = current delay * (PLANTOCK / measured sweep time)
</pre>

For example, if a sweep takes twice the configured target, the next callback delay is roughly halved. The result is never allowed below three seconds. This is feedback control based on the preceding sweep, not a schedule tied to the clock or to individual planets.

== Why four updates per day is not guaranteed ==
A six-hour <code>PLANTOCK</code> only asks the routine to make a complete pass approximately every six hours. There is no concept of "update 1," "update 2," "update 3," and "update 4" for a particular day, and there is no check that stops updates after a planet has received four.

Even when every sweep finishes normally, its boundaries are unrelated to midnight. Small timing differences accumulate from callback scheduling, database activity, and integer rounding. A calendar day can consequently contain only three visits to a particular planet or can catch five visits near the edges of successive sweeps. The routine simply begins another pass whenever the previous one ends.

In an uninterrupted completed sweep, the cursor ordinarily reaches each eligible planet once. The larger problem is that classic has no durable way to know whether any particular planet has already received the update that should correspond to a given part of the day.

== Database growth and wasted work ==
The file traversed by <code>plartia()</code> is not a planet-only file. It contains the persistent records created as the galaxy is explored:

* sector records;
* planet records; and
* wormhole records.

Classic begins its scan at the sector-record portion of the index and counts sector and wormhole records while looking for planets. Those records cannot receive population, production, food-consumption, tax, or spy updates, so this work is scheduler overhead.

This matters because scanning creates a sector record even when the sector has no planets. The database therefore tends to accumulate non-planet records faster than updateable colonies. As exploration continues, more callbacks are consumed merely advancing through the file. The adaptive calculation lowers the callback delay to compensate, but it cannot go below three seconds and each invocation still examines at most 20 records and updates at most one planet.

Eventually the requested number of full passes may require more work than the routine can perform at those limits. Long before that hard ceiling, growth during one sweep and the use of the previous sweep as the timing estimate can make the actual cycle length lag behind its configured target. The classic documentation itself warns that CPU load grows with the galaxy and recommends increasing <code>PLANTOCK</code> or reducing <code>UNIVMAX</code> when performance becomes a problem.

== Restarts and downtime ==
Classic stores its traversal cursor, callback count, and timing counters only in static variables. They are lost when the module or server restarts. The planet record contains no last-update day, pass number, or elapsed-time marker.

This has several consequences:

* A restart in the middle of a sweep starts the next run at the beginning of the database. Planets before the old cursor may be updated again before planets after it receive the interrupted pass.
* Hours or days of downtime produce no updates, and there is no catch-up when the game returns.
* A restart cannot distinguish a planet updated moments before shutdown from one that has not been updated for days.
* The adaptive interval also has to establish itself again instead of resuming from durable scheduler state.

These failures are not recoverable from the classic records because the information needed to reconstruct the missed work was never recorded.

== ge-next correction ==
ge-next 0.2 replaced the classic sweep with a day-and-pass scheduler. The configuration specifies the desired number of updates per day with <code>PLANUPD</code> (four by default), rather than specifying an approximate duration for an endlessly repeated sweep.

Each planet record has an unsigned-long <code>timestamp</code>. ge-next packs two values into it:

* the game day, represented as the number of days since 1980-01-01, in the upper bits; and
* the update-pass number in the low four bits.

The low four bits accommodate the supported range of 1 through 15 updates per day. After processing a planet, ge-next records the current day and pass on that planet. Zygor's record additionally stores the current scheduler state and the calibrated callback interval, allowing the scheduler to resume after a restart.

Because every planet carries its own progress marker, encountering a record does not automatically mean applying another economic update. ge-next compares the stored day/pass with the current day/pass and computes exactly how many updates are due. Restarting midway through a pass may cause the scanner to revisit earlier records, but their timestamps prevent the same pass from being applied twice.

If a planet is behind because of downtime or an interrupted run, ge-next replays the missing calls to <code>multiply()</code>. Catch-up is limited to the previous seven days so a very old record cannot monopolize one callback with an unlimited amount of historical work. Intermediate catch-up updates run without generating repetitive player mail; only the final live update can send normal notices.

ge-next also stops after completing the configured number of passes for the day. It does not immediately begin an unbounded fifth pass. The scheduler targets completion within 23 hours, leaving time for timing variation.

=== Startup calibration refined in 0.2.2 ===
ge-next 0.2 initially estimated the delay between planet-update callbacks from the database size at startup. On a new game with very few records, that estimate could be about 1,000 seconds per callback at the default four updates per day. If players then explored and created many more planet records, the first pass could take longer than a day. The scheduler recalculated its callback delay only after finishing a pass, so it never reached the recalculation point; the new planets remained unvisited by that pass.

ge-next 0.2.2 changed the startup estimate from abrupt database-size brackets to a gradual estimate based on the record count. More importantly, [[Game execution flow#Midnight routine|midnight cleanup]] now detects when the first pass has not finished (<code>passnum <= 1</code>) and clears the saved callback interval on Zygor. On the next startup, the scheduler estimates the interval again using the now-larger database instead of carrying forward the stale value. Once a pass does finish, the normal end-of-pass calibration can take over. This correction does not make the first day immune to rapid growth, but prevents an unfinished first pass from indefinitely blocking recalibration.

== More efficient traversal ==
The revised routine starts at the planet-record key and remains within the planet portion of the index. It no longer walks every ordinary sector and wormhole record merely to locate the next planet. It can also skip empty or unowned planets while retaining explicit progress through the planet records.

The result is that database growth from exploring empty sectors no longer consumes most of the planetary scheduler's work. More importantly, the economic state of a planet is determined by its recorded update history, not by whether a process-local cursor happened to reach it often enough.

== Porting guidance ==
A port should treat planetary production as a scheduled, idempotent job:

* persist a day/period identifier or last-update time on every planet;
* calculate elapsed periods from that stored value;
* make revisiting an already processed record harmless;
* retain enough global state to resume an interrupted pass;
* impose a documented limit on catch-up work; and
* traverse a planet-only index or query instead of scanning unrelated sector and wormhole records.

Database iteration order should determine only when a due update is processed, never whether the planet is considered to have experienced the pass at all.

[[Category:Classic bugs: Planets]]
[[Category:Classic bugs: Database]]
[[Category:Classic bugs: Scheduler]]

{{GE navigation}}

Classic bug: Planet record-limit failure

2026-10-18T17:54:03Z

CodexBot: Link Btrieve explanation at first mention

{{Classic bug
|id=GE-BUG-012
|affected=Classic 3.2e and published classic source
|status=Verified in source and observed in a full production database
|fixed=ge-next 0.3
|source=GEMAIN.C: gesdb(), getplanetdat(); GEPLANET.C: getsector(), xgetsector(), getplanet()
}}

== Summary ==
Classic Galactic Empire can create incomplete [[Sector|sectors]] when the shared sector/planet/wormhole database reaches <code>MAXPLREC</code>. The sector generator continues building an in-memory sector after one or more database insertions have been refused, and none of the creation callers are told which records were actually saved.

The resulting sector header may advertise planets or wormholes whose child records do not exist. Later code assumes those records exist and can display an unrelated planet left in the global planet workspace. Players observed these as ''[[wikipedia:The_Phantom_Planet|phantom planets]]'': the sector scan plotted several different planets, but scanning each numbered planet repeatedly displayed the same bearing, distance, environment, and resources. Some reported distances were millions of units. In one test, the phantom planet later changed into Zygor because the periodic planet updater had loaded Zygor into the shared workspace.

The same partial-creation problem can produce one-way wormholes. A saved wormhole can lead to a destination sector or return wormhole that could not be inserted after the record cap was reached.

== What MAXPLREC limits ==
<code>MAXPLREC</code> is presented to the sysop as the maximum size of <code>MBMGEPLT.DAT</code> in KiB. Classic multiplies the configured value by two because every logical record is 512 bytes. The default value of 32,767 therefore becomes a code-level limit of 65,534 records, although the classic configuration text describes it as holding 65,535.

The count includes every record in the shared file, not just planets:

* one sector-header record for every generated sector;
* one child record for every planet; and
* one child record for every wormhole.

A sector containing four planets consequently needs five records. Wormhole creation can require still more because the game also creates or updates the destination sector and attempts to install a return wormhole there.

The [[Btrieve]] file on disk can be larger than the configured payload limit due to indexes and other file overhead. The production database involved in the original investigation was 35,716,096 bytes even though the configured <code>MAXPLREC</code> represented approximately 32 MiB of 512-byte records.

== Classic creation sequence ==
When an unexplored sector is scanned, <code>xgetsector()</code> constructs the entire sector in global memory before and during a series of separate database writes:

# Randomly decide how many planets the sector will contain and whether any slots are wormholes.
# Generate each object's coordinates in the in-memory <code>sector.ptab[]</code> table.
# Insert the sector-header record, including <code>numplan</code> and the complete object table.
# Build and insert each planet or wormhole as a separate child record.
# For each new wormhole, create or load its destination sector and add the reciprocal wormhole when a slot is available.

The record-limit check is not performed on this operation as a whole. Instead, classic performs <code>cntrbtv()</code> inside the low-level <code>gesdb(GEADD)</code> case before ''every individual insert''. If the current count is below <code>max_plrec</code>, that one record is inserted. If the count has reached the cap, the insert is skipped and only an informational <code>Max Sect Reached</code> message is logged.

The result is not propagated to <code>xgetsector()</code>. The caller proceeds through all remaining creation steps as though every insertion succeeded.

== Partial sectors near the limit ==
Suppose the database has room for two more records and the generator chooses a sector with four planets:

# The sector header is inserted. It permanently says that planet slots 1 through 4 exist and stores four plotted coordinates.
# Planet 1 is inserted into the final available slot.
# Inserts for planets 2, 3, and 4 are silently refused by the <code>MAXPLREC</code> check.

The database now contains a structurally incomplete sector. A later sector scan reads the valid header and plots all four entries from <code>sector.ptab[]</code>. A planet scan requests the separate child record. Only planet 1 can be loaded; the other three keys do not exist.

This explains an important visual clue from the live failure: [[Scan command|<code>SCAN SECTOR</code>]] could show planets in distinct positions while <code>SCAN PLANET 1</code>, <code>SCAN PLANET 2</code>, and so forth reported identical data. The map was using the planned coordinates saved in the sector header, while the detailed scans were trying and failing to load the missing child records.

If the database is already full before generation begins, none of the new records are saved. The freshly generated sector can still exist temporarily in global memory for the current command, so it may appear real until another operation replaces that workspace. A later scan can generate a different temporary sector for the same coordinates because no persistent sector header was ever written.

== Why missing planets become other planets ==
Classic uses one global <code>planet</code> structure as its shared planet record workspace. <code>getplanet()</code> asks Btrieve to load the requested key into that structure, but on failure it only logs an error. It does not clear <code>planet</code>, returns the same value on success and failure, and its callers continue by setting <code>plptr</code> to that same workspace.

The missing planet therefore appears to have the contents of whichever real planet was loaded most recently. Possible sources include:

* an earlier numbered planet scan;
* another planet-related command;
* another user's activity; or
* the background planetary updater.

This produced several observed forms of the bug:

* every phantom planet in a sector displayed the same bearing and distance;
* all showed the same environment, resources, population, and stockpiles;
* bearings and distances changed when another real planet replaced the shared workspace;
* distances reached millions of units because the stale record belonged to a completely different sector; and
* after the updater loaded Zygor, a missing planet scan displayed Zygor's name, ownership, and supplies.

The behavior is not merely cosmetic. <code>getplanetdat()</code> reports success as long as the requested number appears in the sector header, even when the child lookup failed. Many classic commands then read or manipulate <code>plptr</code>. Depending on the command and the last record in memory, code intended for the phantom object can inspect or act on an unrelated real planet.

== One-way wormholes ==
Wormholes expose a second partial-write path. The source sector and its wormhole child can be inserted while space remains, but the database may hit the cap before the destination sector and reciprocal wormhole are saved.

The source wormhole remains usable because its record contains destination coordinates. Traveling through it moves the ship to those coordinates, but the destination can load as an empty, unsaved sector with no return wormhole. During reproduction, logs showed failures while creating the two destination sectors selected for wormholes; entering one of the surviving source wormholes deposited the player in an empty sector.

This is distinct from classic's intentional behavior when an already-full destination sector has no free object slot. Here, the return path is absent because the database cap interrupted creation.

== Existing sectors ==
Sectors and child records that were completely saved before the database filled continue to load normally. During the original incident, previously explored sectors retained their correct planet positions and details. The failure affects newly generated sectors and any sectors left partially written as the record count crosses the cap.

Normal updates to existing records are not blocked by <code>MAXPLREC</code>; the defect is specifically in creation and in the handling of missing child records.

== ge-next's initial fix ==
The first ge-next fix, committed during 0.3 development, moved a record-count check to the start of <code>xgetsector()</code>. If an ordinary requested sector did not exist and the database was already at <code>MAXPLREC</code>, ge-next cleared the in-memory sector, filled in the requested coordinates, set <code>numplan</code> to zero, and returned it as an empty sector without trying to save anything.

This fixed the most common case: once the database was full, scanning another unexplored location no longer generated a temporary table of phantom planets. It was nevertheless incomplete. If the database was merely ''near'' the limit, creation could still begin successfully. The low-level per-record cap could then be reached between the sector header and its later planet or wormhole records. The first fix also prevented a wormhole destination from being completed if the source-sector work consumed the last nominal slots.

Testing immediately demonstrated both remaining cases: a four-object sector whose fourth child did not exist, and saved source wormholes whose destination sectors could not be created.

== Complete creation fix ==
The follow-up ge-next fix treats <code>MAXPLREC</code> as a soft boundary between complete sector-creation operations rather than a hard boundary between individual record inserts.

It made two coordinated changes:

* The low-level cap was removed from <code>gesdb(GEADD)</code>. Once sector creation has started, all sector, planet, and wormhole records required by that operation may be inserted.
* The start-of-sector guard remains for ordinary exploration, but wormhole destination creation bypasses it so the reciprocal side of a wormhole can be completed.

The database may therefore exceed the configured target by the records needed to finish the sector and any wormhole destinations already in progress. Afterward, the next attempt to generate an unrelated unexplored sector sees that the count is at or above the limit and returns a consistent empty sector. A small, bounded overshoot is preferable to permanently saving a header that references nonexistent children or a wormhole with no generated destination.

== Later defensive hardening ==
Before the final ge-next 0.3 release, planet lookup was also hardened so a missing record is safe regardless of its cause:

* <code>getplanet()</code> clears the global planet workspace before lookup;
* it returns <code>FALSE</code> when the requested key does not exist and <code>TRUE</code> only after a real record is loaded;
* <code>getplanetdat()</code> propagates that result instead of treating the sector header as proof that the child exists; and
* scans, orbit administration, transfers, trade, beacons, planetary weapons, and other callers stop their operation when the load fails.

This defense prevents stale Zygor data, another player's last planet, or any other previous workspace contents from masquerading as a missing planet even if a database becomes inconsistent for some reason unrelated to <code>MAXPLREC</code>.

== Discovery transcript ==
[[Discovery transcript: GE-BUG-012|Read the Discord discussion and tests that uncovered this bug]].

== Porting guidance ==
Sector generation should be atomic at the logical level. A port should use a transaction where available, or reserve enough capacity before writing the sector header and all of its children. The header must never advertise an object until that object's backing record is guaranteed to exist.

Wormholes require the same rule across both ends: either create a valid destination and reciprocal link, or do not expose the source wormhole.

Every record-loading function should also:

* initialize or invalidate its destination before lookup;
* return an explicit success/failure result;
* require callers to check that result; and
* avoid shared stale state being interpreted as newly loaded data.

Silently refusing one write in the middle of a multi-record object is not a safe implementation of a database-size limit.

[[Category:Classic bugs: Planets]]
[[Category:Classic bugs: Database]]
[[Category:Classic bugs: Wormholes]]

{{GE navigation}}

Ge-next installation

2026-10-18T17:54:01Z

CodexBot: Link Btrieve explanation at first mention

{{DISPLAYTITLE:ge-next installation}}
This page gives the ge-next-specific choices and filenames. For the shared installation, backup, and rollback procedure, begin with [[Installing Galactic Empire]]; for saved files and resets, see [[Database files]].

== Choose a release ==
* [https://github.com/manicpop/ge-next/releases 16-bit ge-next releases] are for DOS MajorBBS/Worldgroup and [[MBBSEmu]]. Since ge-next 0.3.2, MBBSEmu uses the normal 16-bit package; it requires MBBSEmu v1.0-alpha-090826 or newer. See [[Running Galactic Empire with MBBSEmu]] for emulator setup.
* [https://github.com/manicpop/ge-next32/releases 32-bit ge-next releases] are for The Major BBS V10, not MBBSEmu.

Choose a '''full release archive''' for a new installation. Both architectures present themselves as ge-next and are intended to have the same gameplay; <code>PROJECT_ARCH</code> identifies the build in version and DATA output. They have different database layouts, so do not substitute one architecture's saved files for the other's. The release DLL is ready to install; source compilation is not required.

[[ge-arena]] is a separate module and download, despite sharing ge-next's source tree. Its <code>MPOGA*</code> files are not an upgrade to or replacement for ge-next's <code>MPOGE*</code> files.

== ge-next package contents ==
{| class="wikitable"
! Files !! ge-next-specific role
|-
| <code>MPOGEMP.DLL</code>, <code>MPOGEMP.MDF</code> || Module and definition. The MDF identifies <code>MPOGEMSG</code>, <code>MPOGEHLP</code>, and <code>MPOGESHP</code> as its message resources.
|-
| <code>MPOGEMSG.MSG</code>, <code>MPOGEHLP.MSG</code>, <code>MPOGESHP.MSG</code> || Main settings/messages, help, and ship classes. Full release archives ship these sources, not precompiled MCV files; use the host's message compilation procedure. See [[Configuring Galactic Empire]].
|-
| <code>MPOGEUSR.DAT</code>, <code>MPOGESHP.DAT</code>, <code>MPOGEPLT.DAT</code>, <code>MPOGEMAL.DAT</code>, <code>MPOGETEA.DAT</code> || Supplied starting files and, after play begins, the live game. The team file is text; the others are [[Btrieve]] files. [[Database files]] explains how to back up or reset the entire set.
|-
| Matching <code>*.NEW</code> (16-bit) or <code>*.VIR</code> (32-bit) || Clean templates for an intentional new game, not a step in a routine upgrade.
|-
| <code>MPOGEMNU.TXT</code>, <code>RELNOTES.TXT</code>, <code>FRONTEND.TXT</code>, <code>LICENSE.txt</code> || Menu text, release notes, DATA frontend reference, and license. The 16-bit archive also includes optional <code>RLTELNET.SH</code> and a linker <code>.MAP</code> file.
|}

The 16-bit archive retains DOS 8.3 filenames. Keep the files from one release together, including any compiled message resources generated from its MSG sources.

== Activating the module ==
Use <code>MPOGEMP.MDF</code> when adding ge-next to a MajorBBS/Worldgroup menu. With MBBSEmu, use module identifier <code>MPOGEMP</code> in <code>modules.json</code> and point its path at the 16-bit package; [[Running Galactic Empire with MBBSEmu]] covers the rest of that setup. Review <code>MPOGEMSG.MSG</code> and <code>MPOGESHP.MSG</code> before admitting players, then compile all three message sources for the installed DLL. The full archive already has starting <code>.DAT</code> files; copying templates over them is unnecessary.

The general [[Installing Galactic Empire#Install a new game|installation checklist]] covers host startup and first-use testing. Do not replace a running game's <code>.DAT</code> files merely because a new full archive contains fresh ones.

== ge-next upgrade boundary ==
ge-next 0.3 renamed the module and data from <code>MBM*</code> to <code>MPO*</code> and changed persistent structures. Saved games from earlier ge-next releases are '''not''' directly compatible with 0.3 or later. For later upgrades, read every intervening <code>RELNOTES.TXT</code>; a patch archive may omit files expected to be present from its specified base release.

Use [[Installing Galactic Empire#Upgrade or roll back|the shared upgrade procedure]] for backups, merging local MSG changes, preserving live DAT files, and rollback. MBBSEmu installations also have live SQLite <code>.db</code> files; [[Database files#MBBSEmu|Database files]] explains their handling. Neither the clean templates nor the starting DAT files in a new archive are a migration tool.

== ge-next checks ==
In the game, <code>HELP VERSION</code> should show the intended ge-next version and architecture. If a frontend uses [[Data command|DATA]], verify its pairing and reported project metadata against <code>FRONTEND.TXT</code>. The ordinary menu, ship, scan, roster, persistence, and host-log checks are listed on [[Installing Galactic Empire#Install a new game|the general installation page]].

== See also ==
* [[Installing Galactic Empire]]
* [[Database files]]
* [[Configuring Galactic Empire]]
* [[Running Galactic Empire with MBBSEmu]]

{{GE navigation}}
[[Category:ge-next]]
[[Category:Sysop documentation]]

Sys command

2026-10-18T17:53:56Z

CodexBot: Link Btrieve explanation at first mention

The '''SYS''' command provides privileged diagnostic and administrative controls from inside Galactic Empire. These are not normal gameplay commands: many of them bypass prices, cargo capacity, travel, proximity, or ship-class restrictions, and some can deliberately place game records into combinations that normal play could never produce.

Classic GE describes the commands as debugging aids and warns that they can give a player a distinct advantage. A production game should therefore limit them to trusted administrators.

== Syntax ==
<syntaxhighlight lang="text">
SYS HELP
SYS subcommand [arguments]
</syntaxhighlight>

<code>SYS HELP</code> displays the subcommands documented by the installed version. ge-next also makes the same text available through [[Help command|<code>HELP SYS</code>]], but only to a user who is authorized to use <code>SYS</code>.

== Access control ==
Three configuration settings govern access:

; <code>SYSCMDS</code>
: Enables or disables the command as a whole.
; <code>SYSONLY</code>
: When enabled, restricts the command to users who pass the board's sysop authorization test. Turning it off makes these powerful commands available to ordinary players and is not recommended.
; <code>SYSKEY</code>
: On MajorBBS 6.x and later systems, identifies the key required for SYS access. It defaults to <code>SYSOP</code>, but an administrator can define a dedicated key such as <code>GEOP</code> and give it to selected game operators. MajorBBS 5.x builds instead test the account's built-in sysop flag.

Authorization is checked before any subcommand is interpreted. Classic GE responds <code>Huh?</code> if <code>SYS</code> is disabled or the user is unauthorized; it also uses that response for an unrecognized SYS subcommand. ge-next instead returns its ordinary invalid-command message for disabled or unauthorized SYS use, making it look like an actual invalid game command rather than acknowledging a special command.

== Classic subcommands ==
These are the active SYS subcommands in classic GE 3.2e. All remain available in standard ge-next, with the noted changes. There are no active classic-only SYS subcommands in this version; old Cybertron test branches in the classic source are compiled out.

{| class="wikitable"
! Syntax !! Effect
|-
| <code>SYS HELP</code>
| Displays the available SYS commands.
|-
| <code>SYS GET [amount] [item]</code>
| Adds the requested item directly to the current ship. It does not enforce cargo capacity, purchase price, or normal acquisition rules.
|-
| <code>SYS KILL [user]</code>
| Sets every matching active ship above the destruction threshold. Destruction then proceeds through the game's normal ship-destruction processing.
|-
| <code>SYS CASH [amount]</code>
| Changes the current user's cash. Classic requires an amount and adds it directly. ge-next permits a negative amount to remove cash without going below zero, prevents overflow, and fills cash to its supported maximum when the amount is omitted.
|-
| <code>SYS GOTO [x] [y]</code>
| Teleports the current ship to the center of the specified sector and clears its hostility timer. ge-next validates both positive and negative coordinates against the actual galaxy radius; classic's one-sided test can accept invalid negative coordinates and rejects the positive outer edge.
|-
| <code>SYS CLASS [number]</code>
| Changes the current ship's class and top speed. It does not construct a new ship or automatically reconcile every existing system and inventory value with the new class. ge-next also rejects disabled or invalid class entries.
|-
| <code>SYS SHIELDTYPE [number]</code>
| Directly changes the installed shield class. ge-next rejects negative values.
|-
| <code>SYS PHASERTYPE [number]</code>
| Directly changes the installed phaser class. ge-next rejects negative values.
|-
| <code>SYS MAINT</code>
| Classic starts its special fast-maintenance path and immediately performs a repair pass. ge-next starts ordinary timed maintenance without requiring planetary orbit, but still refuses while the ship's combat timer is active.
|-
| <code>SYS UNJAM</code>
| Removes the current ship's jamming effect immediately. ge-next clears its separate jamming-severity and duration fields.
|-
| <code>SYS LIST [number]</code>
| Displays as many as 50 occupied live-ship slots, beginning at the optional slot number. Classic shows channel, identity, sector, damage, update tick, and Cybertron target. ge-next adds course-control, Cybertron-update, and last-attacker state useful for debugging combat and NPC behavior.
|-
| <code>SYS CLASSLIST</code>
| Lists the loaded ship classes and selected NPC-allocation fields, including whether Cybertrons may attack the class and its configured pursuit count.
|-
| <code>SYS CYBPAUSE [seconds]</code>
| Suspends Cybertron processing for the specified number of seconds.
|}

Classic <code>SYS MAINT</code> has several rough edges. It prints the normal maintenance-start message, whose <code>%d</code> [[Centock|centock]] placeholder expects a repair-time argument, but this call supplies none; the displayed number is therefore undefined stack data, not a real estimate. The command sets the repair flag and runs only one repair pass immediately, rather than completing all repairs at once; later passes occur on ship-state updates. It prints that start message even while the battle-exit restriction is active, after which <code>repairship()</code> immediately cancels the work. On an undamaged ship, the immediate pass still reaches the completion path, lowering the shields and clearing their charge.

<code>SYS CLASS</code>, <code>SYS SHIELDTYPE</code>, and <code>SYS PHASERTYPE</code> are direct diagnostic edits rather than purchases. They do not charge the user and should not be assumed to enforce the normal class table, upgrade eligibility, or installation side effects.

== ge-next-only subcommands ==
The following operations are not in classic GE 3.2e. The in-game <code>SYS HELP</code> list contains the commonly useful controls; a few low-level inspection commands are accepted without being advertised there.

{| class="wikitable"
! Syntax !! Effect
|-
| <code>SYS MAINT NOW</code>
| Immediately completes all maintenance without waiting for the normal repair process.
|-
| <code>SYS FACTIONS</code>
| Displays the current user's standing with each of the eight factions.
|-
| <code>SYS NEBSEED</code>
| Displays the seed from which the current nebula layout is derived.
|-
| <code>SYS FILLSLOTS</code>
| Populates every vacant NPC slot according to the currently loaded Cybertron and Droid class allotments. It is useful after changing allocations or while diagnosing the NPC population.
|-
| <code>SYS MIDNIGHT</code>
| Runs GE's midnight housekeeping routine immediately. This is a debugging control, not a substitute for the board's scheduled cleanup.
|-
| <code>SYS TEAMDUMP</code>
| Displays the in-memory team records, including internal identifiers, member counts, deletion dates, passwords, and founder secrets. ge-next 0.3 moved this sensitive diagnostic output from classic's undocumented, unprivileged <code>TEAM DUMPITOUT</code> to SYS.
|-
| <code>SYS MULTIPLY [number]</code>
| Runs from one to 50 production cycles on the inhabited planet currently being orbited, then saves the planet. It refuses planets without a population and owner.
|-
| <code>SYS ORBIT [planet]</code>
| Places the ship in orbit around a numbered planet in its present sector without enforcing the normal distance requirement. It cannot orbit a wormhole. ge-next also stops the ship and displays the planet's update timestamp for diagnostics.
|-
| <code>SYS ASSIGNCYBS</code>
| Reassigns the Cybertrons pursuing the current player according to ge-next's distance-based pursuit selection.
|-
| <code>SYS FILL [amount]</code>
| Sets every item slot in the current ship to the requested quantity. Omitting the amount uses the largest supported item quantity. Unlike <code>SYS GET</code>, this replaces every item quantity rather than adding one selected item.
|}

<code>SYS MULTIPLY</code>, <code>SYS ORBIT</code>, and <code>SYS MIDNIGHT</code> were introduced in ge-next 0.1. Later releases added the NPC inspection and assignment controls as the Cybertron and Droid allocation systems were corrected and expanded.

== ge-arena ==
ge-arena retains SYS authorization and permits an authorized operator to enter the command from the lobby. Only <code>SYS HELP</code> and <code>SYS CLASSLIST</code> work there; the class list is limited to ships configured for the selected arena mode.

The following commands require an active match, an operator participating in that match, and a selected ship:

<syntaxhighlight lang="text">
SYS NEBSEED SYS GET SYS KILL
SYS GOTO SYS CLASS SYS SHIELDTYPE
SYS PHASERTYPE SYS MAINT SYS UNJAM
SYS LIST SYS ORBIT SYS FILL
</syntaxhighlight>

Persistent-game or unsupported controls are disabled in ge-arena. These include <code>SYS FACTIONS</code>, <code>SYS FILLSLOTS</code>, <code>SYS CASH</code>, <code>SYS MIDNIGHT</code>, <code>SYS TEAMDUMP</code>, <code>SYS CYBPAUSE</code>, <code>SYS MULTIPLY</code>, and <code>SYS ASSIGNCYBS</code>. The restrictions prevent an operator in the lobby from modifying nonexistent ship state and exclude systems that ge-arena deliberately does not persist.

== Operational cautions ==
* Make a backup before using commands that alter persistent users, planets, or world state.
* Do not use <code>SYS GET</code> or <code>SYS FILL</code> to test normal cargo limits; bypassing those limits is their purpose.
* Do not assume a ship produced by <code>SYS CLASS</code> is equivalent to a normally purchased ship of that class.
* Treat <code>SYS TEAMDUMP</code> output as confidential.
* Check logs after SYS commands that write records; a success message alone does not establish that a [[Btrieve]] update succeeded.
* Leave <code>SYSONLY</code> enabled unless deliberately running a controlled test in which every participant may use administrative commands.

== See also ==
* [[Sysop documentation]]
* [[Help command]]
* [[Maintenance command|Maintenance]]
* [[Cybertrons]]
* [[Planetary production]]
* [[Classic bug: SYS GOTO desynchronizes warp state]]

{{GE navigation}}
[[Category:Commands]]
[[Category:Sysop documentation]]

Original release history

2026-10-18T17:53:52Z

CodexBot: Link Btrieve explanation at first mention

The surviving original release history is preserved in [[GEREADME.DOC]]. Its dated entries run from version 2.0a on April 29, 1989, through version 3.2e on August 6, 1994. The 2.0a notes explicitly describe that release as a revision of version 1.4; the earlier releases are not dated in this changelog.

== Release chronology ==
{| class="wikitable"
! Release !! Date in surviving notes !! Historical significance
|-
| 1.4 and earlier || Before April 1989; dates not established here || 2.0a names 1.4 as its predecessor. Elwynor's retrospective history traces the titles ''Galactic War'', ''Galactic Raiders'', and ''Galactic Empire'', but does not date each change.
|-
| [[GEREADME.DOC#04/29/89_Release_2.0a|2.0a]] || April 29, 1989 || First official 2.0 release outside beta; added Cybertron opponents, multiple ship classes and fleets, and kill-focused scoring.
|-
| [[GEREADME.DOC#05/01/89_Release_2.0b|2.0b]]–[[GEREADME.DOC#12/01/89_Release_2.0n|2.0n]] || May–December 1989 || Frequent combat, economy, scanner, and scoring adjustments. The notes record changes to galaxy-edge behavior and a random starting point for planetary updates.
|-
| [[GEREADME.DOC#01/10/90_Release_2.1a|2.1a]]–[[GEREADME.DOC#03/22/90_Release_2.1e|2.1e]] || January–March 1990 || New planet-based scoring and roster details, database changes, [[Btrieve]] and cleanup work, and further combat fixes. A 2.1f entry is explicitly marked ''not released''.
|-
| [[GEREADME.DOC#06/15/90_Release_2.2a_BETA_(NOT_GENERALLY_RELEASED)|2.2a]]–[[GEREADME.DOC#09/09/90_Release_2.2e|2.2e]] || June–September 1990 || Early beta releases followed by wider releases; 2.2c added colorized screens, revised scans, and moved the neutral zone to sector 290.
|-
| [[GEREADME.DOC#07/23/91_Release_2.3a|2.3a]]–[[GEREADME.DOC#02/08/92_Release_2.3g|2.3g]] || July 1991–February 1992 || More configurable planet ownership and transfer rules, mines and jammers, Cyberquads, and working zippers by 2.3g.
|-
| [[GEREADME.DOC#07/15/92_Release_3.0a_(BETA_RELEASE)|3.0a]] || July 15, 1992 || Beta debut of the on-demand Virtual Galaxy, sector 0 0 neutral zone, wormholes, scanner locks, navigation aids, and terminal-program support.
|-
| [[GEREADME.DOC#08/30/92_Release_3.0b_(STILL_BETA)|3.0b]]–[[GEREADME.DOC#09/11/92_Release_3.0d_(BETA_to_go)|3.0d]] || August–September 1992 || 3.0b added MajorBBS 6.0 DLL support; 3.0c activated Droid ships and explicit shield controls; 3.0d added registration protection for general release.
|-
| [[GEREADME.DOC#11/01/92_Release_3.0l_(General_Release_-_NOT_BETA!!)|3.0l]]–[[GEREADME.DOC#2/5/93_Release_3.0p|3.0p]] || November 1992–February 1993 || 3.0l is labeled a general, non-beta release. Later notes added self-destruct blast damage, <code>DATA</code> support, and additional neutral-zone planet configuration.
|-
| [[GEREADME.DOC#7/4/93_Release_3.1b|3.1b]] || July 4, 1993 || New database keys and registration code, protected-memory allocation for systems above 128 users, expanded ship options, and warp overspeed.
|-
| [[GEREADME.DOC#12/14/93_Release_3.2c|3.2c]] and [[GEREADME.DOC#Patch_level_6_(3.2c.6)_2/8/94|patches]] || December 14, 1993–February 8, 1994 || Scoring and stock-default rebalance, database reset, and six documented patch levels covering spies, cloak, shields, missiles, and planetary updates.
|-
| [[GEREADME.DOC#03/06/94_Release_3.2d|3.2d]] || March 6, 1994 || Configurable item/phaser/shield prices, revised fighter attacks, optional command headings, stronger phasers, wormhole projectile cleanup, and <code>SET FILTER</code>.
|-
| [[GEREADME.DOC#08/06/94_Release_3.2e|3.2e]] || August 6, 1994 || Per-class Cybertron and Droid messages and corrected high-warp display; last release recorded in the supplied classic notes.
|}

The table highlights milestones, not every letter release or patch. In particular, a dated note records what the developer intended to release; it does not by itself prove that every described correction worked in the final code. The [[Classic bug database]] documents surviving discrepancies.

== Installation and compatibility ==
Several releases required new databases, a database conversion, a fresh registration code, or coordinated changes to the MSG and ship-class files. The 3.2c base release explicitly required resetting all databases after a ship-table field-size error; 3.1b required new empty databases and registration information. An operator upgrading a historical system should read that release's installation notes rather than assume that a same-series update is data-compatible.

== Later history ==
The 1994 endpoint belongs to the original MBM release line. Elwynor Technologies' later Worldgroup and MajorBBS ports, and the separately developed ge-next line, are covered under [[History of Galactic Empire]] and [[Versions of Galactic Empire]].

== See also ==
* [[GEREADME.DOC]]
* [[Versions of Galactic Empire]]
* [[Classic Galactic Empire]]

{{GE navigation}}
[[Category:History]]
[[Category:Versions]]

MajorBBS integration

2026-10-18T17:53:51Z

CodexBot: Link Btrieve explanation at first mention

'''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]]

Database files

2026-10-18T17:53:49Z

CodexBot: Link Btrieve explanation at first mention

'''Galactic Empire''' keeps its saved game in files beside the module. A sysop should know which files belong together, which clean templates to retain, and which files to restore when starting a new game. For field layouts and [[Btrieve]] keys, see [[Data structures]]; this page covers the files as an operational set.

== Game files ==
{| class="wikitable"
! Purpose !! Classic GE !! Elwynor GE !! ge-next (0.3+)
|-
| Players, preferences, scores || <code>MBMGEUSR.DAT</code> || <code>ELWGEUSR.DAT</code> || <code>MPOGEUSR.DAT</code>
|-
| Persistent player ships || <code>MBMGESHP.DAT</code> || <code>ELWGESHP.DAT</code> || <code>MPOGESHP.DAT</code>
|-
| Discovered sectors, planets, wormholes || <code>MBMGEPLT.DAT</code> || <code>ELWGEPLT.DAT</code> || <code>MPOGEPLT.DAT</code>
|-
| In-game mail || <code>MBMGEMAL.DAT</code> || <code>ELWGEMAL.DAT</code> || <code>MPOGEMAL.DAT</code>
|-
| Teams || <code>MBMGETEA.DAT</code> || <code>ELWGETEA.DAT</code> || <code>MPOGETEA.DAT</code>
|}

The <code>USR</code>, <code>SHP</code>, <code>PLT</code>, and <code>MAL</code> files are Btrieve databases. Despite its <code>.DAT</code> extension, the <code>TEA</code> file is '''not''' a Btrieve database: it is GE's fixed-width text team table. Keep it with the rest of the saved game when backing up or resetting. ge-arena uses only its own <code>MPOGAUSR.DAT</code> and <code>MPOGAPLT.DAT</code>; it does not use persistent ship, mail, or team files.

These game variants have distinct file prefixes. Do not merge their directories or substitute one variant's data files for another's. In particular, a classic <code>MBMGEUSR.DAT</code> is not an in-place replacement for a ge-next <code>MPOGEUSR.DAT</code>, and 16-bit and 32-bit files should not be interchanged without a supported conversion procedure.

== Templates and record sizes ==
The 16-bit packages provide clean <code>*.NEW</code> templates corresponding to their <code>*.DAT</code> files. The 32-bit packages use <code>*.VIR</code> templates for the same purpose. Keep the original templates unchanged so a fresh game can be created later.

The 16-bit Btrieve user, ship, and planet-family records are 246, 501, and 493 bytes respectively. The 32-bit versions use 256-byte user records and 512-byte ship and planet-family records. Mail has its own record format, and the team file is text rather than a Btrieve record set. These sizes matter when choosing the correct package or diagnosing a mismatched file; the individual fields belong in [[Data structures]].

== Back up or start over ==
Before changing files, stop the game or BBS and make a copy of the entire game's data set. Back up the matching <code>.DAT</code> files together, including <code>TEA</code> if present; restoring only a user or planet file can leave ships, scores, ownership, and teams inconsistent. Preserve the clean <code>.NEW</code> or <code>.VIR</code> templates separately from these live-game backups. If the host provides a supported consistent-backup method, that is an alternative to stopping it; ordinary copies taken while Btrieve is writing may contain records from different points in time.

A recoverable installation backup should also include the matching module executable, module-definition and configuration files, compiled main/help/ship-class messages, and any local text resources in use, such as menu text or frontend settings. Record the relevant BBS/module configuration and keep release notes with the backup. Database files are the critical saved game, but they may not be usable with an unrelated DLL or message-file version.

To start a new game, with the module stopped, copy each clean template over its matching <code>.DAT</code> file: for example, <code>MPOGEUSR.NEW</code> to <code>MPOGEUSR.DAT</code> in 16-bit ge-next, or <code>MPOGEUSR.VIR</code> to <code>MPOGEUSR.DAT</code> in ge-next32. Do this for '''all''' files used by that game, not just one database. Keep a backup of the old game until the fresh one has started successfully. This resets the game; it is not a way to repair an existing game while preserving its progress.

== Upgrades and rollback ==
Before upgrading, read the intervening release notes and check for changes to database records, file prefixes, configuration options, or required migrations. Keep the old installation and a consistent backup until the new version has been verified. Use the new release's message files as the starting point and merge local configuration values deliberately; replacing messages blindly can discard local settings, while retaining old messages can omit required options or text. A clean <code>.NEW</code> or <code>.VIR</code> template is for starting over, not for upgrading a live game while preserving its players and planets.

After startup, inspect host and module logs, then test the menu, roster, a saved ship and planet, scans, and a database-changing action. Verify scheduled cleanup when practical and keep the previous backup until the new build has seen normal multi-user play. If rollback is needed, restore the executable, messages, configuration, and all related saved records from the '''same backup point'''. Replacing only the DLL while leaving records written by a newer layout is not a safe rollback.

== MBBSEmu ==
MBBSEmu converts the module's Btrieve <code>.DAT</code> files to corresponding SQLite <code>.db</code> files and runs the game using those SQLite copies. A <code>.DAT</code> file may remain in the folder even when the live changes are in its <code>.db</code> companion. The team <code>TEA.DAT</code> remains a text file; it does not become a Btrieve-backed <code>.db</code> game database.

For backups under MBBSEmu, stop the emulator and copy the game's <code>.db</code> files '''and''' its <code>.DAT</code> files as one set, plus the team file if used. For a full reset, stop MBBSEmu, back up the old files, remove the game's corresponding <code>.db</code> copies, and copy the clean <code>.NEW</code> templates over '''all''' of that game's <code>.DAT</code> files (including the team file). MBBSEmu will create fresh SQLite copies when it next loads the module. Merely replacing <code>.DAT</code> while leaving an old <code>.db</code> in place is not a reliable reset.

== See also ==
* [[Data structures]]
* [[Integer and storage assumptions]]
* [[MBBSEmu]]
* [[Classic registration and security system]]

{{GE navigation}}
[[Category:Sysop documentation]]
[[Category:Development]]

Porting Galactic Empire

2026-10-18T17:53:45Z

CodexBot: Link Btrieve explanation at first mention

'''Porting Galactic Empire''' means reproducing a MajorBBS game, not merely getting its C source to compile on another platform. GE depends on host callbacks, shared workspaces, [[Btrieve]] records and keys, and the order in which timed events run. A port should decide which classic behavior it is preserving and which known defects it is correcting.

== Choose a compatibility target ==
There is a difference between reproducing the intentions of classic GE, reproducing every visible behavior of the 3.2e binary, and reproducing the source's accidental behavior. Those goals can conflict: widening an overflowing calculation may be the right fix for gameplay but will not reproduce a classic exploit. State the target and record intentional departures; the [[Classic bug database]] supplies concrete cases.

When comparing versions, separate original GE behavior from ge-next's changes. Elwynor's 32-bit port is useful for checking host and architecture differences, but it is not a substitute for the 16-bit source or a running classic game. See [[Versions of Galactic Empire]].

== Recreate the host contract ==
GE is entered through MajorBBS module registration. The host supplies the current channel and account, invokes input and lifecycle callbacks, runs scheduled <code>rtkick()</code> callbacks, and provides message formatting and Btrieve services. A replacement host needs to preserve the effects of those services, not just their function names. See [[MajorBBS integration]] and [[Game execution flow]].

Distinguish ordinary exit, carrier loss, account deletion, GE's midnight maintenance, and the BBS disconnecting users for its own cleanup. These follow different paths and can have different consequences for a ship. ge-next's use of <code>rsmodes</code> during a cleanup-related hangup is an intentional correction to classic behavior.

== Keep session and world state separate ==
The 16-bit code uses <code>usrnum</code> to select a live BBS channel and global pointers and scratch variables for the current operation. A channel is reusable, not a permanent account or ship identifier. A concurrent port must isolate or serialize operations that touch this shared state, including scans, output, database buffers, and delayed ordnance. Merely copying the globals into a server-wide object would introduce cross-user races.

GE has several lifetimes that must remain distinct: the connection, saved user record, current ship, created sector, and weapons already in flight. Ship destruction, leaving the module, hanging up, and deleting an account are not interchangeable cleanup operations. A projectile can outlive the connection that fired it; represent a departed owner explicitly. See [[Ship slot]], [[Scantab]], and [[Data structures]].

== Preserve event order ==
Movement, automatic ship systems, projectiles, NPC decisions, and planetary updates have different schedules. Replacing them with one undifferentiated loop can change which hit receives kill credit, when a damaged ship stops acting, whether a weapon intercepts before its target moves, and when a planet is updated. Preserve cadence and meaningful ordering before changing mechanics. See [[Game timing]] and [[Game execution flow]].

Sectors are generated on demand, with planet and wormhole records stored in Btrieve. A concurrent implementation must prevent two operations from independently creating the same sector or conflicting destination records. Test both first discovery and later reads of an existing sector. See [[Sector]] and [[Wormholes]].

== Match storage and arithmetic deliberately ==
Classic GE assumes a 16-bit <code>int</code>, 32-bit <code>long</code>, narrow byte fields, and fixed Btrieve key layouts. Wider native arithmetic, different packing, or different signedness can change play and saved data. Classic structures do not all have the same size as their Btrieve records, so <code>sizeof</code> cannot be accepted uncritically. The 32-bit ports use explicit narrow types and different record lengths. See [[Integer and storage assumptions]] and [[Data structures]].

Btrieve has behavior beyond reading and writing bytes: key ordering, duplicate and nonmodifiable keys, record-position operations, return codes, and file-selection state can all affect GE. Preserve the observable behavior of the operations GE calls. MajorBBS message formatting and output-buffer clearing are likewise part of the interface; a message delivered to the wrong channel is a portability bug even if its text is correct.

== A practical verification sequence ==
# Establish a baseline with stock classic files, configuration, and more than one connected player. Record command output and timed behavior before changing the implementation.
# Audit persistent structures against the actual Btrieve templates and key definitions. Add size and offset checks where the target compiler permits them.
# Reproduce module entry, exit, hangup, cleanup, message output, and database operations before tuning combat or NPC logic.
# Test arithmetic boundaries: zero, negative input, maximum inventories, signed/unsigned scores, coordinate axes, galaxy edges, and numeric sentinels.
# Test delayed behavior: moving targets, wormholes, mines, projectiles whose owner leaves, and users reconnecting on a reused channel.
# Compare a confirmed defect against the [[Classic bug database]], then apply any correction separately from unrelated porting changes.
# Where an emulator and real MajorBBS disagree, verify host behavior before adding a game-side workaround.

== See also ==
* [[MajorBBS integration]]
* [[Integer and storage assumptions]]
* [[Data structures]]
* [[Game execution flow]]
* [[MBBSEmu]]
* [[Source code]]

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

Integer and storage assumptions

2026-10-18T17:53:44Z

CodexBot: Link Btrieve explanation at first mention

Classic GE was written for 16-bit x86 C and [[Btrieve]]. Its calculations, in-memory structures, database records, and output conventions do not all have the same width. These details matter when investigating a classic bug or porting the game; see [[Porting Galactic Empire]] for the wider workflow.

== Integer and floating-point widths ==
In the original 16-bit environment, <code>char</code> and GE's <code>byte</code> are one byte, <code>int</code> and <code>unsigned</code> are two bytes, and <code>long</code> and <code>unsigned long</code> are four bytes. GE also stores positions, headings, speeds, damage, and some energy values as <code>double</code>. A field's declared type, not a modern compiler's <code>int</code> size, controls what can be saved in it.

For example, <code>WARUSR.score</code> and <code>WARUSR.cash</code> are 32-bit unsigned values in the 16-bit code, but ship and user kill counters are 16-bit <code>unsigned</code> values. <code>WARSHP.shield</code> and <code>WARSHP.lastfired</code> are 16-bit signed <code>int</code> values; ship inventory quantities are 32-bit <code>unsigned long</code>. Broad statements such as “scores are 32-bit” do not describe every counter in a record.

The 32-bit port uses MajorBBS types such as <code>SHORT</code>, <code>USHORT</code>, and <code>ULONG</code> in persistent structures. This is necessary because a native 32-bit <code>int</code> can change intermediate arithmetic even if the destination field is narrow. ge-next32's <code>gernd()</code> returns <code>USHORT</code> to preserve 16-bit unsigned behavior at callers that depend on it. Fixed-width fields alone are not enough: promotions, casts, and the point at which a result is narrowed also matter.

== Arithmetic and display ==
* Multiplication may overflow before a later division reduces the result. Widen the operands before multiplying if the larger intermediate is intended.
* Subtracting from an unsigned value can wrap instead of producing a negative number. Check availability before changing inventory or energy.
* Converting a floating-point result to an integer truncates its fractional part. Moving the conversion earlier or later changes distance, damage, or production.
* A stored unsigned value may be displayed or sorted as signed. Classic's roster score key is one example: storage type, Btrieve key interpretation, and printed representation must be checked separately. See [[Roster command]].
* MajorBBS message resources have their own formatter conventions. A C <code>printf()</code> format is not automatically valid in an MSG file; the expected argument width must match the directive.

These are not theoretical hazards. See [[Classic bug: Cargo weight overflow]], [[Classic bug: Cash and counter wraparound]], and [[Classic bug: Flux subtraction underflow]] for gameplay consequences.

== Byte sentinels and slot limits ==
Byte-sized fields often use a value outside the valid slot range as a sentinel, but the meaning is specific to each field. For mines in ge-next, <code>MINE_UNUSED</code> is 255 and <code>MINE_NO_USER</code> is 254: an unused mine and a live mine without a player owner are different states. Classic did not make that distinction in the same way. A port must reserve sentinel values when sizing channel or ship tables and must not turn one field's “255” into another field's “no user.” See [[Mines]] and [[Ship slot]].

== Btrieve record sizes and layout ==
The shipped classic 16-bit Btrieve templates use 246-byte user records, 501-byte ship records, and 493-byte sector/planet/wormhole records. The corresponding classic C structures are larger: 255, 514, and 512 bytes respectively. GE's Btrieve calls use the configured record length, so copying <code>sizeof(struct)</code> bytes as though it were the on-disk format would be wrong. 16-bit ge-next made its structures match the actual 246/501/493-byte records.

Elwynor's V10 port and ge-next32 use 256-byte user records and 512-byte ship and planet-family records, with matching structure sizes. Those are not byte-for-byte interchangeable with 16-bit files just because the field names look alike. ge-next32 uses explicit filler and compile-time size checks. The ge-arena builds place some newer fields in reserved record space rather than silently enlarging the files. [[Data structures]] gives the complete record table, key layout, and evolution of the fields.

Btrieve keys make offsets and signedness as important as total size. Field order, padding, string width, and key interpretation must be verified against the real file definition. A size check cannot catch a field moved to the wrong offset. Do not infer disk layout solely from a compiler's default packing or a later port's structure.

== Porting rule ==
First establish the valid range and intended result for each operation. Then choose whether invalid input is rejected, an internal result is clamped, or a genuine classic wrap is deliberately retained. Document that choice and test the relevant boundaries. Widening every calculation or preserving every overflow without inspection can each change the game in unintended ways.

== See also ==
* [[Data structures]]
* [[Porting Galactic Empire]]
* [[Classic bug database]]
* [[Roster command]]

{{GE navigation}}
[[Category:Development]]
[[Category:Classic bugs: Numeric correctness]]

Installing Galactic Empire

2026-10-18T17:53:42Z

CodexBot: Link Btrieve explanation at first mention

'''Galactic Empire''' is distributed as a BBS module, not a standalone game. Installation begins by choosing a build that matches both the host and the version of the game. This page covers the common steps; the linked guides provide version-specific files, registration, and emulator instructions.

== Choose a game and host ==
{| class="wikitable"
! Game !! Suitable host and starting point
|-
| [[Classic Galactic Empire|Classic GE 3.2e]] || Original 16-bit MajorBBS/Worldgroup game. On MBBSEmu, use a compatible classic package and consult [[Running Galactic Empire with MBBSEmu#Running classic GE|the classic setup notes]]. The distributed build may require a board-specific registration setting; see [[Classic registration and security system]].
|-
| [[Elwynor Galactic Empire|Elwynor GE]] || Faithful 32-bit port of classic GE for Worldgroup 3.2 and The Major BBS V10. Use its own package and installation instructions; it is not interchangeable with the 16-bit classic module.
|-
| [[ge-next]] || Persistent GE game with separate 16-bit MajorBBS/Worldgroup and 32-bit MajorBBS V10 builds. Supported MBBSEmu versions use the '''16-bit''' package. See [[ge-next installation]].
|-
| [[ge-arena]] || Separate match-based module, available in 16-bit and 32-bit builds. It has its own file prefix, configuration, and saved game; do not install it as an update to ge-next.
|}

Download a '''full release archive''' for the selected game and architecture. A patch archive assumes a particular installed version and may omit files needed for a new installation. Read that release's notes before copying anything, especially when replacing an existing game. Playing on someone else's BBS requires no local module installation; see [[Where to play online]].

== Understand the files ==
{| class="wikitable"
! File type !! Purpose
|-
| <code>*.DLL</code>, <code>*.MDF</code> || The executable module and its MajorBBS module definition. The MDF identifies the module and its message resources. See [[MajorBBS integration]].
|-
| <code>*.MSG</code>, <code>*.MCV</code> || Editable message/configuration sources and compiled runtime resources. Main messages, help, and ship classes normally have separate MSG files. Loading a module on a board should generate MCVs based on the MSG files; do not copy MCV files from a different installation. See [[Configuring Galactic Empire]].
|-
| <code>*.DAT</code> || Starting data in a full archive, then the live saved game after play begins. The files used vary by game; the team file is text, not a [[Btrieve]] database. See [[Database files]].
|-
| <code>*.NEW</code>, <code>*.VIR</code> || Clean data templates supplied with 16-bit and 32-bit packages respectively. Retain them for a deliberate fresh start; they are '''not''' backups of the live game.
|-
| Other text files || Release notes, menu text, licensing, and optional frontend documentation or utilities. Keep them with the matching release.
|}

File prefixes identify the game: classic uses <code>MBM*</code>, ge-next 0.3+ uses <code>MPOGEMP</code> for its module and <code>MPOGE*</code> for support files, and ge-arena uses <code>MPOGA*</code>. Do not mix files just because their suffixes or purposes look alike. Nor should 16-bit and 32-bit databases or compiled messages be swapped without an explicitly supported conversion path. [[Database files]] lists the actual saved files for each game.

== Install a new game ==
# Extract the complete, matching release to the location expected by the host. If installing more than one GE variant, keep each one's files and saved data separate.
# Register or enable the module through the BBS's module/menu setup using its MDF. Under MBBSEmu, configure the module in <code>modules.json</code> instead; follow [[Running Galactic Empire with MBBSEmu]] for emulator-specific setup. Classic registration is a separate matter from host module registration.
# Review any settings that must be chosen before play. See [[Configuring Galactic Empire]].
# Start the host. Check its log for missing DLLs, messages, databases, or record-size errors. Enter the game as a test user, check its menu and help, create or load a ship where applicable, and verify a scan and a saved change.

Full release archives normally include starting <code>.DAT</code> files, so startup is '''not''' a general instruction to rebuild a database from <code>.NEW</code> or <code>.VIR</code>. An arena match may generate its own sectors during play, but that is different from creating the installation's data files. To reset an existing game, stop it and follow the complete procedure in [[Database files#Back up or start over|Database files]].

== Upgrade or roll back ==
ge-next can generally be upgraded across point releases only, for example ge-next 0.3 should upgrade to ge-next 0.3.3 just fine. Classic GE games cannot be upgraded to ge-next. ge-next 0.2 and lower games cannot be upgraded to ge-next 0.3.

Before an upgrade, stop the game or take a host-supported consistent backup. Preserve the '''entire''' matching saved-data set, the DLL, MDF, MSG and MCV files, local text resources, and host configuration. Under MBBSEmu, also account for its live SQLite <code>.db</code> companions; see [[Database files#MBBSEmu|MBBSEmu database handling]]. Read every intervening release note for incompatible record layouts, required resets, renamed files, or new configuration entries.

Install the new module and use its MSG sources as the baseline, merging local settings deliberately. Do not overwrite live <code>.DAT</code> files with the starter files from a full release unless you are intentionally resetting the game. Do not bring over MCV files from the previous instance; an old MCV may refer to the wrong message identifiers or options in a new DLL. After starting the upgrade, inspect the host log and test an existing account and saved record before opening the game to everyone.

If an upgrade must be undone, restore '''the DLL, resources, configuration, and all saved data from the same backup point'''. Replacing only the DLL is not a safe rollback after newer code has written records. The detailed procedure and reset distinctions are in [[Database files#Upgrades and rollback|Database files]].

== Running multiple variants ==
Classic GE, ge-next 0.3+, and ge-arena can coexist because their current releases use different module names and file prefixes. Give each its own host registration, message resources, and saved files. Distinct filenames prevent collisions; they do not make one game's databases compatible with another's. Refer to [[ge-next installation]] for that game's exact files and to [[Database files]] for the data each variant keeps.

== Further guides ==
* [[ge-next installation]] - ge-next packages and upgrade notes
* [[Running Galactic Empire with MBBSEmu]] - local emulator setup, including classic GE
* [[Classic registration and security system]] - original game's registration and common online build
* [[Configuring Galactic Empire]] - MSG files, configuration, and MCV compilation
* [[Database files]] - backups, templates, resets, and rollback
* [[GEINST.DOC|Original GEINST.DOC]] - historical 3.2 installation manual, not a guide to every modern build

{{GE navigation}}
[[Category:Sysop documentation]]

Data structures

2026-10-18T17:53:41Z

CodexBot: Link Btrieve explanation at first mention

''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]]

Classic Galactic Empire

2026-10-18T17:53:39Z

CodexBot: Link Btrieve explanation at first mention

'''Classic Galactic Empire''' is this wiki's name for the original M.B. Murdock & Associates game, particularly releases 3.2d and 3.2e and the published classic source. It is the baseline used when documenting original gameplay, implementation assumptions, and inherited defects; ''classic'' was not a separate product title used by its publisher.

== Earlier lineage ==
Michael B. Murdock developed the game for MajorBBS through M.B. Murdock & Associates. Elwynor Technologies' retrospective account names ''Galactic War'' and ''Galactic Raiders'' as earlier forms of the game. ''Galactic Raiders'' briefly remained a separate module without Cybertrons. The original 2.0a release notes refer to an earlier version 1.4, so the dated changelog's April 1989 starting point is not the game's beginning.

== Final classic releases ==
Version 3.0, introduced in 1992, established the on-demand Virtual Galaxy and many features recognizable in the final game. Release 3.2c (December 1993 with patches through February 1994) changed stock balance, scoring, and databases. Release [[GEREADME.DOC#03/06/94_Release_3.2d|3.2d]] (March 6, 1994) added configurable prices and revised weapons, navigation, and message filtering. Release [[GEREADME.DOC#08/06/94_Release_3.2e|3.2e]] (August 6, 1994) added configurable per-class Cybertron messages and corrected high-warp display. It is the final release recorded in the original notes. When this wiki refers to features or behavior of classic Galactic Empire, it is referring to version 3.2e unless otherwise stated.

The published notes identify intended behavior, but not every announced fix is complete in the surviving code. See [[Original release history]] for a fuller chronology and the [[Classic bug database]] for verified discrepancies.

== Configuration ==
Classic GE is highly configurable. Stock behavior can be changed through the main message/configuration file and ship-class table. Consequently:
* ship prices and capabilities are not guaranteed to match between systems;
* galaxy size and boundary behavior may differ;
* NPC classes and population can be customized;
* item values, weights, production, and scoring can vary;
* user-visible text is not reliable evidence of the underlying release.

See [[Configuring Galactic Empire]] and [[Classic NPC ship classes]].

== Implementation ==
Classic is a single-threaded MajorBBS module written for a 16-bit C environment. It combines fixed in-memory tables and per-channel state with persistent [[Btrieve]] records. Those assumptions matter to emulation and porting. See [[Source code]], [[Data structures]], and [[Integer and storage assumptions]].

== Known defects ==
The published source includes defects ranging from display errors to numeric overflow, stale ownership, and cross-user memory corruption. They are cataloged individually in the [[Classic bug database]] so ports can decide which behavior to preserve and which defects to correct.

== Reference areas ==
* [[History of Galactic Empire]]
* [[Original release history]]
* [[Official classic documentation]]
* [[Source code]]
* [[Classic bug database]]
* [[Configuring Galactic Empire]]

== See also ==
* [[Original release history]]
* [[Versions of Galactic Empire]]
* [[Classic bug database]]

{{GE navigation}}
[[Category:Versions]]

Glossary

2026-10-18T17:53:26Z

CodexBot: Add Btrieve to the glossary

This glossary defines common player terms and implementation terms used throughout the ''Galactic Empire'' wiki. A linked term leads to a fuller explanation; features specific to ge-next or ge-arena are identified where that distinction matters. GE often uses one word in ordinary messages and a different name for the underlying field or routine.

{| class="wikitable sortable"
! Term !! Meaning
|-
| [[Rotation and headings|Absolute heading]]|| Direction measured clockwise from galactic north, independent of the ship's current orientation.
|-
| [[Ship upgrades#Acceleration boosters|Acceleration boosters]]|| ge-next ship upgrade that doubles a ship's acceleration without raising its rated cruising speed.
|-
| [[Ship upgrades#Armor plating|Armor plating]]|| ge-next ship upgrade that reduces applicable incoming damage after class durability is applied.
|-
| [[Bearing]]|| Signed direction to an object relative to the observer's heading: positive to starboard, negative to port.
|-
| [[Btrieve]]|| Indexed record storage used for GE's persistent players, ships, planets, and mail; its keys also determine lookup and roster order.
|-
| [[Ship inventory#Cargo capacity|Cargo weight]]|| Total weight of a ship's carried items, used when checking available cargo capacity.
|-
| [[Cash]]|| A player's spendable currency; distinct from a planet's operating cash and tax bank.
|-
| [[Centock]]|| Traditional approximate short game interval; up to six seconds.
|-
| [[Cloaking]]|| Ship concealment system that affects detection and some combat interactions.
|-
| [[Combat#Damage and the combat timer|Combat timer]]|| Hostility delay that temporarily prevents an ordinary exit and can affect maintenance; tracked by <code>cantexit</code>.
|-
| [[Cybertrons|Cyber-Base]]|| Powerful stationary Cybertron class; an NPC ship rather than an owned planet.
|-
| [[Cybertrons|Cybertron]]|| Automated hostile ship type with its own classes and behavior.
|-
| [[Maintenance#Passive damage control|Damage control]]|| Ship capability affecting repair information and recovery from system damage.
|-
| [[DAMF]]|| Ship-class damage factor used in several damage calculations.
|-
| [[Decoys|Decoy]]|| Deployable countermeasure intended to distract or absorb incoming guided weapons.
|-
| [[Droids|Droid]]|| Automated ship category other than Cybertrons. ("Droid" is the term used in the source code, not displayed to a player.)
|-
| [[Enforcer Planet]]|| Galactic Command planet responsible for neutral-zone warnings and punishment.
|-
| [[Ship upgrades#Enhanced damage control|Enhanced damage control]]|| ge-next ship upgrade that increases passive repair speed and adds repair-time estimates to reports.
|-
| [[Ship upgrades#Enhanced lock|Enhanced lock]]|| ge-next ship upgrade that reports selected actions of a ship held under an active scanner lock.
|-
| [[Ship upgrades#Enhanced scanners|Enhanced scanners]]|| ge-next ship upgrade that adds additional information to eligible scans.
|-
| [[Droids#Factions and distress in ge-next|Faction]]|| Ship-class allegiance used in automated-ship hostility and friendly-fire rules (ge-next only).
|-
| [[Attacking planets#Fighter assault|Fighter]]|| Planetary defense item that can also be used in fighter attacks by eligible ships.
|-
| [[Combat#Kill credit, scoring, and salvage|Flotsam]]|| Cargo recovered after a ship is destroyed; not everything aboard the wreck can be collected.
|-
| [[Flux]]|| Energy in a ship's active neutron flux pile, consumed by propulsion and ship systems.
|-
| [[Flux pod]]|| Carried item that can replenish the active flux pile.
|-
| [[Planetary production|Food]]|| Planetary supply consumed by troops (and men in ge-next).
|-
| [[Rotation and headings|Galactic heading]]|| Absolute compass direction: 0 north, 90 east, 180 south, 270 west.
|-
| [[Galactic perimeter]]|| Outer boundary that wraps a ship or repels and damages it, according to <code>UNIVWRAP</code>.
|-
| [[Gold]]|| Cargo commodity used in trade and planetary economy; the objective in ge-arena Hoard.
|-
| [[Bearing#A scanned ship's heading|Heading]]|| In a ship scan, the target's orientation relative to the line back toward the observer: about 0 means facing the observer; about 180 means facing away. Not an absolute galactic heading.
|-
| [[Hyper-phasers|Hyper-phaser]]|| Ship phaser used while traveling in hyperspace that only hits other ships in hyperspace.
|-
| [[Impulse travel|Impulse]]|| Travel below warp 1.00, including the displayed 0.00–0.99 speed range.
|-
| [[Ion cannons|Ion cannon]]|| Planetary defensive weapon installed and fired from a planet.
|-
| [[Jamming|Jammer]]|| Carried electronic-warfare item that interferes with enemy scans and targeting.
|-
| [[Jettison command|Jettison]]|| Discard carried items from a ship, usually to free cargo space; the discarded goods are not transferred to a planet.
|-
| [[Kill credit#When credit is decided|Lastfired]]|| Ship state recording the most recent qualifying attacker for possible kill credit; it does not necessarily identify the hit that first caused fatal damage.
|-
| [[Locks|Lock]]|| Tracked live target used by scans and guided weapons.
|-
| [[Maintenance]]|| Repair service and process for a ship in stationary orbit, subject to combat restrictions.
|-
| [[Planetary production|Men]]|| Colonist population that can reproduce, produce goods, and contribute to taxes and scoring.
|-
| [[Mines|Mine]]|| Deployed explosive that remains at a location until its timer expires or it detonates.
|-
| [[Missiles|Missile]]|| Guided projectile weapon used in hyperspace.
|-
| [[Nebulas|Nebula]]|| A sector type that reduces visibility; added in ge-next.
|-
| [[Neutral zone]]|| Sector <code>0 0</code>, normally subject to Enforcer Planet weapon restrictions.
|-
| [[Orbit]]|| Stationary position around a planet required for several planetary interactions.
|-
| [[Warp travel#Overspeed|Overspeed]]|| Travel above a ship class's rated cruising warp, with risks and penalties that differ between classic and ge-next.
|-
| [[Distance unit|Parsec]]|| Classic GE's displayed distance unit.
|-
| [[Phasers|Phaser]]|| Rechargeable directed-energy ship weapon.
|-
| [[Phasers#Firing arc and spread|Phaser spread]]|| Width of a standard phaser's firing arc; spreading the beam farther weakens a hit.
|-
| [[Planetary production#Cash spent and funded bonus|Planetary bank]]|| Cash held by a planet for its own production and trade, separate from the owner's personal cash and the tax bank.
|-
| [[Planetary update cycle|Production pass]]|| One scheduled application of <code>multiply()</code> to a planet; ge-next can replay missed passes after downtime.
|-
| [[Ship upgrades#Reinforced neutron core|Reinforced neutron core]]|| ge-next ship upgrade that reduces the warp engine damage accumulated during overspeed travel.
|-
| [[Report command|Report]]|| Command family that displays a ship's navigation, systems, cargo, and other status information.
|-
| [[Ge-arena#Playing and resupplying|Respawn]]|| Return to play with a new match-local ship after destruction in ge-arena; not part of persistent classic GE or ge-next.
|-
| [[Roster command|Roster]]|| Player ranking display: based on accumulated score in persistent GE, and on recorded match wins in ge-arena.
|-
| [[Scan command|Scan]]|| Command family used to discover objects and inspect ships, sectors, planets, and ranges.
|-
| [[Scantab#How letters are used|Scan letter]]|| Temporary letter identifying a visible ship on a player's scanner display; not the ship's permanent number or active slot.
|-
| [[Ship upgrades#Scan range boost|Scan range boost]]|| ge-next ship upgrade that doubles a ship's effective scanner range without bypassing concealment rules.
|-
| [[Scan command#Scanner range and the scantab|Scanner range]]|| Effective detection reach of a ship's scanners; distinct from the scale chosen for a particular scan display.
|-
| [[Scantab]]|| Each player's temporary mapping from scan letters to current ship slots.
|-
| [[Scoring and rosters|Score]]|| Persistent points accumulated through combat, planets, and other configured scoring events.
|-
| [[Sector]]|| 10,000-by-10,000-[[Distance unit|distance-unit]] square identified by signed galactic X/Y coordinates.
|-
| [[Self-destruct]]|| Deliberate destruction of one's own ship after a countdown, producing a blast that can damage nearby ships.
|-
| [[Shields|Shield]]|| Defensive ship system that absorbs or reduces suitable incoming hits.
|-
| [[Ship class configuration|Ship class]]|| Configured ship type defining limits, movement, systems, and other class properties.
|-
| [[Ship number]]|| Owner-scoped identifier of a persistent ship record; not its active slot or list position.
|-
| [[Ship slot]]|| Reusable in-memory position holding one active player or automated ship.
|-
| [[Ship upgrades|Ship upgrade]]|| Optional improvement installed on an individual ship in ge-next; classic GE has no upgrade system.
|-
| [[Spies]]|| Agents carried by ships and deployed to gather planetary intelligence; spies stocked on a planet provide counterespionage.
|-
| [[Ge-arena#Staging and ship selection|Staging]]|| ge-arena's pre-match minute for choosing a ship and preparing in sector 0 0 before combat begins.
|-
| [[Distance unit|Subsector]]|| ge-next's displayed distance unit.
|-
| [[Tahanian Station]]|| Galactic Command station in sector 0 0 for colonists, troops, and food; ge-arena lobby setting.
|-
| [[Taxes|Tax]]|| Revenue collected from an owned planet's population into a separate tax balance.
|-
| [[Taxes#Revenue and collection|Tax bank]]|| Taxes accumulated on an owned planet for later collection by its owner, separate from its operating cash.
|-
| [[Teams|Team]]|| Player association with shared team state and communication in persistent GE play.
|-
| [[Torpedoes|Torpedo]]|| Guided projectile weapon used at impulse speeds.
|-
| [[Ship upgrades#Transponder control|Transponder control]]|| ge-next ship upgrade that adjusts how many Cybertrons may pursue the ship at once.
|-
| [[Attacking planets#Troop assault|Troops]]|| Soldiers defending a planet against invasion and revolt; also carried for troop attacks.
|-
| [[Data structures|User record]]|| Persistent player data, including settings, cash, score, and ownership counters.
|-
| [[Warp travel|Warp]]|| Hyperspace travel at displayed speed 1.00 or higher.
|-
| [[Planet administration#3. Set work assignments and trade policy|Work allocation]]|| Percentage of a planet's workforce assigned to each production category.
|-
| [[Wormholes|Wormhole]]|| Paired feature that moves a ship between distant sectors.
|-
| [[Zippers|Zipper]]|| Carried device that triggers nearby mines to detonate on the next mine update; it does not move the ship.
|-
| [[Zygor]]|| Galactic Command's principal planet in sector <code>0 0</code>.
|}

See [[Coordinate system]] for sector coordinates and bearings, [[Game timing]] for the different meanings of a "tick," and [[Data structures]] for the records behind several implementation terms.

{{GE navigation}}
[[Category:Game reference]]

Btrieve

2026-10-18T17:53:22Z

CodexBot: Add concise Btrieve reference for GE records and keys

'''Btrieve''' is the indexed record-storage system used by ''Galactic Empire'' and MajorBBS. GE saves players, ships, planets, and mail as records in separate files. Unlike a table queried with SQL, a Btrieve file is accessed through operations such as finding a record by a '''key''' or stepping to the next or previous record in key order.

The same file can have several keys. For example, GE can find a player by user ID, while the user database's score key lets [[Roster command|<code>ROSTER</code>]] walk players in score order. The game does not need to load every player and sort the list itself. When a stored score changes, the database updates that key's ordering. This is why a key's field offset and signedness matter: they affect lookup and order, not just how bytes are saved. See [[Scoring and rosters]] and [[Data structures]] for GE's specific records and keys.

GE's <code>.DAT</code> files are therefore not plain text, and the separate team file is an exception: it is a text table, not Btrieve. On 32-bit systems, the Btrieve call interface is known as <code>WBTRV32</code>. [[MBBSEmu]] uses the [https://github.com/mbbsemu/wbtrv32 open-source WBTRV32 replacement], which preserves the Btrieve-style calls while storing the live data in SQLite <code>.db</code> files. See [[Database files]] for filenames, backups, and resets.

== See also ==
* [[Database files]]
* [[Data structures]]
* [[Roster command]]
* [[MBBSEmu]]

{{GE navigation}}
[[Category:Development]]
[[Category:Sysop documentation]]

Data command

2026-10-18T04:35:31Z

CodexBot: Restore original FRONTEND.TXT placement after interrupted edit

The '''DATA''' command has two substantially different implementations. In classic ''Galactic Empire'', it is a documented interface for terminal programs, used by frontends such as [[GECP]], but it also exposes a considerable amount of raw internal state and relies on a hardcoded access word. In ge-next, it is a configurable, session-enabled frontend protocol whose output is designed to follow the same information restrictions as ordinary play.

== Classic implementation ==

The classic command is not listed in normal in-game help. [[GETERM.DOC]] documents <code>DATA SCAN</code> and <code>DATA REPORT</code> for terminal-program authors, and [[GEINST.DOC]] also describes them as commands intended for graphical or other alternative displays. Classic 3.2e additionally implements <code>DATA SECTOR</code>, which is not covered by <code>GETERM.DOC</code>. Its syntax is:

<syntaxhighlight lang="text">
DATA qazwsx REPORT
DATA qazwsx SCAN
DATA qazwsx SECTOR
</syntaxhighlight>

The middle word is hardcoded in the game. <code>GETERM.DOC</code> calls it the terminal-program password, intended to keep everyday users from using these commands. Because that same word is published in the documentation and source, it is not meaningful authentication. A client must repeat it with every DATA request; there is no session-level enable state.

=== REPORT ===

<code>DATA qazwsx REPORT</code> emits user and ship structures as records named <code>UD1</code>, <code>UD2</code>, and <code>SD1</code> through <code>SD7</code>. Some fields duplicate information available through ordinary reports, including the user ID, score, cash, population, ship name, inventory, position, energy, installed equipment, and registered kills.

Other fields expose implementation details that are not normally available to the player:

{| class="wikitable"
! Exposed value
! Why it is normally hidden
|-
| Numeric ship-class index
| Normal reports identify the class by name rather than exposing its table index.
|-
| Exact numeric hull damage
| <code>REPORT SYSTEMS</code> describes damage in words instead of displaying the internal damage value.
|-
| Raw speed value
| The normal navigation report converts internal speed units into the displayed impulse or warp value.
|-
| Raw phaser state
| The command exposes the internal phaser charge or damage counter rather than only the player-facing operative/inoperative state.
|-
| <code>lastfired</code>
| This is the internal user-channel attribution used when deciding who receives credit for a destruction. It is not a player-visible ship statistic.
|-
| Raw shield state and charge
| Ordinary reports present the shield state and, while shields are raised, a percentage. DATA exposes the underlying state value and charge.
|-
| Raw cloak state
| This reveals cloak transition and damage-state values rather than only the visible cloak status.
|-
| Tactical and helm damage counters
| Normal reports say that these systems are damaged. They do not reveal the exact internal repair magnitude.
|-
| Training counter
| This is an internal state used by the training sequence, not gameplay information reported to the player.
|-
| Raw location code
| The <code>where</code> field encodes whether the ship is in space, at Zygor, or orbiting a numbered planet. Normal output describes the location instead.
|-
| Incoming weapon slots
| Every incoming torpedo and missile slot includes its raw source channel and remaining distance. Classic has no equivalent player-facing ordnance report.
|-
| Jammer state, hostile state, and combat-exit timer
| These are internal flags or countdowns. Their exact values are not shown during normal play.
|-
| Maintenance, hyper-phaser, and fire-control counters
| These expose internal repair or cooldown state. Classic does not even list damaged fire control in <code>REPORT SYSTEMS</code>.
|-
| Self-destruct and ship-status values
| The player can see a self-destruct countdown as it runs, but cannot ordinarily query its raw counter or the ship record's internal status code.
|}

The result is more than a machine-readable version of the visible reports. It is effectively a partial dump of the user and ship records, including values that can reveal combat state and implementation details to a player or automated client.

=== SCAN ===

<code>DATA qazwsx SCAN</code> updates the scanning table and emits the player's scan range, the player's own position, and one row for every visible ship contact. A contact row includes:

* its scan-table letter;
* exact galactic [[Sector|sector]] coordinates;
* exact local coordinates within the sector;
* distance, [[Bearing|bearing]], relative heading, and speed;
* its numeric class index and class name.

A normal range scan plots contacts and gives useful navigational information, but it does not reveal every contact's exact sector and local coordinates. Identifying a ship's class normally requires a ship scan, which can notify the target. Classic DATA SCAN therefore provides precise and sometimes otherwise unavailable information without that notification.

When the player's jammer field is active, classic DATA SCAN suppresses the contact rows and prints <code>** Jammed **</code>. It does use the normal scan-table construction, so it does not simply reveal every cloaked or out-of-range ship. However, it bypasses the command-level damaged-tactical-system check used by the ordinary [[Scan command|<code>SCAN</code>]] command, allowing the data scan to be requested when the player's tactical scanners are inoperative.

=== SECTOR ===

<code>DATA qazwsx SECTOR</code> loads the current sector and emits its exact coordinates followed by every planetary object, including each object's number, exact local coordinates, and raw object type.

Unlike the ordinary sector scan, this path does not apply the tactical-system or jamming checks. A player can therefore use it to recover precise sector layout and object-type information while jammed or while tactical scanners are damaged. This is one of the clearest cases where the classic DATA interface leaks information that normal gameplay intentionally withholds.

=== Protocol limitations ===

The classic frontend interface has several limitations by modern protocol standards:

* There is no configurable frontend identifier or pairing handshake.
* Access relies on a word embedded in the source code.
* REPORT records resemble delimited data, while SCAN and SECTOR use different, more human-oriented layouts.
* There are no explicit end-of-section records.
* User-entered text is not escaped, so delimiters in names can make parsing ambiguous.
* Many fields are raw structure values rather than player-visible concepts; even the fields described in <code>GETERM.DOC</code> depend on classic's internal representation.

== ge-next implementation ==

ge-next replaces the classic DATA interface with a frontend protocol that avoids exposing most raw internal state. The command must first be made available through the <code>FRONTEND</code> setting in <code>MPOGEMSG.MSG</code>:

{| class="wikitable"
! FRONTEND value
! Behavior
|-
| <code>OFF</code>
| DATA behaves as an invalid command.
|-
| <code>ALL</code>
| DATA sections are available immediately, although message metadata remains disabled until separately requested.
|-
| Any other string
| The session must send <code>DATA ON string</code>, with an exact case-sensitive match, before using the other DATA commands.
|}

A successful pairing returns an <code>ON:</code> record containing the frontend identifier, project name, version, and architecture. This is an application-level pairing mechanism, not strong authentication, but it allows each game installation to be associated with an intended frontend instead of relying on a universal source-visible password.

=== Sections ===

The ge-next interface divides information into independently requested sections:

{| class="wikitable"
! Command
! General contents
|-
| <code>DATA USER</code>
| Player identity, finances, score, population, and related user information.
|-
| <code>DATA SHIP</code>
| Ship identity, class, registered kills, communications frequency, and ship number.
|-
| <code>DATA CAP</code>
| Current ship capabilities.
|-
| <code>DATA INV</code>
| Inventory, cargo weight, and cargo capacity.
|-
| <code>DATA UPG</code>
| Installed upgrades and transponder state.
|-
| <code>DATA NAV</code>
| Navigation information corresponding to <code>REPORT NAVIGATION</code>.
|-
| <code>DATA ORD</code>
| Incoming ordnance information corresponding to <code>REPORT ORDNANCE</code>.
|-
| <code>DATA SYS</code>
| System condition corresponding to <code>REPORT SYSTEMS</code>.
|-
| <code>DATA MSG</code>
| Message-filter settings.
|-
| <code>DATA SCAN</code>
| Parseable range-scan information.
|-
| <code>DATA SHIPSCAN target</code>
| Parseable ship-scan information, subject to the normal ship-scan rules and notification policy.
|-
| <code>DATA SECTOR</code>
| Parseable sector-scan information.
|}

Each data record ends in <code>*</code>, and a completed section ends with <code>STOP:section*</code>. Text fields percent-encode percent signs, commas, asterisks, carriage returns, and line feeds so that user-entered names cannot corrupt the record structure. The [https://github.com/manicpop/ge-next/blob/main/mpogemp/FRONTEND.TXT FRONTEND.TXT] file, included with ge-next, is the authoritative field-by-field protocol reference.

=== Information visibility ===

The ge-next routines were written to return the information represented by the corresponding player-facing commands rather than exposing raw structures. Important examples include:

* <code>DATA SYS</code> returns descriptive system states and follows the Enhanced Damage Control rules for whether a repair time is visible. It does not expose every raw damage counter.
* <code>DATA SCAN</code> and <code>DATA SECTOR</code> apply the relevant range, cloak, nebula, jamming, and damaged-scanner behavior.
* <code>DATA SHIPSCAN</code> uses the normal ship-scan behavior. The target receives the same scan notification it would receive from <code>SCAN SHIP</code>, unless the normal locked-target exception applies.
* <code>DATA ORD</code> resolves weapon sources into player-facing descriptions instead of exposing reusable MajorBBS channel numbers as identities.
* Message metadata is separately enabled with <code>DATA METADATA ON</code>; enabling DATA alone does not turn it on.

There are a small number of deliberate exceptions where a frontend needs information that the terminal interface does not print directly:

* <code>DATA SHIP</code> includes the persistent [[Ship number|ship number]] so a frontend can retain per-ship settings.
* Mine contacts include exact distance and bearing so a frontend can plot them on a map. The terminal scan plots mines graphically but does not list those two numbers.

These are explicit protocol decisions rather than the broad, incidental disclosure of internal fields found in the classic command.

== ge-arena ==

ge-arena uses the same access, framing, escaping, scan restrictions, and metadata system. It retains applicable ge-next sections and adds arena-specific records such as match state and player standings. Fields that have different meanings in an arena mode are documented separately in the ge-arena section of <code>FRONTEND.TXT</code>.

== Summary of differences ==

{| class="wikitable"
! Area
! Classic GE
! ge-next
|-
| Access
| Hardcoded word repeated with every request
| Configurable per-installation setting and per-session pairing
|-
| Purpose
| Documented terminal-program interface used by frontends, including GECP; exposes raw state
| Documented frontend protocol
|-
| Information policy
| Exposes numerous hidden counters, channel numbers, and structure fields
| Generally mirrors information available through normal player commands
|-
| Scan restrictions
| Some DATA paths bypass damaged-scanner, notification, or jamming behavior
| Reuses normal visibility and notification rules
|-
| Framing
| Inconsistent layouts with no common terminator
| Named records and <code>STOP:</code> terminators
|-
| User text
| Not escaped
| Percent-encoded where required
|-
| Message tagging
| None
| Optional, separately enabled metadata records
|}

== See also ==

* [[GETERM.DOC]]
* [[GEINST.DOC]]
* [[GECP]]
* [[Set command]]
* [[Scan command]]

{{GE navigation}}
[[Category:Commands]]
[[Category:ge-next]]

GECP

2026-10-18T04:32:14Z

CodexBot: Link GECP to the classic DATA interface

'''Galactic Empire Control Panel''' ('''GECP''') is a graphical player frontend by Dave Walton for ''classic Galactic Empire''. It provides a visual interface for navigation, combat, and mapping rather than replacing the game server.

'''Compatibility:''' GECP works with classic GE, not ge-next or ge-arena. Its classic protocol assumptions should not be taken as support for the later games.

== Versions and features ==
The [https://www.digger.net/projects/gecp/ project page] describes a Java-based version 2, intended to run wherever Java 8 is available, and an earlier DOS version that can also be run under DOSBox. The frontend offers a map, hotkeys and macros, and controls for common ship actions such as navigation and combat. Consult the project page for downloads and installation instructions.

GECP is a client-side aid that uses classic GE's [[Data command|DATA interface]] to obtain machine-readable ship and scan information; the BBS still runs the game. The original [[GETERM.DOC]] documents that interface for terminal-program authors. For a ge-next frontend, see [[GE3D]] and the redesigned [[Data command|DATA protocol]].

== See also ==
* [[Utilities]]
* [[Creating a keymap]]

{{GE navigation}}
[[Category:Playing Galactic Empire]]
[[Category:Community]]

New command

2026-10-18T03:56:33Z

CodexBot: Consolidate buying and selecting ships into focused pages

The '''NEW''' command purchases ships and major ship equipment at Zygor. In ge-next, it also purchases permanent ship upgrades.

== Syntax ==

<syntaxhighlight lang="text">
NEW SHIP class
NEW SHIELD mark
NEW PHASER mark
</syntaxhighlight>

ge-next adds:

<syntaxhighlight lang="text">
NEW UPGRADE
NEW UPGRADE number
NEW UPGRADE 7 [HIGH | NORMAL | LOW]
</syntaxhighlight>

The ship must be orbiting Zygor, planet 1 in sector 0 0. The purchase also requires enough cash and, where applicable, an eligible ship class. In ge-next, players whose standing with Galactic Command is too poor cannot trade at Zygor until the penalty expires.

[[Help command|<code>HELP CLASS</code>]] lists the available ship classes and their class numbers. <code>HELP NEWPRICE</code> lists shield and phaser prices, but this is stored as text in the help file; it does not display configured values like HELP CLASS does. Server configuration is therefore authoritative, because prices and limits can be changed by the sysop without changing the help file to match. In fact, in classic GE, Mark-19 shields are listed at 250 million cash, but are actually set at 200 million, because the game's internal limits cap this value at 201.2 million. ge-next lowered the prices of both Mark-19 systems and updated HELP CLASS to match instead of changing the cap.

== Purchasing a ship ==

<code>NEW SHIP class</code> purchases an additional ship of the selected class. It does not transform the current ship, trade it in, or immediately transfer command to the new vessel. The new ship becomes another persistent ship in the player's fleet.

A player who enters the game without a ship receives the configured starter class free of charge. That allocation is separate from a <code>NEW SHIP</code> purchase.

The full class price is deducted from the player's cash. A newly purchased ship starts as a fresh vessel with:

* Mark-1 shields and Mark-1 phasers (if this class has them<ref group="lower-alpha">Technically, these values are set to 1 regardless; the check for whether a class has those systems is separate.</ref>);
* three flux pods;
* no other cargo;
* no damage;
* full energy;
* shields uncharged and down;
* a random position in sector 0 0, safely separated from its planets; and
* a new per-user [[Ship number|ship number]] (used to sort the ship list, not shown to player).

The purchase fails if the player has reached the configured maximum number of ships. Classic Galactic Empire defaults to a maximum of 8 ships per player; ge-next defaults to 45.

== Shields and phasers ==

<code>NEW SHIELD mark</code> and <code>NEW PHASER mark</code> replace the corresponding system on the current ship. Marks range from 1 through 19, but the selected Mark cannot exceed the maximum supported by the ship class. The purchase does not repair hull damage or unrelated systems. In classic GE and ge-next through 0.3.2, the replacement retained the old system's charge and damage state; downgrading shields could even leave the new Mark with more charge than its normal maximum. As of ge-next 0.3.3, a purchased shield starts down with zero charge, while a purchased phaser starts fully charged. This also clears damage to the system being replaced. See [[Classic bug: Replacement systems retain old charge]].

The old system is traded in rather than discarded. Its trade-in credit is:

<syntaxhighlight lang="text">
old list price - (old list price / 3)
</syntaxhighlight>

Integer arithmetic is used, so this is approximately two-thirds of the old system's list price. The credit is subtracted from the new system's price. If the player still owes money and the difference is less than 1,000 credits, the game charges a minimum installation fee of 1,000 credits.

A player may also install a lower Mark. When the trade-in credit exceeds the new system's price, the excess is refunded after a fee equal to 2% of the trade-in credit. This makes deliberate downgrading possible, but prevents the player from recovering the entire credited value as cash.

Classic Galactic Empire permits a player to purchase the same Mark already installed and still applies the replacement calculation. ge-next rejects a same-Mark purchase because no equipment change would occur. ge-next also protects cash additions from overflowing the player's cash field.

== Upgrades in ge-next ==

<code>NEW UPGRADE</code> without a number lists the upgrades available to the current ship class, their prices, and whether they are already installed. <code>NEW UPGRADE number</code> purchases an eligible upgrade.

Upgrade cost is based on the configured base price and the current ship class's damage factor (DAMF). Consequently, installing the same upgrade can cost more on a larger or more durable class. An upgrade cannot be purchased if the class is ineligible or that ship already has it.

The available upgrades are:

# '''[[Ship upgrades#Enhanced scanners|Enhanced scanners]]''' provide additional scan information and reduce the effects of jamming.
# '''[[Ship upgrades#Armor plating|Armor plating]]''' increases the ship's durability.
# '''[[Ship upgrades#Acceleration boosters|Acceleration boosters]]''' improve acceleration.
# '''[[Ship upgrades#Scan range boost|Scan range boost]]''' increases scanner range.
# '''[[Ship upgrades#Enhanced lock|Enhanced lock]]''' provides additional sensor information about a locked target's activity.
# '''[[Ship upgrades#Enhanced damage control|Enhanced damage control]]''' speeds repairs and provides repair-time information.
# '''[[Ship upgrades#Transponder control|Transponder control]]''' changes how likely Cybertrons are to pursue the ship.
# '''[[Ship upgrades#Reinforced neutron core|Reinforced neutron core]]''' allows the ship to sustain overspeed for longer.

Transponder control has three settings. It can be installed and configured in one command with <code>NEW UPGRADE 7 HIGH</code>, <code>NORMAL</code>, or <code>LOW</code>. Once installed, the setting can be changed at Zygor without another purchase charge. Buying it without a setting initially selects normal operation.

Upgrades belong to the individual ship. They cannot be transferred to another ship, returned for cash, or recovered after the ship is destroyed. Installed upgrades are listed by [[Report command|<code>REPORT UPGRADE</code>]].

== Classic and ge-next ==

{| class="wikitable"
! Behavior
! Classic Galactic Empire
! ge-next
|-
| Purchase additional persistent ships
| Yes
| Yes
|-
| Replace shields and phasers
| Yes
| Yes
|-
| Equipment trade-in and downgrade refunds
| Yes
| Yes
|-
| Re-purchase the currently installed Mark
| Allowed and charged
| Rejected
|-
| Permanent ship upgrades
| No
| Yes
|-
| Galactic Command standing can block Zygor trade
| No
| Yes
|}

== Notes ==

<references group="lower-alpha" />

== See also ==
* [[Ship upgrades]] for upgrade effects and eligibility
* [[Item and equipment configuration#Shields and phasers|Shield and phaser price options]]

* Classic help: [[MBMGEHLP.MSG#HELP_NEW|NEW]], [[MBMGEHLP.MSG#HELP_NEWPRICE|NEWPRICE]]
* [[Help command]]
* [[Report command]]
* [[Ships]]

{{GE navigation}}
[[Category:Commands]]
[[Category:Ships]]

Ship number

2026-10-18T03:56:30Z

CodexBot: Consolidate buying and selecting ships into focused pages

A '''ship number''' is the identifier assigned to one of a player's persistent ships. It belongs to the player's ship record, not to the temporary slot currently used to run that ship in memory.

== Assignment ==
A user record keeps <code>topshipno</code>, the highest number assigned to that player so far. Creating another ship increments that counter and places the new number in the ship record's <code>shipno</code> field. The database identifies a persistent ship by its owner together with this ship number. The number is therefore scoped to that user's ships: different users can each have a ship number 1.

== Fleet selection ==
The ship-selection routine lists a player's stored ships in ship-number order. It gives the visible entries consecutive menu choices and keeps the corresponding <code>shipno</code> for loading the selected record. Thus a menu choice is not necessarily the ship's persistent number. If ships numbered 1 and 2 are gone but numbers 3 and 5 remain, those surviving ships can appear as choices 1 and 2; selecting choice 2 loads ship number 5. A newly created ship receives a new number rather than filling a gap, keeping the ship selection list in the order of when the ships were first acquired. Classic lists all owned ships at once; ge-next paginates the menu, restarting the displayed choices at 1 on each page. See [[Classic bug: Ship-selection output overflow]] for why pagination was needed.

== Not a ship slot ==
The [[Ship slot]] is a reusable in-memory position for a currently active user or NPC. A player may leave and re-enter while retaining the same persistent ship number but using a different live slot. Scan letters are another distinct identifier: [[Scantab]] maps a player's temporary letters to current slots.

ge-arena does not retain ordinary persistent ship records between matches, so its temporary arena ships should not be interpreted as a user's numbered fleet.

== See also ==
* [[New command]]
* [[Ship slot]]
* [[Scantab]]

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

Cash

2026-10-18T03:56:26Z

CodexBot: Consolidate buying and selecting ships into focused pages

'''Cash''' is the player's spendable balance for [[Buy command|cargo]], [[New command|ships]], phasers, shields, upgrades, and services such as [[Maintenance command|maintenance]]. It belongs to the player account, not to a particular ship, and occupies no cargo space. A planet's operating cash and tax balance are separate; neither is automatically available to its owner.

== Earning and spending ==
Players can earn cash by [[Sell command|selling cargo]] at [[Zygor]], collecting [[Taxes|taxes]] from owned planets, and receiving applicable combat rewards. Purchases and services deduct from the player balance. When a player buys goods at an ordinary planet, the payment is added to that planet's bank; it is not paid directly into the owner's account. Owners can buy from their own planets, but they still pay from their personal cash. See [[Buy command]] and [[Economy and cargo]] for the relationship among the different balances.

[[Gold]] is a physical inventory item, not another name for cash. It takes cargo space and can be carried, sold, or produced on a planet. An owned planet can convert gold already in its stock to planetary cash during a production update; a player does not gain that cash directly.

== Name and display ==
Classic GE calls cash '''C's''' in some messages, such as purchases, sales, and equipment installation. ge-next does not assign the currency a name: those messages show the numeric amount in gold-colored text without a unit. The color does not mean the player is carrying [[Gold|gold cargo]]. Reports also label the balance as cash.

== Storage and overflow ==
Classic stores player cash, planetary cash, and planetary tax in 32-bit unsigned-long fields. Their storage range is 0 through 4,294,967,295. Some classic reports format those values as signed longs: a valid balance of 2,147,483,648 can appear as -2,147,483,648 even though the stored cash has not wrapped. Some paths then interpret that negative-looking value as invalid and clear it.

The actual unsigned wrap occurs when an unchecked addition exceeds 4,294,967,295: adding one at the maximum stores zero. Large transactions have another hazard because quantity multiplied by price can overflow before the resulting balance is updated. These problems can affect purchases, sales, tax collection, rewards, and administrator grants, as well as planetary production and stock counters. [[Classic bug: Cash and counter wraparound]] explains the arithmetic, symptoms, and specific correction in ge-next.

ge-next checks the relevant arithmetic before changing balances, rejects or caps an operation when its result cannot fit, and displays unsigned values without interpreting the upper half of their range as negative. Its cash balances retain the same 32-bit storage limit.

== See also ==
* [[Economy and cargo]]
* [[Gold]] and [[Taxes]]
* [[Buy command]], [[Buy command]], and [[Sell command]]
* [[Classic bug: Cash and counter wraparound]]

{{GE navigation}}
[[Category:Economy]]

Classic player ship classes

2026-10-18T03:56:23Z

CodexBot: Consolidate buying and selecting ships into focused pages

These are the stock player classes in classic GE 3.2e. A new player receives an Interceptor; later ships can be purchased at [[Zygor]]. Prices, limits, and capabilities come from the distributed [[MBMGESHP.MSG]] source. A sysop can change them. See [[Ships]] for the role of a ship in play and [[Ship class configuration]] for editing the definitions.

== At a glance ==
'''Shield / phaser''' gives the highest Mark the class can install, not the equipment currently installed. '''Warp''' is rated cruising speed; '''scan''' is range in displayed distance units. Price is in cash (C's), and kill points are the class's value to an attacker.
{| class="wikitable"
! # !! Class !! Shield / phaser max !! Warp !! Cargo (tons) !! Scan !! Price (C's) !! Kill pts
|-
| 1 || Interceptor || 10 / 10 || 10 || 1,000 || 100,000 || 65,000 || 750
|-
| 2 || Stealth Fighter || 15 / 15 || 20 || 2,000 || 200,000 || 500,000 || 1,500
|-
| 3 || Heavy Freighter || 5 / 5 || 8 || 60,000 || 50,000 || 40,000 || 500
|-
| 4 || Destroyer || 15 / 15 || 25 || 5,000 || 100,000 || 600,000 || 2,000
|-
| 5 || Star Cruiser || 15 / 15 || 25 || 3,000 || 200,000 || 700,000 || 5,000
|-
| 6 || Battle Cruiser || 19 / 19 || 30 || 6,000 || 250,000 || 800,000 || 5,000
|-
| 7 || Frigate || 12 / 12 || 30 || 12,000 || 250,000 || 1,250,000 || 5,000
|-
| 8 || Dreadnought || 19 / 19 || 50 || 40,000 || 500,000 || 2,000,000 || 10,000
|-
| 9 || Freight Barge || 6 / 3 || 15 || 200,000 || 200,000 || 3,000,000 || 5,000
|}

== Equipment and durability ==
Classic torpedo and missile entries are ''capability flags'', not launcher counts or starting ammunition. '''Other systems''' lists permitted systems and planetary attack ability. '''Acceleration''' is the class setting; '''DAMF''' describes resilience for applicable damage, with 100 as the baseline. The final column is the class's unprovoked-Cybertron-fire flag followed by its configured simultaneous pursuer limit. Cybertrons will fire unprovoked on classes set to "Yes," the pursuer value is how many Cybertrons will be dispatched to pursue that ship. Although no classes are configure this way by default, a class set to "No" but with a positive pursuer limit will attract Cybertrons, but the Cybertrons will not fire unless provoked.
{| class="wikitable"
! Class !! Torpedo / missile !! Other systems !! Acceleration !! DAMF !! Cyb fire / pursuers
|-
| Interceptor || Yes / No || mines, decoys, jammers, zippers || 5,000 || 90 || Yes / 1
|-
| Stealth Fighter || Yes / Yes || mines, decoys, jammers, zippers, planetary attack, cloak || 5,000 || 90 || Yes / 2
|-
| Heavy Freighter || Yes / No || mines, decoys, jammers, planetary attack || 3,000 || 200 || No / 0
|-
| Destroyer || Yes / Yes || mines, decoys, jammers, zippers, planetary attack || 5,000 || 90 || Yes / 2
|-
| Star Cruiser || Yes / Yes || mines, decoys, jammers, zippers, planetary attack, cloak || 10,000 || 100 || Yes / 2
|-
| Battle Cruiser || Yes / Yes || mines, decoys, jammers, zippers, planetary attack, cloak || 3,000 || 125 || Yes / 2
|-
| Frigate || Yes / Yes || mines, decoys, jammers, zippers, planetary attack || 10,000 || 125 || Yes / 2
|-
| Dreadnought || Yes / Yes || mines, decoys, jammers, zippers, planetary attack, cloak || 15,000 || 125 || Yes / 2
|-
| Freight Barge || No / No || decoys, jammers, planetary attack || 1,000 || 200 || No / 0
|}

The source also defines class 41, the '''Sysopian Death Star''', intended for Sysop use rather than ordinary play. It cannot be bought through [[New command|<code>NEW SHIP</code>]]. To use it, a Sysop can run [[Sys command|<code>SYS CLASSLIST</code>]] to find its class number, then <code>SYS CLASS</code> followed by that number to change their current ship's class. With the default class table, the command is <code>SYS CLASS 41</code>. Its exceptional values, including Warp 255 and 100,000,000 tons of capacity, are not part of normal ship progression.

== Earlier player ships and class changes ==
The 3.2e lineup above was not the original one. M.B. Murdock's [[GEREADME.DOC|release notes]] record several changes to player ships:

* '''2.0a (April 1989):''' Version 2 introduced multiple ship types, described as ranging from the '''Light Freighter''' to the Dreadnought. The Light Freighter was the original free starting ship. See [[GEREADME.DOC#04/29/89_Release_2.0a|2.0a]] and [[GEREADME.DOC#05/12/89_Release_2.0e|2.0e]].
* '''2.0c–2.0g (May 1989):''' The Heavy Freighter gained the ability to [[Attack command|attack planets]] in 2.0c: previously freighters had the cargo space to carry an invasion force but could not launch it. Fighter weight was reduced, and ship carrying capacities were increased again in 2.0g. See [[GEREADME.DOC#05/07/89_Release_2.0c|2.0c]] and [[GEREADME.DOC#05/17/89_Release_2.0g|2.0g]].
* '''2.0e (May 1989):''' New players began receiving an '''Interceptor''' instead of a Light Freighter so they could fight Cybertrons from the outset. This was a change to the ''starting ship'', not proof that the Light Freighter was immediately renamed or removed: the [[GEREADME.DOC#06/15/89_Release_2.0i|2.0i notes]] still mention Light Freighters, Heavy Freighters, and Interceptors separately. The 2.0e notes also say all ships began with Mark-1 phasers and shields. See [[GEREADME.DOC#05/12/89_Release_2.0e|2.0e]].
* '''2.0h (May 1989):''' The release notes say [[Hyper-phasers]] were no longer identical across ship classes: Interceptors now had a harder time fighting larger ships. Phaser Marks already existed, but the notes do not specify how class and Mark affected hyper-phaser damage. See [[GEREADME.DOC#05/30/89_Release_2.0h|2.0h]].
* '''3.0i and 3.0o (1992–93):''' A Sysop-only '''Sysopian Death Star''' was added in 3.0i. The class table was substantially expanded in 3.0o, allowing sysops to define more classes and specify equipment eligibility and Cybertron targeting behavior per class. See [[GEREADME.DOC#10/11/92_Release_3.0i|3.0i]] and [[GEREADME.DOC#01/15/93_Release_3.0o|3.0o]].
* '''3.1b (July 1993):''' The '''Freight Barge''' was added to the standard table as a very large-capacity ship for supplying planetary invasions. Offensive weapon damage was also revised to account for ship size, including changes to phasers and hyper-phasers. See [[GEREADME.DOC#7/4/93_Release_3.1b|3.1b]].
* '''3.2c (December 1993):''' The Freight Barge was reduced in size and stripped of much of its offensive equipment after proving too effective as a fighting platform. The final 3.2e class still permits a Mark-3 phaser, but has no torpedo, missile, mine, or zipper capability; it retains its invasion role. The 3.2c release also introduced a separate [[DAMF]] value for each class, decoupling durability from cargo size. See [[GEREADME.DOC#12/14/93_Release_3.2c|3.2c]] and [[MBMGESHP.MSG]].

In the surviving 3.2e code, hyper-phaser damage is multiplied by the attacker's installed phaser Mark and divided by a factor based on the target class's tonnage; the attacker's class also limits which Marks it can install. The surviving release notes do not establish when this Mark-based calculation was introduced, or whether the 2.0h change already used class-dependent equipment limits rather than a separate class multiplier.

A surviving earlier ship configuration lists '''Light Freighter''' in class slot 2, whereas the distributed 3.2e table puts '''Stealth Fighter''' in that slot. Because that older file includes training-game material, it does not establish the exact stock lineup of a particular main-game release. The release notes do not say precisely when the Light Freighter disappeared from the standard selection or when the Stealth Fighter took its place. Ship tables were also customizable by sysops, so a class missing from the 3.2e default was not necessarily absent from every game.

== See also ==
* [[Ships]] and [[New command]]
* [[Classic NPC ship classes]]
* [[Ship class configuration]] and [[DAMF]]

{{GE navigation}}
[[Category:Ships]]

Ships

2026-10-18T03:56:20Z

CodexBot: Consolidate buying and selecting ships into focused pages

A ship is a player's way of moving through the galaxy. It carries supplies and weapons, scans nearby space, orbits planets, and can be damaged or destroyed. Ships are also part of the world around the player: Cybertrons and other automated vessels travel, fight, haul cargo, or defend territory.

== Choosing a ship ==
Each ship belongs to a '''class''', a design with its own strengths and limits. A fast scouting craft is useful for exploration; a freighter can carry far more cargo; a warship trades some flexibility for firepower and durability. No class is best at every job. A game's sysop can change the available classes, so the in-game [[Help command|<code>HELP CLASS</code>]] display is the best guide to that installation's choices.

A class sets limits, not the ship's complete present condition. It can say how powerful a shield or phaser the ship may install, how fast it normally travels, what it can launch, how much it can carry, and how far it can scan. The actual ship has its own equipment, supplies, damage, position, and combat record. A ship with a Mark-19 shield ''maximum'' does not necessarily have a Mark-19 shield installed.

== Ships in play ==
Players explore with [[Navigation and scanning|navigation and scanners]], fight with [[Combat|weapons]] and [[shields]], move supplies in a [[ship inventory]], and repair damage through [[Maintenance|maintenance]]. [[Report command|<code>REPORT NAV</code>]], <code>REPORT SYS</code>, <code>REPORT INV</code>, and other [[Report command|reports]] show the current state of the particular ship being flown. See [[System damage|system failures]] for how individual systems can be disabled.

A player may own multiple persistent ships and select which one to fly. A destroyed ship is lost, but the player and any other ships remain. Ships can be bought at [[Zygor]] when the player has the money and the class is offered. See [[New command]] for purchases and [[Ship number#Fleet selection|fleet selection]] for how stored ships appear on entry. ge-arena instead gives participants match-local ships: they choose from that mode's roster or receive its sole class automatically, and can respawn after being destroyed. It has no persistent player fleet.

== Other vessels ==
[[Cybertrons]] are automated opponents. [[Droids]] is the source-code term for other automated ships; it does not imply that every such vessel is harmless. Their behavior, faction relationships, and population rules depend on the version. An NPC has a ship class too, but it does not buy a vessel the way a player does. See [[Droids#Factions and distress in ge-next|faction rules]] and [[Ship slot#User, Cybertron, and Droid ranges|NPC slot allocation]].

== Stock class lists ==
* [[Classic player ship classes]] and [[Classic NPC ship classes]] give the shipped classic 3.2e rosters.
* [[ge-next player ship classes]] and [[ge-next NPC ship classes]] give the shipped ge-next rosters. Those pages also identify which class designs appear in the stock ge-arena modes.

These lists show defaults, not a guarantee about every live BBS. The same named class can have different specifications in classic and ge-next, and a sysop can change either table.

== How classes are defined ==
For readers who want the mechanics: class definitions live in a compiled [[Ship class configuration|ship-class table]]. A class number identifies a design; a [[ship number]] identifies an individual owned vessel, while a [[ship slot]] is its place in the game's active tables. Depending on the build, the class table also includes purchase value, kill points, [[DAMF|damage factor]], and settings used by automated ships. Those are configuration details rather than a complete description of a ship's role in play. See [[Ship class configuration]], [[Scoring and rosters]], and [[Data structures]] for more.

== See also ==
* [[Classic player ship classes]]
* [[ge-next player ship classes]]
* [[Classic NPC ship classes]]
* [[ge-next NPC ship classes]]
* [[Ship class configuration]]
* [[Ship slot]]

{{GE navigation}}
[[Category:Ships]]
[[Category:Game reference]]

Economy and cargo

2026-10-18T03:56:16Z

CodexBot: Consolidate buying and selecting ships into focused pages

'''Economy and cargo''' connects a player's cash, the goods carried by ships, and the stock and finances of planets. These are related but separate resources: transferring up an item is not the same as buying it, and cash earned by a colony does not automatically appear in its owner's account. Prices, item weights, and many production settings are configurable by the sysop; the figures on this wiki describe the distributed settings unless otherwise stated.

== Where value is kept ==
{| class="wikitable"
! Resource !! Where it is kept !! Principal use
|-
| [[Cash|Player cash]] || User account || Buys goods, ships, equipment, and services. It is not cargo and does not consume hold space.
|-
| [[Ship inventory|Ship cargo]] || Individual ship || Carries weapons, supplies, people, and [[Gold|gold]]. Each item occupies its configured weight and may be lost when that ship is destroyed.
|-
| Planetary stock || Individual [[Planets|planet]] || Holds goods that may be produced, reserved, sold to visitors, or transferred under the applicable access rules.
|-
| Planetary cash and tax || Individual planet || Trade receipts and converted gold fund the planetary bank; tax is a separate owner-accessible balance. Neither is automatically the player's cash.
|}

Gold is the bridge between physical cargo and money. A player can carry or sell it, and an owned planet converts gold already in its inventory into planetary cash during a production update. Gold produced on that same update normally waits until a later update for conversion. See [[Gold]], [[Cash]], and [[Taxes]].

== Cargo and capacity ==
Ships carry fourteen [[Items|item types]] whose configured weights count against the ship class's cargo capacity. Cargo is distinct from installed equipment: a ship can transport missiles without a launcher or carry fighters the ability to attack planets with them. For fractional weights, capacity checks, inventory reports, and how carried quantities change, see [[Ship inventory]]. [[Ship class configuration]] explains which equipment a class can use.

== Production and planetary wealth ==
A colony assigns its population's work among reproduction, food, gold, and other goods. Production depends on its environment, resources, population, cash, and the owner's choices. Its inventory and maximum stock are not unlimited. A positive planetary bank supports higher production and stock limits; high taxes can raise revenue but lower productivity and increase revolt risk. See [[Planetary production]], [[Colonizing planets]], and [[Taxes]].

A planet can gain cash when a ship buys its goods or when stored gold is converted during a production update. An owner can manage the planet's tax and trade settings through [[Planet administration]], but its cash and stock remain planetary resources until an allowed game action moves value elsewhere. Selling goods to visiting ships, mining gold, and collecting tax are different ways to build wealth, each with different labor, transport, and risk costs.

== Trade and transfers ==
Buying requires a valid orbit, available stock, the appropriate access or trade password, enough player cash, and enough cargo room. An ordinary owned planet can sell selected stock to a visitor; that purchase moves goods from the planet to the ship and pays money into the planetary bank. The owner can set sale prices and reserves. [[Zygor]] is the special neutral-zone market for buying supplies, purchasing ships and equipment, selling ship cargo, and requesting maintenance. Ships can [[Sell command|<code>SELL</code>]] cargo to Zygor, '''not''' to an arbitrary player-owned planet. See [[Planet administration]], [[Buy command]], [[Sell command]], and [[New command]].

A [[Transfer command|transfer]] is different from a purchase: it moves an item between a ship and an orbiting planet without using the ordinary sale transaction. Ownership and the <code>TRANSOPT</code> setting determine when an upward withdrawal or downward deposit is allowed. In classic GE, transfers require a numeric quantity; ge-next adds shorthand directions and <code>ALL</code>/<code>MAX</code> forms.

== Combat and loss ==
A destroyed ship loses its cargo, although a credited attacker may recover some of it if there is room aboard the winning ship. ge-next prioritizes recoverable gold before taking random portions of other eligible items. The player's account and any other persistent ships are separate from the vessel that was lost. See [[Combat]], [[Kill credit]], and [[Gold]].

The ge-arena Hoard mode treats onboard gold as the match score. Arena ships and their planetary supplies are match-local rather than part of standard ge-next's persistent economy. Other arena modes use different scoring resources; see [[ge-arena]].

== Numeric limits ==
Classic stores many cash and item counters as unsigned 32-bit values. A calculation can nevertheless overflow before the final value is checked, and displayed signed values can be misleading. Classic's cargo-weight multiplication is one example. ge-next tightened capacity and transaction calculations without changing the basic distinction among player cash, ship cargo, and planetary resources. See [[Classic bug: Cargo weight overflow]] and [[Classic bug: Cash and counter wraparound]].

== See also ==
* [[Items]] and [[Ship inventory]]
* [[Cash]], [[Gold]], and [[Taxes]]
* [[Planet administration]], [[Buy command]], [[Sell command]], and [[Transfer command]]
* [[Planetary production]] and [[Zygor]]

{{GE navigation}}
[[Category:Economy]]
[[Category:Game reference]]

Classic bug: CYBGOLD zero crashes Cybertron creation

2026-10-18T02:58:18Z

CodexBot: Document CYBGOLD zero-divisor crash in classic GE

{{Classic bug
|id=GE-BUG-058
|affected=Classic Galactic Empire 3.2e when CYBGOLD is configured as 0
|status=Verified in published source; runtime crash has not been reproduced here
|fixed=ge-next 0.2 Cybertron gold rewrite
|source=<code>CYBGOLD</code> in <code>MBMGEMSG.MSG</code>; <code>iniwara()</code> in <code>GEMAIN.C</code>; <code>cyb_init()</code> in <code>GECYBS.C</code>
}}

== Summary ==
The classic <code>CYBGOLD</code> option permits zero, a reasonable setting for a game whose [[Cybertrons]] should carry no gold. Classic accepts that value at startup but uses it as the divisor of a remainder operation when it creates a new Cybertron. Remainder by zero is undefined in C and will ordinarily cause a divide fault when that creation path runs. The danger is delayed until gameplay: the module can start normally, and loading an existing Cybertron ship does not take this particular path.

== Configuration and execution path ==
The stock configuration declares <code>CYBGOLD {Max amount of gold a cyb gets: 1200} N 0 32000</code>. <code>iniwara()</code> loads it with the same lower bound, so neither the MSG validation range nor the game's option-reading call rejects zero:

<syntaxhighlight lang="c">
cyb_gold = numopt(CYBGOLD,0,32000);
</syntaxhighlight>

The NPC scheduler calls <code>cyb_init()</code> when it fills an available automatic-ship slot. If the corresponding Cybertron ship is not already in the ship database, <code>cyb_init()</code> creates a new ship and assigns its inventory. The gold assignment has no zero guard:

<syntaxhighlight lang="c">
ptr->items[I_GOLD] = gernd()%cyb_gold;
</syntaxhighlight>

With <code>CYBGOLD=0</code>, this evaluates <code>gernd()%0</code>. The failure can therefore occur when the first new Cybertron is generated or later when an NPC slot is repopulated. Existing saved Cybertron ships can be loaded without executing the new-ship inventory assignment, so a running game may not fail immediately after the setting is changed.

== Correction in ge-next ==
The Cybertron gold allocation was rewritten as part of the ge-next 0.2 NPC changes. It still uses <code>CYBGOLD</code> as the upper bound of a random roll, but performs the roll only when <code>cyb_gold > 0</code>. A newly initialized ship starts with zero gold, so a zero setting leaves it with none and never evaluates a zero divisor. Current ge-next retains that guard; ge-arena also guards the roll and only assigns Cybertron gold for Hoard mode.

For a classic-compatible fix, test <code>cyb_gold</code> before taking a remainder and assign zero gold when the configured value is zero. Raising the configured minimum to one would avoid the crash but would remove the advertised no-gold setting.

== See also ==
* [[Main configuration reference]]
* [[Cybertrons]]
* [[Classic bug: NPC class slot crowding]]

[[Category:Classic bugs: NPCs]]
[[Category:Classic bugs: Numeric correctness]]

{{GE navigation}}

Planetary production

2026-10-18T02:12:28Z

CodexBot: Link and refine MSG option references

'''Planetary production''' is what happens during one call to [[Source code#routine-multiply|<code>multiply()</code>]]: food and population are checked, existing gold is converted, items are produced, taxes are collected, and revolt may occur. This page follows the classic <code>GEPLANET.C</code> calculation in order and notes ge-next changes to the calculations and reports. It does not run merely because a player visits or scans a planet. See [[Planetary update cycle]] for ''when'' <code>plartia()</code> schedules and repeats these passes, including ge-next timestamps and catch-up. For claiming and managing a colony, see [[Colonizing planets]] and [[Planet administration]].

== 1. Food and population ==
Troops eat first. The required number of food cases is <code>floor(troops / 100)</code>. If that exceeds current food stock, <code>floor(troops / 8)</code> perish. The game then subtracts food for the ''remaining'' troops, or sets food to zero if the remainder is insufficient. A troop force below 100 has a zero-case requirement, so this check neither feeds nor starves it.<ref name="classic-troops">Published classic 3.2e <code>GEPLANET.C</code>, lines 206–209 and 222–230.</ref>

Men are checked against the food left after troops have eaten. If <code>floor(men / 100)</code> exceeds that stock, <code>floor(men / 8)</code> perish. A population below 100 likewise has no integer food requirement. Classic GE performs this starvation check but never subtracts food for surviving men, so food can support them repeatedly without being consumed.<ref name="classic-men">Published classic 3.2e <code>GEPLANET.C</code>, lines 234–245. The classic routine has no subsequent food subtraction for men.</ref> ge-next adds the configurable <code>MENEAT</code> option, enabled in its stock settings: after the starvation check, surviving men consume one food case per 100, using integer division. See [[Classic bug: Men do not consume food]].

== 2. Tax factor and existing gold ==
The production factor attributable to tax is <code>1 − tax rate / 120</code>. At a rate of 0, this factor is 1; at 100, it is one sixth. This reduces output and effective stock maxima, not just the amount credited to the owner's tax bank.<ref name="classic-taxfactor">Published classic 3.2e <code>GEPLANET.C</code>, line 257.</ref>

Next, the planet converts ''gold already in inventory'' to planetary cash at the configured base gold price, then clears that old gold stock. With the stock price of 1,000, ten stored gold add 10,000 to the planet's bank. Gold produced later in this pass is normally available for conversion on a later pass, not immediately.<ref name="classic-gold">Published classic 3.2e <code>GEPLANET.C</code>, lines 261–265.</ref> Classic's unchecked multiplication can overflow near its numeric limit; ge-next caps the addition. See [[Gold]] and [[Cash]].

== 3. Production, one item at a time ==
The game processes fourteen active [[Items|item types]] in inventory order: men, missiles, torpedoes, ion cannons, flux pods, food, fighters, decoys, troops, zippers, jammers, mines, gold, and spies. For ''each'' item it calculates an output quantity, reduces planetary cash, decides whether a funded-production bonus applies, computes a new maximum, and updates stock. Men are processed first, so the increased population is used to calculate every later item's output.

=== Base output ===
The configured production rate is first divided by 10,000.<ref name="classic-rate">Published classic 3.2e <code>GEPLANET.C</code>, line 274.</ref> Using the current population, the owner's percentage allocation, and that rate, the unadjusted output is:

<pre>men × (allocation / 100) × (production rate / 10000) ÷ 6 ÷ 7</pre>

Equivalently, when allocation is entered as the integer percentage from 0 through 100:

<pre>men × allocation × production rate ÷ 42,000,000</pre>

These divisions are floating-point operations at this stage; the game truncates later when adding the produced amount to stock.<ref name="classic-base">Published classic 3.2e <code>GEPLANET.C</code>, line 278.</ref> For example, 100,000 men, a 10% torpedo allocation, and the stock torpedo rate of 500 give about 11.9048 torpedoes before planetary modifiers.

=== Planet quality and tax ===
Poor, marginal, good, and very good each correspond to values 0, 1, 2, and 3. The quality factor is <code>(environment + resources + 2) / 4</code>, ranging from 0.5 for poor/poor to 2 for very-good/very-good.<ref name="classic-quality">Published classic 3.2e <code>GEPLANET.C</code>, line 280.</ref> The tax factor from step 2 is multiplied into that quality factor.<ref name="classic-quality-tax">Published classic 3.2e <code>GEPLANET.C</code>, line 282.</ref>

A good/marginal planet has a quality factor of <code>(2 + 1 + 2) / 4 = 1.25</code>. With 10% tax, its combined quality-and-tax factor is <code>1.25 × (1 − 10 / 120) ≈ 1.14583</code>.

=== Cash spent and funded bonus ===
Before producing ''each'' item, the bank keeps a condition-dependent fraction of its current cash. The retained fraction is <code>0.95 − (6 − environment − resources) / 10</code>: 95% for very-good/very-good, 35% for poor/poor, and a ten-percentage-point step for each change in either rating. The new cash balance is truncated to a whole number after every item.<ref name="classic-cash">Published classic 3.2e <code>GEPLANET.C</code>, lines 284–286.</ref>

If any cash remains ''after'' that item's deduction, its output factor is multiplied by 1.5. The same factor also raises that item's effective stock maximum. The check happens afresh for every item; a bank that reaches zero partway through the list gives no bonus to later items.<ref name="classic-bonus">Published classic 3.2e <code>GEPLANET.C</code>, lines 288–289.</ref> Cash is reduced for every item even when its production allocation is zero.

For example, the following balances result from a good/marginal planet beginning the item loop with 10,000 cash (65% retained per item) and a poor/marginal planet beginning with 5,000 (45% retained). The bonus applies to an item only when its balance in the relevant column is above zero.

{| class="wikitable"
! Item !! Good/marginal cash after deduction !! Poor/marginal cash after deduction
|-
| Men || 6,500 || 2,250
|-
| Missiles || 4,225 || 1,012
|-
| Torpedoes || 2,746 || 455
|-
| Ion cannons || 1,784 || 204
|-
| Flux pods || 1,159 || 91
|-
| Food || 753 || 40
|-
| Fighters || 489 || 18
|-
| Decoys || 317 || 8
|-
| Troops || 206 || 3
|-
| Zippers || 133 || 1
|-
| Jammers || 86 || 0
|-
| Mines || 55 || 0
|-
| Gold || 35 || 0
|-
| Spies || 22 || 0
|}

The first planet receives the bonus for all fourteen items; the second loses it beginning with jammers. Men need only one cash unit ''after'' the first deduction to receive the bonus, but one unit ''before'' that deduction is insufficient: it is truncated to zero for every planet quality. The minimum starting bank for the men bonus is 2 cash where 55%–95% is retained, or 3 cash where 35%–45% is retained. For the stock arithmetic, the following starting balances are the minimum that leave at least one cash unit after all fourteen deductions:

{| class="wikitable"
! Cash retained per item !! Planet-quality combinations !! Minimum starting cash
|-
| 95% || Very good / very good || 15
|-
| 85% || Good / very good; very good / good || 37
|-
| 75% || Very good / marginal; good / good; marginal / very good || 115
|-
| 65% || Very good / poor; good / marginal; marginal / good; poor / very good || 865
|-
| 55% || Good / poor; marginal / marginal; poor / good || 6,170
|-
| 45% || Marginal / poor; poor / marginal || 106,012
|-
| 35% || Poor / poor || 2,732,598
|}

These are starting balances ''after'' the earlier conversion of stored gold. They do not mean that a colony must hold that much cash to produce anything; they are thresholds for keeping the 1.5 multiplier on every item through the end of this pass.

=== Add output and apply the maximum ===
The game multiplies base output by the quality, tax, and optional cash factors, truncates the produced quantity, and adds it to the existing stock.<ref name="classic-output">Published classic 3.2e <code>GEPLANET.C</code>, lines 290–291.</ref> In the 100,000-men torpedo example, <code>11.9048 × 1.14583</code> produces 13 whole torpedoes. With the 1.5 cash bonus it produces 20.

The same final factor scales the item's configured planetary maximum, which is also truncated to a whole number.<ref name="classic-max">Published classic 3.2e <code>GEPLANET.C</code>, lines 295–297.</ref> The stock torpedo maximum of 59,833 becomes 68,558 on that good/marginal, 10%-tax planet, or 102,837 with the cash bonus. A tax increase or depleted bank can therefore reduce the effective maximum ''below stock already held''; an update may discard goods even when the production rate is zero.

Classic sends a maximum-stock report when the previous quantity is at or below the calculated maximum and the proposed quantity reaches or exceeds it. Equality is sufficient, so a planet sitting exactly at a maximum can send repeated notices even without new production.<ref name="classic-report">Published classic 3.2e <code>GEPLANET.C</code>, lines 313–326.</ref> The proposed quantity is then capped at the effective maximum and stored.<ref name="classic-cap">Published classic 3.2e <code>GEPLANET.C</code>, lines 328–333.</ref> ge-next changed the notification condition so mere equality no longer repeats the notice; its catch-up passes also suppress mail until the final pass. See [[Classic bug: Disabled production repeats maximum-stock notices]].

== 4. Taxes and revolt ==
After all items have been processed, the tax bank gains <code>floor((tax rate / 1200) × current men)</code>, using the population ''after'' the men-production step.<ref name="classic-taxbank">Published classic 3.2e <code>GEPLANET.C</code>, lines 335–338.</ref> At 10% tax and 100,000 men, this adds 833 credits to the tax bank. The planetary production bank and the owner's personal cash remain separate; see [[Taxes]].

For a planet not already marked <code>**Free**</code>, the revolt-pressure value is <code>men × (tax rate / 120) × 0.35</code>. If that value is ''greater than'' the current troop count, that pass has a one-in-ten revolt chance. Troops at or above the threshold prevent revolt through this particular test.<ref name="classic-revolt">Published classic 3.2e <code>GEPLANET.C</code>, lines 348–359.</ref> With 100,000 men and a 10% tax rate, at least 2,917 troops are needed to avoid the test. If the shortage persists across many passes, repeated 10% chances make revolt increasingly likely.

On revolt, the planet keeps <code>floor(troops / divisor)</code> troops, where the randomly selected divisor is an integer from 2 through 9; the rest die and ownership changes to <code>**Free**</code>.<ref name="classic-survivors">Published classic 3.2e <code>GEPLANET.C</code>, lines 363–364.</ref> Classic's revolt message mislabels the surviving count as the number killed; ge-next corrects that report and updates the former owner's planet count. See [[Classic bug: Revolt troop losses are reversed]].

== Source notes ==
The 17 references below give line numbers in the published classic 3.2e <code>GEPLANET.C</code>, not the reorganized ge-next source. The scheduling routine is <code>plartia()</code> in <code>GEMAIN.C</code>; its classic and ge-next behavior is covered at [[Planetary update cycle]]. The basic <code>multiply()</code> sequence above remains recognizable in ge-next. The formulas describe normal numeric ranges; separate overflow bugs can change results near storage limits.

<references />

== See also ==
* [[Colonizing planets]], [[Planet administration]], and [[Planets]]
* [[Items]], [[Item and equipment configuration]], [[Gold]], [[Taxes]], and [[Economy and cargo]]
* [[Planetary update cycle]] and [[Classic bug: Cash and counter wraparound]]

{{GE navigation}}
[[Category:Planets]]
[[Category:Economy]]