Garry's Mod Wiki

ENTITY

A list of hooks only available for Scripted Entities.

The exceptions to this rule are documented at Custom Entity Fields, which can be applied to all entities.

Some more "hooks" are available for all entities (including engine entities) with the function Entity:AddCallback.

See also: ENT structure

The hooks listed here are also dependent on the scripted entity type. For instance, a base scripted entity will not use ENTITY:DoSchedule at all, that is only for scripted NPCs

Inherits methods from Entity.

Events

boolean ENTITY:AcceptInput( string inputName, Entity activator, Entity caller, string data )
Called when another entity fires an event to this entity.
A helper function for creating Scripted Entities. Similar to ENTITY:AddOutputFromKeyValue, call it from ENTITY:AcceptInput and it'll return true if it successfully added an output from the passed input data.
A helper function for creating Scripted Entities. Call it from ENTITY:KeyValue and it'll return true if it successfully added an output from the passed KV pair.
Called whenever the entity's position changes. A callback for when an entity's angle changes is available via Entity:AddCallback. Like ENTITY:RenderOverride, this hook works on any entity (scripted or not) it is applied on. If EFL_DIRTY_ABSTRANSFORM is set on the entity, this will be called serverside only; otherwise, this will be called clientside only. This means serverside calls of Entity:SetPos without the EFL_DIRTY_ABSTRANSFORM flag enabled (most cases) will be called clientside only. The give concommand will call this hook serverside only upon entity spawn.
boolean ENTITY:CanProperty( Player ply, string property )
Controls if a property can be used on this entity or not. This hook will only work in Sandbox derived gamemodes that do not have SANDBOX:CanProperty overridden. This hook will work on ALL entities, not just the scripted ones (SENTs)
boolean ENTITY:CanTool( Player ply, table tr, string toolname, table tool, number button )
Controls if a tool can be used on this entity or not. This hook will only work in Sandbox derived gamemodes that do not have SANDBOX:CanTool overridden. This hook will work on ALL entities, not just the scripted ones (SENTs)
This is used internally - although you're able to use it you probably shouldn't. Called just before ENTITY:Initialize for "ai" type entities only.
boolean ENTITY:DoImpactEffect( table tr, number damageType )
Called so the entity can override the bullet impact effects it makes. This is called when the entity itself fires bullets via Entity:FireBullets, not when it gets hit. This hook only works for the "anim" type entities.
Called by the default base_ai SNPC, checking whether ENT. bDoingEngineSchedule is set by ENTITY:StartEngineSchedule. . This is a helper function only available if your SENT is based on base_ai
ENTITY:DoSchedule( table sched )
Runs a Lua schedule. Runs tasks inside the schedule.
ENTITY:Draw( number flags )
Called if and when the entity should be drawn opaquely, based on the Entity:GetRenderGroup of the entity. See ENT structure and RENDERGROUP enum for more information. See also ENTITY:DrawTranslucent. This function is not called by the game whenever the player looks away from the entity due to optimizations. To change that, you must define an empty Entity:Think method client-side!
ENTITY:DrawTranslucent( number flags )
Called when the entity should be drawn translucently. If your scripted entity has a translucent model, it will be invisible unless it is drawn here.
ENTITY:EndTouch( Entity entity )
Called when the entity stops touching another entity. This only works for brush entities and for entities that have Entity:SetTrigger set to true.
Called whenever an engine schedule is finished; either the last task within the engine schedule has been finished or the schedule has been interrupted by an interrupt condition. This hook only exists for ai type SENTs. This hook isn't called when the engine schedule is failed, the schedule is cleared with NPC:ClearSchedule or NPC:SetSchedule has been called.
ENTITY:ExpressionFinished( string strExp )
Called when an NPC's expression has finished. This hook only exists for ai type SENTs.
boolean ENTITY:FireAnimationEvent( Vector pos, Angle ang, number event, string name )
Called before firing clientside animation events, such as muzzle flashes or shell ejections. See ENTITY:HandleAnimEvent for the serverside version. This hook only works on "anim", "nextbot" and "ai" type entities.
number ENTITY:GetAttackSpread( Entity wep, Entity target )
Called to determine how good an NPC is at using a particular weapon. "ai" base only
Called when scripted NPC needs to check how he "feels" against another entity, such as when NPC:Disposition is called.
Specify a mesh that should be rendered instead of this SENT's model.
Called when the shadow needs to be recomputed. Allows shadow angles to be customized. This only works for anim type entities.
Called every second to poll the sound hint interests of this SNPC. This is used in conjunction with other sound hint functions, such as sound. EmitHint and NPC:GetBestSoundHint. This hook only exists for ai type SENTs
Called by GM:GravGunPickupAllowed on ALL entites in Sandbox-derived gamemodes and acts as an override.
boolean ENTITY:GravGunPunt( Player ply )
Called when this entity is about to be punted with the gravity gun (primary fire). Only works in Sandbox derived gamemodes and only if GM:GravGunPunt is not overridden.
ENTITY:HandleAnimEvent( number event, number eventTime, number cycle, number type, string options )
Called before firing serverside animation events, such as weapon reload, drawing and holstering for NPCs, scripted sequences, etc. See ENTITY:FireAnimationEvent for the clientside version. This hook only works on "anim", "ai" and "nextbot" type entities.
boolean ENTITY:ImpactTrace( table traceResult, number damageType, string customImpactName = "nil" )
Called when a bullet trace hits this entity and allows you to override the default behavior by returning true.
ENTITY:Initialize()
Called when the entity is created. This is called when you Entity:Spawn the custom entity. This is called after ENTITY:SetupDataTables and GM:OnEntityCreated.
boolean ENTITY:IsJumpLegal( Vector startPos, Vector apex, Vector endPos )
Called when deciding if the Scripted NPC should be able to perform a certain jump or not. This is only called for "ai" type entities
boolean ENTITY:KeyValue( string key, string value )
Called when the engine sets a value for this scripted entity. This hook is called before ENTITY:Initialize when the key-values are set by the map. Otherwise this hook will be called whenever Entity:SetKeyValue is called on the entity. See GM:EntityKeyValue for a hook that works for all entities. See WEAPON:KeyValue for a hook that works for scripted weapons.
ENTITY:NextTask( table sched )
Start the next task in specific schedule. This hook only exists for ai type SENTs.
ENTITY:OnChangeActiveWeapon( Weapon old, Weapon new )
Called when the currently active weapon of the SNPC changes. This hook only works on ai type entities.
ENTITY:OnChangeActivity( number act )
Called when the NPC has changed its activity. This hook only works for ai type entities.
ENTITY:OnCondition( number conditionID )
Called each time the NPC updates its condition. This hook only exists for ai type SENTs.
ENTITY:OnDuplicated( table entTable )
Called on any entity after it has been created by the duplicator and before any bone/entity modifiers have been applied. This hook is called after ENTITY:Initialize and before ENTITY:PostEntityPaste.
Called after duplicator finishes saving the entity, allowing you to modify the save data. This is called after ENTITY:PostEntityCopy.
Called when the SNPC completes its movement to its destination. This hook only works on ai type entities.
Called when the SNPC failed to move to its destination. This hook only works on ai type entities.
ENTITY:OnReloaded()
Called when the entity is reloaded by the lua auto-refresh system, i. e. when the developer edits the lua file for the entity while the game is running.
ENTITY:OnRemove( boolean fullUpdate )
Called when the entity is about to be removed. See also Entity:CallOnRemove, which can even be used on engine (non-Lua) entities. ExampleCreate an explosion when the entity will be removed. To create an entity, you can read ents. Create. function ENT:OnRemove() local explosion = ents. Create( "env_explosion" ) -- The explosion entity explosion:SetPos( self:GetPos() ) -- Put the position of the explosion at the position of the entity explosion:Spawn() -- Spawn the explosion explosion:SetKeyValue( "iMagnitude", "50" ) -- the magnitude of the explosion explosion:Fire( "Explode", 0, 0 ) -- explode end
ENTITY:OnRestore()
Called when the entity is reloaded from a Source Engine save (not the Sandbox saves or dupes) or on a changelevel (for example Half-Life 2 campaign level transitions). For the duplicator callbacks, see ENTITY:OnDuplicated.
ENTITY:OnStateChange( number oldState, number newState )
Called by the engine when NPC's state changes. This hook only exists for ai type SENTs.
Called when the entity is taking damage. Calling Entity:TakeDamage, Entity:TakeDamageInfo, Entity:DispatchTraceAttack, or Player:TraceHullAttack (if the entity is hit) in this hook on the victim entity can cause infinite loops since the hook will be called again. Make sure to setup recursion safeguards like the example below. This hook is only called for ai, nextbot and anim type entities.
ENTITY:OnTaskComplete()
Called from the engine when TaskComplete is called. This allows us to move onto the next task - even when TaskComplete was called from an engine side task. This hook only exists for ai type SENTs.
ENTITY:OnTaskFailed( number failCode, string failReason )
Called when a task this NPC was running has failed for whatever reason. This hook only exists for ai type SENTs.
boolean ENTITY:OverrideMove( number interval )
Called to completely override NPC movement. This can be used for example for flying NPCs. This hook only exists for ai type SENTs.
boolean ENTITY:OverrideMoveFacing( number interval, table data )
Called to completely override NPC movement facing. This hook only exists for ai type SENTs.
Polls whenever the entity should trigger the brush. This hook is broken and will not work without code below
ENTITY:PhysicsCollide( table colData, PhysObj collider )
Called when the entity collides with anything. The move type and solid type must be VPHYSICS for the hook to be called. If you want to use this hook on default/engine/non-Lua entites ( like prop_physics ), use Entity:AddCallback instead! This page describes a hook for Lua entities
Vector, Vector, number ENTITY:PhysicsSimulate( PhysObj phys, number deltaTime )
Called from the Entity's motion controller to simulate physics. This will only be called after using Entity:StartMotionController on a scripted entity of anim type. This hook can work on the CLIENT if you call Entity:StartMotionController and use Entity:AddToMotionController on the physics objects you want to controlDo not use functions such as PhysObj:EnableCollisions or PhysObj:EnableGravity in this hook as they're very likely to crash your game. You may want to use ENTITY:PhysicsUpdate instead.
ENTITY:PhysicsUpdate( PhysObj phys )
Called whenever the physics of the entity are updated. This hook won't be called if the Entity's PhysObj goes asleep
ENTITY:PostEntityCopy()
Called after the duplicator finished copying the entity. See also ENTITY:PreEntityCopy and ENTITY:PostEntityPaste.
ENTITY:PostEntityPaste( Player ply, Entity ent, table createdEntities )
Called after the duplicator pastes the entity, after the bone/entity modifiers have been applied to the entity. This hook is called after ENTITY:OnDuplicated. See also ENTITY:PreEntityCopy.
ENTITY:PreEntityCopy()
Called before the duplicator copies the entity. If you are looking for a way to make the duplicator spawn another entity when duplicated. (For example, you duplicate a prop_physics, but you want the duplicator to spawn prop_physics_my), you should add prop_physics. ClassOverride = "prop_physics_my". The duplication table should be also stored on that prop_physics, not on prop_physics_my. See also ENTITY:PostEntityCopy.
ENTITY:RenderOverride( number flags )
Called instead of the engine drawing function of the entity. This hook works on any entity (scripted or not) it is applied on. This does not work on "physgun_beam", use GM:DrawPhysgunBeam instead. As a downside of this implementation, only one RenderOverride may be applied at a time. Drawing a viewmodel in this function will cause GM:PreDrawViewModel, WEAPON:PreDrawViewModel, WEAPON:ViewModelDrawn, GM:PostDrawViewModel, and WEAPON:PostDrawViewModel to be called twice. Issue Tracker: 3292This is called before PrePlayerDraw for players. If this function exists at all on a player, their worldmodel will always be rendered regardless of PrePlayerDraw's return. Issue Tracker: 3299
ENTITY:RunAI()
Called from the engine every 0. 1 seconds. Returning true inside this hook will allow CAI_BaseNPC::MaintainSchedule to also be called. This hook only exists for ai type SENTs.
boolean ENTITY:RunEngineTask( number taskID, number taskData )
Called when an engine task is ran on the entity. This hook only exists for ai type SENTs.
ENTITY:RunTask( table task )
Called every think on running task. The actual task function should tell us when the task is finished. This hook only exists for ai type SENTs.
Called whenever a Lua schedule is finished or ENTITY:StartEngineSchedule is called. Clears out schedule and task data stored within NPC's table. This is a helper function only available if your SENT is based on base_ai
ENTITY:SelectSchedule()
Set the schedule we should be playing right now. Allows the NPC to start either a Lua schedule or an engine schedule. Despite sharing the same name as CAI_BaseNPC::SelectSchedule(), this isn't hooked to that function; this is called by Lua's ENTITY:RunAI, doesn't return an engine function, returning an engine function doesn't help and doesn't make the NPC start an engine schedule. To alter initial engine schedule, it is recommended to use ENT:TranslateSchedule. This is a helper function only available if your SENT is based on base_ai
Toggles automatic frame advancing for animated sequences on an entity. This has the same effect as setting the ENT. AutomaticFrameAdvance property. (See ENT structure)
ENTITY:SetTask( table task )
Sets the current task. This hook only exists for ai type SENTs.
ENTITY:SetupDataTables()
Called when the entity should set up its Data Tables. This is a much better option than using Set/Get Networked Values. This hook is called after GM:OnEntityCreated and GM:NetworkEntityCreated.
ENTITY:SpawnFunction( Player ply, table tr, string ClassName )
This is the spawn function. It's called when a player spawns the entity from the spawnmenu. If you want to make your SENT spawnable you need this function to properly create the entity. Unlike other ENTITY functions, the "self" parameter of this function is not an entity but rather the table used to generate the SENT. This table is equivalent to scripted_ents. GetStored("ent_name").
ENTITY:StartEngineSchedule( number scheduleID )
Called by the engine only whenever NPC:SetSchedule is called. This hook only exists for ai type SENTs.
boolean ENTITY:StartEngineTask( number taskID, number TaskData )
Called when an engine task has been started on the entity. This hook only exists for ai type SENTs.
ENTITY:StartSchedule( Schedule sched )
Starts a schedule previously created by ai_schedule. New. Not to be confused with ENTITY:StartEngineSchedule or NPC:SetSchedule which start an Engine-based schedule. This hook only exists for ai type SENTs.
ENTITY:StartTask( Task task )
Called once on starting task. This hook only exists for ai type SENTs.
ENTITY:StartTouch( Entity entity )
Called when the entity starts touching another entity. This only works for brush entities and for entities that have Entity:SetTrigger set to true.
ENTITY:StoreOutput( string name, string info )
Used to store an output so it can be triggered with ENTITY:TriggerOutput. Outputs compiled into a map are passed to entities as key/value pairs through ENTITY:KeyValue. TriggerOutput will do nothing if this function has not been called first.
Returns true if the current running Task is finished. Tasks finish whenever NPC:TaskComplete is called, which sets TASKSTATUS_COMPLETE for all NPCs, also sets self. bTaskComplete for ai type SENTs. This hook only exists for ai type SENTs.
number ENTITY:TaskTime()
Returns how many seconds we've been doing this current task This hook only exists for ai type SENTs.
table ENTITY:TestCollision( Vector startpos, Vector delta, boolean isbox, Vector extents, number mask )
Allows you to override trace result when a trace hits the entitys Bounding Box. Your entity must have Entity:EnableCustomCollisions enabled for this hook to work. This hook is called for anim type only.
boolean ENTITY:Think()
Called every frame on the client. Called about 5-6 times per second on the server. You may need to call Entity:Spawn to get this hook to run server side. You can force it to run at servers tickrate using the example below.
ENTITY:Touch( Entity entity )
Called every tick for every entity being "touched". See also ENTITY:StartTouch and ENTITY:EndTouch. For physics enabled entities, this hook will not be ran while the entity's physics is asleep. See PhysObj:Wake.
Called by the engine to alter NPC activities, if desired by the NPC. This hook only exists for ai type SENTs.
number ENTITY:TranslateSchedule( number schedule )
Called by the engine to alter NPC schedules, if desired by the NPC. This hook only exists for ai type SENTs.
ENTITY:TriggerOutput( string output, Entity activator, string data = "nil" )
Triggers all outputs stored using ENTITY:StoreOutput.
Called whenever the transmit state should be updated.
ENTITY:Use( Entity activator, Entity caller, number useType, number value )
Called when an entity "uses" this entity, for example a player pressing their +use key (default e) on this entity. To change how often the hook is called, see Entity:SetUseType. This hook only works for nextbot, ai and anim scripted entity types.

Methods

Gets the NPC classification. Internally gets the m_iClass variable which is polled by the engine. This will be equivalent to NPC:Classify. This is a helper function only available if your SENT is based on base_ai
ENTITY:SetMaxYawSpeed( number maxyaw )
Sets the NPC max yaw speed. Internally sets the m_fMaxYawSpeed variable which is polled by the engine. This is a helper function only available if your SENT is based on base_ai
ENTITY:SetNPCClass( number classification )
Sets the NPC classification. Internally sets the m_iClass variable which is polled by the engine. This is a helper function only available if your SENT is based on base_ai