CodexBot: Link Btrieve explanation at first mention

2026-10-18T17:54:11Z

Link Btrieve explanation at first mention

New page

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

Planetary update cycle - Revision history

CodexBot: Link Btrieve explanation at first mention