Scripting with LUA

• Globals
  • call_method(this, baseClassObj, methodObj) - used to call a method on a base class
  • void VariantClear(variant struct) - frees the resources used by a VARIANT
  • editChar - IEditCharacter interface
  • viewer - ICharacterView interface
  • activeChar - IUserObject interface of the character currently being edited
  • ui - IUserObject interface of the user interface hierarchy
  • bitLib - provides bitwise operations
    • And - bitwise and, usage: ret = bitLib.And(value1, value2)
    • Or - bitwise or, usage: ret = bitLib.Or(value1, value2)
    • Xor - bitwise xor, usage: ret = bitLib.Xor(value1, value2)
    • Not - bitwise not, usage: ret = bitLib.Not(value)
    • ShiftL - bitwise left shift, usage: ret = bitLib.ShiftL(value, numBitsToShift)
    • ShiftR - bitwise right shift, usage: ret = bitLib.ShiftR(value, numBitsToShift)
    • Set - set a bit, usage: ret = bitLib.Set(value, mask, bitLib.Hex('04010100'))
    • Clear - clear a bit, usage: ret = bitLib.Clear(value, mask, bitLib.Hex('00010000'))
    • Hex - converts a string to a number, usage: ret = bitLib.Hex('FF00FF00')
  • matrixLib - library providing 4x4 matrix operations
    • float determinant(matrix mtx) -- returns the determinant of the matrix
    • matrix identity(matrix mtx) -- sets mtx to the identity matrix
    • float, matrix inverse(matrix mtx, float determinant) -- returns the determinant and inverse of the matrix
    • matrix lookAtLH(vertex3d eye, vertex3d lookAt, vertex3d up)
    • matrix lookAtRH(vertex3d eye, vertex3d lookAt, vertex3d up)
    • matrix multiply(matrix mtx1, matrix mtx2) -- multiplies mtx1 by mtx2 and returns the result
    • matrix orthoLH(float width, float height, float minZ, float maxZ)
    • matrix orthoRH(float width, float height, float minZ, float maxZ)
    • matrix perspectiveFOVLH(float fov, float aspect, float nearZ, float farZ)
    • matrix perspectiveFOVRH(float fov, float aspect, float nearZ, float farZ)
    • matrix perspectiveLH(float width, float height, float nearZ, float farZ)
    • matrix perspectiveRH(float width, float height, float nearZ, float farZ)
    • matrix reflect(float a, float b, float c, float d) -- creates a matrix that will reflect across the plane defined by a,b,c,d
    • matrix rotationAxis(vertex3d axis, float angle) -- creates a matrix with a rotation about the given axis (in radians)
    • matrix rotationX(float radians) -- returns a matrix with a rotation about the x axis
    • matrix rotationY(float radians) -- returns a matrix with a rotation about the y axis
    • matrix rotationZ(float radians) -- returns a matrix with a rotation about the z axis
    • matrix rotationYawPitchRoll(float yaw, float pitch, float roll)
    - yaw, pitch and roll are given in radians
    • matrix scaling(float x, float y, float z) -- returns a scaling matrix
    • matrix translation(float x, float y, float z) -- returns a translation matrix
    • matrix transpose(matrix mtx) -- flips mtx between row major and column major ordering and returns the new matrix
  • quatLib - library providing quaternion operations
    • quaternion conjugate(quaternion q) -- returns the conjugate of a quaternion
    • float dot(quaternion q1, quaternion q2) -- returns the dot product of two quaternions
    • quaternion exp(quaternion q) -- calculates the exponential
    • quaternion identity(quaternion q) -- sets q to the identity quaternion
    • quaternion inverse(quaternion q) -- conjugates and renormalizes a quaternion
    • float length(quaternion q) -- returns the length of a quaternion
    • float lengthSq(quaternion q) -- returns the square of the length of a quaternion
    • quaternion naturalLog(quaternion q) -- calculates the natural logarithm
    • quaternion multiply(quaternion q1, quaternion q2) -- multiplies two quaternions
    • quaternion normalize(quaternion q) -- computes a unit length quaternion
    • quaternion rotationAxis(vertex3d axis, float roll) -- rotates a quaternion about an arbitrary axis
    • quaternion matrixToQuaternion(matrix mtx) -- builds a quaternion from a rotation matrix
    • matrix quaternionToMatrix(quaternion q) -- builds a rotation matrix from a quaternion
    • quaternion rotationYawPitchRoll(float yaw, float pitch, float roll) -- builds a quaternion with the given yaw, pitch, and roll
    • quaternion slerp(quaternion start, quaternion end, float pct) -- interpolates between two quaternions, using spherical linear interpolation
• These are additional function available certain types of objects
  • interfaces (e.g. IMesh, ISkeleton, IUserObject, ...)
    interfaces can be cast to other interfaces if the object supports that interface. This is equivalent to calling QueryInterface on a COM object. Syntax is as follows:
    • mesh = IMesh(obj);
    • obj = IUserObject(mesh);
    methods available on all interface instances:
    
    • bool isSet() - returns true if the object has been initialized, false otherwise
  • structs (e.g. vertex3d, fragVertex, fragTriangle, ...)
    methods available on all struct instances:
    
    • bool isSet() - returns true if the object has been initialized, false otherwise
    • void copy(struct instance) - copies the contents of one struct to another, the 2 structs must of the same type
  • arrays - you can create an array of just about any type using the following syntax:
    • myArray = [typename]_Array();
    • myArray = float_Array();
    methods available on all array instances:
    
    • int size() - returns the number of elements in the array
    • void resize(int newsize) - reallocates the memory used by the array
    • int add(typename item) - adds the given item to the end of the array and returns its index
    • void remove(int index) - removes the element at the given index
    • void removeall() - removes all elements from the array
• LuaLocalListener is used to get events from the local hierarchy, (i.e. the hierarchy that contains the listener itself) This object listens for events using IUserObject::Listen.
• LuaGlobalListener is used to get events from multiple hierarchies. This is especially useful for Tools that may need to get events from the active character which can be destroyed and created several times during the course of the program. This object listens for events using IEditCharacter::Listen.
• ScriptCode is wrapped into a function by the LuaScript plugin e.g. if you enter "print('hello world')" into a ScriptCode property, the plugin will convert it to this internally:

  function()
  print('hello world')
  end
  

  If the ScriptCode property is on an event listener object (LuaLocalListener, LuaGlobalListener) 2 parameters are added.
  • 'this' is an IUserObject interface. Its value depends on the properties of the Listener object. If the Listener::Type property is set to 'Class' and the parent of the Listener is a class and the Listener::Source property is empty then the 'this' parameter will be the object where the event originated (i.e. event.obj). In all other cases 'this' will be the parent of the Listener object.
  • 'event' is the fragEvent structure that contains data about the event. event.type tells you which member of the event contains the data (e.g. if event.type == eventConstructor then event.construct will contain the data) It's important to access the correct member of the event since the event uses a union, other members may appear to be filled in but would contain invalid values