Entity Scripts

From Blue Mars Developer Guidebook

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

Contents

Overview

An Entity is a game object accessible by name and ID, with position, orientation, and behavior implemented by a Lua script. An entity can have any number of child entities, which will have position and orientation relative to that of the parent entity (e.g. the wheel on a vehicle). Entities have slots which can contain character models, lights, particle emitters, clouds, and static geometry.

An entity class is defined by an entity script, written in Lua, and an .ent file that registers the entity class. This is an example .ent file:

<Entity Name="MyEntity" Script="Levels/COMPANYCODE/Common/Scripts/Entities/MyEntity.lua" />

New entities should be added according to the guidelines in the General Attraction Submission Format. Replace COMPANYCODE with your company code, and LevelName with the name of your city level.

  • .ent files are located in
    • Levels/COMPANYCODE/Common/Entities/ - these will load in any <COMPANYCODE> level, or
    • Levels/COMPANYCODE/COMPANYCODE_LevelName/Entities/ - these will only load in the <COMPANYCODE_LevelName> level.
    • See script registration for an example.
  • .lua files are located in
    • Levels/COMPANYCODE/Common/Scripts/Entities/ - these will load in any <COMPANYCODE> level, or
    • Levels/COMPANYCODE/COMPANYCODE_LevelName/Scripts/Entities/ these will only load in the <COMPANYCODE_LevelName> level.
    • See the scripts section for an example.


Scripts

See this Basic Script Example Tutorial which covers how to

  • Register and create an entity LUA script
  • Place the entity script in a level
  • Launch the entity script

Properties

An entity script can expose entity properties for tweaking in the Sandbox Editor by listing them in a Properties table in the class declaration. For example, these properties in an entity script:

MyProperties = {
   Properties = {
      bBoolean=0,
      fFloat=0,
      iInteger=0,
      nNumber=1,
      objObj="",
      objectObject = "object.cgf",
      sString="string",
      colorColor={x=0,y=1,z=0},
      clrClr={x=0,y=1,z=0},
      sndSnd="",
      soundSound="",
      vectorVector={x=0,y=0,z=0},
      texTex="",
      textureTexture="",
      fileFile="",
      anyNumber=0,
      anyString="sometext",
   }
}

will appear in the Sandbox Editor thus:

Image:Entityproperties.PNG

To appear in the Sandbox Editor, each property must be initialized to a value. Moreover, the Sandbox Editor will determine how the property can be edited based on the prefix of the property name (a form of Hungarian notation).

For example, the property "bBoolean" above is determined to be a boolean property (actually, 1 or 0) and displayed in the Sandbox Editor as "Boolean" (without the "b" prefix) and edited with a checkbox.

In most other cases, the Sandbox Editor will display a type-specific selector when you click on the field, and also allow you to edit the field directly. Once you're satisfied with the new values, remember to Save the level.

If a property has no recognized type prefix, like "anyNumber" and "anyString" above, the type is inferred from the initial value.

Here's the list of prefixes:

f
float - the Sandbox Editor will show an editable floating point selector
i
integer - the Sandbox Editor will show an editable integer number selector
n
integer - the Sandbox Editor will show an editable positive number selector
s
string - the Sandbox Editor will show an editable text box
b
number (1 or 0) - the Sandbox Editor will show a checkbox (note that bools defined in Properties are treated in code as 1 or 0, rather than true or false, as a regular Lua bool)
clr, color
color - the Sandbox Editor will show a color chooser

Image:Colorproperty.PNG

file
string - the Sandbox Editor will display a file chooser

Image:Fileproperty.PNG

obj,object
string - the Sandbox Editor will display a file chooser set to "Object"

Image:Objectproperty.PNG

vector
vector - the Sandbox Editor will display allow you to edit the entire vector or expand it to edit the individual vector components

Image:Vectorproperty.PNG

snd,sound
string - the Sandbox Editor will display a file chooser set to "Sound"

Image:Soundproperty.PNG

tex,texture
string - the sandbox Editor will display a file chooser set to "Texture"

Image:Textureproperty.PNG

These are not applicable to Blue Mars but are listed here for completeness:

shader
text
ei
es
soclass
soclasses
sostate
sostates
sopattern
soaction
sohelper
sonavhelper
soevent
sotemplate
gametoken
seq_
mission_


As a real example, the Golf minigame supervisor has the following properties:

