Class "Entity"

First, see the tutorial on entities.

Class Diagram

    classDiagram
    class Entity:::diagramCurrentPage
    class EntityBomb
    class EntityEffect
    class EntityFamiliar
    class EntityKnife
    class EntityLaser
    class EntityNPC
    class EntityPickup
    class EntityPlayer
    class EntityProjectile
    class EntityTear
    Entity <|-- EntityBomb
    Entity <|-- EntityEffect
    Entity <|-- EntityFamiliar
    Entity <|-- EntityKnife
    Entity <|-- EntityLaser
    Entity <|-- EntityNPC
    Entity <|-- EntityPickup
    Entity <|-- EntityPlayer
    Entity <|-- EntityProjectile
    Entity <|-- EntityTear
    link Entity "Entity.html" "Go to page for 'Entity' class"
    link EntityBomb "EntityBomb.html" "Go to page for 'EntityBomb' class"
    link EntityEffect "EntityEffect.html" "Go to page for 'EntityEffect' class"
    link EntityFamiliar "EntityFamiliar.html" "Go to page for 'EntityFamiliar' class"
    link EntityKnife "EntityKnife.html" "Go to page for 'EntityKnife' class"
    link EntityLaser "EntityLaser.html" "Go to page for 'EntityLaser' class"
    link EntityNPC "EntityNPC.html" "Go to page for 'EntityNPC' class"
    link EntityPickup "EntityPickup.html" "Go to page for 'EntityPickup' class"
    link EntityPlayer "EntityPlayer.html" "Go to page for 'EntityPlayer' class"
    link EntityProjectile "EntityProjectile.html" "Go to page for 'EntityProjectile' class"
    link EntityTear "EntityTear.html" "Go to page for 'EntityTear' class"

Functions

Add·Burn ()

void AddBurn ( EntityRef Source, int Duration, float Damage )

Adds a burn effect to an enemy. Duration is in number of frames. Damage is the damage taken per frame.

Duration Information

Duration must be a minimum of 3 frames to deal damage. Every consecutive damage tick is 20 frames apart.

• 2 damage ticks = 23 frames
• 3 damage ticks = 43 frames
• 4 damage ticks = 63 frames

Duration has an upper limit. For an EntityPlayer, it maximum is one interval. For a normal entity, the maximum is 6 intervals.

Example Code

This code damages every entity in the room for 1 second with the damage source set to the player. The total damage dealt is 1.

local player = Isaac.GetPlayer()
local entities = Isaac.GetRoomEntities()
for i, entity in ipairs(entities) do
    entity:AddBurn(EntityRef(player), 30, 1)
end

---

Add·Charmed ()

void AddCharmed ( EntityRef sourceEntity, int Duration )

Adds a charmed-effect to an enemy. Duration is in Number of Frames. Charmed enemies are friendly towards isaac and attack other enemies.

Duration = -1 makes the effect permanent and the enemy will follow you even to different rooms.

Example Code

This code charms every entity in the room for 1 second.

local player = Isaac.GetPlayer()
local entities = Isaac.GetRoomEntities()
for i, entity in ipairs() do
    entity:AddCharmed(EntityRef(player), 30)
end

---

Add·Confusion ()

void AddConfusion ( EntityRef Source, int Duration, boolean IgnoreBosses )

Adds a confusion effect to an entity.

Duration infos

The Duration has a maximum of 5 seconds

Example Code

This code confuses every entity in the room for 1 second while ignoring bosses.

local player = Isaac.GetPlayer()
local entities = Isaac.GetRoomEntities()
for i, entity in ipairs(entities) do
    entity:AddConfusion(EntityRef(player), 30, true)
end

---

Add·Entity·Flags ()

void AddEntityFlags ( int Flags )

Add EntityFlags to the entity. Flags are used to add specific effects like being friendly or being immune from spike damage. You can add multiple flags at the same time by bitwise-concatenating them.

Example Code

This code adds slowing and confusion to the enetity.

local player = Isaac.GetPlayer()
local entities = Isaac.GetRoomEntities()
for i, entity in ipairs(entities) do
    entity:AddEntityFlags(EntityFlag.FLAG_SLOW | EntityFlag.FLAG_CONFUSION)
end

---

Add·Fear ()

