PHost - Hosting Stages

Index

• Introduction
• Host Order
  • Phase 1 - Turn Processing
  • Phase 2 - Host Action
  • Phase 3 - Result Generation
• Manipulating the Host Sequence
  • The Auxhost Files
  • The PControl Section
  • Host Data Check
  • Commands
• Quick Overview

Introduction

During hosting, things happen in a certain order: missions, production, movement, and so on. It is important for players to know this order. For example, mine laying happens before movement which means the minefield will appear at the place where you are, not where you go to. This document describes the complete order of actions of PHost. It also provides information on how to add your own processing stages to the host sequence.

Back to top

Host Order

PHost consists of three phases; the middle one is again split into stages. The order of these parts is fixed. Hosts can, however, disable some stages, or run add-ons at any place between two stages or phases.

Phase 1 - Turn Processing

• PHost initialization, command-line parsing, etc.
• Hosting files are read and validated.
• Turn files are read and processed in random order. Turn files are checked for cheating and then incorporated into the hosting files. This will update all information from the client (mission changes, cargo transfers between same-race objects, ...). transfer and unload move cargo into transporters. Most command messages are executed. Starbases are built.
• Rumors are sent in random order.
• (v4.0h:) In turn 1, PHost checks all ships for special functions. If they should have some according to shiplist.txt, but do not have any, PHost assigns them the standard set. This is to support Master programs that do not know about AssignTo=Ship-style functions.
• When DelayAllianceCommands is off, alliance changes are performed here.
• Remote Control commands are performed in the following order
  • "drop"
  • "allow"/"forbid"
  • "control"
  • "give"
• Remote-controlled ships are given back to their real owner.

(v3.4c:) Note that PHost versions up to 3.4b do alliance processing at the beginning of phase 2, and process remote control orders and rumors in whatever order they're coming in. In addition, these host versions send rumors in whatever order they come in and therefore do not guarantee anonymity.

Phase 2 - Host Action

Note on Cloaking: Ships that are ordered to cloak (using the mission cloak or super spy or one of its substitutes) start the turn cloaked if they fulfill the conditions for cloaking. Later on, they can only de-cloak; once they are de-cloaked, they stay uncloaked for the rest of the turn.

All places where cloaking can fail have been identified in this list. Note, however, that add-on programs may cancel cloaking as well. In addition, cloaking immediately fails whenever a ship has too little fuel or too much damage after an add-on invocation.

Injected Commands: (v4.0e:) Commands "injected" using auxcmds.txt are processed at the very beginning of phase 2.

• alliance changes (if DelayAllianceCommands is off)
• Remote Control commands, in the order (1) "drop", (2) "allow"/"forbid", (3) "control", (4) "give".

All give commands and the gsX friendly code orders are validated, and then performed simultaneously. In particular, two players can exchange two ships and still fulfill the "partner must have ship at same position" requirement.

De-Cloak: (v4.0j:) Ships that change ownership must decloak.

If LargeMeteorsImpacting is nonzero, do that many large meteors. Otherwise, do one large meteor at a chance of RandomMeteorRate.

Planets can be hit by several meteors in one turn.

For each planet, do a small meteor at a chance of MeteorShowerOdds.

Planets can be hit by at most one meteor shower per turn. However, a planet hit by a meteor can still receive a meteor shower.

Anti-cloak ships decloak ships in range. The anti-cloak ships are processed in Id order. A ship in range of multiple Lokis will be decloaked by the one with the lowest Id.

De-Cloak: Ships affected by an anti-cloak ship must de-cloak at once.

Does the friendly-code changing on all victim planets. Uses per-player Id order to pick the ship to define the new friendly code for each planet. See Super Spy mission.

De-Cloak: When the ionic pulse (described with the Super Spy mission) triggers, ships must de-cloak at once.

Picks a planet NewNativesPerTurn times, and attempts to give it new natives. If it picks a planet that already has natives (or if it picks a planet already picked this turn), nothing happens.

