Add a system to allow selection of non-owned units

[GoogleFrog]

A lot of RTS engines allow the selection of enemy and allied units. Usually this just gives the player an expanded tooltip for the unit, but it can also be used for game mechanics. For example, a bounty system for a FFA mode would be cleanest to implement by selecting enemies and clicking buttons on the UI to configure how much bounty you want to pay. Selecting some allied units could also be good for team games.

LuaUI can probably hack enemy selection in at the moment, but it would be fragile and involve essentially reimplementing the concept of selection. Engine support would be more robust. Selecting enemies prettymuch already works when spectating, or with /godmode enabled. The engine would be good for:

• Setting filters on what can be selected.
• Handling state changes that could cause deselection (eg going outside LOS).
• Sending commands to selected units.

Responsibility for legal selection shouldn't be left up to luaUI, as it is user-space rather than game mechanics-space.

Setting a selection filter could look something like this: Spring.SetUnitSelectable(unitID, playerID, canSelect, visionMask, canCommand, canSeeCommands)

• unitID specifies the unit.
• playerID is for specifying players. This could potentially be used by spectators too to let them send some commands. It would often be convinient for this to be teamID or even allyTeamID, but playerID seems like the most natural and powerful.
• canSelect is a boolean that determines whether to allow selection.
• visionMask is a bit mask (0-15) for the vision state required for this playerID to select the unit. The bits here are ANDed with the vision state. When the vision state of a unit changes, the unit should be rechecked and possibly deselected (sort of as if it had died).
• canCommand is whether commands issued by the player are allowed. gadget:AllowCommand can handle the commands from there. This callin already has a playerID argument.
• canSeeCommands would set whether the commands of the selected unit are accessible, both to luaUI and to the default hold-shift system. This would include Spring.DrawUnitCommands.

The vision mask and command visibility toggle should be luaRules-side because there is potential for widgets to hack information out of selecting unseen enemies. Once a unit is allowed to be selected, further filtering can happen in luaUI with widget:SelectionChanged. Eg the engine will allow mixed selections of allied and enemy units, but games can implement selection filtering in luaUI.

Spectators could even use this system of commanding "enemy" units. Eg, some meme tournament could let spectators have a subtle effect on units to support their favorite player. This could be done with luarules messages, but why do that when commands already exist.

[sprunk]

Some commentary:

• Spring.SetUnitNoSelect exists. Perhaps the engine can just assume everything can be selected all the time, but behave as if this was called with false on units outside your own team first. So if you never call it for enemies they would stay unselectable as with current, but Lua could set it to true, for selection of enemy units. A bitmask for vision would make sense as a new parameter (with backward compatibility since the currently-applicable own units are always in los anyway).
• perhaps there's room for gadget:AllowUnitSelect(unitID, playerID) that works the same way AllowUnitCommand does, and Spring.SetUnitNoControl that works the same way SetUnitNoSelect does (up to working on own units, and including the comment above about enemy units). A difference would be that commands are synced while selection is unsynced.
• Script.Get{Select,Ctrl}Team functions exist and return a single teamID (or a special value that means none/all). Perhaps they should return a table, and there would be setters for each of those, and they would reflect the sort of default starting state for units of those teams. For example, if you're initially team 3, then Script.GetCtrlTeam returns {3} initially and units belonging to team 3 start with the "controllable by " bit set to true, but you can call Spring.SetUnitNoControl(some_unit_of_team_3, false) or Spring.SetUnitNoControl(some_unit_of_team_7, true) on specific units. Then if you do, say, Script.SetCtrlTeam(7, true) new units from team 7 will also start with the bit set to true, etc. This default would also apply if units change hands (capture, share etc) to maintain backward compatibility (don't want to keep control of captured units, or not gain it if you're the one capturing) since Lua can refresh the desired state in appropriate callins.
• GoogleFrog's canSeeCommands would be the third part of the family - Spring.SetUnitNoRead, gadget:AllowUnitRead and Script.GetReadTeam and could affect other things that are currently not available for enemy units (so not just order queue but also decoy health, firestate and movestate, stockpile...).

[GoogleFrog]

I wrote down the idea that led to this feature request: https://zero-k.info/Forum/Thread/36119?postID=256736

[GoogleFrog]

perhaps there's room for gadget:AllowUnitSelect(unitID, playerID) that works the same way AllowUnitCommand does ... gadget:AllowUnitRead

I think it would be better to let luarules set some fairly powerful filters, rather than use callins. LuaUI might want to rapidly read or mess with what is selected. Going through luarules each time that happens seems like a lot of overhead, and I can't imagine a scenario when it would be required over filtering. Remember, fancy stuff like selection filtering shouldn't be in luarules, that can be done in luaUI once luarules determines what is even legal.

[icexuick]

Would be handy for selecting a group/army of an ally and ask to get/give/sell the selected allied units.

Might be a bad idea, but we're recently exploring a "unit market" widget where you can select your own units and offer them for 'sale'. Allies can then decide to buy units, and will transfer them if the buyer has enough resources.

Other way around, asking to buy, could be interesting here.