<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). 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>Internally, this function uses cached values that are stored in Lua, as opposed to <page>player.GetAll</page>, which is a C++ function. Because a call operation from Lua to C++ *and* with a return back to Lua is quite costly, this function will be more efficient than <page>player.GetAll</page>.</note>⤶ </description> <added>2023.10.13</added> <realm>Shared</realm> <file line="13-L20">lua/includes/extensions/entity_iter.lua</file> <rets> <ret name="" type="function">The Iterator Function from <page text="ipairs">Global.ipairs</page></ret>⤶ <ret name="" type="table<Player>">Table of all existing <page text="Players">Player</page>. This is a cached copy of <page>player.GetAll</page>⤶ <ret name="" type="function">The Iterator Function from <page text="ipairs">Global.ipairs</page>.</ret>⤶ <ret name="" type="table<Player>">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:⤶ ⤶ An example:⤶ ``` -- NEVER DO THIS!!! ⤶ local scan_ents = select(2, player.Iterator()) ⤶ table.Add(scan_ents, ents.FindByClass("ttt_decoy")) -- Bad code. local scan_ents = select( 2, player.Iterator() ) table.Add( scan_ents, ents.FindByClass( "ttt_decoy" ) ) ⤶ -- Fine code. A copy of the table is being made and used.⤶ local scan_ents = table.Copy( 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) 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> <description>Prints out all players to the console.</description> <code> for _, ply in player.Iterator() do print( ply ) end </code> <output>Prints out all players to the console.</output>⤶ </example>