Class engine.Entity

An entity is anything that goes on a map, terrain features, objects, monsters, player, ...


Usually there is no need to use it directly, and it is better to use specific engine.Grid, engine.Actor or engine.Object classes. Most modules will want to subclass those anyway to add new comportments

Functions

engine.Entity.invalidateAllMO ()

Invalidates the whole Map Object repository

engine.Entity.fromBase (t, base)

Create a new entity with a base calls importBase

Tables

engine.Entity._no_save_fields

Fields we shouldn't save

engine.Entity.temporary_values_conf

temporary values storage

Fields

engine.Entity.__position_aware

Subclasses can change it to know where they are on the map

engine.Entity.loadNoDelay

Do we delay the load for this entity or not

Local Functions

engine.Entity.copy_recurs (dst, src, deep)

recursive copy

engine.Entity.importBase (t, base)

Import base into entity

Methods

engine.Entity:init (t, no_default)

Initialize an entity Any subclass MUST call this constructor

engine.Entity:cloned (src)

If we are cloned we need a new uid flags entity as changed

engine.Entity:replacedWith (isdone, new)

If we are replaced we need a new uid flags entity as changed

engine.Entity:loaded ()

If we are loaded we need a new uid flags entity as changed

engine.Entity:changeUid (newuid)

Change the entity's uid WARNING: ONLY DO THIS IF YOU KNOW WHAT YOU ARE DOING!.

engine.Entity:stripForExport ()

Try to remove all "un-needed" effects, fields, ...

engine.Entity:setupMinimapInfo (mo, map)

Setup minimap color for this entity You may overload this method to customize your minimap

engine.Entity:addParticles (ps)

Adds a particles emitter following the entity

engine.Entity:addParticles3D (def, args[, shader])

Adds a particles emitter following the entity and duplicate it for the back calls addParticles() twice internally

engine.Entity:removeParticles (ps)

Removes a particles emitter following the entity

engine.Entity:getParticlesList (back)

Get the particle emitters of this entity

engine.Entity:closeParticles ()

Removes the particles from the running threads but keep the data for later

engine.Entity:defineDisplayCallback ()

Attach or remove a display callback Defines particles to display

engine.Entity:makeMapObject (tiles, idx)

Create the "map object" representing this entity Do not touch unless you KNOW what you are doing.
You do NOT need this, this is used by the engine.Map class automatically.
DO NOT TOUCH!!!

engine.Entity:alterMakeMapObject (tiles, mo, z, last_mo)

Allows to alter the generated map objects
Does nothing by default

engine.Entity:getMapObjects (tiles, mos, z)

Get all "map objects" representing this entity
Do not touch unless you KNOW what you are doing.

engine.Entity:removeAllMOs (no_invalidate)

Remove all Map objects for this entity

engine.Entity:setMoveAnim (oldx, oldy, speed, blur, twitch_dir, twitch)

Setup movement animation for the entity The entity is supposed to possess a correctly set x and y pair of fields - set to the current (new) position

engine.Entity:resetMoveAnim ()

Reset movement animation for the entity - removes any anim

engine.Entity:MOflipX (v)

Sets the flip state of MO and associated MOs

engine.Entity:MOflipY (v)

Sets the flip state of MO and associated MOs

engine.Entity:getEntityFinalSurface (tiles, w, h)

Get the entity image as an sdl surface and texture for the given tiles and size

engine.Entity:getEntityFinalTexture (tiles, w, h)

Get the entity image as an sdl texture for the given tiles and size

engine.Entity:getDisplayString ([tstr])

Get a string that will display in text the texture of this entity

engine.Entity:toScreen (tiles, x, y, w, h, a, allow_cb, allow_shader)

Displays an entity somewhere on screen, outside the map

engine.Entity:resolve (t, last, on_entity, key_chain)

Resolves an entity
This is called when generating the final clones of an entity for use in a level.

engine.Entity:printResolvers (t)

Print all resolvers registered

engine.Entity:added ()

