1462 lines
46 KiB
HTML
1462 lines
46 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="#overview">Overview</a>
|
|
<ul>
|
|
<li><a href="#invocation">Invocation</a></li>
|
|
<li><a href="#colors">Colors</a></li>
|
|
<li><a href="#coordinates">Coordinate Systems</a></li>
|
|
</ul>
|
|
</li>
|
|
<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>
|
|
<li><a href="#joint">joint member methods</a></li>
|
|
<li><a href="#sound">sound 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="overview" />
|
|
<h2>Overview</h2>
|
|
|
|
<a name="invocation" />
|
|
<h3>Anaglym Invocation</h3>
|
|
|
|
<p><tt>anaglym</tt> usage:</p>
|
|
<pre> anaglym [options] script-file</pre>
|
|
<p>
|
|
<tt>anaglym</tt> command-line options:
|
|
<ul>
|
|
<li><tt>-w width</tt> - specify the width in pixels of the window</li>
|
|
<li><tt>-h height</tt> - specify the height in pixels of the window</li>
|
|
<li><tt>-f</tt> - do not fullscreen window</li>
|
|
<li><tt>-g</tt> - do not grab mouse input</li>
|
|
<li><tt>-s samples</tt> - set multisample level (default 4)</li>
|
|
</ul>
|
|
</p>
|
|
|
|
<a name="colors" />
|
|
<h3>Colors</h3>
|
|
|
|
<p>
|
|
Unless otherwise noted, color values described in this document
|
|
consist of red, green, and blue components.
|
|
Each component is a real number that can range from 0.0 to 1.0.
|
|
</p>
|
|
|
|
<a name="coordinates" />
|
|
<h3>Coordinate Systems</h3>
|
|
|
|
<p>
|
|
Anaglym uses the OpenGL right-handed coordinate system for its 3D coordinates.
|
|
The default orientation is such that the XY plane is horizontal (the
|
|
"ground" plane).
|
|
The Z axis extends positively into the "air" above the XY plane, and the
|
|
default gravity vector pulls along the negative Z axis.
|
|
</p>
|
|
<p>
|
|
When 2D coordinates are used (with mouse cursor positions and
|
|
overlay drawing routines), the origin is in the lower-left corner of
|
|
the screen.
|
|
The X axis increases positively toward the right edge of the screen.
|
|
The Y axis increases positively toward the top of the screen.
|
|
The upper-right pixel on the screen has coordinates (width-1, height-1).
|
|
</p>
|
|
|
|
|
|
<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_clearWorld" />
|
|
<h3>clearWorld</h3>
|
|
<p><tt>ag.clearWorld()</tt></p>
|
|
<p>
|
|
This function removes all objects from the world.
|
|
</p>
|
|
|
|
<a name="ag_createAMotor" />
|
|
<h3>createAMotor</h3>
|
|
<p><tt>motor = ag.createAMotor(obj1, obj2, axis0 [, axis1 [, axis2 ] ])</tt></p>
|
|
<p>
|
|
This function creates an angular motor in the simulation.
|
|
An angular motor supplies torque to the bodies it is connected to around the
|
|
axes specified in order to control the relative angular velocities of
|
|
the two objects around the axes.
|
|
Up to three axes can be specified, but only one is required.
|
|
<tt>obj1</tt> and <tt>obj2</tt> specify the two objects that are connected
|
|
with the motor.
|
|
One of <tt>obj1</tt> or <tt>obj2</tt> can be the number 0 to signify
|
|
that the other object should be connected to the static environment.
|
|
</p>
|
|
<p>
|
|
Connecting two objects with an angular motor does not restrict their
|
|
positions relative to one another.
|
|
See <a href="#ag_createHinge">createHinge()</a>.
|
|
</p>
|
|
<p>
|
|
Each axis<em>n</em> argument should be a table containing named parameters.
|
|
All parameters are optional.
|
|
Valid parameters:
|
|
<ul>
|
|
<li><tt>x</tt> - x coordinate of axis vector (default 1)</li>
|
|
<li><tt>y</tt> - y coordinate of axis vector (default 0)</li>
|
|
<li><tt>z</tt> - z coordinate of axis vector (default 0)</li>
|
|
<li><tt>rel</tt> - controls relative orientation of axis. Possible values:
|
|
<ul>
|
|
<li>0 - axis is anchored to the static environment (default)</li>
|
|
<li>1 - axis is anchored to the first body</li>
|
|
<li>2 - axis is anchored to the second body</li>
|
|
</ul>
|
|
</li>
|
|
<li><tt>angle</tt> - initial angle of the motor on this axis (default 0)</li>
|
|
<li><tt>lo_stop</tt> - minimum angle of the motor (default disabled)</li>
|
|
<li><tt>hi_stop</tt> - maximum angle of the motor (default disabled)</li>
|
|
<li><tt>vel</tt> - target angular velocity of the motor on this axis (default 0)</li>
|
|
<li><tt>fmax</tt> - maximum amount of force the motor will apply around this axis to try to reach a velocity of <tt>vel</tt> (default 0)</li>
|
|
<li><tt>bounce</tt> - bounciness of the motor stops (default 0)</li>
|
|
</ul>
|
|
The motor will only allow movement around each axis from the <tt>lo_stop</tt>
|
|
to <tt>hi_stop</tt> angles.
|
|
The motor will attempt to maintain relative angular velocities of <tt>vel</tt>
|
|
around each axis.
|
|
The maximum amount of force that the motor is allowed to apply in order to
|
|
maintain this velocity is specified by the <tt>fmax</tt> axis parameter.
|
|
Specifying a low <tt>fmax</tt> value will cause the motor to take a while
|
|
to reach its target velocity, and will mean that other objects can
|
|
slow down or stop the motor easily.
|
|
In contrast, a very high <tt>fmax</tt> value will allow the motor to reach
|
|
its target velocity more quickly and the motor will be harder to stop by
|
|
collisions with other objects.
|
|
The <tt>bounce</tt> parameter should range from 0 to 1, with 0 meaning a hard stop and 1 meaning full bounciness.
|
|
</p>
|
|
|
|
<a name="ag_createHinge" />
|
|
<h3>createHinge</h3>
|
|
<p><tt>hinge = ag.createHinge(obj1, obj2, anchor, axis)</tt></p>
|
|
<p>
|
|
This function creates a hinge joint between two objects,
|
|
keeping a single axis from each object aligned.
|
|
The two objects can rotate around this axis independently.
|
|
One of <tt>obj1</tt> or <tt>obj2</tt> can be the number 0 to signify
|
|
that the other object should be connected to the static environment.
|
|
<tt>anchor</tt> and <tt>axis</tt> should be Lua "arrays" (tables with
|
|
integer indices starting at 1), with three elements each.
|
|
<tt>anchor</tt> gives the coordinates of a point on the hinge.
|
|
<tt>axis</tt> gives the direction vector of the hinge.
|
|
</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_fillArc" />
|
|
<h3>fillArc</h3>
|
|
<p><tt>ag.fillArc(r, g, b, x, y, radius, a1, a2)</tt></p>
|
|
<p>
|
|
This function tells the engine to draw a filled-in 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>fillArc()</tt> should normally be called from the
|
|
<tt>update_overlay</tt> event handler.
|
|
</p>
|
|
|
|
<a name="ag_fillCircle" />
|
|
<h3>fillCircle</h3>
|
|
<p><tt>ag.fillCircle(r, g, b, x, y, radius)</tt></p>
|
|
<p>
|
|
This function tells the engine to draw a solid 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>fillCircle()</tt> should normally be called from the
|
|
<tt>update_overlay</tt> event handler.
|
|
</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 [, optargs])</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.
|
|
</p>
|
|
<p>
|
|
If specified, <tt>optargs</tt> should be a table of named parameters.
|
|
Possible parameters are:
|
|
<ul>
|
|
<li><tt>scale</tt> - specify the scale of the model (default 1.0)</li>
|
|
<li><tt>static</tt> - boolean to indicate if the object is static</li>
|
|
<li><tt>reference</tt> - boolean to indicate if the object is a reference object </li>
|
|
</ul>
|
|
</p>
|
|
<p>
|
|
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.
|
|
Static objects do not have a mass associated with them; they are considered
|
|
to be a part of the environment.
|
|
</p>
|
|
<p>
|
|
A reference object will not be drawn and cannot participate in physics.
|
|
A reference object is useful when one wishes to load a model some time
|
|
before actually using it.
|
|
You can instantiate a reference object into a normal object by calling
|
|
the <a href="#object_clone">clone()</a> method on the object.
|
|
</p>
|
|
|
|
<a name="ag_loadSound" />
|
|
<h3>loadSound</h3>
|
|
<p><tt>sound = ag.loadSound(sound_name)</tt></p>
|
|
<p>
|
|
This routine loads a <a href="#sound">sound</a> object from file
|
|
<tt>sound_name</tt> and returns a Lua reference to the loaded sound.
|
|
The <tt>sound_name</tt> should contain the file extension,
|
|
since multiple formats are supported (.wav, .mp3, etc...).
|
|
</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_pickObjects" />
|
|
<h3>pickObjects</h3>
|
|
<p><tt>objects = ag.pickObjects(x, y)</tt></p>
|
|
<p>
|
|
This function allows for 3D object "picking."
|
|
<tt>x</tt> and <tt>y</tt> should be the 2D screen coordinates of the
|
|
"pick point."
|
|
<tt>pickObjects</tt> returns a Lua array of the objects in the
|
|
"pick line" (the line from the camera through the "pick point" on the
|
|
screen.
|
|
Upon error, <tt>pickObjects</tt> returns <tt>nil</tt>.
|
|
For each object in the "pick line", the following properties are set:
|
|
<ul>
|
|
<li><tt>pick_dist</tt> - the distance to the object along the pick line</li>
|
|
<li><tt>pick_pos</tt> - the 3D coordinates of the pick point</li>
|
|
<li><tt>pick_normal</tt> - the normal of the object at the pick point</li>
|
|
</ul>
|
|
</p>
|
|
|
|
<a name="ag_pickOne" />
|
|
<h3>pickOne</h3>
|
|
<p><tt>obj_hit = ag.pickOne(x, y, obj)</tt></p>
|
|
<p>
|
|
This function allows for 3D object "picking," but only tests the given
|
|
object for intersection with the pick line and is thus much more efficient
|
|
than <a href="#ag_pickObjects">pickObjects()</a> if you only care about
|
|
selecting on a given object.
|
|
<tt>x</tt> and <tt>y</tt> should be the 2D screen coordinates of the
|
|
"pick point."
|
|
<tt>obj</tt> indicates which object to be tested.
|
|
<tt>pickOne</tt> returns a boolean for whether or not the given object
|
|
was hit by the "pick line."
|
|
If the return value is <tt>true</tt>, then the following properties are
|
|
set on <tt>obj</tt>:
|
|
<ul>
|
|
<li><tt>pick_dist</tt> - the distance to the object along the pick line</li>
|
|
<li><tt>pick_pos</tt> - the 3D coordinates of the pick point</li>
|
|
<li><tt>pick_normal</tt> - the normal of the object at the pick point</li>
|
|
</ul>
|
|
</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_setCursorVisible" />
|
|
<h3>setCursorVisible</h3>
|
|
<p><tt>ag.setCursorVisible(visible)</tt></p>
|
|
<p>
|
|
This function sets whether the mouse cursor is visible or not.
|
|
<tt>visible</tt> should be a boolean value.
|
|
When the cursor is visible, the absolute x and y coordinates passed
|
|
to mouse event handlers are meaningful.
|
|
</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 [, optargs])</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>
|
|
<p>
|
|
If specified, <tt>optargs</tt> should be a table containing
|
|
named parameters.
|
|
Valid parameters:
|
|
<ul>
|
|
<li><tt>static</tt> - boolean to indicate if the object is static</li>
|
|
<li><tt>reference</tt> - boolean to indicate if the object is a reference object </li>
|
|
</ul>
|
|
</p>
|
|
|
|
<a name="ag_createCapsule" />
|
|
<h3><tt>createCapsule</tt></h3>
|
|
<p><tt>obj = ag.createCapsule(radius, length [, optargs])</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>
|
|
<p>
|
|
If specified, <tt>optargs</tt> should be a table containing
|
|
named parameters.
|
|
Valid parameters:
|
|
<ul>
|
|
<li><tt>static</tt> - boolean to indicate if the object is static</li>
|
|
<li><tt>reference</tt> - boolean to indicate if the object is a reference object </li>
|
|
</ul>
|
|
</p>
|
|
|
|
<a name="ag_createPlane" />
|
|
<h3><tt>createPlane</tt></h3>
|
|
<p>1) <tt>obj = ag.createPlane(a, b, c, d [, optargs])</tt></p>
|
|
<p>2) <tt>obj = ag.createPlane(x, y, z, rot_x, rot_y, rot_z [, optargs])</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>
|
|
<p>
|
|
If specified, <tt>optargs</tt> should be a table containing
|
|
named parameters.
|
|
Valid parameters:
|
|
<ul>
|
|
<li><tt>reference</tt> - boolean to indicate if the object is a reference object </li>
|
|
</ul>
|
|
</p>
|
|
|
|
<a name="ag_createSphere" />
|
|
<h3><tt>createSphere</tt></h3>
|
|
<p><tt>obj = ag.createSphere(radius [, optargs])</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>
|
|
<p>
|
|
If specified, <tt>optargs</tt> should be a table containing
|
|
named parameters.
|
|
Valid parameters:
|
|
<ul>
|
|
<li><tt>static</tt> - boolean to indicate if the object is static</li>
|
|
<li><tt>reference</tt> - boolean to indicate if the object is a reference object </li>
|
|
</ul>
|
|
</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.
|
|
The new object created will be a regular (non-reference) object, regardless
|
|
of whether <tt>obj</tt> was a regular or reference object.
|
|
</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_setTransparency" />
|
|
<h3>setTransparency</h3>
|
|
<p><tt>obj:setTransparency(t)</tt></p>
|
|
<p>
|
|
This function sets the transparency of the object.
|
|
<tt>t</tt> should be between 0.0 and 1.0, with 1.0 being fully transparent.
|
|
Note that the object will only render transparent if it is created with
|
|
the optional ''enable_blending'' attribute set to ''true.''
|
|
This does incur a slight performance hit.
|
|
This call has no effect when the object has a texture specified, as the
|
|
transparency is taken from the texture in that case.
|
|
</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="joint" />
|
|
<h2>Joint member methods</h2>
|
|
|
|
<a name="joint_setAMotorAxis" />
|
|
<h3>setAMotorAxis</h3>
|
|
<p><tt>joint:setAMotorAxis(anum, rel, x, y, z)</tt></p>
|
|
<p>
|
|
Set axis parameters of the AMotor joint.
|
|
See <a href="#ag_createAMotor">ag.createAMotor()</a> for more information.
|
|
</p>
|
|
|
|
<a name="joint_setNumAxes" />
|
|
<h3>setAMotorNumAxes</h3>
|
|
<p><tt>joint:setAMotorNumAxes(num)</tt></p>
|
|
<p>
|
|
Set the number of axes of the AMotor joint.
|
|
See <a href="#ag_createAMotor">ag.createAMotor()</a> for more information.
|
|
</p>
|
|
|
|
<a name="joint_setAMotorAngle" />
|
|
<h3>setAMotorAngle</h3>
|
|
<p><tt>joint:setAMotorAngle(anum, angle)</tt></p>
|
|
<p>
|
|
Set the angle of the specified of axis of the AMotor joint.
|
|
See <a href="#ag_createAMotor">ag.createAMotor()</a> for more information.
|
|
</p>
|
|
|
|
<a name="joint_setAMotorLoStop" />
|
|
<h3>setAMotorLoStop</h3>
|
|
<p><tt>joint:setAMotorLoStop(anum, lostop)</tt></p>
|
|
<p>
|
|
Set the low stop angle of the specified axis of the AMotor joint.
|
|
See <a href="#ag_createAMotor">ag.createAMotor()</a> for more information.
|
|
</p>
|
|
|
|
<a name="joint_setAMotorHiStop" />
|
|
<h3>setAMotorHiStop</h3>
|
|
<p><tt>joint:setAMotorHiStop(anum, histop)</tt></p>
|
|
<p>
|
|
Set the high stop angle of the specified axis of the AMotor joint.
|
|
See <a href="#ag_createAMotor">ag.createAMotor()</a> for more information.
|
|
</p>
|
|
|
|
<a name="joint_setAMotorVel" />
|
|
<h3>setAMotorVel</h3>
|
|
<p><tt>joint:setAMotorVel(vel)</tt></p>
|
|
<p>
|
|
Set the velocity of the AMotor joint.
|
|
See <a href="#ag_createAMotor">ag.createAMotor()</a> for more information.
|
|
</p>
|
|
|
|
<a name="joint_setAMotorFMax" />
|
|
<h3>setAMotorFMax</h3>
|
|
<p><tt>joint:setAMotorFMax(vel)</tt></p>
|
|
<p>
|
|
Set the maximum force that the AMotor joint will apply to
|
|
maintain its constraints.
|
|
See <a href="#ag_createAMotor">ag.createAMotor()</a> for more information.
|
|
</p>
|
|
|
|
<a name="joint_setAMotorBounce" />
|
|
<h3>setAMotorBounce</h3>
|
|
<p><tt>joint:setAMotorBounce(bounce)</tt></p>
|
|
<p>
|
|
Set the bounciness of the AMotor joint.
|
|
See <a href="#ag_createAMotor">ag.createAMotor()</a> for more information.
|
|
</p>
|
|
|
|
<hr />
|
|
|
|
<a name="sound" />
|
|
<h2>Sound member methods</h2>
|
|
|
|
<a name="sound_play" />
|
|
<h3>play</h3>
|
|
<p><tt>snd:play()</tt></p>
|
|
<p>
|
|
Begins playing the <tt>snd</tt> sound at the beginning.
|
|
</p>
|
|
|
|
<a name="sound_resume" />
|
|
<h3>resume</h3>
|
|
<p><tt>snd:resume()</tt></p>
|
|
<p>
|
|
Begins playing the <tt>snd</tt> sound where it stopped after calling
|
|
<a href="#sound_stop">stop()</a>.
|
|
</p>
|
|
|
|
<a name="sound_stop" />
|
|
<h3>stop</h3>
|
|
<p><tt>snd:stop()</tt></p>
|
|
<p>
|
|
Stops playing the <tt>snd</tt> sound at its current position.
|
|
</p>
|
|
|
|
<a name="sound_loop" />
|
|
<h3>loop</h3>
|
|
<p><tt>snd:loop(count)</tt></p>
|
|
<p>
|
|
Begins playing the <tt>snd</tt> sound at the beginning and sets the loop
|
|
count to <tt>count</tt>. <tt>snd:loop(1)</tt> is equivalent to
|
|
<tt>snd:play()</tt>.
|
|
</p>
|
|
|
|
<a name="sound_loopForever" />
|
|
<h3>loopForever</h3>
|
|
<p><tt>snd:loopForever()</tt></p>
|
|
<p>
|
|
Begins playing the <tt>snd</tt> sound at the beginning and sets the loop
|
|
count to infinity. This routine is good for background music.
|
|
</p>
|
|
|
|
<a name="sound_getVolume" />
|
|
<h3>getVolume</h3>
|
|
<p><tt>snd:getVolume()</tt></p>
|
|
<p>
|
|
Get the volume for the <tt>snd</tt> sound.
|
|
</p>
|
|
|
|
<a name="sound_setVolume" />
|
|
<h3>setVolume</h3>
|
|
<p><tt>snd:setVolume(vol)</tt></p>
|
|
<p>
|
|
Set the volume for the <tt>snd</tt> sound to <tt>snd</tt>.
|
|
<tt>snd</tt> should be between <tt>0.0</tt> and <tt>1.0</tt>.
|
|
</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>
|