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

Def files vs `Unit/Weapon/FeatureDefs` keys design pass

Open
#801 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
679
Forks
290
Avg merge
3d 2h
Merged PRs (30d)
40

Description

Unit (and weapon/feature) def files accept a different set of values compared to the ones exposed in `UnitDefs` in wupgets.

For example, you might put `maxvelocity = 3` in `units/tank.lua`, but then in `wupgets/wupget.lua` when indexing the `UnitDefNames.tank` table the key is not `maxvelocity` but `speed` and the value you read is not `3` but `90` (because the unit changes from elmo/frame to elmo/second).

The request/task is let unit def files specify values in the same format and unit as is later exposed in `UnitDefs`. The previous value would still be accepted and be in the current unit. So for example the current
```cpp
speed = udTable.GetFloat("maxVelocity", 0.0f) * GAME_SPEED;
```
would instead become
```cpp
const decltype(speed) speed_legacy = udTable.GetFloat("maxVelocity", 0.0f) * GAME_SPEED;

speed = udTable.GetFloat("speed", speed_legacy);
^ ^ ^
│ │ └ no GAME_SPEED scaling, raw input
│ │
│ └ old value still accepted as a backup, for game convenience

└ key matches UnitDefs table in rts/Lua/LuaUnitDefs.cpp
```
Or, a precedent commit to illustrate: 11813e45b0a04b083dd2f29a5ec44df1078a3371

Open questions:
* should TA spellings of keys be deprecated eventually, since there would inevitably be two parallel standards in games where some won't migrate? Sprecoil doesn't really handle TA content out of the box anymore and it's simple to convert. Not in any haste though.
* perhaps the direct format should also perform brutal checks and crash on invalid data? So a valid value would always be exposed verbatim, otherwise fail early and fail hard. An example would be `health = -1`, currently this is processed into `0.1`.

Contributor guide

Open the contributing guide

Research direction

Compare the def-file keys and units with the exposed UnitDefs keys in rts/Lua/LuaUnitDefs.cpp, using units/tank.lua, wupgets/wupget.lua, and the shown speed-loading code as entry points. Review commit 11813e45b0a04b083dd2f29a5ec44df1078a3371 for precedent. Done means the supported direct-format keys and legacy fallbacks are defined, with decisions recorded for deprecation and invalid-value handling.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
game-dev
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.