Entity and player searching - nsimplex/wicker GitHub Wiki

#Entity and player searching

The following are the functions provided by wicker to search general entities and players. Searching for players can also be done using the general entity search by requiring the tag "player", but the player specific search functions are much faster, since they only iterate over the list of players, instead of over all entities. Explanations are given after presenting both sets of functions, since they are very similar.

The explanations assume the following line of code is prepended to the top of any file using the mentioned functions.

Game = wickerrequire "game"

In Up and Away, this line is optional, since this is already done automatically for every mod file due to the setup within code/modenv.lua.

###General entity search

Game.FindAllEntities(center, radius, fn, and_tags, not_tags, or_tags)

Game.FindSomeEntity(center, radius, fn, and_tags, not_tags, or_tags)

Game.FindRandomEntity(center, radius, fn, and_tags, not_tags, or_tags)

Game.FindClosestEntity(center, radius, fn, and_tags, not_tags, or_tags)

Game.FindClosestEntities(center, radius, fn, max_count, and_tags, not_tags, or_tags)

###Player search

Game.FindAllPlayers(fn)

Game.FindSomePlayer(fn)

Game.FindRandomPlayer(fn)

Game.FindClosestPlayer(center, fn)

Game.FindClosestPlayers(center, fn, max_count)


Game.FindAllPlayersInRange(center, radius, fn)

Game.FindSomePlayerInRange(center, radius, fn)

Game.FindRandomPlayerInRange(center, radius, fn)

Game.FindClosestPlayerInRange(center, radius, fn)

Game.FindClosestPlayersInRange(center, radius, fn, max_count)

All functions have an alias obtained by replacing "Find" with "Get", e.g. GetAllPlayers(fn).

The parameters mean the following:

  • center: The center of the search, which should be a either a Point object or entity (in which case the entity's position will be taken as the center). For the FindClosest functions, this is also the point/entity to which the distance is compared.

  • radius: The radius of the search. It should be a non-negative number.

  • fn: An optional function used to select the desired entities. Each entity in the search space is passed to this function as its first and only argument; if the function returns false or nil, that entity is discarded. If fn is nil, all entities are accepted (provided they also have the tags according to the parameters and_tags, not_tags, or_tags, as explained below). fn can also be a string, in which case it is equivalent to the function function(inst) return inst.prefab == fn end.

  • max_count: The maximum number of elements in the table returned by the plural versions of the FindClosest functions.

  • and_tags, not_tags, or_tags: Optional tables specifying tags for the entities searched. and_tags specifies tags all of which the selected entities must have; or_tags specifies tags at least one of which the selected entities must have; not_tags specifies tags none of which the selected entities must have. These parameters are passed to TheSim:FindEntities(), being more efficient than (but functionally equivalent to) checking for tags in the fn parameter.

The FindAll functions return all entities satisfying the criteria as a (possibly empty) table, much like TheSim:FindEntities(). The FindSome functions return the first entity they find satisfying the criteria, or nil if there is no such entity; this is the fastest category of the search functions, and should be used when one only wants to check if there exists at least one entity satisfying some criteria. The FindRandom functions return a randomly selected entity satisfying the criteria, or nil if there is no such entity. The singular FindClosest functions (such as FindClosestEntity) return the closest entity to center satisfying the criteria, or nil if there is no such entity. The plural FindClosest functions (such as FindClosestEntities) return a table with the max_count closest entities satisfying the criteria (if there are less than max_count matches, they return a table with as many as there are, hence the max_ prefix in the name of this parameter).

The InRange player search variants simply restrict the search to a disk, instead of searching through all players in the game.

Whenever GetPlayer() was called in singleplayer-specific code, one of the FindPlayer(s) functions should be the desired replacement; though, in the case of the FindAll and the plural FindClosest functions, since they return a table the code should be adjusted to iterate over the elements of the table.

⚠️ **GitHub.com Fallback** ⚠️