Orion

On an Orion universe only. These functions exist everywhere, but the module only turns on in a universe that has Orion. Anywhere else, StartOrion and the gestures return the error this universe does not have Orion: the module reads nothing, and nothing reaches the game. The robot reads it on the pages its session goes through, and remembers it. If it doesn't know yet, an open session reads one Facilities page, the one that shows the anomaly scanner even at level zero; with no session, the error says so. The settings only return this error once the universe is known: until the robot knows, they are saved, with no effect outside an Orion universe. The Orion constants and the A: coordinate prefix are described in Constants and values.

These names are new: if your !global.ank already defines one, your scripts get the engine's, see the introduction. Rename yours.

Everything the bot's Orion page does is done here: read the module's report, set each setting, and the gestures the module makes by itself, by hand.

The switch and the report

Function	Returns
`StartOrion()` / `StopOrion()`	1: an error	The "Orion active" box, saved. `StartWorker("orion")` and `StopWorker("orion")` do the same. `StartOrion` returns an error on a universe without Orion, and saves nothing.
`GetOrion()`	1: a structure	The module's last report, with no request.
`RefreshOrion()`	2: the structure and an error	Reads the game right now, like the "Refresh" button: four requests, worker off included, no gesture. When the session has not seen Orion (scanner at zero), one more Facilities page, which reopens the gestures if the universe has it. When refused, it returns the previous report with the error. If a module pass is running, it reads nothing and says so in its error: the report returned then predates that pass.

IsWorkerEnabled("orion"), IsWorkerRunning("orion") and RunWorkerNow("orion") work too. ListWorkers only names orion on a universe the bot knows has Orion.

GetOrion returns these fields:

Enabled: the switch. ReadAt: the time of the report, in the account's time zone, nil until a reading has succeeded. Error: the last reading error.
Lithium, LithiumCap, LithiumPerHour, NextStopSeconds: the stock, its cap, what the conversions produce, and the time before a conversion stops for lack of resource.
Conversions, one line per planet: Planet, Name, Coordinate, Resource (empty when stopped), Load, PerHour, Endless, RemainingSeconds.
Missions: Object, Name, Level, PvP, Delivery, Stars, Coordinate, Wave, Waves, NextWaveSeconds, DisappearsInSeconds, ClaimCost, PossibleRewards, EarnedRewards, NextWave (Ships, Types, -1 for a hidden count), FleetsFlying, FleetsHolding, FleetsReturning, Finished, Lost, ClaimWithinSeconds, RewardsToClaim. A reward carries Kind, Name, Quantity, Value. Lost: another player holds the anomaly, the module's fleet turned back, and the mission cannot be claimed. The module only sees it on its own takes: a mission taken with OrionInvestigate says nothing of it.
MissionsInUse, MissionsMax.
Scanner: MaxLevel, MaxResults, DiscoveriesInUse, DiscoveriesMax, and Cards, the cards of the last scan: Mission, Name, Level, PvP, Delivery, Stars, Coordinate, Duration, Waves, Distance, ClaimCost, PossibleRewards.
Planets, those of the Empire page: Planet, Name, Coordinate, Scanner (-1 until that page has been read).

The countdowns in seconds start at ReadAt. A report never made returns empty lists, and a script loops over them without a second thought.

o = GetOrion()
Print("lithium", o.Lithium, "/", o.LithiumCap, "per hour", o.LithiumPerHour)
for m in o.Missions {
	if m.Finished && !m.Lost {
		Print(m.Name, "to claim within", m.ClaimWithinSeconds, "s, cost", m.ClaimCost)
	}
}

The settings of the page

Function	Returns
`GetOrionSettings()`	1: a structure	All the settings as the module applies them: `Enabled`, `IntervalMinutes`, `AutoClaim`, `Conversions` (`Planet`, `Resource`, `Load`), `Deliveries`, `ScanLevel`, `ScanRange`, `Transporter`, `MissionPlanet`.
`SetOrionInterval(minutes)`	1: an error	The gap between two readings, from 10 to 180 minutes.
`SetOrionAutoClaim(on)`	1: an error	The "Claim the rewards of finished missions" box.
`SetOrionConversion(planet, resource, load)`	1: an error	The conversion to hold on a planet. Resource: `"metal"`, `"crystal"`, `"deuterium"` or `"food"`. Load: from 10 to 100, in steps of 10.
`ClearOrionConversion(planet)`	1: an error	"Leave it to the game": the module no longer holds this planet. Its running conversion carries on.
`SetOrionDeliveries(on)`	1: an error	The "Run anomaly deliveries" box.
`SetOrionScanLevel(level)`	1: an error	The level of the module's scans, 1 or more. Beyond what the scanners allow, the module scans at the highest allowed.
`SetOrionScanRange(range)`	1: an error	The range of the module's scans: 10, 50 or 150 systems.
`SetOrionTransporter(kind)`	1: an error	The ships of the deliveries: `"auto"` (large first, small to complete), `"small"` or `"large"`.
`SetOrionMissionPlanet(planet)`	1: an error	The planet the module aims at: its report, its gestures and those of this page. `0` to let it take the one with the highest scanner, which it also does when this one has none.