void AddFear ( EntityRef Source, int Duration )

Adds a fear-effect to an entity.

Duration infos

The Duration has a maximum of 5 seconds

Example Code

This code frightens every entity in the room for 1 second.

local player = Isaac.GetPlayer()
local entities = Isaac.GetRoomEntities()
for i, entity in ipairs(entities) do
    entity:AddFear(EntityRef(player), 30)
end

---

Add·Freeze ()

void AddFreeze ( EntityRef Source, int Duration )

Freezes an entity, making it unable to move and attack.

Duration infos

The Duration has a maximum of 5 seconds

Example Code

This code freezes every entity in the room for 1 second.

local player = Isaac.GetPlayer()
local entities = Isaac.GetRoomEntities()
for i, entity in ipairs(entities) do
    entity:AddFreeze(EntityRef(player), 30)
end

---

Add·Health ()

void AddHealth ( float HitPoints )

Heals an entity.

---

Add·Midas·Freeze ()

void AddMidasFreeze ( EntityRef Source, int Duration )

Turns the entity into a gold statue (can't move, can't attack, drops coins when killed)

Duration infos

The Duration has a maximum of 5 seconds

Bug

The golden color applied to the entity will stay for the full duration passed into the function, despite the freeze effect only lasting for a maximum of 5 seconds.

Example Code

This code turns every entity in the room into gold for 1 second.

local player = Isaac.GetPlayer()
local entities = Isaac.GetRoomEntities()
for i, entity in ipairs(entities) do
    entity:AddMidasFreeze(EntityRef(player), 30)
end

---

Add·Poison ()

void AddPoison ( EntityRef Source, int Duration, float Damage )

Adds a poison effect to the entity.

Duration infos

The Duration must be a minimum of 3 frames to deal damage. Every consecutive damage tick is 20 frames apart.

2 Damage-ticks = 23 frames
3 = 43
4 = 63
...

Bug

The Duration value seems to have an upper limit. For a PlayerEntity, its only lasting for the duration of one damage interval. For Entities its up to 6 damage-intervals.

Example Code

This code applies a poison effect to every entity in the room for 1 second.

local player = Isaac.GetPlayer()
local entities = Isaac.GetRoomEntities()
for i, entity in ipairs(entities) do
    entity:AddPoison(EntityRef(player), 30, 1)
end

---

Add·Shrink ()

void AddShrink ( EntityRef Source, int Duration )

Adds a shrink effect to the entity.

Duration infos

The Duration has a maximum of 5 seconds

Example Code

This code shrinks every entity in the room for 1 second.

local player = Isaac.GetPlayer()
local entities = Isaac.GetRoomEntities()
for i, entity in ipairs(entities) do
    entity:AddShrink(EntityRef(player), 30)
end

---

Add·Slowing ()

void AddSlowing ( EntityRef Source, int Duration, float SlowValue, Color SlowColor )

Makes the friction higher effectively slowing down the entity.

Example Code

This code slows every entity in the room for 1 second with 0.5 original speed and applying a red color to it.

local player = Isaac.GetPlayer()
local slowColor = Color(1, 0, 0, 1, 0, 0, 0)
local entities = Isaac.GetRoomEntities()
for i, entity in ipairs(entities) do
    entity:AddSlowing(EntityRef(player), 30, 0.5, slowColor)
end

---

Add·Velocity ()

void AddVelocity ( Vector Velocity )

Adds velocity to the entity. This can be used to move him in a certain direction (for example as a result of collision)

---

Blood·Explode ()

void BloodExplode ( )

Explodes with gibs and blood.

---

Can·Shut·Doors ()

boolean CanShutDoors ( )

Enemies keep the doors shut.

---

Clear·Entity·Flags ()

void ClearEntityFlags ( int Flags )

Removes all of the provided EntityFlags from the entity.

---

Collides·With·Grid ()

boolean CollidesWithGrid ( )

Returns true if the entity is currently colliding with a valid GridEntity, as dictated by its Entity.GridCollisionClass.

---

Die ()

void Die ( )

Kills the entity and trigger its death animation.

---

Exists ()

boolean Exists ( )

Checks whether the entity is still spawned in the current room.

This is mostly useful in situations where you are unwrapping an EntityPtr and the corresponding entity may or may not have been killed in the interim period.