ARGolfSupervisor = {
  Properties = {
    sMasterEntityClass = "ARGolfGame_Master",
    sPlayerEntityClass = "ARGolfGame_MP",
    sSinglePlayerEntityClass = "ARGolfGame_SP",
    sGameClass = "AR:Golf",
    sGameMenuMovie = "",   
    bAutoStart = 1,
    fileCourseInfoLua = "Levels/AR/Common/Scripts/Entities/Minigames/Golf/CourseInfo_orig.lua",
    fTimeOfDay = 11.25,
    sCourseInfoLuaTable = "CourseInfo_orig",
    sExitToLevel = "AR_Startup",
  },
  ...

and they will show up in the Sandbox Editor:

Image:golfprops.jpg

Callbacks

Each entity script can implement a number of event callbacks, functions that are called by the system.

They are all class members following the conventions of object-oriented Lua, so we list them here assuming the entity is implicitly the first parameter.


OnSpawn()
called when the entity is created
OnDestroy()
Called when the entity is destroyed

These are only called in the Sandbox Editor:


OnReset()
called by the Sandbox Editor when it resets state, i.e. when a level is started with BlueMars>Switch to Preview Mode or CTRL-G and ended with ESC.


OnPropertyChange()
called when an entity property is changed in the Sandbox Editor.


The following are similar but available for both standard CryEngine server and client machines (not a relevant distinction for Blue Mars)


OnInit()
Called when when the entity is created.
OnShutDown()
called when the entity is destroyed


State callbacks are defined per-state (see entity states). If there are no states listed in the entity, then they can be defined at the top level.


OnBeginState()
alled when the state is first entered- perform any state initialization here
OnEndState()
called when the state is exited -perform any state cleanup here
OnUpdate(deltaTime)
called every frame
OnTimer(timerId)
called when a timer expires
OnEvent()
used by Avatar Reality for Multiplayer
OnDamage()
OnEnterArea(entity, areaID)
called when an object enters an entity's trigger bounding box or area
OnLeaveArea(entity, areaID)
called when an object leaves an entity's trigger bounding box or area
OnProceedFadeArea()
OnMoveNearArea()
OnBind()
OnUnBind()
OnMove()
OnCollision(hitdata)
OnPhysicsBreak()
OnSoundDone()
called when a sound is finished playing
OnStartLevel()
called when a level is loaded (but before the game has started)
OnStartGame()
called when the game has started
OnFSCommand(command, args)
receives Actionscript fscommands from Flash movies in the HUD


Inheritance

Lua is not an object-oriented language but to some extent entity scripts can inherit from other entity scripts using the utility function MakeDerivedEntity

States

CryEngine adds support for defining states in an entity script. Most standard CryEngine entity scripts use states (simple example - trigger entities). Entity script states are particularly useful for implementing Minigames. For example, this golf game state transition diagram

Image:minigolfstates.png

might be implemented as this state listing in the minigame entity script:

 GolfGame =
 {
   States = 
   {
     "Init",
     "Title",
     "ShowCourse",
     "PrepareToShoot",
     "Swing",
   }
 }

Most, but not all, #Callbacks can be defined per state. Here's an example state with its own OnUpdate function:

 GolfGame.Title =
 {
  OnBeginState = function(self)
    self:ShowSplash();
  end,
  OnUpdate = function(self,time)
    if (HUD.GetLastFSCommand() == self.FSCommands.start) then
      self:GotoState("ShowCourse");
    end
  end,
  OnEndState = function(self)
    self:HideSplash();
    HUD.ClearLastFSCommand();
  end,
 }

Note the use of the Entity function GotoState to transition to a new state.

Be sure not to use the same name for a state and a function in the class. For example, if for some reason you also defined

function GolfGame:Title() end

then attempting to call the function will result in Lua error.

You may see some standard CryEngine lua scripts are partitioned into CryEngine client-server states, which supports the standard CryEngine multiplayer mode. In Blue Mars, if you want other players to actively participate in the minigame, you'll need to have your script use the Avatar Reality Multiplayer_Minigame_API.

Flowgraph Events

Entity scripts can declare flow node inputs and output ports that can be activated when the entity is used as a flow graph node.

MyTrigger.FlowEvents =
{
	Inputs =
	{
		Disable = { MyTrigger.Event_Disable, "bool" },
		Enable = { MyTrigger.Event_Enable, "bool" },
		Enter = { MyTrigger.Event_Enter, "bool" },
		Leave = { MyTrigger.Event_Leave, "bool" },
	},
	Outputs =
	{
		Disable = "bool",
		Enable = "bool",
		Enter = "bool",
		Leave = "bool",
	},
}

Each input port is assigned an input value type and a function to handle the incoming input value. Output ports are likewise are assigned a value type. Values are sent to an output port with the Entity/ActivateOutput function.


The value types are (text color corresponds to the port display color):

  • bool
  • entity
  • float
  • int
  • string
  • vec3


Note that an input function which handles a parameter value ("string", "entity", etc.) accepts the value as the second argument. See Adding FlowGraph ports to a Lua script for an example.


Resources

Example

ARAvatarTrigger Entity

The ARAvatarTrigger code is included as an example of a commonly used entity script (see Blue Mars Game Programming for other examples)

ARWatchTogether Entity

The ARWatchTogether is an another sample to describe the Dynamic Object mechanism.

CryMod Modding Portal

http://www.crymod.com/ is a resource for developing Crysis mods but much of the CryEngine information is applicable here, for example:


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