CryEngine Lua Utilities

From Blue Mars Developer Guidebook

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

Contents

Overview

CryEngine includes some Lua utility functions. They're mostly pretty simple, so you can use them directly or as examples of how to implement your own. The source is available in the CryMod SDK at http://crymod.com/

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

Functions for printing messages in the console and log file, subject to the console log settings. These functions ultimately call System.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


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
EntityName(entity)
retrieve entity name from either an entity object (table) or entity ID.
EntityNamed(name)
calls System.GetEntityByName


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


IsNotNullVector(a)
returns true if a is not a zero vector


LengthSqVector(a)
returns the square of the length of a vector


LengthVector(a)
returns the length of a vector


DistanceSqVectors(a, b)
return the squared distance between two vectors.


DistanceSqVectors2d(a, b)
return the squared 2d (x,y) distance between two vectors.


DistanceVectors(a, b)
returns the distance between two vectors.


dotproduct3d(a, b)
returns the 3d dot product of two vectors.


dotproduct2d(a, b)
returns the 2d dot product of two vectors.


LogVec(name, v)
debug function to print vector in the log


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


CopyVector(dest, src)
copy the components of one vector to another


NegVector(a)
negate a vector


SubVectors(dest, a, b)
subtract one vector from another


SumVectors(a, b)
return the vector sum of vectors a and b in a new vector


FastSumVectors(dest,, a, b)
place the vector sum of vectors a and b in vector dest


DifferenceVectors(a, b)
return the vector difference of vectors a and b in a new vector


FastDifferenceVectors(dest, a, b)
place the vector different of a and b in vector dest
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


ScaleVector(a, b)
scale vector a by factor b


ScaleVectorInPlace(a, b)
scale vector a by factor b (a is modified. There is no return value)


NormalizeVector(a)
normalize a vector (modifies and returns it)


FastScaleVector(dest, a, b)


LerpColors(a, b, k)
linear interpolation between colors a and b


Lerp(a, b, k)
linear interpolation between numbers a and b


__max(a, b)


__min(a, b)


clamp(_n, _min, _max))


Interpolate(actual, goal, speed)


sgn(a)
returns the sign of a number


sgnnz(a)
returns the sign of a number, treating zero as positive


sqr(a)
returns the square of number a


randomF(a, b)
generate a random number between a and 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


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

These functions operate on vectors


vecToAngles(vec)


anglesToVec(angles)


vecFrontToUp(front, up)
compute an up vector from a front vector


vecFrontToRight(front, up)
compute a right vector from a front vector


vecSet(v, x, y, z)
set components of a vector, returns vector


vecCopy(v, vb)
copy components of vector vb to va
vecDistanceSq(v, t)
return distance squared between two points


vec2DDistanceSq(v, t)
return 2D squared distance two points


vecScale(v, t)
scale a vector


vecSLerp(va, vb, t, angle)
spherical interpolation between vectors


vecLerp(va, vb, t))
performs a linear interpolation between vectors


vecSub(va, vb)
subtract one vector from another


vecAdd(va, vb)
add two vectors


vecLenSq(v)
return the squared length (magnitude) of a vector


vecLen(v)
return the length (magnitude) of a vector


vecMul(v, vb)
multiply (component-wise) two vectors


vecNormalize(va)
normalize a vector


vecDot(va, vb)
return the dot product of a two vectors


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)
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