From Blue Mars Developer Guidebook

This page is protected and certified by Avatar Reality Inc. Only Editable by Avatar Reality Staff Members.

Contents 1 Overview 2 Common 2.1 Globals 2.2 Table 2.3 Log 2.4 Misc 3 Math 3.1 Constants 3.2 Common Math Functions 4 Item System Math 4.1 Vector 4.2 Misc 4.3 Point 5 Map 6 Entity Utils

Overview

CryEngine includes some Lua utility functions.

Common

General utility functions defined in Game/Scripts/common.lua:

Globals

g_SignalData

A table used to pass extra data in AI signals. Using this variable avoids allocating temporary Lua memory.

This is how it's defined.

-- data structure passed to the Signals, use this global to avoid temporary lua mem allocation
g_SignalData_point = {x=0,y=0,z=0};
g_SignalData_point2 = {x=0,y=0,z=0};

-- REMEMBER! ALWAYS write 
-- g_SignalData.point = g_SignalData_point 
-- before doing direct value assignment (i.e. not referenced) like
-- g_SignalData.point.x = ...
-- and any math.lua vector function on it (FastSumVectors(g_SignalData.point,..) etc

g_SignalData = {
	point = g_SignalData_point, -- since g_SignalData.point is always used as a handler
	point2 = g_SignalData_point2,
	ObjectName = "",
	id = NULL_ENTITY,
	fValue = 0,
	iValue = 0,
	iValue2 = 0,
}

Other temps:

g_StringTemp1 = "                                            ";

g_HitTable = {{},{},{},{},{},{},{},{},{},{},}

Table

count(_tbl)

returns number of key-value pairs in a table

new(_obj, norecurse)

returns a new copy of a table

merge(dst, src, recurse)

merges the contents of table src into table dst, excepting functions

mergef(dst, src, recursive)

merges the contents of table src into table dst, including functions

SafeTableGet( table, name )

returns table[name] or nil if table is nil

Log

Vec2Str(vec)

returns a string representation of a vector

LogError(fmt, ...)

log an error string

LogWarning(fmt, ...)

log a warning string

Log(fmt, ...)

log a message string

g_dump_tabs=0;

dump(_class, no_func, depth)

dump the contents of a class to the log (no_func is a boolean - "false" will cause function members to be printed).

ShowTime()

log the current time

Misc

EmptyString(str)

check if a string is set and it's length > 0

NumberToBool(n)

check if a number value is true or false

useful for entity parameters

EntityName(entity)

easy way to log entity id

accepts both entity table or entityid

EntityNamed(name)

easy way to get entity by name

useful for "console debugging"!

Math

CryEngine loads a number of math constants and functions in Game/Scripts/Utils/Math.lua.

Constants

Math.lua defines the following Lua vector constants:

g_Vectors =
{
	v000=ConstVec({x=0,y=0,z=0}),
	v001=ConstVec({x=0,y=0,z=1}),
	v010=ConstVec({x=0,y=1,z=0}),
	v011=ConstVec({x=0,y=1,z=1}),
	v100=ConstVec({x=1,y=0,z=0}),
	v101=ConstVec({x=1,y=0,z=1}),
	v110=ConstVec({x=1,y=1,z=0}),
	v111=ConstVec({x=1,y=1,z=1}),

	up = ConstVec({x=0,y=0,z=1}),
	down = ConstVec({x=0,y=0,z=-1}),

	temp={x=0,y=0,z=0},
	tempColor={x=0,y=0,z=0},
	
	temp_v1={x=0,y=0,z=0},
	temp_v2={x=0,y=0,z=0},
	temp_v3={x=0,y=0,z=0},
	temp_v4={x=0,y=0,z=0},
	
	vecMathTemp1={x=0,y=0,z=0},
	vecMathTemp2={x=0,y=0,z=0},	
}

Constants for pi and angle conversion:

g_Rad2Deg = 180/math.pi;
g_Deg2Rad = math.pi/180;
g_Pi = math.pi;
g_2Pi = 2*math.pi;
g_Pi2 = 0.5*math.pi;

Common Math Functions

IsNullVector(a)

returns true if a is a zero vector, i.e. all components are zero.

IsNotNullVector(a)

returns true if a is not a zero vector, i.e. any components are non-zero.

LengthSqVector(a)

returns the square of the length of vector a

faster than LengthVector

LengthVector(a)

returns the lenfth of vector a

DistanceSqVectors(a, b)

DistanceSqVectors2d(a, b)

DistanceVectors(a, b)

dotproduct3d(a,b)

dotproduct2d(a,b)

LogVec(name,v)

debug function to log a vector value

name - text to precede vector value in the log

v - vector to log

ZeroVector(dest)

make dest a zero vector, i.e. set all its components to zero

no return value

CopyVector(dest,src)

copy the components of vector src to vector dest

NegVector(a)

negate vector a, i.e. multiply its components by -1

no return value

SubVectors(dest,a,b)

same as FastDifferenceVectors

SumVectors(a,b)

return the vector sum of vectors a and b in a new vector

a and b are not modified

FastSumVectors(dest,a,b)

place the vector sum of vectors a and b in vector dest

a and b are not modified

no return value

DifferenceVectors(a,b)

return the vector difference of vectors a and b in a new vector

a and b are not modified

FastDifferenceVectors(dest,a,b)

place the vector different of a and b in vector dest

a and b are not modified

no return value

ProductVectors(a,b)

returns the vector product of a and b

a and b are not modified

FastProductVectors(dest,a,b)

calculates the vector product of a and b' and places the result in vector dest

a and b are not modified

no return value

ScaleVector(a,b)

scale vector a by factor b

returns a new vector. a is not modified

ScaleVectorInPlace(a,b)

scale vector a by factor b

a is modified. There is no return value

NormalizeVector(a)

normalize a vector

modifies a and returns it

FastScaleVector(dest,a,b)

LerpColors(a,b,k)

linear interpolation

Lerp(a,b,k)

__max(a, b)

__min(a, b)

clamp(_n, _min, _max)

Interpolate(actual,goal,speed)

sgn(a)

returns sign of number a, -1 if a<0, 0 if a=0, 1 if a>0

sgnnz(a)

returns 1 if a>=0, else -1

sqr(a)

returns the square of number a

randomF(a,b)

VecRotate90_Z(v)

VecRotateMinus90_Z(v)

iff(c,a,b)

if c is true then return a, else return b

crossproduct3d( dest, p, q )

place the cross product of p and q in vector dest

RotateVectorAroundR( dest, p, r, angle )

rotate vector p around vector r by angle

the length of r needs to be 1

ProjectVector( dest, P, N )

project P to the surface whose normal vector is N.

DistanceLineAndPoint( a, p, q )

get a distance between line(pt+q) and point(a)

Item System Math

Defined in Game/Scripts/Entities/Item/ItemSystemMath.lua

Vector

vecToAngles(vec)

anglesToVec(angles)

vecFrontToUp(front, up)

compute an up vector from a front vector

up is optional

vecFrontToRight(front,up)

compute a right vector from a front vector

up is optional

vecSet(v,x,y,z)

set components of a vector, returns vector

v - vector to modify

vecCopy(va,vb)

copy components of vector vb to va

vecDistanceSq(v,t)

return distance squared of two vectors

vec2DDistanceSq(v,t)

return 2D squared distance (i.e. using only x and y components) of two vectors

vecScale(v,t)

vecSLerp(va,vb,t,angle)

vecLerp(va,vb,t)

vecSub(va,vb)

vecAdd(va,vb)

vecLenSq(v)

vecLen(v)

vecMul(va,vb)

vecNormalize(va)

vecDot(va,vb)

vecCross(va,vb)

Misc

retDef(val,def)

Point

PointInCircle(x,y,center,r)

PointInPolygon(p,polygon)

PointToLineDistanceSq(point, lineStart, lineEnd)

return squared distance of point to line and closest point to line

Map

In Map.lua, the following functions are defined on a Map class.

Insert(key,value)

Remove(key)

Push(val)

Pop()

Entity Utils

In Scripts/Utils/EntityUtils.lua:

MakeDerivedEntity(derivedClass)

create a new table that is a derived class of parent entity

BroadcastEvent(sender, event)

DumpEntities()

MakeUsable(entity)

adds an OnUsed event handler to the entity

MakePickable(entity)

adds a bPickable property to the entity Properties table

MakeSpawnable(entity)

CompareEntitiesByName(ent1, ent2)

MakeCompareEntitiesByDistanceFromPoint(point)

EntityCommon.PhysicalizeRigid(entity,slot,properties,active)