---

Get·Boss·ID ()

int GetBossID ( )

If the entity is a boss, it returns its specific boss id. If it isn't a boss it will return 0.

A boss ID is NOT equal to the entity Type, but is defined as a separate value in the entities2.xml file inside the "bossID" attribute.

For Delirium, this function returns the boss id, delirium is currently transformed into.

---

Get·Color ()

const Color GetColor ( )

Returns the Color object associated to this entity.

---

Get·Data ()

table GetData ( )

Returns a Lua table that contains mod-related data associated with the entity. Initially, this will always be an empty table. Any values stored in the table by mods will persist until the entity is despawned.

GetData is typically used by smaller mods as a quick way to store information about an entity without having to create a dedicated data structure.

Example Code

This code adds custom data to an entity or prints it in the console if it exists.

function checkAndSetData(entity)
  local data = entity:GetData()
  if data.foo == nil then -- Keys of data should be strings
    data.foo = "bar" -- Values of data can be any data type
    print("Assigned an intial key of: foo --> bar")
  else
    print("Key foo already exists: " .. tostring(data.foo))
  end
end

There are three main problems with GetData:

1. Data is not unique per mod, which means that using GetData is essentially the same thing as using a global variable. Using global variables are bad for two main reasons. First, other mods can overwrite or mess with your data, so it isn't safe to use them. Second, the scope of global variables makes it difficult to determine where the variable is used when reading the code, and makes it harder to track down bugs, especially in larger programs.

2. Most entities will despawn when leaving the room. For example, even though heart pickups are persisted by the game, they will be despawned and respawned each time the room is left and reentered, respectively. Thus, most entities will have their data deleted upon leaving the room. The exceptions to this are players, familiars, and entities with EntityFlag.FLAG_PERSISTENT.

3. Even for entities that don't despawn when you leave a room, GetData is still not a suitable storage mechanism because it will be deleted when exiting to the menu or restarting/finishing a run. Well-programmed mods should never lose state when end-users save and quit the game, so instead of programming a GetData conversion + serialization routine, it's much simpler to just avoid using it to begin with.

For these reasons, programmers who want their code to be the best that it can be should always avoid using GetData in favor of data structures that are local to their own mod (or local to the specific mod feature). The index for such data structures is usually the pointer hash, which can be retrieved for any entity by using the GetPtrHash function.

---

Get·Drop·RNG ()

RNG GetDropRNG ( )

Returns the assigned RNG object for the entity. This RNG is used to determine the items that are dropped on the entities death.

---

Get·Entity·Flags ()

int GetEntityFlags ( )

Get the EntityFlagsof the entity. This will be a number which acts like a bitmask.

Example Code

This code prints something in the console, if the entity has a specific EntityFlags.

if entity:GetEntityFlags() & EntityFlag.FLAG_CONFUSION == EntityFlag.FLAG_CONFUSION then
    print("This entity is confused!")
end

---

Get·Last·Child ()

Entity GetLastChild ( )

Returns the last child of this entity. This is useful for certain segmented enemies so you can go all the way to the bottom "tail" entity in one method call.

Return behavior

If no child is found, this function returns nil.

---

Get·Last·Parent ()

Entity GetLastParent ( )

Returns the last parent of this entity. This is useful for certain segmented enemies so you can go all the way to the top "head" entity in one method call.

Return behavior

If no parent is found, this function returns nil.

---

Get·Sprite ()

Sprite GetSprite ( )

Return the sprite object of the entity.

---

Has·Common·Parent·With·Entity ()

boolean HasCommonParentWithEntity ( Entity Other )

---

Has·Entity·Flags ()

boolean HasEntityFlags ( int Flags )

Returns true if the entity has all named EntityFlags set.

Example Code

This code prints something in the console, if the entity has a specific EntityFlags.

if entity:HasEntityFlags(EntityFlag.FLAG_CONFUSION) then
    print("This entity is confused!")
end

---

Has·Full·Health ()

boolean HasFullHealth ( )

---

Has·Mortal·Damage ()

boolean HasMortalDamage ( )

Notes

The game adds taken damage to a damage buffer, which gets applied in the next frame. HasMortalDamage() returns true if the buffered damage is enough to kill the entity. HasMortalDamage() will be updated additionally after TakeDamage() is called.