Each setting is saved like the button of the page, applied at once, and survives a restart. Out of its bounds it is refused and nothing changes. A reading ticks nothing: a bot with nothing set does nothing more than before.

The gestures

Function	Returns
`OrionScanCost(level, range)`	2: a structure and an error	The cost of a scan: `Cost`, `Lithium`, `LithiumPerHour`, `NextStopSeconds`. Nothing is spent.
`OrionScan(level, range, [force])`	2: a structure and an error	Runs a scan and returns `Cards`, like the cards of the report. It spends lithium and replaces the cards of the previous scan. When refused for lack of room, `FreeInRange` says how many are left, and `force` at `true` accepts a scan reduced to those.
`OrionInvestigate(card)`	2: a structure and an error	Takes the mission of a card, or of its `Mission`. Returns `MissionsWithoutFleet` and `Discoveries`. Its clock starts at that moment, and sending a fleet there is up to you.
`OrionClaim(mission)`	1: an error	Claims the rewards of a finished mission, or of its `Object`, with the gestures of the "Claim" button: the cost and the stock read again from the game, then the report after the claim, about eight requests. Under the cost, on an unreadable cost, or on a mission that is `Lost`, already claimed or still running, it returns its refusal and nothing leaves. Never dark matter. If a module pass is running, it says so too: try again a moment later.
`OrionStartConversion(planet, resource, load)`	1: an error	Starts or replaces the conversion of a planet, once. To have it held, use `SetOrionConversion`.
`OrionStopConversion(planet)`	1: an error	Stops the conversion of a planet. If the module holds it, it restarts at its next pass: remove it first with `ClearOrionConversion`.

A planet is named as everywhere: a celestial, a coordinate or an id. A moon is refused, it has no scanner. A scan centres on the planet the module aims at, and the mission is accepted there: see SetOrionMissionPlanet. Until the Empire page has been read, worker off and no RefreshOrion, they leave from the current planet.

Each gesture waits for the end of manual mode, then leaves in its own transaction, beside those of the worker. On a universe without Orion, none leaves. None replays itself: an answer that says nothing calls for reading again before trying again, with RefreshOrion, and for reading again if that one answers that a pass is running. The report of GetOrion only sees a gesture at the next reading.

The module only runs what it has itself: it does not replace the cards of a script's scan, and it does not serve a mission taken with OrionInvestigate. The fleet is then up to you.

Sending a fleet to an anomaly

It is NewFleet, with the mission ANOMALYENCOUNTER and a destination of type ANOMALY_TYPE: "[A:4:165:9]", NewCoordinate(4, 165, 9, ANOMALY_TYPE), or straight away a card or a mission of the report. SetDuration gives the holding time in hours, brought to the first game step above it (1, 2, 4, 8, 16 or 32) that this anomaly allows. Without it, the bot takes the one that lasts until the anomaly disappears, like the game page. A fleet comes back anyway when the anomaly disappears. FlightTime works out this flight, at the war speed of the universe, if you give it the mission.

o = GetOrion()
for c in o.Scanner.Cards {
	if !c.Delivery || c.PvP { continue }
	p, err = OrionInvestigate(c)
	if err != nil { LogError(err); return }
	Print("without a fleet:", p.MissionsWithoutFleet)
	f = NewFleet()
	f.SetOrigin(GetCachedPlanets()[0])
	f.SetDestination(c)
	f.SetMission(ANOMALYENCOUNTER)
	f.SetSpeed(HUNDRED_PERCENT)
	f.AddShips(SMALLCARGO, 3)
	fleet, err = f.SendNow()
	if err != nil { LogError(err); return }
	Print("left:", fleet.ID)
	break
}

