beyond-all-reason / beyond-all-reason/RecoilEngine

Feature request: table-less GiveOrder for multi-param orders

Open
#580 3 comments 0 reactions 0 assignees View on GitHub
good first issue
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.