CodexBot: Link first command references to command pages

2026-10-12T02:14:47Z

Link first command references to command pages

New page

{{Classic bug
|id=GE-BUG-044
|affected=Classic 3.2e and published classic source
|status=Verified in source; corrected and later refined in ge-next
|fixed=ge-next 0.2; maintenance system overhauled in 0.3
|source=<code>cmd_maint()</code>, <code>repairship()</code>, and <code>cloakstat()</code>
}}

== Summary ==
Classic maintenance does not repair a damaged cloaking device when paid maintenance finishes. It repairs the hull and explicitly restores every other classic damageable system, then announces that repairs and general maintenance are complete while the cloak can remain damaged and unusable.

The cloak does eventually repair itself through the ordinary background system repair logic. That does not make the maintenance result correct: the player has paid for complete maintenance, received a completion announcement, and can still be left with a system listed as damaged.

== Classic maintenance duration ==
The [[Maintenance command|<code>MAINT</code>]] command bases its initial repair counter only on hull damage:

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

Each maintenance update removes three points of hull damage. It then derives a new counter from the remaining hull damage:

<syntaxhighlight lang="c">
if (ptr->damage > 3.0)
ptr->damage -= 3.0;
else
ptr->damage = 0.0;

ptr->repair = (int)(ptr->damage / 3.0);
</syntaxhighlight>

No system-damage value contributes to this duration. A badly damaged system does not make maintenance take longer than the hull alone requires.

== Systems restored at completion ==
When the hull-derived counter reaches its completion threshold, classic resets the hull and these systems:

<syntaxhighlight lang="c">
ptr->damage = 0.0;
ptr->phasr = 100;
ptr->tactical = 0;
ptr->helm = 0;
ptr->firecntl = 0;
ptr->shieldstat = SHIELDDN;
ptr->shield = 0;
ptr->topspeed = shipclass[ptr->shpclass].max_warp;
</syntaxhighlight>

It then prints <code>MAINT7</code>:

<syntaxhighlight lang="text">
Repairs and general maintenance have been completed Sir!
</syntaxhighlight>

The classic damage model can damage six system categories: shields, phasers, fire control, cloak, tactical display, and helm. Five appear in the completion block. The cloak is the only one omitted.

== Cloak damage remains ==
Random system damage stores cloak damage as a negative value:

<syntaxhighlight lang="c">
ptr->cloak = 0 - (int)rndm((ptr->damage + 10.0));
</syntaxhighlight>

The [[Cloak command|<code>CLOAK</code>]] command rejects a negative value and reports that the device is damaged. <code>REP SYS</code> likewise lists the damaged cloaking device.

Nothing in classic <code>repairship()</code> changes that value. A ship can therefore receive the maintenance-complete announcement and immediately still receive the damaged-device response when trying to cloak.

== Why the cloak eventually recovers ==
Classic also has passive system repair. <code>cloakstat()</code> advances a damaged cloak by one point on every ship-state update:

<syntaxhighlight lang="c">
if (ptr->cloak < 0)
{
++ptr->cloak;
if (ptr->cloak == 0)
prfmsg(CLREPR);
}
</syntaxhighlight>

The main ship-state loop calls the relevant routines in this order:

<syntaxhighlight lang="c">
repairship(wptr, zothusn);
shieldstat(wptr, zothusn);
cloakstat(wptr, zothusn);
...
checkdam(wptr, zothusn);
</syntaxhighlight>

On the final maintenance update, <code>repairship()</code> first announces that maintenance is complete without touching the cloak. <code>cloakstat()</code> then repairs only one point. Unless that point reaches zero, the cloak remains damaged after the completion announcement.

This passive repair can make the defect seem intermittent. A lightly damaged cloak may naturally reach zero before paid maintenance finishes. A more severely damaged cloak does not.

== Example ==
Consider a ship that begins maintenance with:

<syntaxhighlight lang="text">
Hull damage: 60
Cloak status: -50
</syntaxhighlight>

Classic maintenance reduces 60 points of hull damage by three per maintenance update and enters its completion block after 19 updates. During those updates, the separate cloak routine repairs approximately 19 points. The exact cloak value around the completion call depends on where in the update cadence the damage and command occurred, but it can still be roughly <code>-31</code>.

The player sees the general maintenance-complete message, yet the cloak still requires about 31 more ship-state updates before <code>cloakstat()</code> reaches zero and reports that the device is operational. Paid maintenance has repaired the hull and every explicitly listed system, but not the cloak.

== Related classic shield behavior ==
Classic's completion block is also unnecessarily destructive toward healthy shields:

<syntaxhighlight lang="c">
ptr->shieldstat = SHIELDDN;
ptr->shield = 0;
</syntaxhighlight>

Those assignments run regardless of whether the shields are damaged. If a healthy shield system is up or retains a positive charge when maintenance finishes, classic lowers it and discards that charge. This is not the same omission as the cloak bug, because damaged shields are repaired; it is the opposite state-management problem. Maintenance changes a healthy operating system when it only needs to normalize a damaged one.

This behavior informed the later ge-next cloak refinement.

== Initial correction in ge-next 0.2 ==
During development of ge-next 0.2, the maintenance completion block was expanded to assign zero to <code>cloak</code>. A negative damage value was therefore cleared when maintenance completed instead of being left for passive repair.

The same January 2025 maintenance change refined shield handling. Instead of always lowering shields and erasing their charge, ge-next changed the reset to:

<syntaxhighlight lang="c">
if (ptr->shieldstat == SHIELDDM)
ptr->shieldstat = SHIELDDN;
if (ptr->shield < 1)
ptr->shield = 0;
</syntaxhighlight>

Damaged shields were normalized to a safe down state, and a negative shield value was cleared. Healthy shields and positive charge were preserved. This was the appropriate general rule: maintenance should repair a damaged system without unnecessarily disabling a healthy active one.

The initial cloak correction did not yet follow that rule. It assigned zero unconditionally. That fixed the classic omission, but it could also turn off an operational cloak if maintenance completed while the cloak had a positive state.

== Refinement in ge-next 0.2.6 ==
ge-next 0.2.6 made the cloak correction conditional in the same manner as the earlier shield adjustment:

<syntaxhighlight lang="c">
if (ptr->cloak < 1)
ptr->cloak = 0;
</syntaxhighlight>

A negative cloak value is repaired, and an already inactive value remains inactive. A positive value representing an operational cloak is left alone. Maintenance therefore no longer finishes with cloak damage, but it also no longer uncloaks a ship merely because repairs completed.

== Maintenance overhaul in ge-next 0.3 ==
ge-next 0.3 replaced the hull-only completion model with a unified accounting of outstanding repairs. Hull, shields, cloak, helm, tactical display, phasers, weapon controls, the additional launcher systems introduced by ge-next, and warp damage are considered by the maintenance routines.

Damaged systems are repaired progressively instead of all being reset on the last hull-repair update. Maintenance does not announce completion until <code>repair_needed()</code> confirms that no applicable hull or system damage remains. The cloak is explicitly counted and repaired in that process.

This later design removes the broader assumption that a timer derived solely from hull damage can represent complete ship maintenance.

[[Category:Classic bugs: Ships]]
[[Category:Classic bugs: User interface]]

{{GE navigation}}

Classic bug: Maintenance omits cloak repair - Revision history

CodexBot: Link first command references to command pages