Anaglym exposes a Lua library named ag which contains functions for interfacing with the Engine. In addition to the ag library, there is a std library which contains a "standard library" of Lua functions that do not directly interface with the Anaglym engine. The library functions are documented below.
ag.clearEventHandler(event_name)
This function removes a Lua callback function from being associated with the engine event specified. event_name should be one of the following strings:
ag.doPhysics()
This function invokes the physics processing part of the engine. It is invoked automatically every update step if the "AutoPhysics" mode is enabled; this mode is enabled by default. See setAutoPhysics for more information.
ag.drawObjects()
This function instructs the engine to draw all visible objects. It is invoked automatically every update step if the "AutoDrawObjects" mode is enabled; this mode is enabled by default. See setAutoDrawObjects for more information.
elapsed_msec = ag.elapsedTime()
This function returns the number of milliseconds that have elapsed since the beginning of the program.
ag.endFrame()
This function signals the engine that all drawing is complete for the current update frame. It is invoked automatically if the "AutoEndFrame" mode is enabled; this mode is enabled by default. See setAutoEndFrame for more information.
ag.exit()
This function instructs the engine to exit. Internally, this function enqueues an "exit" event on the event queue to be processed by the engine. This means that Lua code following the call to exit() will be executed and callbacks to other events may still be called. The engine should exit within one update step.
eye_x, eye_y, eye_z, center_x, center_y, center_z, up_x, up_y, up_z = ag.getCamera()
This function returns the camera position (eye coordinates), focus position (center coordinates), and up vector for the current camera settings.
width, height = ag.getScreenSize()
This function returns the dimensions of the engine window, in pixels.
ag.import(lua_source_name)
This function instructs the engine to import a Lua source file named lua_source_name, which should be a string specifying the name of the Lua library without the ".lua" extension. Source files are searched for relative to the folder containing the hosted script first, then relative to the engine library folder. The import() function can be used to load Lua code that is broken into separate source files.
result = ag.isKeyDown(key)
This function returns a boolean value for whether or not the key given by key is currently pressed or not. key should be a string corresponding to a key name. See keys for key names.
object = ag.loadModel(model_name [, scale])
This function loads an object file and returns the object loaded. If the returned value is nil, loading of the object failed. model_name should be a string specifying the base name of the model file, without the ".obj" extension. Models are searched for relative to the folder containing the hosted script first, then relative to the engine library folder. scale is an optional parameter that defaults to 1.0.
object = ag.loadModelStatic(model_name [, scale])
loadModelStatic() is the same as loadModel(), with the exception that the object loaded is created as a static object. A static object can still be placed with setPosition() and setRotation(). A static object will participate in collision detection when physics computations are performed, however a static object will not be moved by any colliding objects.
texture = ag.loadTexture(texture_name)
This function loads a texture file from the file system and returns a Lua reference to the loaded texture. nil is returned if loading the texture fails. The texture_name should contain the file extension, since multiple formats are supported (.jpg, .png, .bmp, etc...). Textures are searched for relative to the folder containing the hosted script first, then relative to the engine library folder.
ag.print(args...)
This function prints its arguments to the standard output. On Windows, this output stream may be redirected to a file (stdout.txt). Example usage:
local x, y, z = my_obj:getPosition()
ag.print("my_obj position: (", x, ", ", y, ", ", z, ")")
ag.println(args...)
Identical to print() but automatically prints a newline ("\n") after printing the arguments.
ag.registerEventHandler(event_name, handler)
This function registers a Lua callback function (handler) to be called when the engine event specified by event_name occurs. There can be only one registered handler per event, so if a previous Lua function was registered for event_name, it will be overwritten to call the new handler. event_name should be one of:
ag.setAutoDrawObjects(enable_flag)
This function sets the "AutoDrawObjects" mode. enable_flag should be true or false. If AutoDrawObjects mode is enabled, then all visible objects in the engine will be drawn automatically every update step. If it is not enabled, one can call ag.drawObjects() to draw all visible objects in the scene.
ag.setAutoEndFrame(enable_flag)
This function sets the "AutoEndFrame" mode. enable_flag should be true or false. If AutoEndFrame mode is enabled, then ag.endFrame() will be invoked automatically after executing the update and update_overlay Lua callback functions.
ag.setAutoPhysics(enable_flag)
This function sets the "AutoPhysics" mode. enable_flag should be true or false. If AutoPhysics mode is enabled, then collision detection and physics processing is performed automatically on every update step. If it is not enabled, one can call ag.doPhysics() to perform physics updates.
ag.setAutoStartFrame(enable_flag)
This function sets the "AutoStartFrame" mode. enable_flag should be true or false. If AutoStartFrame mode is enabled, then ag.startFrame() will be invoked automatically prior to executing the update and update_overlay Lua callback functions.
ag.setCamera(eye_x, eye_y, eye_z [, center_x, center_y, center_z [, up_x, up_y, up_z] ])
This function sets the camera position (eye coordinates), focus point (center coordinates), and up vector. If the center coordinates or up vector are not specified, their values are unchanged from the previous invocation of setCamera(). The default center point is (0, 0, 0). The default up vector is (0, 0, 1).
ag.startFrame()
This function instructs the engine to begin drawing a frame. It is not necessary to call this function if the "AutoStartFrame" mode is enabled. See ag.setAutoStartFrame().