Oolite Bulletins

The system of ship groups in Oolite is currently murky, confusing, and almost certainly broken in several hard-to-overview ways. I have a set of changes intended to address this, but I could do with some feedback.

The old system works like this: each ship has a group ID. If the group ID is 0, the ship is not a member of a group. If the group ID is the same as the ship's entity ID, the ship is in some contexts considered the leader of the group.

Group IDs are set in, at least, the following contexts:

• All thargoids spawned by the system populator are one group, and all pirates spawned by the system populator are another group. Thargoid and pirate ships added by other means are not automatically added to a group.
• All escorts have their group ID set to the entity ID of their mothership. The mothership’s group ID is also set to its entity ID if it was previously zero, otherwise not. In addition, the mothership has a separate list of IDs of escorts. Some escort-related commands use this list, some use the group ID. In further addition, the escorts have the mothership set as their owner.
• Ships launched by a station using of the methods launchPolice, launchDefenseShip, launchScavenger, launchMiner, launchPirateShip, launchEscort, launchPatrol or launchShipWithRole: (but not launchShuttle or launchTrader) have their group ID set to the station’s entity ID. The station’s group ID is normally set to its own entity ID.
• If a ship attacks a member of its own group (and is not forgiven, which depends on a random roll and the bounty of the target), it is expelled from the group, unless the attacking ship is the leader of the group, in which case the attacked ship leaves the group.
• Missiles are put in the same group as their launcher.
• If a ship dies, and it has escorts, and its ID is reused for a new ship, the old ship’s escorts will think the new ship is their mummy. Conversely, if an escort dies, and its ID is reused, the old escort’s mothership will think the new ship is one of its escorts. (This kind of thing is a fundamental problem with the entity ID system, which is why I’ve been gradually moving away from it.)

My proposed reform looks as follows:

• Groups are stand-alone objects which track their members.
• A ship can be a member of arbitrarily many groups, but also has a “main” group represented by its group property, and an “escort group” consisting of itself and its escorts. An escort’s group property is the escort group of its parent.
• A group may optionally have a leader, initially used for escort groups. The leader is always a member of the group.
• Each group has a name, purely to make debugging easier.
• It may be worth adding a separate “auxiliary group” for a station’s scavengers and miners.
• Group objects will be exposed to JavaScript. The current Ship.groupID property will be removed (with no deprecation period, since the underlying groupID property no longer exists). Additionally, the Entity.ID property will be deprecated, since I want to eventually eliminate all uses of entity IDs.

It’s hard to analyze exactly how this will change game behaviour, but I believe it will mostly resolve unexpected behaviours.

Another issue is how it will change AI semantics. The following methods are particularly significant. (Note: “AI ship” below means the ship the method is being called on, i.e. the ship the AI is attached to.)

• wormholeEscorts – old behaviour was to go through a list of element IDs for escorts, look up the corresponding entity for each ID and, if it’s a ship, set its target to the AI ship’s destination wormhole and send it an “ENTER WORMHOLE” AI message. Proposed new behaviour is to go through the AI ship’s escort group and do the same thing for each ship that isn’t the AI ship itself.
• wormholeGroup – old behaviour was to look for every ship whose group ID matches the AI ship’s entity ID, and tell it to wormhole as above. I’m not entirely sure what to do with this one, see below.
• wormholeEntireGroup – old behaviour was to look for every ship whose group ID matches the AI ship’s group ID, and tell it to wormhole as above. If the AI ship has escorts and is not a member of a wolfpack or thargoid swarm, this means the same as wormholeEscorts. If it is a member of a group other than its own escorts, it will wormhole the group but not the escorts. For a station/carrier whose group ID is its entity ID, this will wormhole all the carrier’s defense ships, patrol ships, miners, scavengers etc. Proposed new behaviour: wormhole the AI ship’s group and escortGroup.

wormholeGroup’s behaviour is weird, and probably accidental. It will wormhole escorts as well as carrier/station auxiliaries, unless the AI ship is a member of a group other than its escort group, in which case it will do nothing. For the first thargoid and the first pirate added by the system populator, it will instead wormhole every thargoid or pirate.