Robbers act in per-player Id order. Each robber robs his victims in Id order (that is, if the Privs don't have enough cargo capacity to empty your fleet, the high-Id victim ships will keep cargo; if the victims have less than fits into the robbers' cargo room, the high-Id robbers will remain empty).

If a robbing ship fails its RobFailureOdds chance, it will not rob anything. If RobCloakedShips is enabled, RobCloakedChance is checked for each robber/victim pair.

Gambling ships generate credits, in Id order.

For each ship in Id order, drops cargo. This includes the standard ship/foreign-planet cargo transfer (order given through the client interface or the unload command), as well as the bdm friendly code and the Beam Down Credits mission.

• If ship is at an unowned planet, cargo is just unloaded onto it. If ship beams down colonists, the planet is colonized.
• If ship is at a foreign planet, cargo is unloaded. If colonists are beamed down and planet and ship are not allied, ground combat or Imperial Assault happens.
• If the ship is at a planet owned by the same player, it will simply unload cargo. Normally, same-race transfers are performed client-side and are already processed in phase 1 (turn processing). However, same-race transfers may still remain in case a unit changes ownership or is under remote control.
• If ship is in free space, cargo is jettisoned, i.e. destroyed.

This stage cannot be skipped (cargo transporters must be empty during rest of host run).

For each ship in Id order, do transfers to other ships (ship/foreign ship transfer orders, given through client interface or transfer command). If transfer fails, cargo is put back to original ship. Cargo transfers between ships of the same race are usually resolved client-side, and therefore already processed in phase 1. Cargo transfers using missions are resolved later.

This stage cannot be skipped (cargo transporters must be empty during rest of host run).

Ships might be overloaded for various reasons. In this stage, all ships' cargo is reduced to fit in the actual cargo hold.

This stage cannot be skipped (ships must not be overloaded during rest of host run).

Academy ships give crew to other ships, in Id order, using the crew exchange mission.

In Id order, ships perform the Training mission.

In Id order, performs the following actions for each ship:

• Transfer Torpedoes, Transfer Fighters and Transfer Money missions.
• btt, btf and btm friendly codes.

When a ship is using both a beam transfer mission and a friendly code, the mission is performed first, then the friendly code. (in PHost 3.4c and below, only the mission is performed).

In Id order, performs the following actions for each ship:

• Beam Up Multiple
• Beam up Fuel and its relatives
• Beam up Credits and Beam up Clans

In Id order, processes the bum friendly code on planets. This also handles the con friendly code (the send config command is handled in phase 1, completely unrelated to this one).

De-Cloak: After this (and the previous) stages, ships may have lost enough fuel to be unable to cloak any longer. Ships lose fuel by Rob, but friends may immediately re-fuel you to keep your cloak (inter-race cargo transfer).

Mine fields decay. Note that because mine decay is before mine laying and sweeping, ships that were inside a minefield before may end up outside after this.

Ships lay mines. The actual order depends on the PHost version.

• 3.2x and below: Id order starting with ship #1 (same as HOST)
• 3.3 up to 3.4d, 4.0: Id order starting with a random ship
• 3.4e and later, 4.0a and later: per-player-Id order, among all ships that want to lay mines

With AlternativeMinesDestroyMines enabled, mines from overlapping fields will explode here when a new overlap is created. This always happens in PHost 4.0a/3.4e and before.

(v4.0b:) Overlapping hostile minefields explode.

This stage is not available in PHost 3.4e/4.0a and below; in these versions, overlapping minefields will only explode when someone attempts to enlarge one of them; see the previous stage.

Ships scan for mines and sweep them, in ship Id order.

This sends out the mine scan messages for minefields seen in the previous stage.

In PHost versions up to 4.0d, Wormhole scanning happens here. In 4.0e and later, it happens after terraforming.

Ships inside Crystalline web minefields lose fuel (WebDrainFuelLoss, multiple times if in multiple webs).

De-Cloak: After this stage, ships may have lost enough fuel to be unable to cloak any longer.