Call when the entity is actually added to a level/whatever This helps ensuring uniqueness of uniques

engine.Entity:removed ()

Call when the entity is actually removed from existence This helps ensuring uniqueness of uniques.

engine.Entity:check (prop[, ...])

Check for an entity's property
If not a function it returns it directly, otherwise it calls the function with the extra parameters

engine.Entity:addTemporaryValue ([prop=tab|string][, v=number|tab], noupdate)

Computes a "temporary" value into a property Example: You want to give an actor a boost to liferegen, but you do not want it to be permanent
You cannot simply increase liferegen, so you use this method which will increase it AND store the increase.

engine.Entity:removeTemporaryValue ([prop=tab|string], id, noupdate)

Removes a temporary value, see addTemporaryValue()

engine.Entity:tableTemporaryValue (t, k, v)

Helper function to add temporary values

engine.Entity:tableTemporaryValuesRemove (t)

Helper function to remove temporary values

engine.Entity:onTemporaryValueChange (prop, v, base)

Called when a temporary value changes (added or deleted) This does nothing by default, you can overload it to react to changes

engine.Entity:getAttrChange (changed_attr, from, to, result_attr, ...)

Gets the change in an attribute/function based on changing another.

engine.Entity:attr (prop[, v][, fix])

Increases/decreases an attribute The attributes are just actor properties, but this ensures they are numbers and not booleans thus making them compatible with temporary values system

engine.Entity:loadList (file, no_default, res[, mod], loaded)

Loads a list of entities from a definition file

engine.Entity:getEntityKind ()

Return the kind of the entity

engine.Entity:checkClassification (type_str)

Putting this here to avoid errors, not sure if appropriate



Functions

engine.Entity.invalidateAllMO () STATIC
Invalidates the whole Map Object repository
engine.Entity.fromBase (t, base) STATIC
Create a new entity with a base calls importBase

Parameters:

Tables

engine.Entity._no_save_fields
Fields we shouldn't save

Fields:

  • _shader
engine.Entity.temporary_values_conf
temporary values storage

Fields

engine.Entity.__position_aware
Subclasses can change it to know where they are on the map
engine.Entity.loadNoDelay
Do we delay the load for this entity or not

Local Functions

Methods
engine.Entity.copy_recurs (dst, src, deep)
recursive copy

Parameters:

  • dst table the destination table
  • src table the source table
  • deep boolean copy ALL the things
engine.Entity.importBase (t, base)
Import base into entity

Parameters:

Methods

engine.Entity:init (t, no_default)
Initialize an entity Any subclass MUST call this constructor

Parameters:

  • t table a table defining the basic properties of the entity
  • no_default boolean alternate settings that override the defaults

Usage:

    Entity.new{display='#', color_r=255, color_g=255, color_b=255}
engine.Entity:cloned (src)
If we are cloned we need a new uid flags entity as changed

Parameters:

  • src source of event, not used by default
engine.Entity:replacedWith (isdone, new)
If we are replaced we need a new uid flags entity as changed

Parameters:

  • isdone boolean
  • new
engine.Entity:loaded ()
If we are loaded we need a new uid flags entity as changed
engine.Entity:changeUid (newuid)
Change the entity's uid WARNING: ONLY DO THIS IF YOU KNOW WHAT YOU ARE DOING!. YOU DO NOT !

Parameters:

  • newuid the new uid
engine.Entity:stripForExport ()
Try to remove all "un-needed" effects, fields, ... for a clean export This does nothing by default
engine.Entity:setupMinimapInfo (mo, map)
Setup minimap color for this entity You may overload this method to customize your minimap

Parameters:

engine.Entity:addParticles (ps)
Adds a particles emitter following the entity

Parameters:

engine.Entity:addParticles3D (def, args[, shader])
Adds a particles emitter following the entity and duplicate it for the back calls addParticles() twice internally

Parameters:

Returns:

  1. back Particles
  2. front Particles
