PlayerList¶

Overview¶

An PlayerList provides access to all active PlayerEntities in the game world, as well as several methods to search for entities.

Info

All methods, except PlayerList.Self() return an array of PlayerEntities.

See each method for examples on how to use this list.

Functions¶

Self¶

function PlayerList.Self() -> PlayerEntity

Returns the PlayerEntity belonging to the currently logged in player character.

Returns	Description
PlayerEntity	A PlayerEntity.

Example

local self = PlayerList.Self()
-- Another way to get the logged in playerEntity
local self2 = Player.GetEntity()
-- self == self2

All¶

function PlayerList.All() -> [ PlayerEntity ]

Returns all active PlayerEntities in the game world in an array.

Returns	Description
[ PlayerEntity ]	An array of PlayerEntities.

Example

local allPlayers = PlayerList.All()
for _,playerEntity in ipairs(allPlayers) do
    if playerEntity.coordGrid == CoordGrid._0_50_50_32_32 then
        -- found a player at a specific coord
    end
end

ByUID¶

function PlayerList.ByUID(uid : Integer) -> [ PlayerEntity ]

Returns the PlayerEntity with the matching UID.

Parameter	Type	Description
uid	Integer	A valid UID value.

Returns	Description
[ PlayerEntity ]	An array of PlayerEntities.

Example

-- A UID obtained elsewhere
local targetPlayerUID = ...
local found = PlayerList.ByUID(targetPlayerUID)
if #found > 0 then
    -- Player was found
    local playerEntity = found[1]
    -- playerEntity.uid == targetPlayerUID
end

ByName¶

function PlayerList.ByName(name : String) -> [ PlayerEntity ]

Returns any PlayerEntity with a display name matching the given name value.

String matches are case-insensitive.
Matches are exact unless wildcard characters ? and/or * are provided.

Parameter	Type	Description
name	String	The string to match against `PlayerEntity.displayName`.

Returns	Description
[ PlayerEntity ]	An array of PlayerEntities.

Example

found = PlayerList.ByName("Durial321")
if #found > 0 then
    -- Run for your life!
end

ByDistance¶

function PlayerList.ByDistance(coordGrid : CoordGrid, range : Integer) -> [ PlayerEntity ]

Returns any PlayerEntity within range tiles of the given coordGrid value.

Exact coord matches should use a value of 0 for range.

Parameter	Type	Description
coordGrid	CoordGrid	The coord at which to centre the distance search.
range	Integer	The maximum tile distance from the given coord which an PlayerEntity must be.

Returns	Description
[ PlayerEntity ]	An array of PlayerEntities.

Example

found = PlayerList.ByDistance(CoordGrid._0_50_50_34_30, 4)
if #found > 0 then
    -- Found a player nearby the target coord
end

Filter¶

function PlayerList.Filter(filterSet : Table) -> [ PlayerEntity ]

Returns any PlayerEntity that matches all tests in the filterSet table.

Available tests are:

Key	Type	Description
uid	Integer	A valid entity UID. `{ uid = playerEntity.uid }` See PlayerList.ByUID()
name	String	A name to match against `PlayerEntity.displayName`. `{ name = "GIM" }` See PlayerList.ByName()
coordGrid	CoordGrid	A coord to test entity distance from. If `range` is not provided, the default value of `range` will be `0`. `{ coordGrid = CoordGrid._0_50_50_32_32 }` See PlayerList.ByDistance()
range	Integer	Ignored if `coordGrid` key is not provided. `{ range = 4 }` See PlayerList.ByDistance()
func	Function	A function which returns a boolean, and which takes a PlayerEntity as its only parameter. This function is called for every entity, and any call that returns `true` will include that PlayerEntity in the return array. `function eastFacingFinder(playerEntity) { return playerEntity.facing == 90 }` `{ func = eastFacingFinder }`

Tests can be combined as shown below:

-- Return all players within 10 tiles of 0_50_50_32_32 that have "GIM" in their display name
found = PlayerList.Filter( { name = "*GIM*", coordGrid = CoordGrid._0_50_50_32_32, range = 10 } )

Info

Tests are inclusive.
All must pass in order for the PlayerEntity to be included in the return array.

Parameter	Type	Description
filterSet	Table	A table of key-value pairs which describe individual tests to perform.

Returns	Description
[ PlayerEntity ]	An array of PlayerEntities.

Example

-- At coord 0_50_50_32_32

-- Filter all Players for the display names that include "GIM"
local foundByFilterName = PlayerList.Filter( { name = "*GIM*" } )

function westFacingFinder(player)
    return player.facing == 270
end

-- Filter all Players for those that pass the func 'westFacingFinder'
local foundByFilterFunc = PlayerList.Filter( { func = westFacingFinder } )

-- Filter all Players for those within 2 tiles of 0_50_50_32_32
local foundByFilterCoord = PlayerList.Filter( { coordGrid = CoordGrid._0_50_50_32_32, range = 2 } )

-- Filter all Players for those within 3 tiles of 0_50_50_9_10 with a display name that starts with "GIM"
local foundByFilterCoordAndName = NPCList.Filter( { coordGrid = CoordGrid._0_50_50_9_10, range = 3, name = "GIM*" } )