Garry's Mod Wiki

ents

The ents library provides functions for creating and finding entities in the game.

Methods

Entity ents.Create( string class )
Creates an entity. This function will fail and return NULL if the networked-edict limit is hit (around 8176), or the provided entity class doesn't exist. Do not use before GM:InitPostEntity has been called, otherwise the server will crash! If you need to perform entity creation when the game starts, create a hook for GM:InitPostEntity and do it there.
Entity ents.CreateClientProp( string model = "models/error.mdl" )
Creates a clientside only prop. See also ClientsideModel. For physics to work you must use the model argument, a simple SetModel call will not be enough. Parented clientside prop will become detached if the parent entity leaves the PVS. A workaround is available on its github page. Issue Tracker: 861
Creates a clientside only scripted entity. The scripted entity must be of "anim" type.
table ents.FindAlongRay( Vector start, Vector end, Vector mins = nil, Vector maxs = nil )
Returns a table of all entities along the ray. The ray does not stop on collisions, meaning it will go through walls/entities. This internally uses a Spatial Partition to avoid looping through all entities.
table ents.FindByClass( string class )
Gets all entities with the given class, supports wildcards. This works internally by iterating over ents. GetAll. Even if internally ents. GetAll is used, It is faster to use ents. FindByClass than ents. GetAll with a single class comparison. Asterisks (*) are the only wildcard supported. This function returns a sequential table, meaning it should be looped with ipairs instead of pairs for efficiency reasons.
table ents.FindByClassAndParent( string class, Entity parent )
Finds all entities that are of given class and are children of given entity. This works internally by iterating over ents. GetAll.
table ents.FindByModel( string model )
Gets all entities with the given model, supports wildcards. This works internally by iterating over ents. GetAll.
table ents.FindByName( string name )
Gets all entities with the given hammer targetname. This works internally by iterating over ents. GetAll. Doesn't do anything on client.
table ents.FindInBox( Vector boxMins, Vector boxMaxs )
Returns all entities within the specified box. This internally uses a Spatial Partition to avoid looping through all entities. Clientside entities will not be returned by this function. There is a limit of 512 entities for the output!
table ents.FindInCone( Vector origin, Vector normal, number range, number angle_cos )
Finds and returns all entities within the specified cone. Only entities whose Entity:WorldSpaceCenter is within the cone are considered to be in it. The "cone" is actually a conical "slice" of an axis-aligned box (see: ents. FindInBox). The image to the right shows approximately how this function would look in 2D. Due to this, the entity may be farther than the specified range! Clientside entities will not be returned by this function. If there are more than 512 entities in the axis-aligned box around the origin, then the result may be incomplete!
table ents.FindInPVS( any viewPoint )
Finds all entities that lie within a PVS (Potential Visibility Set). The function won't take in to account AddOriginToPVS and the like.
table ents.FindInSphere( Vector origin, number radius )
Gets all entities within the specified sphere. This internally uses a Spatial Partition to avoid looping through all entities. Clientside entities will not be returned by this function. This function internally calls ents. FindInBox with some radius checks.
ents.FireTargets( string target, Entity activator, Entity caller, number usetype, number value )
Fires a use event.
table ents.GetAll()
Returns a table of all existing entities. Consider using ents. Iterator instead for better performance. This function returns a sequential table, meaning it should be looped with ipairs instead of pairs for efficiency reasons.
Entity ents.GetByIndex( number entIdx )
Returns an entity by its index. Same as Entity.
number ents.GetCount( boolean IncludeKillMe = false )
Gives you the amount of currently existing entities. Similar to #ents. GetAll() but with better performance since the entity table doesn't have to be generated. If ents. GetAll is already being called for iteration, than using the # operator on the table will be faster than calling this function since it is JITted.
Returns the amount of networked entities, which is limited to 8192. ents. Create will fail somewhere between 8064 and 8176 - this can vary based on the amount of existing temp ents.
Returns entity that has given Entity:MapCreationID.
Returns a Stateless Iterator for all entities. Intended for use in Generic For Loops. See player. Iterator for a similar function for all players. Internally, this function uses cached values that exist entirely within lua, as opposed to ents. GetAll, 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 ents. GetAll. The GM:OnEntityCreated and GM:EntityRemoved 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. An error being thrown inside the GM:OnEntityCreated or GM:EntityRemoved hooks is likely to break this function. Make it certain that no addons are causing any errors in those hooks.