1071 lines
33 KiB
HTML
1071 lines
33 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<title>Anaglym Documentation</title>
|
|
<style type="text/css">
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<h1>Anaglym Documentation</h1>
|
|
|
|
<p>
|
|
Anaglym exposes a Lua library named <tt>ag</tt> which contains functions
|
|
for interfacing with the Engine.
|
|
In addition to the <tt>ag</tt> library, there is a <tt>std</tt> library
|
|
which contains a "standard library" of Lua functions that do not directly
|
|
interface with the Anaglym engine.
|
|
The library functions are documented below.
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<a href="#ag"><tt>ag</tt> library</a>
|
|
<ul>
|
|
<li><a href="#object_creation">object creation functions</a></li>
|
|
<li><a href="#object">object member methods</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#std"><tt>std</tt> library</a></li>
|
|
<li><a href="#handlers">Lua Event Handlers</a></li>
|
|
<li><a href="#key_names">Key Names</a></li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<a name="ag" />
|
|
<h2><tt>ag</tt> library</h2>
|
|
|
|
<a name="ag_callList" />
|
|
<h3>callList</h3>
|
|
<p><tt>ag.callList(display_list)</tt><p>
|
|
<p>
|
|
This function invokes a display list created with
|
|
<a href="#ag_startList"><tt>startList()</tt></a>.
|
|
</p>
|
|
|
|
<a name="ag_clearEventHandler" />
|
|
<h3>clearEventHandler</h3>
|
|
<p><tt>ag.clearEventHandler(event_name)</tt><p>
|
|
<p>
|
|
This function removes a Lua callback function from being associated
|
|
with the engine event specified.
|
|
<tt>event_name</tt> should be a string containing an event name.
|
|
See <a href="#handlers">Lua event handlers</a> for a list of events.
|
|
</p>
|
|
|
|
<a name="ag_doPhysics" />
|
|
<h3>doPhysics</h3>
|
|
<p><tt>ag.doPhysics()</tt></p>
|
|
<p>
|
|
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 <a href="#ag_setAutoPhysics">setAutoPhysics</a> for more information.
|
|
</p>
|
|
|
|
<a name="ag_drawArc" />
|
|
<h3>drawArc</h3>
|
|
<p><tt>ag.drawArc(r, g, b, x, y, radius, a1, a2)</tt></p>
|
|
<p>
|
|
This function tells the engine to draw an arc to the screen.
|
|
The color of the arc is specified by (r, g, b).
|
|
<tt>x</tt> and <tt>y</tt> specify the coordinates of the center
|
|
of the arc.
|
|
The arc ranges from angle <tt>a1</tt> to <tt>a2</tt>, which are
|
|
specified in degrees, going counter-clockwise from the East.
|
|
<tt>drawArc()</tt> should normally be called from the
|
|
<tt>update_overlay</tt> event handler.
|
|
</p>
|
|
|
|
<a name="ag_drawCircle" />
|
|
<h3>drawCircle</h3>
|
|
<p><tt>ag.drawCircle(r, g, b, x, y, radius)</tt></p>
|
|
<p>
|
|
This function tells the engine to draw a circle to the screen.
|
|
The color of the circle is specified by (r, g, b).
|
|
<tt>x</tt> and <tt>y</tt> specify the coordinates of the center
|
|
of the circle.
|
|
<tt>drawCircle()</tt> should normally be called from the
|
|
<tt>update_overlay</tt> event handler.
|
|
</p>
|
|
|
|
<a name="ag_drawImage" />
|
|
<h3>drawImage</h3>
|
|
<p><tt>ag.drawImage(width, height, x, y, texture, [, rot])</tt></p>
|
|
<p>
|
|
This function tells the engine to draw an image to the screen.
|
|
<tt>width</tt> and <tt>height</tt> specify the size of the image,
|
|
in pixels.
|
|
<tt>x</tt> and <tt>y</tt> specify the coordinates of the center
|
|
of the image.
|
|
The image to be drawn is specified by <tt>texture</tt>, which
|
|
should be loaded by
|
|
<a href="#ag_loadTexture"><tt>ag.loadTexture()</tt></a>.
|
|
<tt>drawImage()</tt> should normally be called from the
|
|
<tt>update_overlay</tt> event handler.
|
|
</p>
|
|
|
|
<a name="ag_drawLine" />
|
|
<h3>drawLine</h3>
|
|
<p><tt>ag.drawLine(r, g, b, x1, y1, x2, y2 [, width])</tt></p>
|
|
<p>
|
|
This function tells the engine to draw a line to the screen.
|
|
The color of the line is given by (r, g, b).
|
|
The start and end coordinates of the line are (x1, y1) and (x2, y2).
|
|
<tt>width</tt> is an optional parameter and defaults to 1 if not
|
|
specified.
|
|
It controls the width of the line to be drawn.
|
|
<tt>drawLine()</tt> should normally be called from the
|
|
<tt>update_overlay</tt> event handler.
|
|
</p>
|
|
|
|
<a name="ag_drawObjects" />
|
|
<h3>drawObjects</h3>
|
|
<p><tt>ag.drawObjects()</tt></p>
|
|
<p>
|
|
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 <a href="#ag_setAutoDrawObjects">setAutoDrawObjects</a>
|
|
for more information.
|
|
</p>
|
|
|
|
<a name="ag_drawPoint" />
|
|
<h3>drawPoint</h3>
|
|
<p><tt>ag.drawPoint(size, r, g, b, x, y [, z])</tt></p>
|
|
<p>
|
|
This function draws a point to the screen.
|
|
The size of the point is given by <tt>size</tt>.
|
|
The point will be antialiased.
|
|
The color of the point is given by (r, g, b).
|
|
The position of the point is given by (x, y, z).
|
|
If not specified, <tt>z</tt> defaults to 0.
|
|
This function can be called from either the <tt>update_event</tt>
|
|
or the <tt>update_overlay_event</tt>.
|
|
</p>
|
|
|
|
<a name="ag_drawRect" />
|
|
<h3>drawRect</h3>
|
|
<p><tt>ag.drawRect(r, g, b, width, height, x, y [, rot])</tt></p>
|
|
<p>
|
|
This function draws a rectangle to the screen.
|
|
The color of the rectangle is given by (r, g, b).
|
|
The size is given by <tt>width</tt> and <tt>height</tt>.
|
|
The center of the rectangle is given by (x, y).
|
|
<tt>rot</tt> is an optional parameter that defaults to 0.0.
|
|
It specifies the rotation of the rectangle.
|
|
<tt>drawRect()</tt> should normally be called from the
|
|
<tt>update_overlay</tt> event handler.
|
|
</p>
|
|
|
|
<a name="ag_drawText" />
|
|
<h3>drawText</h3>
|
|
<p><tt>ag.drawText(message, r, g, b, ptsize, x, y)</tt></p>
|
|
<p>
|
|
This function draws the text <tt>message</tt>, which should be
|
|
a string, to the screen at position (x, y), with color
|
|
specified by (r, g, b), and with font size <tt>ptsize</tt>.
|
|
It should normally be called from the <tt>update_overlay</tt>
|
|
event handler.
|
|
</p>
|
|
|
|
<a name="ag_elapsedTime" />
|
|
<h3>elapsedTime</h3>
|
|
<p><tt>elapsed_msec = ag.elapsedTime()</tt></p>
|
|
<p>
|
|
This function returns the number of milliseconds that have elapsed
|
|
since the beginning of the program.
|
|
</p>
|
|
|
|
<a name="ag_endFrame" />
|
|
<h3>endFrame</h3>
|
|
<p><tt>ag.endFrame()</tt></p>
|
|
<p>
|
|
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 <a href="#ag_setAutoEndFrame">setAutoEndFrame</a> for more
|
|
information.
|
|
</p>
|
|
|
|
<a name="ag_endList" />
|
|
<h3>endList</h3>
|
|
<p><tt>ag.endList()</tt></p>
|
|
<p>
|
|
This function ends the creation of a display list created with
|
|
<a href="#ag_startList"><tt>startList()</tt></a>.
|
|
Every call to <tt>startList()</tt> should have a corresponding call
|
|
to <tt>endList()</tt>.
|
|
</p>
|
|
|
|
<a name="ag_exit" />
|
|
<h3>exit</h3>
|
|
<p><tt>ag.exit()</tt></p>
|
|
<p>
|
|
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 <tt>exit()</tt>
|
|
will be executed and callbacks to other events may still be called.
|
|
The engine should exit within one update step.
|
|
</p>
|
|
|
|
<a name="ag_fillRect" />
|
|
<h3>fillRect</h3>
|
|
<p><tt>ag.fillRect(r, g, b, width, height, x, y [, rot])</tt></p>
|
|
<p>
|
|
This function draws a solid, filled rectangle to the screen.
|
|
The color of the rectangle is given by (r, g, b).
|
|
The size is given by <tt>width</tt> and <tt>height</tt>.
|
|
The center of the rectangle is given by (x, y).
|
|
<tt>rot</tt> is an optional parameter that defaults to 0.0.
|
|
It specifies the rotation of the rectangle.
|
|
<tt>fillRect()</tt> should normally be called from the
|
|
<tt>update_overlay</tt> event handler.
|
|
</p>
|
|
|
|
<a name="ag_getCamera" />
|
|
<h3>getCamera</h3>
|
|
<p><tt>eye_x, eye_y, eye_z, center_x, center_y, center_z, up_x, up_y, up_z = ag.getCamera()</tt></p>
|
|
<p>
|
|
This function returns the camera position (eye coordinates),
|
|
focus position (center coordinates), and up vector for the current
|
|
camera settings.
|
|
</p>
|
|
|
|
<a name="ag_getTextSize" />
|
|
<h3>getTextSize</h3>
|
|
<p><tt>width, height = ag.getTextSize(message, ptsize)</tt></p>
|
|
<p>
|
|
This function returns the width and height, in pixels, that
|
|
the text specified by <tt>message</tt>, which should be a string,
|
|
would take when drawn to the screen using font size <tt>ptsize</tt>.
|
|
</p>
|
|
|
|
<a name="ag_getScreenSize" />
|
|
<h3>getScreenSize</h3>
|
|
<p><tt>width, height = ag.getScreenSize()</tt></p>
|
|
<p>
|
|
This function returns the dimensions of the engine window, in pixels.
|
|
</p>
|
|
|
|
<a name="ag_import" />
|
|
<h3>import</h3>
|
|
<p><tt>ag.import(lua_source_name)</tt></p>
|
|
<p>
|
|
This function instructs the engine to import a Lua source file named
|
|
<tt>lua_source_name</tt>, 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 <tt>import()</tt> function can be used to load Lua code that
|
|
is broken into separate source files, and to load
|
|
libraries such as <a href="#std">std</a>.
|
|
</p>
|
|
|
|
<a name="ag_isKeyDown" />
|
|
<h3>isKeyDown</h3>
|
|
<p><tt>result = ag.isKeyDown(key)</tt></p>
|
|
<p>
|
|
This function returns a boolean value for whether or not the key
|
|
given by <tt>key</tt> is currently pressed or not.
|
|
<tt>key</tt> should be a string corresponding to a key name.
|
|
See <a href="#key_names">Key Names</a> for key names.
|
|
</p>
|
|
|
|
<a name="ag_loadModel" />
|
|
<h3>loadModel</h3>
|
|
<p><tt>object = ag.loadModel(model_name [, scale])</tt></p>
|
|
<p>
|
|
This function loads an object file and returns the object loaded.
|
|
If the returned value is <tt>nil</tt>, loading of the object failed.
|
|
<tt>model_name</tt> 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.
|
|
<tt>scale</tt> is an optional parameter that defaults to 1.0.
|
|
</p>
|
|
|
|
<a name="ag_loadModelStatic" />
|
|
<h3>loadModelStatic</h3>
|
|
<p><tt>object = ag.loadModelStatic(model_name [, scale])</tt></p>
|
|
<p>
|
|
<tt>loadModelStatic()</tt> is the same as <tt>loadModel()</tt>, with
|
|
the exception that the object loaded is created as a static object.
|
|
A static object can still be placed with
|
|
<a href="#object_setPosition">setPosition()</a> and
|
|
<a href="#object_setRotation">setRotation()</a>.
|
|
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.
|
|
</p>
|
|
|
|
<a name="ag_loadTexture" />
|
|
<h3>loadTexture</h3>
|
|
<p><tt>texture = ag.loadTexture(texture_name)</tt></p>
|
|
<p>
|
|
This function loads a texture file from the file system and returns
|
|
a Lua reference to the loaded texture.
|
|
<tt>nil</tt> is returned if loading the texture fails.
|
|
The <tt>texture_name</tt> 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.
|
|
</p>
|
|
|
|
<a name="ag_print" />
|
|
<h3>print</h3>
|
|
<p><tt>ag.print(args...)</tt></p>
|
|
<p>
|
|
This function prints its arguments to the standard output.
|
|
It is mainly used for debugging when developing Lua scripts.
|
|
On Windows, this output stream may be redirected to a file (stdout.txt).
|
|
Example usage:
|
|
<pre>local x, y, z = my_obj:getPosition()
|
|
ag.print("my_obj position: (", x, ", ", y, ", ", z, ")")
|
|
</pre>
|
|
</p>
|
|
|
|
<a name="ag_println" />
|
|
<h3>println</h3>
|
|
<p><tt>ag.println(args...)</tt></p>
|
|
<p>
|
|
Identical to <tt>print()</tt> but automatically prints a newline ("\n")
|
|
after printing the arguments.
|
|
</p>
|
|
|
|
<a name="ag_registerEventHandler" />
|
|
<h3>registerEventHandler</h3>
|
|
<p><tt>ag.registerEventHandler(event_name, handler)</tt></p>
|
|
<p>
|
|
This function registers a Lua callback function (<tt>handler</tt>)
|
|
to be called when the engine event specified by <tt>event_name</tt>
|
|
occurs.
|
|
There can be only one registered handler per event, so if a previous
|
|
Lua function was registered for <tt>event_name</tt>, it will be
|
|
overwritten to call the new handler.
|
|
<tt>event_name</tt> should be a string containing the name of the event.
|
|
See <a href="#handlers">Lua event handlers</a> for a list of event names.
|
|
</p>
|
|
<p>
|
|
When the Lua script is initially loaded, any functions found
|
|
that have names matching an event name with "_event" appended
|
|
(ex. "mouse_motion_event" for the "mouse_motion" event)
|
|
are registered automatically as handlers for their corresponding
|
|
events.
|
|
</p>
|
|
|
|
<a name="ag_setAutoDrawObjects" />
|
|
<h3>setAutoDrawObjects</h3>
|
|
<p><tt>ag.setAutoDrawObjects(enable_flag)</tt></p>
|
|
<p>
|
|
This function sets the "AutoDrawObjects" mode.
|
|
<tt>enable_flag</tt> should be <tt>true</tt> or <tt>false</tt>.
|
|
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
|
|
<a href="#ag_drawObjects"><tt>ag.drawObjects()</tt></a>
|
|
to draw all visible objects in the scene.
|
|
The AutoDrawObjects mode is initially enabled.
|
|
</p>
|
|
|
|
<a name="ag_setAutoEndFrame" />
|
|
<h3>setAutoEndFrame</h3>
|
|
<p><tt>ag.setAutoEndFrame(enable_flag)</tt></p>
|
|
<p>
|
|
This function sets the "AutoEndFrame" mode.
|
|
<tt>enable_flag</tt> should be <tt>true</tt> or <tt>false</tt>.
|
|
If AutoEndFrame mode is enabled, then
|
|
<a href="#ag_endFrame"><tt>ag.endFrame()</tt></a>
|
|
will be invoked automatically after executing the update
|
|
and update_overlay Lua callback functions.
|
|
The AutoEndFrame mode is initially enabled.
|
|
</p>
|
|
|
|
<a name="ag_setAutoPhysics" />
|
|
<h3>setAutoPhysics</h3>
|
|
<p><tt>ag.setAutoPhysics(enable_flag)</tt></p>
|
|
<p>
|
|
This function sets the "AutoPhysics" mode.
|
|
<tt>enable_flag</tt> should be <tt>true</tt> or <tt>false</tt>.
|
|
If AutoPhysics mode is enabled, then collision detection and
|
|
physics processing are performed automatically on every update step.
|
|
If it is not enabled, one can call
|
|
<a href="#ag_doPhysics"><tt>ag.doPhysics()</tt></a>
|
|
to perform physics updates.
|
|
The AutoPhysics mode is initially enabled.
|
|
</p>
|
|
|
|
<a name="ag_setAutoStartFrame" />
|
|
<h3>setAutoStartFrame</h3>
|
|
<p><tt>ag.setAutoStartFrame(enable_flag)</tt></p>
|
|
<p>
|
|
This function sets the "AutoStartFrame" mode.
|
|
<tt>enable_flag</tt> should be <tt>true</tt> or <tt>false</tt>.
|
|
If AutoStartFrame mode is enabled, then
|
|
<a href="#ag_startFrame"><tt>ag.startFrame()</tt></a>
|
|
will be invoked automatically prior to executing the update and
|
|
update_overlay Lua callback functions.
|
|
The AutoStartFrame mode is initially enabled.
|
|
</p>
|
|
|
|
<a name="ag_setCamera" />
|
|
<h3>setCamera</h3>
|
|
<p><tt>ag.setCamera(eye_x, eye_y, eye_z [, center_x, center_y, center_z [, up_x, up_y, up_z] ])</tt></p>
|
|
<p>
|
|
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 <tt>setCamera()</tt>.
|
|
The default center point is (0, 0, 0).
|
|
The default up vector is (0, 0, 1).
|
|
</p>
|
|
|
|
<a name="ag_setGravity" />
|
|
<h3>setGravity</h3>
|
|
<p><tt>ag.setGravity(gx, gy, gz)</tt></p>
|
|
<p>
|
|
This function sets the gravity vector to (gx, gy, gz).
|
|
The default gravity vector is (0, 0, -9.81).
|
|
</p>
|
|
|
|
<a name="ag_startFrame" />
|
|
<h3>startFrame</h3>
|
|
<p><tt>ag.startFrame()</tt></p>
|
|
<p>
|
|
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 <a href="#ag_setAutoStartFrame">ag.setAutoStartFrame()</a>.
|
|
</p>
|
|
|
|
<a name="ag_startList" />
|
|
<h3>startList</h3>
|
|
<p><tt>displaylist = ag.startList()</tt></p>
|
|
<p>
|
|
This function instructs the engine to start a display list.
|
|
Any <tt>draw*()</tt> functions called between <tt>startList()</tt>
|
|
and <a href="#ag_endList"><tt>endList()</tt></a> will be stored in the display
|
|
list for efficient execution.
|
|
The display list can be called with
|
|
<a href="#ag_callList"><tt>callList()</tt></a>.
|
|
</p>
|
|
|
|
<hr />
|
|
|
|
<a name="object_creation" />
|
|
<h2>Object creation functions</h2>
|
|
|
|
<p>
|
|
The following functions can be used to create "managed" objects.
|
|
These objects are "managed" by the Lua script (as opposed to having
|
|
all of their attributes defined in a model file).
|
|
The properties of managed objects, such as the color, texture, position,
|
|
and rotation, can be controlled by using the
|
|
<a href="#object">object member methods</a>.
|
|
</p>
|
|
|
|
<a name="ag_createBox" />
|
|
<h3><tt>createBox</tt></h3>
|
|
<p><tt>obj = ag.createBox(width, depth, height)</tt></p>
|
|
<p>
|
|
This function creates a managed object which is a box with
|
|
dimensions given by (width, depth, height).
|
|
The center of the box is initially located at the origin.
|
|
</p>
|
|
|
|
<a name="ag_createBoxStatic" />
|
|
<h3><tt>createBoxStatic</tt></h3>
|
|
<p><tt>obj = ag.createBoxStatic(width, depth, height)</tt></p>
|
|
<p>
|
|
Identical to <tt>ag.createBox()</tt> except that the created
|
|
object is static.
|
|
</p>
|
|
|
|
<a name="ag_createCapsul" />
|
|
<h3><tt>createCapsule</tt></h3>
|
|
<p><tt>obj = ag.createCapsule(radius, length)</tt></p>
|
|
<p>
|
|
This function creates a capsule managed object.
|
|
A capsule is like a cylinder, but has a half-sphere "capping"
|
|
each end of the cylinder.
|
|
<tt>radius</tt> specifies the radius of the cylinder (and caps).
|
|
<tt>length</tt> specifies the length of the straight part of
|
|
the capsule (not including the caps).
|
|
The capsule is oriented with its axis along the Z axis and its
|
|
center point at the origin.
|
|
</p>
|
|
|
|
<a name="ag_createCapsuleStatic" />
|
|
<h3><tt>createCapsuleStatic</tt></h3>
|
|
<p><tt>obj = ag.createCapsuleStatic(radius, length)</tt></p>
|
|
<p>
|
|
Identical to <tt>ag.createCapsule()</tt> except that the created
|
|
object is static.
|
|
</p>
|
|
|
|
<a name="ag_createPlane" />
|
|
<h3><tt>createPlane</tt></h3>
|
|
<p>1) <tt>obj = ag.createPlane(a, b, c, d)</tt></p>
|
|
<p>2) <tt>obj = ag.createPlane(x, y, z, rot_x, rot_y, rot_z)</tt></p>
|
|
<p>
|
|
The <tt>createPlane()</tt> function creates a managed plane object.
|
|
All planes are static and are not moved as a result of physics
|
|
collisions (other objects can still bounce off them).
|
|
In the four-argument form, the plane is created with equation
|
|
<tt>ax + by + cz = d</tt>.
|
|
(a, b, c) specifies the normal vector for the plane.
|
|
In the six-argument form, the plane is created by specifying a point
|
|
on the plane, with coordinates (x, y, z), and the Euler rotation
|
|
angles around the x, y, and z axis.
|
|
Specifying no rotation would use the default plane normal of (0, 0, 1).
|
|
If you would like to create a plane by specifying a point on
|
|
the surface and the surface normal, see the
|
|
<a href="#std_createPlanePointNormal">std.createPlanePointNormal()</a>
|
|
function.
|
|
</p>
|
|
|
|
<a name="ag_createSphere" />
|
|
<h3><tt>createSphere</tt></h3>
|
|
<p><tt>obj = ag.createSphere(radius)</tt></p>
|
|
<p>
|
|
This function creates a managed sphere object with the radius given.
|
|
The center of the sphere is initially located at the origin.
|
|
</p>
|
|
|
|
<a name="ag_createSphereStatic" />
|
|
<h3><tt>createSphereStatic</tt></h3>
|
|
<p><tt>obj = ag.createSphereStatic(radius)</tt></p>
|
|
<p>
|
|
Identical to <tt>ag.createSphere()</tt> except that the created
|
|
object is static.
|
|
</p>
|
|
|
|
<hr />
|
|
|
|
<a name="object" />
|
|
<h2>Object member methods</h2>
|
|
|
|
<a name="object_addForce" />
|
|
<h3>addForce</h3>
|
|
<p><tt>obj:addForce(xf, yf, zf)</tt></p>
|
|
<p>
|
|
This function adds a one-time force to <tt>obj</tt>
|
|
with a force vector (xf, yf, zf).
|
|
</p>
|
|
|
|
<a name="object_addForceRel" />
|
|
<h3>addForceRel</h3>
|
|
<p><tt>obj:addForceRel</tt></p>
|
|
<p>
|
|
This function adds a one-time force to <tt>obj</tt>
|
|
with a force vector (xf, yf, zf) which is
|
|
relative to the local reference frame of <tt>obj</tt>.
|
|
</p>
|
|
|
|
<a name="object_addTorque" />
|
|
<h3>addTorque</h3>
|
|
<p><tt>obj:addTorque(xr, yr, zr)</tt></p>
|
|
<p>
|
|
This function adds torque (a rotational force) to <tt>obj</tt>.
|
|
The torque vector around global x, y, and z axes is given by (xr, yr, zr).
|
|
</p>
|
|
|
|
<a name="object_addTorqueRel" />
|
|
<h3>addTorqueRel</h3>
|
|
<p><tt>obj:addTorqueRel(xr, yr, zr)</tt></p>
|
|
<p>
|
|
This function adds torque (a rotational force) to <tt>obj</tt>.
|
|
The torque vector around <tt>obj</tt>'s local x, y, and z axes
|
|
is given by (xr, yr, zr).
|
|
</p>
|
|
|
|
<a name="object_clone" />
|
|
<h3>clone</h3>
|
|
<p><tt>new_obj = obj:clone()</tt></p>
|
|
<p>
|
|
This function makes a copy of the object in the engine.
|
|
This is more efficient than creating a new object in whatever
|
|
manner was used to create <tt>obj</tt>.
|
|
<tt>new_obj</tt> will have all of its own parameters - position,
|
|
rotation, color, texture, etc...
|
|
However, these parameter values will be instantiated with the corresponding
|
|
values from <tt>obj</tt> at the time of cloning.
|
|
One should call
|
|
<tt>new_obj:<a href="#object_setPosition">setPosition()</a></tt>
|
|
in order to place <tt>new_obj</tt> somewhere where it is not
|
|
intersecting with other objects in order to pacify the physics engine.
|
|
</p>
|
|
|
|
<a name="object_destroy" />
|
|
<h3>destroy</h3>
|
|
<p><tt>obj:destroy()</tt></p>
|
|
<p>
|
|
This function destroys the object in the engine.
|
|
<tt>obj</tt> should not be used after this method is called.
|
|
</p>
|
|
|
|
<a name="object_draw" />
|
|
<h3>draw</h3>
|
|
<p><tt>obj:draw()</tt></p>
|
|
<p>
|
|
This function will draw <tt>obj</tt> to the screen.
|
|
It is called automatically by <tt>ag.drawObjects()</tt>,
|
|
so calling it is only required if the "AutoDrawObjects" mode
|
|
is disabled, and <tt>ag.drawObjects()</tt> is not called.
|
|
</p>
|
|
|
|
<a name="object_getAABB" />
|
|
<h3>getAABB</h3>
|
|
<p><tt>minx, miny, minz, maxx, maxy, maxz = obj:getAABB()</tt></p>
|
|
<p>
|
|
This function returns the coordinates of the axis-aligned
|
|
box bounding <tt>obj</tt>.
|
|
</p>
|
|
|
|
<a name="object_getMass" />
|
|
<h3>getMass</h3>
|
|
<p><tt>mass = obj:getMass()</tt></p>
|
|
<p>
|
|
This function returns the mass of <tt>obj</tt>.
|
|
</p>
|
|
|
|
<a name="object_getPosition" />
|
|
<h3>getPosition</h3>
|
|
<p><tt>x, y, z = obj:getPosition()</tt></p>
|
|
<p>
|
|
This function returns the coordinates (x, y, z) of the object.
|
|
Normally, the center-of-mass of the object is located at its
|
|
local origin.
|
|
The coordinates of the object's local origin are returned by
|
|
this call, so these coordinates will be the coordinates of the
|
|
object's center-of-mass.
|
|
</p>
|
|
|
|
<a name="object_getSize" />
|
|
<h3>getSize</h3>
|
|
<p><tt>sx, sy, sz = obj:getSize()</tt></p>
|
|
<p>
|
|
This function returns the axis-aligned size of <tt>obj</tt>.
|
|
</p>
|
|
|
|
<a name="object_setColor" />
|
|
<h3>setColor</h3>
|
|
<p><tt>obj:setColor(r, g, b)</tt></p>
|
|
<p>
|
|
This function sets the color of the object.
|
|
The parameters correspond to the red, green, and blue components
|
|
of the object color.
|
|
Each component should be between 0.0 and 1.0.
|
|
</p>
|
|
|
|
<a name="object_setMass" />
|
|
<h3>setMass</h3>
|
|
<p><tt>obj:setMass(new_mass)</tt></p>
|
|
<p>
|
|
This function sets the mass of <tt>obj</tt> to <tt>new_mass</tt>.
|
|
</p>
|
|
|
|
<a name="object_setPosition" />
|
|
<h3>setPosition</h3>
|
|
<p><tt>obj:setPosition(x, y, z)</tt></p>
|
|
<p>
|
|
This function sets the coordinates for the object's
|
|
center-of-mass (local origin) to (x, y, z).
|
|
</p>
|
|
|
|
<a name="object_setRotation" />
|
|
<h3>setRotation</h3>
|
|
<p><tt>obj:setRotation(xr, yr, zr)</tt></p>
|
|
<p>
|
|
This function sets the object's rotation as specified
|
|
by Euler angles (xr, yr, zr).
|
|
</p>
|
|
|
|
<a name="object_setTexture" />
|
|
<h3>setTexture</h3>
|
|
<p><tt>obj:setTexture(tex)</tt></p>
|
|
<p>
|
|
This function sets the texture of <tt>obj</tt> to <tt>tex</tt>.
|
|
<tt>tex</tt> should be a Lua reference to a texture loaded with
|
|
<a href="#ag_loadTexture">ag.loadTexture()</a>.
|
|
</p>
|
|
|
|
<a name="object_setTextureScale" />
|
|
<h3>setTextureScale</h3>
|
|
<p><tt>obj:setTextureScale(scale)</tt></p>
|
|
<p>
|
|
This function sets the "texture scale" for <tt>obj</tt>.
|
|
Currently, texture scaling is only supported for boxes and planes.
|
|
<tt>scale</tt> actually scales the texture coordinates.
|
|
Hence a scale of 4 would appear to shrink the texture by a factor of
|
|
4 and tile the texture 16 times where it normally would have once.
|
|
</p>
|
|
|
|
<a name="object_setVisible" />
|
|
<h3>setVisible</h3>
|
|
<p><tt>obj:setVisible(visible_flag)</tt></p>
|
|
<p>
|
|
This function sets the visibility of <tt>obj</tt> to <tt>visible_flag</tt>.
|
|
If <tt>visible_flag</tt> is <tt>true</tt>, then the object will be drawn.
|
|
Newly created objects are visible by default.
|
|
</p>
|
|
|
|
<hr />
|
|
|
|
<a name="std" />
|
|
<h2><tt>std</tt> library</h2>
|
|
|
|
<p>
|
|
The <tt>std</tt> Lua library supplies a set of Lua functions that may
|
|
be useful to Lua scripts being executed.
|
|
It is not imported by default.
|
|
Import it like this:
|
|
<pre>
|
|
ag.import("std")
|
|
</pre>
|
|
</p>
|
|
|
|
<a name="std_createPlanePointNormal" />
|
|
<h3>createPlanePointNormal</h3>
|
|
<p><tt>obj = std.createPlanePointNormal(x, y, z, nx, ny, nz)</tt></p>
|
|
<p>
|
|
This function simply wraps
|
|
<a href="#ag_createPlane"><tt>ag.createPlane()</tt></a>
|
|
allowing the user to specify a point on the plane with coordinates (x, y, z)
|
|
and the surface normal of the plane (nx, ny, nz).
|
|
</p>
|
|
|
|
<a name="std_crossProduct" />
|
|
<h3>crossProduct</h3>
|
|
<p><tt>cp = std.crossProduct(vec1, vec2)</tt></p>
|
|
<p>
|
|
This function returns the cross product of the two vectors
|
|
<tt>vec1</tt> and <tt>vec2</tt>.
|
|
The return value is a Lua array with indices 1 to 3.
|
|
The indices of <tt>vec1</tt> and <tt>vec2</tt> should be from 1 to 3.
|
|
This allows specifying a Lua array directly as a parameter to the function.
|
|
For example:
|
|
<pre>
|
|
local z_axis = std.crossProduct({1, 0, 0}, {0, 1, 0})
|
|
</pre>
|
|
</p>
|
|
|
|
<a name="std_dotProduct" />
|
|
<h3>dotProduct</h3>
|
|
<p><tt>dp = std.dotProduct(vec1, vec2)</tt></p>
|
|
<p>
|
|
This function returns the dot product of the two vectors.
|
|
The indices of <tt>vec1</tt> and <tt>vec2</tt> should be from 1 to 3.
|
|
This allows specifying a Lua array directly as a parameter to the function.
|
|
</p>
|
|
|
|
<a name="std_loadModelBounds" />
|
|
<h3>loadModelBounds</h3>
|
|
<p><tt>obj = std.loadModelBounds(model_name, max_x, max_y, max_z)</tt></p>
|
|
<p>
|
|
This function loads a model from the model file given by the string
|
|
<tt>model_name</tt> (without extension).
|
|
The scale used when loading the model is determined automatically.
|
|
It is always a uniform scale.
|
|
The scale is calculated to be the maximum value such that the model
|
|
fits in the bounding box given by (max_x, max_y, max_z).
|
|
To ignore an axis when calculating this scale, set its corresponding
|
|
component to 0.
|
|
For example:
|
|
</p>
|
|
<p>
|
|
<tt>obj = std.loadModelBounds("pillar", 0, 0, 10)</tt>
|
|
</p>
|
|
<p>
|
|
will load the "pillar" model and scale it (uniformly) so that its height is 10.
|
|
</p>
|
|
|
|
<a name="std_pctx" />
|
|
<h3>pctx</h3>
|
|
<p><tt>pixels_x = std.pctx(percent)</tt></p>
|
|
<p>
|
|
This function returns the number of pixels corresponding to
|
|
<tt>percent</tt> percent of the screen's X axis.
|
|
<tt>percent</tt> should be between 0.0 and 1.0.
|
|
</p>
|
|
|
|
<a name="std_pcty" />
|
|
<h3>pcty</h3>
|
|
<p><tt>pixels_y = std.pcty(percent)</tt></p>
|
|
<p>
|
|
This function returns the number of pixels corresponding to
|
|
<tt>percent</tt> percent of the screen's Y axis.
|
|
<tt>percent</tt> should be between 0.0 and 1.0.
|
|
</p>
|
|
|
|
|
|
<hr />
|
|
|
|
<a name="handlers" />
|
|
<h2>Lua Event Handlers</h2>
|
|
|
|
<p>
|
|
The following is a list of all events that the Anaglym engine
|
|
handles:
|
|
<ul>
|
|
<li><a href="#handler_update"><tt>update</tt></a></li>
|
|
<li><a href="#handler_update_overlay"><tt>update_overlay</tt></a></li>
|
|
<li><a href="#handler_key_down"><tt>key_down</tt></a></li>
|
|
<li><a href="#handler_key_up"><tt>key_up</tt></a></li>
|
|
<li><a href="#handler_mousebutton_down"><tt>mousebutton_down</tt></a></li>
|
|
<li><a href="#handler_mousebutton_up"><tt>mousebutton_up</tt></a></li>
|
|
<li><a href="#handler_mouse_motion"><tt>mouse_motion</tt></a></li>
|
|
</ul>
|
|
Lua callback functions may be registered for each of these events.
|
|
</p>
|
|
|
|
<p>
|
|
When a Lua script is loaded, any defined function that matches the
|
|
name of an engine event with "<tt>_event</tt>" appended will
|
|
automatically be registered as a callback for that engine event.
|
|
For example, a function named <tt>key_up_event()</tt> in
|
|
a loaded Lua script will automatically be registered to receive
|
|
<tt>key_up</tt> event notifications.
|
|
</p>
|
|
|
|
<p>
|
|
The prototypes for the Lua event handler callback functions follow.
|
|
</p>
|
|
|
|
<a name="handler_update" />
|
|
<h3>update</h3>
|
|
<p><tt>function update_event()</tt></p>
|
|
<p>
|
|
This function is called for every frame that is drawn on the screen.
|
|
It could be called up to a few dozen times per second.
|
|
</p>
|
|
|
|
<a name="handler_update_overlay" />
|
|
<h3>update_overlay</h3>
|
|
<p><tt>function update_overlay_event(width, height)</tt></p>
|
|
<p>
|
|
This function is called immediately after the <tt>update</tt>
|
|
function.
|
|
During this event, the coordinate system is reset from the normal
|
|
3D system to a 2D system.
|
|
The coordinates range from (0, 0) in the lower-left corner of the
|
|
screen to (width, height) in the upper-right corner of the screen.
|
|
In this mode, depth testing is disabled, so any graphics drawn will
|
|
"overlay" whatever is currently on the screen.
|
|
<tt>width</tt> and <tt>height</tt> contain the size of the
|
|
Anaglym engine window, in pixels.
|
|
</p>
|
|
|
|
<a name="handler_key_down" />
|
|
<h3>key_down</h3>
|
|
<p><tt>function key_down_event(key_name)</tt></p>
|
|
<p>
|
|
This function is called when a key is initially pressed.
|
|
<tt>key_name</tt> is a string containing the name of the
|
|
key pressed.
|
|
See <a href="#key_names">Key Names</a> for a list of key names.
|
|
</p>
|
|
|
|
<a name="handler_key_up" />
|
|
<h3>key_up</h3>
|
|
<p><tt>function key_up_event(key_name)</tt></p>
|
|
<p>
|
|
This function is called when a key is released.
|
|
<tt>key_name</tt> is a string containing the name of the
|
|
key released.
|
|
See <a href="#key_names">Key Names</a> for a list of key names.
|
|
</p>
|
|
|
|
<a name="handler_mousebutton_down" />
|
|
<h3>mousebutton_down</h3>
|
|
<p><tt>function mousebutton_down_event(button, x, y)</tt></p>
|
|
<p>
|
|
This function is called when a mouse button is pressed.
|
|
<tt>button</tt> contains the number of the button pressed
|
|
(1: left, 2: middle, 3: right, 4: scroll wheel up, 5: scroll wheel down).
|
|
The position of the cursor when the mouse button was pressed is at
|
|
(x, y).
|
|
This position is only meaningful when the cursor is shown.
|
|
By default, it is hidden.
|
|
Cursor visibility can be toggled with the F2 key.
|
|
</p>
|
|
|
|
<a name="handler_mousebutton_up" />
|
|
<h3>mousebutton_up</h3>
|
|
<p><tt>function mousebutton_up_event(button, x, y)</tt></p>
|
|
<p>
|
|
This function is called when a mouse button is released.
|
|
<tt>button</tt> contains the number of the button released
|
|
(1: left, 2: middle, 3: right, 4: scroll wheel up, 5: scroll wheel down).
|
|
The position of the cursor when the mouse button was released is at
|
|
(x, y).
|
|
This position is only meaningful when the cursor is shown.
|
|
By default, it is hidden.
|
|
Cursor visibility can be toggled with the F2 key.
|
|
</p>
|
|
|
|
<a name="handler_mouse_motion" />
|
|
<h3>mouse_motion</h3>
|
|
<p><tt>function mouse_motion_event(x, y, xrel, yrel)</tt></p>
|
|
<p>
|
|
This function is called when the mouse moves.
|
|
(x, y) specifies the position that the cursor was moved to.
|
|
This position is only meaningful when the cursor is shown.
|
|
<tt>xrel</tt> and <tt>yrel</tt> contain the relative
|
|
movement distance.
|
|
These values are meaningful regardless of the cursor visibility state.
|
|
</p>
|
|
|
|
|
|
<hr />
|
|
|
|
<a name="key_names" />
|
|
<h2>Key Names</h2>
|
|
|
|
<ul>
|
|
<li><tt>backspace</tt></li>
|
|
<li><tt>tab</tt></li>
|
|
<li><tt>clear</tt></li>
|
|
<li><tt>return</tt></li>
|
|
<li><tt>pause</tt></li>
|
|
<li><tt>escape</tt></li>
|
|
<li><tt>space</tt></li>
|
|
<li><tt>exclaim</tt></li>
|
|
<li><tt>quotedbl</tt></li>
|
|
<li><tt>hash</tt></li>
|
|
<li><tt>dollar</tt></li>
|
|
<li><tt>ampersand</tt></li>
|
|
<li><tt>quote</tt></li>
|
|
<li><tt>leftparen</tt></li>
|
|
<li><tt>rightparen</tt></li>
|
|
<li><tt>asterisk</tt></li>
|
|
<li><tt>plus</tt></li>
|
|
<li><tt>comma</tt></li>
|
|
<li><tt>minus</tt></li>
|
|
<li><tt>period</tt></li>
|
|
<li><tt>slash</tt></li>
|
|
<li><tt>0</tt></li>
|
|
<li><tt>1</tt></li>
|
|
<li><tt>2</tt></li>
|
|
<li><tt>3</tt></li>
|
|
<li><tt>4</tt></li>
|
|
<li><tt>5</tt></li>
|
|
<li><tt>6</tt></li>
|
|
<li><tt>7</tt></li>
|
|
<li><tt>8</tt></li>
|
|
<li><tt>9</tt></li>
|
|
<li><tt>colon</tt></li>
|
|
<li><tt>semicolon</tt></li>
|
|
<li><tt>less</tt></li>
|
|
<li><tt>equals</tt></li>
|
|
<li><tt>greater</tt></li>
|
|
<li><tt>question</tt></li>
|
|
<li><tt>at</tt></li>
|
|
<li><tt>leftbracket</tt></li>
|
|
<li><tt>backslash</tt></li>
|
|
<li><tt>rightbracket</tt></li>
|
|
<li><tt>caret</tt></li>
|
|
<li><tt>underscore</tt></li>
|
|
<li><tt>backquote</tt></li>
|
|
<li><tt>a</tt></li>
|
|
<li><tt>b</tt></li>
|
|
<li><tt>c</tt></li>
|
|
<li><tt>d</tt></li>
|
|
<li><tt>e</tt></li>
|
|
<li><tt>f</tt></li>
|
|
<li><tt>g</tt></li>
|
|
<li><tt>h</tt></li>
|
|
<li><tt>i</tt></li>
|
|
<li><tt>j</tt></li>
|
|
<li><tt>k</tt></li>
|
|
<li><tt>l</tt></li>
|
|
<li><tt>m</tt></li>
|
|
<li><tt>n</tt></li>
|
|
<li><tt>o</tt></li>
|
|
<li><tt>p</tt></li>
|
|
<li><tt>q</tt></li>
|
|
<li><tt>r</tt></li>
|
|
<li><tt>s</tt></li>
|
|
<li><tt>t</tt></li>
|
|
<li><tt>u</tt></li>
|
|
<li><tt>v</tt></li>
|
|
<li><tt>w</tt></li>
|
|
<li><tt>x</tt></li>
|
|
<li><tt>y</tt></li>
|
|
<li><tt>z</tt></li>
|
|
<li><tt>delete</tt></li>
|
|
<li><tt>kp0</tt></li>
|
|
<li><tt>kp1</tt></li>
|
|
<li><tt>kp2</tt></li>
|
|
<li><tt>kp3</tt></li>
|
|
<li><tt>kp4</tt></li>
|
|
<li><tt>kp5</tt></li>
|
|
<li><tt>kp6</tt></li>
|
|
<li><tt>kp7</tt></li>
|
|
<li><tt>kp8</tt></li>
|
|
<li><tt>kp9</tt></li>
|
|
<li><tt>kp_period</tt></li>
|
|
<li><tt>kp_divide</tt></li>
|
|
<li><tt>kp_multiply</tt></li>
|
|
<li><tt>kp_minus</tt></li>
|
|
<li><tt>kp_plus</tt></li>
|
|
<li><tt>kp_enter</tt></li>
|
|
<li><tt>kp_equals</tt></li>
|
|
<li><tt>up</tt></li>
|
|
<li><tt>down</tt></li>
|
|
<li><tt>right</tt></li>
|
|
<li><tt>left</tt></li>
|
|
<li><tt>insert</tt></li>
|
|
<li><tt>home</tt></li>
|
|
<li><tt>end</tt></li>
|
|
<li><tt>pageup</tt></li>
|
|
<li><tt>pagedown</tt></li>
|
|
<li><tt>f1</tt></li>
|
|
<li><tt>f2</tt></li>
|
|
<li><tt>f3</tt></li>
|
|
<li><tt>f4</tt></li>
|
|
<li><tt>f5</tt></li>
|
|
<li><tt>f6</tt></li>
|
|
<li><tt>f7</tt></li>
|
|
<li><tt>f8</tt></li>
|
|
<li><tt>f9</tt></li>
|
|
<li><tt>f10</tt></li>
|
|
<li><tt>f11</tt></li>
|
|
<li><tt>f12</tt></li>
|
|
<li><tt>f13</tt></li>
|
|
<li><tt>f14</tt></li>
|
|
<li><tt>f15</tt></li>
|
|
<li><tt>numlock</tt></li>
|
|
<li><tt>capslock</tt></li>
|
|
<li><tt>scrollock</tt></li>
|
|
<li><tt>rshift</tt></li>
|
|
<li><tt>lshift</tt></li>
|
|
<li><tt>rctrl</tt></li>
|
|
<li><tt>lctrl</tt></li>
|
|
<li><tt>ralt</tt></li>
|
|
<li><tt>lalt</tt></li>
|
|
<li><tt>rmeta</tt></li>
|
|
<li><tt>lmeta</tt></li>
|
|
<li><tt>lsuper</tt></li>
|
|
<li><tt>rsuper</tt></li>
|
|
<li><tt>mode</tt></li>
|
|
<li><tt>compose</tt></li>
|
|
<li><tt>help</tt></li>
|
|
<li><tt>print</tt></li>
|
|
<li><tt>sysreq</tt></li>
|
|
<li><tt>break</tt></li>
|
|
<li><tt>menu</tt></li>
|
|
<li><tt>power</tt></li>
|
|
<li><tt>euro</tt></li>
|
|
<li><tt>undo</tt></li>
|
|
<li><tt>last</tt></li>
|
|
</ul>
|
|
|
|
</body>
|
|
</html>
|