A delivery only accepts transporters, with at least the cargo of the incoming fleet. Like any script dispatch, this one looks at neither the slot reserve nor the sleep: GetFleetSlotsReserved and GetNextSleepTime are there for that. SendSpy takes the same targets.

Slots and messages

Function	Returns
`GetOrionFleetSettings()`	1: a structure	The settings below: `MaxSlots`, `CleanMessages`, `DeliveryCelestials`. No request.
`SetOrionMaxSlots(n)`	1: an error	The "Orion" line of Settings > Fleet slots: the number of anomaly flights, returns included, from 0 (no cap, the default) to 100. Outside these bounds, refused. The reserve and the slots kept for expeditions and the main fleet come first.
`SetOrionDeliveryCelestials(list)`	1: an error	The celestials a delivery can leave from: `["[P:4:273:12]"]`. An empty list: all of them, the default. The transporters of the next expeditions stay docked either way.
`SetOrionCleanMessages(yes)`	1: an error	The "Delete Fleet Command messages of finished missions" box, unticked by default.

A fleet heading for an anomaly is not an attack on the account: GetAttacks, IsUnderAttack, WaitAttack and OnAttackCh do not return it. The "Hostile fleet heading for an anomaly" alert and the Movements page show it.

The alerts

Function	Returns
`WaitOrionAlert(seconds)`	2: the alert and a boolean	Waits for an alert of the module, zero to wait forever. The boolean says whether it came.

Value	Contains
`OnOrionAlertCh`	a channel	The same alerts, read with `a = <-OnOrionAlertCh`.

An alert carries Text, its sentence, and Kind, one of these names:

Value of `Kind`
`"lithium_cap"`	The lithium has reached its cap.
`"rewards"`	A finished mission is waiting to be claimed.
`"rewards_lost"`	Rewards are lost: the time to claim them has passed.
`"combat"`	A combat that was taken has no fleet.
`"delivery"`	A delivery that was taken has no fleet.
`"threat"`	A hostile fleet is heading for an anomaly.

These are the ones the worker raises at its pass, ticked or not in the Notifications: with the worker off none comes, and they cost no request.

for {
	a, seen = WaitOrionAlert(600)
	if !seen { continue }
	if a.Kind == "rewards" {
		SendDiscord(a.Text)
	}
}

The Control Centre

These functions, like the slot functions below, work with the Orion worker off. On a universe without Orion, they return an error and nothing reaches the game.

Function	Returns
`OrionControlCenter(celestial)`	2: a list and an error	Reads the Control Centre tab of a planet that has a scanner: one request, no token used.

Each row has ID (4001 to 4007), Name (the game's name, in the account's language), Level, Bonus, Locked and UnlockLevel (the mission to complete to open it).

To build one, add a line: AddItemToQueue(celestial, 4001, 5). The Brain never starts one of these buildings on its own, nor while it is locked: the line waits, marked on screen.

Slots

Function	Returns
`OrionSlotPrices(celestial)`	2: a structure and an error	The price of the next slot of each kind, read from this planet's scanner tab: `AnomalyDiscovery` and `ScanResult`, each with `Metal`, `Crystal`, `Deuterium`, `Maxed` (the game sells no more) and `Unreadable`.
`OrionBuySlot(kind, celestial)`	1: an error	Buys a slot, paid by this planet: `"anomalyDiscovery"` (one more anomaly investigated at a time) or `"scanResult"` (one more result per scan).

The price is read again right before the purchase. Nothing leaves on a price that cannot be read, or that names anything other than metal, crystal and deuterium: never dark matter. The paying planet must have a scanner. Missing resources come back as an error (game code 100047), and so does the cap (code 100017). A purchase never replays by itself: after an error, read the price again before retrying, it may have gone through.

Raising the scanners

Function	Returns
`OrionProfitableScannerLevel()`	1: an integer	The highest scanner level whose credited lithium is worth more than converting the same price, on this universe: 16 at speed 8, 17 at speed 10. No request.
`OrionEqualizeScanners(levels, sum)`	2: a list and an error	Spreads a sum of levels across scanners at the lowest cost, lowest first: `[5, 1, 3]` towards a sum of 12 returns `[5, 4, 3]`. A calculation, no request, ignoring the planets' fields.

The maximum anomaly level is the sum of the scanners, according to players: the game does not write it.

← Workers Orion: value →