If the number of ion storms exceeds IonStormActivity, the weakest storm dies.

Then, in Id order, storms...

• pick new heading and speed
• move
• change size and voltage

Finally, storms merge if they fulfill the preconditions.

See also: Ion storm formulas

In storm Id order, storms decloak ships and affect then-uncloaked ships (drag them along, damage, crew loss). Ships within multiple storms are affected by all of them, in storm Id order.

If the number of ion storms is less than IonStormActivity, creates new storms. The number of new storms is picked randomly between one and three.

Note that this can exceed the IonStormActivity limit. This is by intention; next turn, a weak storm will die in this case.

Sends out messages about all ion storms to every player.

(v4.0h:) First, in ship Id order, processes Super Refit orders using the refit command

(v4.1f:) Second, in parallel, ships repair other ships using the Repair mission.

Then, in ship Id order

• Super Refit (regular mission, without refit command)
• Hiss
• Self Repair

Robot/Rebel/Colonial ships build fighters, in Id order. This handles the lfm friendly code, the Build Fighters and Gather-build Fighters missions, and the Rebels' fighter auto-build.

In Id order, does the mkt friendly code and the Build Torpedoes, and then Gather-build Torpedoes missions.

In PHost up to version 4.0h/3.4j, Gather-build Torpedoes has precedence and prevents mkt from happening.

The three alchemy functions.

Iterates through all bases in Id order, starting with a random base, and places the build orders in the ship build queue.

Priority build friendly codes are processed here, too, if required by the build queue mode.

Perform ship build orders, in queue order, as long as there are free ship slots.

Starbases with the dmp friendly code recycle unneeded starship parts from their storage.

Tech levels of starbases are downgraded here. A starbase owned by an unregistered player cannot have more than Tech 7 for engines, Tech 6 for other areas, unless it was built with the right natives. This check applies when a registered player slot is taken over by an unregistered player. Over-high tech levels are reduced without compensation.

This stage has no effect on registered players' bases.

In starbase Id order, does...

• fixing/recycling ships
• Maximize defense order
• Load Torpedoes onto Ships order
• Force Surrender order

Ships repair themselves using supplies.

Towing ships board their towee if they can, in tower-Id order.

De-Cloak: (v4.0j:) Ships that change ownership must decloak.

Starbases build free (no-money) fighters.

This stage prepares movement.

Its main purpose is resolution of tow missions. All tows which shall not succeed are canceled. See also Tow conflict resolution rules.