---

Is·Active·Enemy ()

boolean IsActiveEnemy ( boolean includeDead )

return true for non background NPCs (ex: every enemy except fire and shopkeepers)

---

Is·Boss ()

boolean IsBoss ( )

bosses display health bar

---

Is·Dead ()

boolean IsDead ( )

---

Is·Enemy ()

boolean IsEnemy ( )

return true for NPCs that are not controlled by the player

---

Is·Flying ()

boolean IsFlying ( )

---

Is·Frame ()

boolean IsFrame ( int Frame, int Offset )

true every X frames

---

Is·Invincible ()

boolean IsInvincible ( )

---

Is·Visible ()

boolean IsVisible ( )

---

Is·Vulnerable·Enemy ()

boolean IsVulnerableEnemy ( )

return true for enemies that can be damaged

---

Kill ()

void Kill ( )

Kills the entity and makes a blood splat or gibs.

---

Multiply·Friction ()

void MultiplyFriction ( float Value )

---

Post·Render ()

void PostRender ( )

---

Remove ()

void Remove ( )

Remove the entity from the game instantly, without doing any additional effects/animations.

---

Remove·Status·Effects ()

void RemoveStatusEffects ( )

Removes all Status Effects from the entity.

---

Render ()

void Render ( Vector Offset )

Render the current sprite of the Entity at the current entity position + offset.

---

Render·Shadow·Layer ()

boolean RenderShadowLayer ( Vector Offset )

Render the shadow / shadow layer again.

---

Set·Color ()

void SetColor ( Color Color, int Duration, int Priority, boolean Fadeout, boolean Share )

Set the colormask for the entity. This can be used to tint the sprites in different colors.

Example Code

This code changes the color of the sprite to a fully white sprite for 15 frames.

entity:SetColor(Color(1, 1, 1, 1, 255, 255, 255), 15, 1, false, false)

---

Set·Size ()

void SetSize ( float Size, Vector SizeMulti, int NumGridCollisionPoints )

Set the size of the entity.

---

Set·Sprite·Frame ()

void SetSpriteFrame ( string AnimationName, int FrameNum )

---

Set·Sprite·Overlay·Frame ()

void SetSpriteOverlayFrame ( string AnimationName, int FrameNum )

---

Take·Damage ()

boolean TakeDamage ( float Damage, int Flags, EntityRef Source, int DamageCountdown )

Notes

The game adds taken damage to a damage buffer, which gets applied in the next frame. Therefore, TakeDamage() will not decrement the entities HP immediately upon calling the function. Rather, it is only updated on the frame afterwards.

---

To·Bomb ()

EntityBomb ToBomb ( )

Used to cast an Entity object to an EntityBomb object.

Return behavior

If the conversion is not successful, this function returns nil.

---

To·Effect ()

EntityEffect ToEffect ( )

Used to cast an Entity object to an EntityEffect object.

Return behavior

If the conversion is not successful, this function returns nil.

---

To·Familiar ()

EntityFamiliar ToFamiliar ( )

Used to cast an Entity object to an EntityFamiliar object.

Return behavior

If the conversion is not successful, this function returns nil.

---

To·Knife ()

EntityKnife ToKnife ( )

Used to cast an Entity object to an EntityKnife object.

Return behavior

If the conversion is not successful, this function returns nil.

---

To·Laser ()

EntityLaser ToLaser ( )

Used to cast an Entity object to an EntityLaser object.

Return behavior

If the conversion is not successful, this function returns nil.

---

To·NPC ()

EntityNPC ToNPC ( )

Used to cast an Entity object to an EntityNPC object.

Return behavior

If the conversion is not successful, this function returns nil.

---

To·Pickup ()

EntityPickup ToPickup ( )

Used to cast an Entity object to an EntityPickup object.

Return behavior

If the conversion is not successful, this function returns nil.

---

To·Player ()

EntityPlayer ToPlayer ( )

Used to cast an Entity object to an EntityPlayer object.

Return behavior

If the conversion is not successful, this function returns nil.

---

To·Projectile ()

EntityProjectile ToProjectile ( )

Used to cast an Entity object to an EntityProjectile object.

Return behavior

If the conversion is not successful, this function returns nil.

---

To·Tear ()

