Entity Script Basic Example

From Blue Mars Developer Guidebook

Jump to: navigation, search
There are security restrictions on this article



Applicable to the creation of a Minigame entity or any entity, this tutorial walks through the creation of a very simple entity script to illustrate the process of creating a script, registering it with CryEngine, placing the entity in a level, and triggering the script to launch.

Register the entity with BasicScriptExample.ent

  • An entity is registered with an .ent file. To create yours, copy the XML code below into a file named BasicScriptExample.ent, and save it in your Entities directory (Levels/COMPANYCODE/Common/Entities). Replace "CompanyCode" in the path below with your company code name.

Create the BasicScriptExample.lua script

  • Create your new entity script .lua file, saved in your Scripts directory (Levels/COMPANYCODE/Common/Scripts/Entities), containing:
BasicScriptExample =
  Properties = 
    sText = "default display message",

  States = 


function BasicScriptExample:StartScript()
  self:Activate(1); --if using the OnUpdate callback below

BasicScriptExample.Start =
  OnBeginState = function(self) 
  OnUpdate = function(self,time)

BasicScriptExample.Finish =
  OnBeginState = function(self) 
  • Here, the Properties and States tables are defined, and the Editor icon image which labels the entity in the City Editor is defined
  • The sText Property can be changed in the City Editor, the example uses "Hello I am script text!" as seen in the image below
  • We define a StartScript method which
  • Activates the script, which causes the OnUpdate state callback to be invoked every frame
  • Calls ARDebug to turn on the lua debugger and set the log verbosity level (during development)
  • Calls GotoState to go to the Start state
  • The Start state
  • Defines the OnBeginState callback, which
    • Calls ARDebugMessage to display the text specified in the sText Property for a default of 5 seconds. To specify another display time, pass in a second argument with the number of seconds, e.g., ARDebugMessage(self.Properties.sText, 10) for 10 seconds.
    • Calls GotoState to go to the Finish state
  • The Finish state
  • Deactivates the script with Activate(0) -- be sure to turn a script off when it concludes

  • Note about calling GotoState when a script is already in that state:
  • For illustrative purposes, let's say we had not called self:GotoState("Finish") to move on to the Finish state. If the StartScript method was called a second time while we were updating in the Start state, self:GotoState("Start") would not have caused the OnBeginState callback to be received again, since we never left the Start state. OnBeginState will not be received upon calling GotoState on the current state. Being aware of this can be handy when debugging more complicated scripts.

Place your entity in a level

  • After saving the .ent and .lua files, launch the CityEditor and open a level that will load your entity (this can be any level for an entity in Game/Entities). To place your entity in the level, click and drag from the BasicScriptExample class name in the Rollup Bar Entity Browser list to the Perspective window (or double-click on the class name in the browser list and click in the Perspective window).


Trigger your entity

Via ARAvatarTrigger ScriptCommand

  • One way to trigger an entity is to set up an ARAvatarTrigger in the level, and specify a ScriptCommand to execute when an avatar walks into the trigger. Enter the following in the ARAvatarTrigger's ScriptCommand Property, which will get our BasicScriptExample1 entity and call its StartScript method.


Via Flowgraph

  • Another way is to use Flowgraph nodes, in which case we need to define the FlowEvents in our BasicScriptExample.lua.
  • Add the following to the script and save it. If you already have the first part of the script working and the City Editor still open, you will need to close and re-launch the City Editor for the newly-defined FlowEvent to be recognized (for minor script updates this is not necessary - the ReloadScript button can be used, which you can see half-way down the RollupBar in the Entity Script section, with the BasicScriptExample1 selected).
function BasicScriptExample:Event_Start()

BasicScriptExample.FlowEvents = {
  Inputs = {
    Start = {BasicScriptExample.Event_Start, "bool"},
  • Back in the City Editor, select the BasicScriptExample1 entity, find the FlowGraph section of the RollupBar and click Create. Hit OK to create the Flowgraph. Note that the Flowgraph is attached to the entity, so deleting the BasicScriptExample1 entity will also result in deleting this Flowgraph.
  • Right-click in the Flowgraph and select Add Graph Default Entity (which is the same as Add Selected Entity since BasicScriptExample1 is selected).
  • Then select the ARAvatarTrigger in the level, right-click in the Flowgraph and select Add Selected Entity on the left side of the first node.
  • Click on the ARAvatarTrigger's Enter Output, and drag the arrow to the BasicScriptExample's Start Input, as pictured below.


When an avatar enters the trigger, the BasicScriptExample will receive the Start event (Event_Start above) which calls its StartScript() method, the same method we used above with the ScriptCommand.

Problems with this wiki page? Contact us either by: Support Email or Support Ticket System

Blue Mars Guidebook Privacy Policy
Blue Mars Guidebook Community Guidelines

Personal tools