In addition, this stage applies the damage speed limit, and fixes up the waypoints of all interceptors (this just points the interceptors' waypoints to their targets, it does not yet compute the final positions). These two operations are required for correct tow conflict resolution.

• Hyperjumpers decloak; remaining cloakers perform cloak fuel burn;
• Invalid intercept orders (target has died) are cleared;
• Moves all "normal" (non-intercept) ships in Id order.
  • Move the ship towards its waypoint. In the presence of minefields, determines which (if any) the ship will hit and processes the the effect: the ship will, during this stage, accumulate damage (and therefore might have to de-cloak), possibly get slower (and therefore possibly lose its tow lock), and burn fuel for movement or hitting a web mine.
  • The Ramscoop operates after the ship's movement has come to an end.
  • If the ship has towed another ship, that ship will now either be allowed to move on its own, or have its waypoint cleared.
  Hyperjumpers and fuelless ships also move during this sub-phase, according to much simpler rules (no mine hits, no towing).
• Next, intercepts are resolved and all intercepting ships moved.
• Then, ships travel through wormholes.
• Then, gravity wells pull ships towards planets.
• Finally, ships burn FuelUsagePerTurnFor100KT.

Ships that move can run on mines and get damaged. Ships running on web mines lose fuel. This may cause their cloaking device to fail immediately. Ships can not run on mines during...

• ...hyperjumps and wormholes. Movement in hyperspace bypasses all minefields.
• ...zero-fuel movement (if AllowNoFuelMovement is enabled). Ships use their sub-warp impulse engines for that and are safe from sub-space mines.
• ...gravity wells. This is a natural process not affected by human/lizard/pick-a-race-made devices.

De-Cloak: After this stage, ships may have lost enough fuel to be unable to cloak any longer. Actually, ships de-cloak immediately when getting too badly damaged from a mine hit, or running out of fuel. Ships which travel through a wormhole de-cloak as well. (v4.0i/3.4k:) Ships which hyperjump must also decloak.

Glory devices go off in Id order. If a Glory Device ship also has a working Anti-cloak device, it will perform its de-cloak operation immediately before detonating.

De-Cloak: Ships affected by an anti-cloak ship must de-cloak at once. After this phase, ships which got over the damage limit (by a Glory Device) must de-cloak, too.

Chunneling happens in order of initiator-Id.

De-Cloak: (v4.0i/3.4k:) Ships which initiate a chunnel or act as chunnel Mate must de-cloak.

Loki ships decloak again, in Id order. This uses the new positions of the Lokis and of the cloakers. A cloaker going from A to B will not be decloaked by a Loki going from B to A (assuming B and A are more than 10 ly apart), but any ship starting where the Loki started, or ending where the Loki ends, will be decloaked.

De-Cloak: Ships affected by an anti-cloak ship must de-cloak at once. After this phase, ships which got over the damage limit (by a Glory Device) must de-cloak, too.

The Colonize mission, in ship Id order.

Ships repair themselves, again.

In starbase Id order, does...

• Refuel ships
• Repair base
• Unload Freighters

Resolves each group of ships and planets according to the battle order rules.

De-Cloak: (v4.0j:) Ships that reach the DamageLevelForCloakFail or lose their fuel must decloak at once. Likewise, ships that change ownership must decloak.

Ships repair themselves, again.

Terraform ships operate in Id order.

De-Cloak: After this (and the previous) stages, ships may have lost enough fuel or got damaged to be unable to cloak any longer. Since ships now decloak immediately during combat, this stage doesn't have too much of an effect now, but it will be useful if you use a third-party combat system.

Ships scan for wormholes, in Id order.

In PHost up to version 4.0d, this stage is executed just after mine scanning.

Normal Sensor Sweep and Bioscanning, in Id order.

Note that when ExtendedSensorSweep is enabled, the mine scanning part of sensor sweep happens in MineSweeping, before movement. The wormhole scanning happens in WormholeScan.

First, does Pillage and Rebel Ground Attack in per-player Id order. Second, Dark Sense generates messages.

Mines and factories produce, Bovinoid natives provide supplies (see Production Formulas). Afterwards, trans uranium decay forms new minerals in planet core (TransuraniumDecayRate).

Happiness changes according to the tax rates set by the client. When the planet's happiness already is below 30, the tax rate is set to zero (and new happiness is computed using that value).

See also: Formulas

Tax revenue generated.

See also: Formulas

Colonists and natives grow.

See also: Formulas

For each planet:

• Overpopulation eats supplies
• Overpopulation dies
• Structure decay
• Riots damage structures
• Population losses due to civil wars

See also: Formulas

Perform remaining ship build orders, to fill up slots freed by combat.

Cyborgs assimilate natives.

Super Spy ships generate their reports, in Id order.

Ships orbiting a foreign planet (and having fuel) generate exploration reports.

(v4.0:) Ships and planets gain experience corresponding to their actions this turn. PHost also sends out experience reports here.

Phase 3 - Result Generation

• External messages (from add-ons) are processed.
• shipscan.ext is written.
• Score computation.
• Alliance changes are performed here when DelayAllianceCommands is on.
• Remote-controlled ships are given to their controlling race.
• Result and Utility data files are generated.

Back to top

Manipulating the Host Sequence

There are two ways to manipulate the host sequence. Note that you can only add (and sometimes remove) actions, you can not re-order stages.

Whenever you add one of your programs into the sequence, PHost will save all its data to disk, close all files and so on, and run your program. It will then read back the host data, verify it, and continue.

The Auxhost Files

HOST 3.20 introduced the auxhost1.ini and auxhost2.ini hooks. HOST 3.22.005 introduced auxbc.ini. PHost supports these hooks as well.

• auxhost1.ini is run between phase 1 and 2, that is, after all turn processing but before host processing begins.
• auxhost2.ini is run between phase 2 and 3, that is, after host processing is complete and before result files are generated.
• auxbc.ini is run immediately before combat.

These .ini files are text files in the game directory, each line containing a command to be run.

PHost does not support auxbatt.ini (you can use the PControl method as mentioned below to achieve the same results), and it does not support file extensions other than .ini for these files (Tim's host will also run auxhost1.exe and auxhost1.bat and so on).

The PControl Section

In pconfig.src, a section pcontrol configures the host sequence. For each stage, you can specify some actions to do.

Note again that you can not change the order of the actions, no matter in what order names appear in that section.

Stages of Phase 2

The pcontrol section can contain lines of the form

StageName = Action

where the StageName is specified in the above description of the stages, and the Action is one of the following:

• Normal: the stage is run normally. This is the default for all stages.
• Skip: the stage is not run. Some stages are important to PHost and can not be skipped.
• Replace command: replaces this stage by the specified command (see below). Sections which cannot be Skipped can't be Replaced either.
• Execute command: execute the specified command, then run the stage normally.
• Before command: (v4.0c:) same as Execute: execute the specified command, then run the stage normally.
• After command: (v4.0c:) execute the specified command after the stage has run.

The action names can be abbreviated up to their first letter only.

Each command can be one of the following:

• file.ini: executes the specified .ini file, from top to bottom. The file is searched in the game and root directory. (v4.0h:) You can also specify absolute paths if you wish.
• file.ini%section: execute only the specified section from the .ini file. Sections are delimited in the same way as in pconfig.src.
• *command: (v4.0c:) execute the specified shell command. This is a shortcut for making a one-line .ini file.

(v4.0c:) You can specify multiple actions by giving multiple assignments to the same stage name. The actions will be executed in order. The stage is skipped when at least one Skip or Replace is used, otherwise the stage will be executed. Therefore, the sequence of actions is:

• First, execute all Before, Execute and Replace commands, in the order in which they were seen in the configuration file.
• Unless there was a Skip or Replace action, execute the stage itself.
• Finally, execute all After commands.

In PHost version 3.4f/4.0b and older, you can have at most one action per stage.

Between Phases (Auxhost)

(v4.0k:) Instead of making auxhost1.ini and auxhost2.ini files, you can specify the commands directly in pconfig.src.

Auxhost1 = Command
Auxhost2 = Command

The command is just a reference to another ini file or a shell command, as in Auxhost1 = *mfq %d. There is no point in specifying Before, Skip, etc.

Addons

(v4.0k:) Many add-ons are used again and again with the same set of PControl settings. To simplify setup, you can write these PControl settings in a separate file, and refer to that file from the PControl section.

Addon = filename

PHost will look for that file in both the game and the root directory, so you can use the same file for many games. PHost will look for a %pcontrol section delimiter and read just that section. Therefore, if the add-on understands these section delimiters, you can directly place the instructions in the add-on configuration file.

Example: Here is an example to use with the Stargate add-on:

% pcontrol
TowResolution = Execute *stargate 1 %d %r
SensorSweep   = Execute *stargate 2 %d %r

You would refer to that file by using Addon = stargate.txt (unfortunately, Stargate doesn't support % section delimiters).

Host Data Check

After every add-on invocation, PHost reloads the universe and validates it briefly.

• All configuration and data files are re-read (except for the PControl configuration itself), specification files are validated.
• Ships with more than 100% damage are deleted.
• Ships with invalid tow or intercept orders have their mission reset. Here, invalid means the target ship does not exist or, in case of tow, is at a different position.
• Ships that can no longer cloak are decloaked. This can happen if they have too little fuel, are damaged, or had their mission changed.

Note that this is not a full host file check. For example, it will not complain if a ship is overloaded. Effectively, PHost trusts add-ons. It just tidies up some things which add-ons often forget.

Since this check is run after every add-on invocation, ships may decloak earlier when an add-on is used than they would if no add-on were used.

Commands

As mentioned above, there are two ways to specify commands to execute. You can place them in an .ini file, one per line, or you can specify them directly in pconfig.src.

Commands are handed to the operating system's command shell (i.e. command.com or cmd.exe under Microsoft operating systems, /bin/sh on Unix), one by one. Therefore, fancy things such as multi-line commands or goto are not permitted.

The following symbols are handled specially:

%section

In an .ini file, specifies a section boundary. If a section was specified in pconfig.src, execution starts or ends here.

# anything

In an .ini file, lines starting with a number sign are comments and are ignored.

%d

(v4.0k:) In a command, this symbol is replaced by the game directory name (first directory parameter specified in PHost invocation). For example, Combat = Replace *flak-server %d will run the add-on flak-server with the current game directory as a parameter. PHost automatically suppresses duplicate directory delimiters if you use this to construct file names. Note that, in an .ini file, this symbol cannot be first in a command, to avoid confusing it with a section delimiter.

%r

(v4.0k:) In a command, this symbol is replaced by the root directory name (second directory parameter specified in PHost invocation). Everything said for %d applies here, too.

%s

(v4.1e:) In a command, this symbol is replaced by the current random number seed. If the add-on supports initializing its random number generator using the command line, you can make the add-on invocation repeatable: this value is derived from (but not identical to) the value given using the -S or -s command line option, so when you invoke PHost again with the same seed and the same input data, it will pass the same seed to the add-on. As a convenience, PHost will also pass the same value through the environment, in a variable PHOST_RANDSEED.

%%

(v4.0k:) Produces a literal percent sign.

Back to top

Quick Overview

Here are all the stages of phase 2, in order of execution, with links to their descriptions:

1. TransferOwner
2. LargeMeteors
3. MeteorShowers
4. AntiCloak_1
5. DeluxeSuperSpy
6. NewNativesAppear
7. RobMission
8. GamblingShips
9. CargoDump
10. CargoTransfer
11. TrimShipCargo
12. CrewExchange
13. Training
14. BeamTransfers
15. GatherMission
16. BeamUpCredits
17. MinefieldDecay
18. MineLaying
19. MinesDestroyMines
20. MineSweeping
21. MinefieldScan
22. Old position of WormholeScan (until v4.0d)
23. WebDraining
24. MoveIonStorms
25. IonStormEffects
26. NewIonStorms
27. IonStormReports
28. SpecialMissions_1 (Super Refit, Hiss, Self Repair)
29. BuildFighters
30. BuildTorpedoes
31. Alchemy
32. ShipBuildOrders
33. ShipBuilding_1
34. DumpOldBaseParts
35. BaseMissions_1 (Fix/Recycle, Maximize Defense, Load Torps, Force Surrender)
36. SupplyRepair_1
37. BoardingParties
38. FreeFighters
39. TowResolution
40. Movement
41. GloryDevices
42. Chunneling
43. AntiCloak_2
44. ColonizeMission
45. SupplyRepair_2
46. BaseMissions_2 (Refuel, Repair base, Unload)
47. Combat
48. SupplyRepair_3
49. Terraforming
50. WormholeScan
51. SensorSweep
52. SpecialMissions_2 (Pillage, RGA, Dark Sense)
53. PlanetaryProduction
54. PlanetaryHappiness
55. PlanetaryTaxation
56. PlanetaryGrowth
57. PlanetaryLosses (Overpopulation dies, riots, structure decay)
58. ShipBuilding_2
59. Assimilation
60. SuperSpyMission
61. ShipExploration
62. Experience

Back to top

Last updated 31 May 2015.