Lua API: getElements

[qaisjp]

People want an efficient way to get all elements matching a particular set of filters (e.g. on screen only in #4746), that doesn't involve looping over all elements in Lua and performing expensive checks.

I propose an expressive API that can be expanded to additional use cases in the future.

getElements({
  searchRoot = root,
  filterScreen = true,
  filterStreamedIn = true,
  filterTypes = {"vehicle", "player"}
})

Prior art

• getElementChildren supports a type filter
• getElementsByType supports getElementsByType(string theType, [element startat=getRootElement(), bool streamedIn=false])

How to roll this out

We should start simple and not try to do too much at once, especially so we can address @ArranTuna's needs in #4746 sooner rather than later.

[qaisjp]

One concern is that this function could be super expensive, or return strange types that people don't know how to handle.

I think we should make filterTypes and searchRoot required to start, to help keep the implementation simple. We can always relax restrictions later, but if we start with something that has too many defaults, it could trap us in a corner in terms of backwards compatibility.

getElements() -- ❌ not allowed, filter spec required
getElements({}) -- ❌ not allowed, searchRoot and filterTypes are required
getElements({searchRoot = root, filterTypes={"vehicle"}}) -- ✅ equivalent to getElementsByType("vehicle")
getElements({searchRoot = root, filterTypes={}}) -- It should return nothing

[qaisjp]

How should recursion work?

• Should we accept a recursive = true / recursive = false
• Should this be required?
  • getElementsByType (and many other functions) recurse by default, but getElementChildren is not recursive
  • If we have a default, should the default be recursive = true?

[Fernando-A-Rocha]

I think you don't need backwards compatibility with getElementsByType, getElements is a different new function that can work in its own way with defaults for ease of use.

[Fernando-A-Rocha]

I think searchRoot should be renamed to parentElement or startat like the argument's name in getElementsByType

[qaisjp]

Agreed, my comment about backwards compatibility is actually thinking ahead in case we want to change any behaviour in this function in the future.

[qaisjp]

parentElement seems good

[ArranTuna]

It might as well also have a range arg like getElementsWithinRange

[Fernando-A-Rocha]

Awesome idea yea
And also interior and dimension filters would be great

[CArg22]

filtering should support position, resource, model
specific for elements
vehicles: , occupants, damage, health
ped: health, weapons
colshape: type