<function name="Iterator" parent="player" type="libraryfunc"> <description> Returns a [Stateless Iterator](https://www.lua.org/pil/7.3.html) for all players on the server. Intended for use in [Generic For Loops](https://www.lua.org/pil/4.3.5.html). See <page>ents.Iterator</page> for a similar function for all entities. Internally, this function uses cached values that exist entirely within lua, as opposed to <page>player.GetAll</page>, which is a C++ function. Because switching from lua to C++ (and vice versa) incurs a performance cost, this function will be somewhat more efficient than <page>player.GetAll</page>. <note>The <page>GM:OnEntityCreated</page> and <page>GM:EntityRemoved</page> hooks are used internally to invalidate this function's cache. Using this function inside those hooks is not guaranteed to use an up-to-date cache because hooks are currently executed in an arbitrary order.</note> <warning>An error being thrown inside the <page>GM:OnEntityCreated</page> or <page>GM:EntityRemoved</page> hooks is likely to break this function. Make it certain that no addons are causing any errors in those hooks.</warning> <warning>Modifying the return table will affect all subsequent calls to this function until the cache is refreshed, replacing all of your player.GetAll usages may come with unintended side effects because of this.⤶ ⤶ Example of bad code:⤶ ```⤶ local scan_ents = select(2, player.Iterator())⤶ ⤶ table.Add(scan_ents, ents.FindByClass("ttt_decoy")) -- DO NOT DO THIS!!!⤶ ```⤶ </warning>⤶ </description> <added>2023.10.13</added> <realm>Shared</realm> <file line="314-L320">lua/includes/extensions/player.lua</file> <rets> <ret name="" type="function">The Iterator Function from <page text="ipairs">Global.ipairs</page></ret> <ret name="" type="table">Table of all existing <page text="Players">Player</page>. This is a cached copy of <page>player.GetAll</page></ret>⤶ <ret name="" type="table">Table of all existing <page text="Players">Player</page>. This is a cached copy of <page>player.GetAll</page>⤶ <warning>This table is intended to be read-only.⤶ ⤶ Modifying the return table will affect all subsequent calls to this function until the cache is refreshed, replacing all of your player.GetAll usages may come with unintended side effects because of this.⤶ ⤶ Example of bad code:⤶ ```⤶ -- NEVER DO THIS!!!⤶ ⤶ local scan_ents = select(2, player.Iterator())⤶ ⤶ table.Add(scan_ents, ents.FindByClass("ttt_decoy"))⤶ ```⤶ </warning>⤶ </ret>⤶ <ret name="" type="number"> The starting index for the table of players. This is always `0` and is returned for the benefit of [Generic For Loops](https://www.lua.org/pil/4.3.5.html) </ret> </rets> </function> <example> <description>Example usage of this function.</description> <code> for _, ply in player.Iterator() do print( ply ) end </code> <output>Prints out all players to the console.</output> </example>