engine.Entity:removeParticles (ps)
Removes a particles emitter following the entity

Parameters:

engine.Entity:getParticlesList (back)
Get the particle emitters of this entity

Parameters:

  • back string or bool "all" is a valid value
engine.Entity:closeParticles ()
Removes the particles from the running threads but keep the data for later
engine.Entity:defineDisplayCallback ()
Attach or remove a display callback Defines particles to display
engine.Entity:makeMapObject (tiles, idx)
Create the "map object" representing this entity Do not touch unless you KNOW what you are doing.
You do NOT need this, this is used by the engine.Map class automatically.
DO NOT TOUCH!!!

Parameters:

Returns:

    nil

Or

  1. self._mo
  2. self.z
  3. last_mo
engine.Entity:alterMakeMapObject (tiles, mo, z, last_mo)
Allows to alter the generated map objects
Does nothing by default

Parameters:

  • tiles Tiles
  • mo Map Object
  • z
  • last_mo last Map Object

Returns:

  1. mo
  2. z
  3. last_mo
engine.Entity:getMapObjects (tiles, mos, z)
Get all "map objects" representing this entity
Do not touch unless you KNOW what you are doing.
You do NOT need this, this is used by the engine.Map class automatically.
DO NOT TOUCH!!!

Parameters:

  • tiles Tiles
  • mos map objects
  • z int recursive index
engine.Entity:removeAllMOs (no_invalidate)
Remove all Map objects for this entity

Parameters:

  • no_invalidate boolean don't invalidate the map object
engine.Entity:setMoveAnim (oldx, oldy, speed, blur, twitch_dir, twitch)
Setup movement animation for the entity The entity is supposed to possess a correctly set x and y pair of fields - set to the current (new) position

Parameters:

  • oldx the coords from where the animation will seem to come from
  • oldy the coords from where the animation will seem to come from
  • speed the number of frames the animation lasts (frames are normalized to 30/sec no matter the actual FPS)
  • blur apply a motion blur effect of this number of frames
  • twitch_dir defaults to 8, the direction to do movement twitch
  • twitch defaults to 0, the amplitude of movement twitch
engine.Entity:resetMoveAnim ()
Reset movement animation for the entity - removes any anim
engine.Entity:MOflipX (v)
Sets the flip state of MO and associated MOs

Parameters:

  • v passed to the map object's flipX()
engine.Entity:MOflipY (v)
Sets the flip state of MO and associated MOs

Parameters:

  • v passed to the map object's flipY()
engine.Entity:getEntityFinalSurface (tiles, w, h)
Get the entity image as an sdl surface and texture for the given tiles and size

Parameters:

  • tiles Tiles a Tiles instance that will handle the tiles (usually pass it the current Map.tiles)
  • w the width
  • h the height

Returns:

    nil if no texture

Or

  1. the sdl surface
  2. the texture
engine.Entity:getEntityFinalTexture (tiles, w, h)
Get the entity image as an sdl texture for the given tiles and size

Parameters:

  • tiles Tiles a Tiles instance that will handle the tiles (usually pass it the current Map.tiles)
  • w the width
  • h the height

Returns:

    nil if no texture

Or

    the texture
engine.Entity:getDisplayString ([tstr])
Get a string that will display in text the texture of this entity

Parameters:

engine.Entity:toScreen (tiles, x, y, w, h, a, allow_cb, allow_shader)
Displays an entity somewhere on screen, outside the map

Parameters:

  • tiles Tiles a Tiles instance that will handle the tiles (usually pass it the current Map.tiles, it will if this is null)
  • x int where to display
  • y int where to display
  • w int the width
  • h int the height
  • a optional number the alpha setting
  • allow_cb
  • allow_shader
engine.Entity:resolve (t, last, on_entity, key_chain)
Resolves an entity
This is called when generating the final clones of an entity for use in a level.
This can be used to make random enchants on objects, random properties on actors, ...
by default this only looks for properties with a table value containing a __resolver field

