Overview

To implement a new entity using Lua, two files need to be stored in the game folder.

The first one is the Ent file which is parsed by the Entity System to know the file location of the Lua script. The second one is the Lua script which 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 an XML file like the example below.

<Entity
 Name="RadarBase"
 Script="Scripts/Entities/Others/RadarBase.lua"
/>

The following table outlines the properties parsed by the Entity System.

Property

Description

Name

Name of the Entity class.

Script

Path of the Lua script used to implement the entity class.

Invisible

Prevents it from being visible as one of the available entity classes inside Sandbox.

Lua Script

The Lua script consist of one main table which should have the same name as the name intended for the entity class.

Properties Table

The Properties table needs to be placed inside the entity class table. It will be parsed by the Sandbox Editor and provides level editor a way to change entity class parameters through the user interface.

In order to have the parameters listed in the table above, the following Properties table.

Properties =
{
	object_Character = "objects/library/architecture/airfield/radar/radar.cga",
	sAnimation = "Default",
	sDestroyedEffect = "explosions.C4_explosion.ship_door",
	fHealth = 100,

	Physics =
	{
		bRigidBody=1,
		bRigidBodyActive = 1,
		bRigidBodyAfterDeath =1,
		bResting = 0,
		Density = -1,
		Mass = 500,
	},
},

The values assigned inside the Lua table are used to provide default values in Sandbox. The property values for each instance placed on a level will be saved individually in the level file.

Sandbox provide the Archetype tool for assigning a common set properties reused for multiple instance (even across multiple levels). More information on Archetypes can be found in the Sandbox Manual.

Any time a property of an instance is changed within Sandbox, the OnPropertyChange() function will be called if it is has been implemented for the Script Entity.

It is possible to give the Editor hints, concerning the value type desired for a property value. This is done by using one of the following prefixes on the value name.

Prefix

Type

b

boolean.

f

float.

i

integer.

s

string.

clr

color.

object_

an object compatible with CryENGINE: a CFG, CGA, CHR or CDF file.

Editor Table

The Editor table can be added inside the entity class table. It gives some information to Sandbox on additional information to draw on the instances of an entity.

Value item

Description

Model

CGF model which the Editor render over any instance of the entity.

ShowBounds

Indicates if the Editor draw the bounding box of the entity when it is selected.

AbsoluteRadius

 

Icon

BMP icon drawn over the entity.

IconOnTop

When true, the icon will be drawn on top of the entity, otherwise the icon will be drawn just under it.

DisplayArrow

 

Links

 

Special Comments

You can add special comments behind a variable which can be utilized by the engine. Currently you can change the default sliders inside the editor by providing information about a number variable.

For example:

The comment...

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

... tells the engine that:

Functions

The Script Entity can include several callback functions called by the engine or game system. Look at the Callback References for more information.