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

Make LuaRulesParams nested and more flexible

Open
#2,419 0 comments 0 reactions 0 assignees View on GitHub
area: Lua API
Dominant language
C++
Stars
683
Forks
293
Avg merge
3d 2h
Merged PRs (30d)
40

Description

### Context

LuaRulesParams is the backend for game, unit, feature and team rulesParams/modParams.

Currrently can hold only bool, float and string values, but being able to hold other lua types like maybe integer, maybe arbitrary types (like lua usertypes or other engine types), and also nested tables would be desired.

The current implementation needs some changes to support this, and we should have a design before attempting an implementation. This requires some decisions.

There is also an ai api that needs to be improved to be able to access further types. To decide upon that, we have https://github.com/beyond-all-reason/RecoilEngine/issues/1057, but the ai api can also depend a bit on upcoming and future LuaRulesParams improvements.

### Related issues

- https://github.com/beyond-all-reason/RecoilEngine/issues/1057
- https://github.com/beyond-all-reason/RecoilEngine/issues/2045

### Decisions

So, there are several decision to be made:

#### LuaRulesParams needs to have the nesting concept.

It's already a table, but can't handle nested tables.

What could be the backend for that?

- Now depends on a `spring::unordered_map` to hold its children, but this can be too limiting and also maybe not very efficient as the strings would need to be hashed all the time.
- There's already `LuaParser`, used for customParams at the moment
- could both subsystems use the same backend?
- problem here is LuaParser doesn't have a good GetMap method, and only supports returning an `unordered_map` of `float` or `string` (no variant type)
- it allows determining the type of a child to boolean/number/string/table/nil.
- doesn't have visibility rules.
- would actually be possible to merge unit rulesParams/modParams and customParams

#### LuaRulesParams need to be able to hold other value types at its union.

- bool already present, but not supported completely as it's eventually represented as string.
- paramPath may need to be added, either as hash/int or string so a param knows its a container instead of literal.
- int could be supported even though it's not a real lua type at the version we use, it still can distinguish them in certain situations
- is holding arbitrary types feasible or desired? decisions over this can be deferred, but would also be great having a design that allows extending in the future.

#### Lua mixed dict/array tables makes things a bit awkward to support tables.

As a result a c++ backend supporting everything might get too unwieldy.

- could accept only `dict`
- could accept only pure `dict` or `array`
- could completely remake LuaRulesParams to actually use lua as backend.
- might be more error prone and less efficient.
- might need to hold the game dict at syncedLuaRules, and then allow other lua handles access to that through api. not sure this is generally done in the engine at the moment, or at all, and might be concerns around desyncs or breaching of the lua handle sandboxes.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the current LuaRulesParams backend and LuaParser, then compare the related decisions in issues #1057 and #2045. Evaluate nesting, supported value types, mixed dictionary/array tables, visibility rules, and possible Lua-backed storage. Done means a documented design resolving these choices and its relationship to the AI API.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, lua
Domain
backend-api-design, game-dev
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.