The only use of wormholeGroup in built-in AIs is in pirateAI.plist: "WITCHSPACE OKAY" = (wormholeEscorts, wormholeGroup);. In light of that a reasonable new behaviour would be to wormhole only the group (i.e., peers) and not the escortGroup, making wormholeEntireGroup equivalent to (wormholeEscorts, wormholeGroup). Another option would be to make wormholeGroup equivalent to wormholeEntireGroup. It sort of depends how these commands are used by existing OXP AIs, and what the authors thought they meant.

I guess I should, at some point, download every OXP in existence and index all their AIs and scripts. Maybe when EliteWiki is back on a real host. :-)

I don't think wormholeGroup is used in many scripts. As a script can't generate groups this command is probably never intentionally used. It is in pirateAI as you say, but currently that part of the code is never executed. Certainly not in the current versions, but I can't remember having seen pirate ships wormhole in 1.65.
When the command is in other AI, it is probably a modified copy of the pirateAI and is used for a non group ship. So even when the wormhole behaviour changes a bit, I don't think the script will notice it because there are no group members.

Currently stations never have the groupID set themselves so they won't get the “ENTER WORMHOLE” message. But even so, I don't think anyone will have a station script that will react on that message. So there is no need for treating stations as exception: it will be the responsibility of the AI writer to handle this well. One can even make a station broadcast a farewell response to its members upon receiving the “ENTER WORMHOLE” message.
Even setting a destination to the wormhole for a station is no problem as I can't think of a situation were a station does something with a destination.

Same for scavengers and miners: They probably should get also the message to not have to deal with exceptions, and its up to the AI to deal with the message. By default the AI should not handle it. Only issue could be a carrier that enters a wormhole. But let a scripters deal with when he gives a carrier miners/scavengers and wants the miners/scavengers follow it. e.g. by giving those ships a custom AI on launch.

wormholeEscorts is probably more often used and will be unchanged in behaviour if I read your words right.

wormholeEntireGroup should be the same as wormholeGroup. For my feeling I always would expect that when I wormole a group, any groupmember with escorts will also take its escorts along.

Probably we also need a AI command to leave a group. e.g. when a pirate has a full hold it will become a trader a some point. I think it should be able to leave the group at that point. An other problem are of course group members that are scattered over the system after a fight. e.g. a pirate in combat wandering of from the group. It will never be able to reach the wormhole in time, so maybe only group members in scanner range should get a message?

In general I only see benefits for a change when this prevents the ID bugs you refer to.

I think groups may need to be members of groups. If I imagine ship A flying in group 1 and ship B escorting ship A, then we want ship A and B in group 2 and group 2 to be a member of group 1. I think.

I am not sure that this works properly if ships can be in multiple groups, but without hierarchy.

I don’t see a need for group 2 to be a member of group 1. Forwarding group actions from group 1 to group to is the responsibility of ship A.

If ship A is killed, then what happens to group 2? Does it somehow get merged into group 1?

It becomes a leaderless group. When and if the escorts perform a escortCheckMother, they’ll find they no longer have a mothership and start looking for a new one, or whatever their AIs do in that case. This matches current behaviour.

Maybe only leaders (escorts-key in shipdata) should have the right to be in more than one group to get some kind of battle-groups.
If the leader gets lost, the escort has to ask for a new leader (from lost mommies battle-group) and gets another group membership - if accepted.

I'd also suggest to change the handling for escorts. It doesn't make sense that a escort always knows where it's mommy is - even if millions kms away.
So a range-check would make sense for me (maybe 2x scanner range).

Some kind of hierarchy would make things more clear for scripters.

EDIT: You were a bit faster, Ahruman.

Ahruman wrote:

Additionally, the Entity.ID property will be deprecated, since I want to eventually eliminate all uses of entity IDs.

Does it mean that a entity doesn't have a unique (numeric) identifier then? This is currently a very nice way to identify entites or to react depending on odd/even.