ReadMapList

Last Updated2015-10-30

Created At2007-12-02

Loads a map list to an ADT Array. A map list is a list of maps from a file. SourceMod allows easy configuration of maplists through addons/sourcemod/configs/maplists.cfg. Each entry is given a name and a file (for example, "rtv" => "rtv.cfg"), or a name and a redirection (for example, "rtv" => "default"). This native will read a map list entry, cache the file, and return the list of maps it holds. Serial change numbers are used to identify if a map list has changed. Thus, if you pass a serial change number and it's equal to what SourceMod currently knows about the map list, then SourceMod won't re-parse the file. If the maps end up being read from the maps folder (MAPLIST_FLAG_MAPSFOLDER), they are automatically sorted in alphabetical, ascending order. Arrays created by this function are temporary and must be freed via CloseHandle(). Modifying arrays created by this function will not affect future return values or or the contents of arrays returned to other plugins.

native Handle ReadMapList(Handle array = INVALID_HANDLE, int& serial = -1, const char[] str = "default", int flags = 1 << 1)

Parameters

Handle array

Array to store the map list. If INVALID_HANDLE, a new blank array will be created. The blocksize should be at least 16; otherwise results may be truncated. Items are added to the array as strings. The array is never checked for duplicates, and it is not read beforehand. Only the serial number is used to detect changes.

int& serial

Serial number to identify last known map list change. If -1, the the value will not be checked. If the map list has since changed, the serial is updated (even if -1 was passed). If there is an error finding a valid maplist, then the serial is set to -1.

const char[] str

Config name, or "default" for the default map list. Config names should be somewhat descriptive. For example, the admin menu uses a config name of "admin menu". The list names can be configured by users in addons/sourcemod/configs/maplists.cfg.

int flags

MAPLIST_FLAG flags.

Return Value

Handle On failure: INVALID_HANDLE is returned, the serial is set to -1, and the input array (if any) is left unchanged. On no change: INVALID_HANDLE is returned, the serial is unchanged, and the input array (if any) is left unchanged. On success: A valid array Handle is returned, containing at least one map string. If an array was passed, the return value is equal to the passed Array Handle. If the passed array was not cleared, it will have grown by at least one item. The serial number is updated to a positive number.

Error

Invalid array Handle that is not INVALID_HANDLE.