beyond-all-reason / beyond-all-reason/RecoilEngine
Feature request: table-less GiveOrder for multi-param orders
- Dominant language
- C++
- Stars
- 679
- Forks
- 290
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 40
Description
The request would be to add a new family of GiveOrder functions where the params are at the end. This is to avoid making a table or passing a fake arg, since params are variadic.
Compare (the `123` arg is the timeout, whose existence seems not widely known):
```lua
-- basic variant: no convenience, but still avoid a table
Spring.GiveOrder(CMD.MOVE, {x, y, z}, CMD.OPT_SHIFT, 123)
Spring.GiveOrderFlat(CMD.MOVE, CMD.OPT_SHIFT, 123, x, y, z)
-- stop command doesn't take parameters but a bogus arg (1337 here) is normally needed
Spring.GiveOrderToUnit(unitID, CMD.STOP, 1337, 0, 123)
Spring.GiveOrderToUnitFlat(unitID, CMD.STOP, 0, 123)
-- avoid nested tables
Spring.GiveOrderArrayToUnit( unitID, {
{ CMD.PATROL, {x + 100, y, z + 100}, 0, 123 },
{ CMD.PATROL, {x - 100, y, z - 100}, CMD.OPT_SHIFT, 123 }
}
Spring.GiveOrderArrayToUnitFlat( unitID, {
{ CMD.PATROL, 0, 123, x + 100, y, z + 100 },
{ CMD.PATROL, CMD.OPT_SHIFT, 123, x - 100, y, z - 100 }
}
```
Some remarks:
* a bunch of existing table-less functions accept a true/false arg to change the meaning of arguments or returns. I think that is bad because the bool is magic and would prefer a new function over a boolean arg.
* perhaps GiveOrder et al could just be changed to that convention without making a new function. Games can have back-compatibilty trivially:
```lua
local originalGiveOrder = Spring.GiveOrder
Spring.GiveOrder = function (cmdID, cmdParam, cmdOpts)
if type(cmdParam) == 'table' then
return originalGiveOrder(cmdID, cmdOpts, unpack(cmdParam))
else
return originalGiveOrder(cmdID, cmdOpts, cmdParam)
end
end
```
* this is how the inner command in CMD.INSERT already works. As in, it's already (for example):
```lua
Spring.GiveOrder(CMD.INSERT, {0, CMD.MOVE, CMD.OPT_SHIFT, x, y, z}, CMD.OPT_ALT)
```
* having variadic args at the end works nicely with the `unpack` function.
Contributor guide
Research direction
Start by locating the existing GiveOrder, GiveOrderFlat, GiveOrderToUnit, and GiveOrderArrayToUnit entry points, then compare their argument handling with the CMD.INSERT inner-command convention described here. Review the compatibility and boolean-argument alternatives before defining the intended API family; done means the convention and affected functions are agreed and the requested table-less multi-parameter calls work without fake arguments.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, lua
- Domain
- api, game-dev
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100