EntityTear ToTear ( )

Used to cast an Entity object to an EntityTear object.

Return behavior

If the conversion is not successful, this function returns nil.

---

Update ()

void Update ( )

Runs the post-update logic for the entity for a single frame, which will cause the associated callback to fire. Mods usually never need to call this function, as it can cause bugs when post-update logic is ran more than once a frame.

---

Variables

Child

Entity Child

Warning

Sisters Vis bosses do have their counter part entity as their Child. But none of them have a Parent entity set.

---

Collision·Damage

float CollisionDamage

---

Color

Color Color

---

Depth·Offset

float DepthOffset

Get/Set the depth-offset of the entity. This value is added to the Y Position of the entity, which is then used to determine the rendering order of each entity. Default is 0 for all entities.

Example Code

This code explains how this variable works.

entity1.Position.Y -- => 50
entity2.Position.Y -- => 45
-- Entity1 is rendered in front of Entity2

entity1.DepthOffset = -10
-- new Entity1 renderYPosition => 40
-- Entity2 is rendered in front of Entity1

---

Drop·Seed

const int DropSeed

Get the Seed of the Drop RNG.

---

Entity·Collision·Class

EntityCollisionClass EntityCollisionClass

---

FlipX

boolean FlipX

---

Frame·Count

const int FrameCount

---

Friction

float Friction

loaded from entity config

---

Grid·Collision·Class

EntityGridCollisionClass GridCollisionClass

Notes

EntityPlayers can only use GRIDCOLL_NONE, GRIDCOLL_WALLS, and GRIDCOLL_GROUND. All other enums will behave like GRIDCOLL_WALLS.

---

Hit·Points

float HitPoints

Notes

The HitPoints value is not decremented immediately upon taking damage like you would expect. Rather, it is only updated on the frame after the entity takes damage.

---

Index

const int Index

---

Init·Seed

const int InitSeed

---

Mass

float Mass

Notes

Stationary enemies have a Mass of 100. This does not apply to some stationary non-enemies, like slots.

---

Max·Hit·Points

float MaxHitPoints

---

Parent

Entity Parent

This is a reference to the "parent" entity. For most entities, this field will be nil. This field is used in multi-segment entities to refer back to which segment is the "main" entity, like the head.

---

Position

Vector Position

---

Position·Offset

const Vector PositionOffset

---

Render·ZOffset

int RenderZOffset

Bugs

This variable doesn't seem to do anything useful. Use DepthOffset instead.

---

Size

float Size

Returns the size of the hitbox on an entity.

---

Size·Multi

Vector SizeMulti

---

Sorting·Layer

SortingLayer SortingLayer

---

Spawner·Entity

Entity SpawnerEntity

---

Spawner·Type

EntityType SpawnerType

---

Spawner·Variant

int SpawnerVariant

---

Spawn·Grid·Index

const int SpawnGridIndex

---

Splat·Color

Color SplatColor

The color of the gibs when an entity dies.

The Color of this property is read only, so if you want to change it, you have to replace the entire thing with a new Color object.

---

Sprite·Offset

Vector SpriteOffset

---

Sprite·Rotation

float SpriteRotation

---

Sprite·Scale

Vector SpriteScale

Get/set the scale of the enemy sprite. This can be used to also scale the shadow of the entity.

Also used as a Player stat - Change this in a callback to MC_EVALUATE_CACHE using the CacheFlag.CACHE_SIZE flag. This is equal to the Size stat.

Most items that apply a Size Up (Magic Mushroom, Pill Larger...) do so by multiplying the SpriteScale by 1.2500623464584 (this is speculated to be 1.25 with a floating number error, you may choose to use 1.25 for futureproofing instead).

Most items that apply a Size Down (Mini Mushroom, Binky, Pill Smaller...) do so by multiplying the SpriteScale by 0.79996013641357 (this is speculated to be 0.8 with a floating number error, you may choose to use 0.8 for futureproofing instead).

Pluto uses its own multiplier of 0.5.

---

Sub·Type

int SubType

---

Target

Entity Target

---

Target·Position

Vector TargetPosition

---

Type

const EntityType Type

---

Variant

int Variant

---

Velocity

Vector Velocity

---

Visible

boolean Visible

---

---

Last update: March 12, 2023