Parameters:

  • t optional table table defaults to self
  • last optional boolean resolve last
  • on_entity optional boolean
  • key_chain optional table stores keys, defaults to {}
engine.Entity:printResolvers (t)
Print all resolvers registered

Parameters:

  • t optional table defaults to self
engine.Entity:added ()
Call when the entity is actually added to a level/whatever This helps ensuring uniqueness of uniques
engine.Entity:removed ()
Call when the entity is actually removed from existence This helps ensuring uniqueness of uniques. This recursively removes inventories too, if you need anything special, overload this
engine.Entity:check (prop[, ...])
Check for an entity's property
If not a function it returns it directly, otherwise it calls the function with the extra parameters

Parameters:

  • prop the property name to check
  • ... the functions arguments (optional)
engine.Entity:addTemporaryValue ([prop=tab|string][, v=number|tab], noupdate)
Computes a "temporary" value into a property Example: You want to give an actor a boost to liferegen, but you do not want it to be permanent
You cannot simply increase liferegen, so you use this method which will increase it AND store the increase. it will return an "increase id" that can be passed to removeTemporaryValue() to remove the effect.

Parameters:

  • prop the property to affect. This can be either a string or a table of strings, the latter allowing nested properties to be modified. (default tab|string)
  • v the value to add. This should either be a number or a table of properties and numbers. (default number|tab)
  • noupdate boolean if true the actual property is not changed and needs to be changed by the caller

Returns:

    an id that can be passed to removeTemporaryValue() to delete this value
engine.Entity:removeTemporaryValue ([prop=tab|string], id, noupdate)
Removes a temporary value, see addTemporaryValue()

Parameters:

  • prop the property to affect (default tab|string)
  • id int the id of the increase to delete
  • noupdate boolean if true the actual property is not changed and needs to be changed by the caller
engine.Entity:tableTemporaryValue (t, k, v)
Helper function to add temporary values

Parameters:

engine.Entity:tableTemporaryValuesRemove (t)
Helper function to remove temporary values

Parameters:

engine.Entity:onTemporaryValueChange (prop, v, base)
Called when a temporary value changes (added or deleted) This does nothing by default, you can overload it to react to changes

Parameters:

  • prop the property changing
  • v the value of the change
  • base the base table of prop
engine.Entity:getAttrChange (changed_attr, from, to, result_attr, ...)
Gets the change in an attribute/function based on changing another. Measures the difference in resultattr from adding temporary values from and to to changedattr.

Parameters:

  • changed_attr the attribute being changed
  • from the temp value added to changed_attr which we are starting from
  • to the temp value added to changed_attr which we are ending on
  • result_attr the result we are measuring the difference in
  • ... arguments to pass to result_attr if it is a function

Returns:

  1. the difference
  2. the from result
  3. the to result
engine.Entity:attr (prop[, v][, fix])
Increases/decreases an attribute The attributes are just actor properties, but this ensures they are numbers and not booleans thus making them compatible with temporary values system

Parameters:

  • prop the property to use
  • v the value to add, if nil the function returns (optional)
  • fix forces the value to v, does not add (optional)

Returns:

  1. nil if v was specified
  2. nil if property doesn't exist
  3. If v isn't specified then it returns the current value if it exists and isn't 0
engine.Entity:loadList (file, no_default, res[, mod], loaded)
Loads a list of entities from a definition file

Parameters:

  • file string the file to load from
  • no_default optional boolean if true then no default values will be assigned
  • res optional table the table to load into, defaults to a new one
  • mod func a function to which will be passed each entity as they are created. Can be used to adjust some values on the fly (optional)
  • loaded optional table a table of already loaded files

Usage:

    MyEntityClass:loadList("/data/my_entities_def.lua")
engine.Entity:getEntityKind ()
Return the kind of the entity

Returns:

    "entity"
engine.Entity:checkClassification (type_str)
Putting this here to avoid errors, not sure if appropriate

Parameters:

Returns:

    false
generated by LDoc 1.4.3