Developer Guide (Version 1.12)

Structure of a Script Entity

CryLua is deprecated and will be removed in a future version of Lumberyard.


This page contains information on using Lua scripting to work with the legacy Entity system. These Lua scripts use the legacy script context. Starting with Lumberyard 1.8, Lua scripts use the new behavior context that replaces the legacy script context. Scripts that were written before the integration of the behavior context no longer work in Lumberyard versions 1.8 and later. For information on updating Lua code from legacy script context to the new behavior context, see the migration notes for Lumberyard 1.8. For information on using Lua with Lumberyard's new component entity system, see Writing Lua Scripts for the Component Entity System.

To implement a new entity using Lua, two files need to be created and stored in the game directory:

  • The Ent file tells the Entity system the location of the Lua script file.

  • The Lua script file implements the desired properties and functions.

With the SDK, both the .ent and .lua files are stored inside the <Game_Folder>\Scripts.pak file.

Ent File

The Ent files are all stored inside the <Game_Folder>\Entities directory and need to have the .ent file extension. The content is XML as follows:

<Entity Name="LivingEntity" Script="Scripts/Entities/Physics/LivingEntity.lua" />

Entity properties set in the Ent file include:


Name of the entity class.


Path to the Lua script that implements the entity class.


Flag indicating whether or not the entity class is visible in Lumberyard Editor.

Lua Script

The Lua script, in addition to implementing the entity class, provides a set of information used by Lumberyard Editor when working with entities on a level. The property values set inside the Lua script are default values assigned to new entity instances. Editor variables specify how entities are drawn in Lumberyard Editor.

The following code excerpt is from the sample project files in your Lumberyard directory (...\dev\Cache\SamplesProject\pc\samplesproject\scripts\entities\physics\livingentity.lua).

LivingEntity = { Properties = { soclasses_SmartObjectClass = "", bMissionCritical = 0, bCanTriggerAreas = 1, DmgFactorWhenCollidingAI = 1, object_Model = "objects/default/primitive_capsule.cgf", Physics = { bPhysicalize = 1, -- True if object should be physicalized at all. bPushableByPlayers = 1, }, Living = { height = 0, -- vertical offset of collision geometry center vector_size = {0.4, 0.4,0.9}, -- collision cylinder dimensions height_eye = 1.8, -- vertical offset of camera height_pivot = 0.1, -- offset from central ground position that is considered entity center head_radius = 0.3, -- radius of the 'head' geometry (used for camera offset) height_head = 1.7, -- center.z of the head geometry groundContactEps = 0.004, --the amount that the living needs to move upwards before ground contact is lost. defaults to which ever is greater 0.004, or 0.01*geometryHeight bUseCapsule = 1,--switches between capsule and cylinder collider geometry inertia = 1, -- inertia koefficient, the more it is, the less inertia is, 0 means no inertia inertiaAccel = 1, -- inertia on acceleration air_control = 1, -- air control koefficient 0..1, 1 - special value (total control of movement) air_resistance = 0.1, -- standard air resistance gravity = 9.8, -- gravity vector mass = 100, -- mass (in kg) min_slide_angle = 60, -- if surface slope is more than this angle, player starts sliding (angle is in radians) max_climb_angle = 60, -- player cannot climb surface which slope is steeper than this angle max_jump_angle = 45, -- player is not allowed to jump towards ground if this angle is exceeded min_fall_angle = 65, -- player starts falling when slope is steeper than this max_vel_ground = 10, -- player cannot stand of surfaces that are moving faster than this timeImpulseRecover = 0.3, -- forcefully turns on inertia for that duration after receiving an impulse nod_speed = 1, -- vertical camera shake speed after landings bActive = 1,-- 0 disables all simulation for the character, apart from moving along the requested velocity collision_types = 271, -- (271 = ent_static | ent_terrain | ent_living | ent_rigid | ent_sleeping_rigid) entity types to check collisions against }, MultiplayerOptions = { bNetworked= 0, }, bExcludeCover=0, }, Client = {}, Server = {}, -- Temp. _Flags = {}, Editor={ Icon = "physicsobject.bmp", IconOnTop=1, }, }

This information is followed by functions that implement the entity class.


Entity properties are placed inside the entity class. These properties are assigned to all new instances of the entity class created, visible and editable in Lumberyard Editor as the instance's Entity Properties table. The property values set for individual entity instances placed on a level are saved in the level file. When a property of an entity instance is changed in Lumberyard Editor, the OnPropertyChange() function called (if it is has been implemented for the script entity).

Lumberyard Editor provides the Archetype tool for assigning a common set of properties reused for multiple instance (even across multiple levels). For more information on Archetypes, see Archetype Entity in the Amazon Lumberyard User Guide.

When specifying entity class property names, use the following prefixes to signal the data type expected for a property value. This enables Lumberyard Editor to validate a property value when set.

Entity class property prefixes

Prefix Data Type
b boolean
f float
i integer
n positive integer
s string
clr color
object_ object compatible with Lumberyard (CFG, CGA, CHR or CDF file)

You can add special comments to property values that can be utilized by the engine. For example:

--[25,100,0.1,"Damage threshold"]

This comment tells the engine the following:

  • Value is limited to between 25 and 100.

  • The float value uses a step of 0.01 (this limits the fidelity of values).

  • The string "Damage threshold" will be displayed in the Lumberyard Editor as a tool tip.

Editor Table

The Editor table provides additional configuration information to Lumberyard Editor on how to handle instances of the entity.

Entity class editor variables

Variable Description
Model CGF model to be rendered over an entity instance.
ShowBounds Flag indicating whether or not a bounding box is drawn around an entity instance when selected.
Icon BMP icon to be drawn over an entity instance.
IconOnTop Flag indicating whether or not the icon is drawn over or under an entity instance.


A script entity can include several callback functions called by the engine or game system. See Entity System Script Callbacks for more information.

On this page: