HWR Map Functions Reference

Created by Michael Horvath.

Note that this reference may be out-of-date. If you are having problems, check the descriptions of the functions inside "data\scripts\MapFunctions.lua" as these are probably the most current.

"DetermChunk" functions (these go in the "DetermChunk" portion of your level file):

"NonDetermChunk" functions (these go in the "NonDetermChunk" portion of your level file):

Other functions:

Table manipulation functions:

Random number functions:

Vector functions (modeled after functions found in the POV-Ray raytracer):

Miscellaneaous mathematical functions:

Trigonometric functions:

Curve and surface functions (these are used by the "shapeAdd" function):

Debug functions:



Top

Name: easyPatch
Description: Creates a resource patch with minimal effort.
Syntax: easyPatch([tPos], [fRUs], [tSeed])
Arguments: [tPos]: the shape's center coordinates.
[fRUs]: (optional) the percent of the default RU to retain.
[tSeed]: (optional) the seed for the random number functions.


Top

Name: shapeAdd
Description: Creates one of several available shapes.
Syntax: shapeAdd([tPos], [tDst], {[sLay], [fA], [fB], ...}, [tRot], [tSeed])
Arguments: [tPos]: a table containing the shape's center coordinates.
[tDst]: the distribution table used to populate the shape.
[tPar]: a table containing the following six parameters: [sLay], [fA], [fB], [fC], [fD] and [fE]. The last five vary depending on [sLay].
[sLay]: the type of shape to generate. (string)
If [sLay] is "Cylinder":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals the length of axis 3.
[fD]: equals the thickness.
[fE]: is always zero.
If [sLay] is "Cone":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals the length of axis 3.
[fD]: equals the thickness.
[fE]: is always zero.
If [sLay] is "Ellipsoid":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals the length of axis 3.
[fD]: equals the thickness.
[fE]: is always zero.
If [sLay] is "Cuboid":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals the length of axis 3.
[fD]: equals the thickness.
[fE]: is always zero.
If [sLay] is "Toroid":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals the width of the tube.
[fD]: equals the thickness.
[fE]: equals the height of the tube.
If [sLay] is "Helicoid":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals the length of axis 3.
[fD]: equals the width. (Thickness is not supported in this case.)
[fE]: is the number of revolutions.
If [sLay] is "Paraboloid":
[fA]: equals the length of axis 1 at a height of 1000 units.
[fB]: equals the length of axis 2 at a height of 1000 units.
[fC]: equals the length of axis 3.
[fD]: equals the thickness.
[fE]: is always zero.
If [sLay] is "Hyperboloid":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals the length of axis 3.
[fD]: equals the thickness.
[fE]: is always zero.
If [sLay] is "Astroid":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals the length of axis 3.
[fD]: equals the thickness.
[fE]: is always zero.
If [sLay] is "Funnel":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals roughly the inverse of the length of axis 3 for large numbers of objects.
[fD]: equals the thickness.
[fE]: is always zero.
If [sLay] is "Dini":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals the distance between each twist.
[fD]: is always zero.
[fE]: is the number of twists.
If [sLay] is "Corkscrew":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals the height of the screw.
[fD]: is always zero.
[fE]: is always zero.
If [sLay] is "Seashell":
[fA]: equals the length of axis 1 of the tube.
[fB]: equals the length of axis 2 of the tube.
[fC]: equals the vertical separation between revolutions.
[fD]: equals the radius of the center gap.
[fE]: equals the number of revolutions.
If [sLay] is "SineDisc":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals the maximum height of the wave.
[fD]: is always zero.
[fE]: equals the frequency of the wave pattern.
If [sLay] is "SinePlane":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals the maximum height of the wave.
[fD]: is always zero.
[fE]: equals the frequency of the wave pattern.
If [sLay] is "Moebius":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals half the width of the strip.
[fD]: is always zero.
[fE]: is always zero.
If [sLay] is "Klein":
[fA]: equals the scaling along the x-axis.
[fB]: equals the scaling along the z-axis.
[fC]: equals the scaling along the y-axis.
[fD]: is always zero.
[fE]: is always zero.
If [sLay] is "Klein8":
[fA]: equals the scaling along the x-axis.
[fB]: equals the scaling along the z-axis.
[fC]: equals the scaling along the y-axis.
[fD]: is always zero.
[fE]: is always zero.
If [sLay] is "Boy":
[fA]: equals the scaling along the x-axis.
[fB]: equals the scaling along the z-axis.
[fC]: equals the scaling along the y-axis.
[fD]: is always zero.
[fE]: is an integer greater than 2.
If [sLay] is "Rectangle":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals the length of axis 3.
[fD]: equals the thickness.
[fE]: is always zero.
If [sLay] is "Ellipse":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals the length of axis 3.
[fD]: equals the thickness.
[fE]: is always zero.
If [sLay] is "Parabola":
[fA]: equals the distance between the vertex and the focus.
[fB]: equals the length.
[fC]: equals the height.
[fD]: equals the thickness.
[fE]: is always zero.
If [sLay] is "Hyperbola":
[fA]: equals the length of axis 1.
[fB]: equals the length of axis 2.
[fC]: equals the distance from the origin to one of the foci.
[fD]: equals the thickness.
[fE]: is always zero.
If [sLay] is "Hypotrochoid":
[fA]: equals the radius of the greater circle.
[fB]: equals the radius of the lesser circle.
[fC]: equals the radius of the sphere sweep.
[fD]: equals the distance from the center of the lesser circle.
[fE]: equals the number of revolutions.
If [sLay] is "Epitrochoid":
[fA]: equals the radius of the greater circle.
[fB]: equals the radius of the lesser circle.
[fC]: equals the radius of the sphere sweep.
[fD]: equals the distance from the center of the lesser circle.
[fE]: equals the number of revolutions.
[tRot]: a table containing the X, Y and Z Euler rotation angles, in degrees, for the entire object.
[tSeed]: the seed for the random number functions.


Top

Name: harmonographAdd
Description: Creates a squiggly curving tube. The shape is similar to that produced by a harmonograph, except in three dimensions. See for more info: http://en.wikipedia.org/wiki/Harmonograph
Syntax: harmonographAdd([tPos], [tDst], {{[fA], [fF], [fP], [fD]}, [tGrp2], [tGrp3], [tGrp4], [tGrp5], [tGrp6], [fTim], [fRad], [fThk], [tScale], [iMod]}, [tRot], [tSeed])
Arguments: [tPos]: a table containing the shape's center coordinates.
[tDst]: the distribution table used to populate the shape.
[tPar]: a table containing the following six parameters:
[tGrp1]: a table containing the following four parameters:
[fA]: amplitude.
[fF]: frequency.
[fP]: phase (degrees).
[fD]: damping.
[tGrp2]: ditto.
[tGrp3]: ditto.
[tGrp4]: ditto.
[tGrp5]: ditto.
[fTim]: the time parameter.
[fRad]: the radius of the curving tube.
[fThk]: the thickness of the tube as a percentage of the radius.
[tScale]: scale the entire shape by this much.
[iMod]: 0 = non-random, 1 = random.
[tRot]: a table containing the X, Y and Z rotation angles (degrees) for the entire object.
[tSeed]: the seed for the random number functions.


Top

Name: branchAdd
Description: Creates a branching tree using either straight sections or smooth splines.
Syntax: branchAdd([tPos], [tDst], {[tDiv], [tInt], [tFrq], [tBeg], [tEnd], [tRad], [tLen], [tThk], [tAng], [iMod],}, [tRot], [tSeed], ...)
Arguments: [tPos]: a table containing the shape's center coordinates.
[tDst]: the distribution table used to populate the shape.
[tPar]: a table containing the following ten parameters:
[tDiv]: a table containing the minimum and maximum number of new shoots that are generated each time the tree divides.
[tInt]: a table containing the minimum and maximum number of segments between instances of division.
[tFrq]: a table containing the minimum and maximum number of times the tree divides.
[tBeg]: a table containing the minimum and maximum number of segments added to the beginning of the tree.
[tEnd]: a table containing the minimum and maximum number of segments added to the end of the tree (at the end of each branch). (Note: this value needs to be greater than zero in order for the last division to be noticable.)
[tRad]: a table containing the the minimum and maximum radius of a segment.
[tLen]: a table containing the minimum and maximum length of a segment.
[tThk]: a table containing the minimum and maximum thickness, as percentages of the radius, of a segment.
[tAng]: a table containing the minimum and maximum angle of deviation between segments.
[iMod]: 0 is non-random mode, 1 is random placement with steadily decreasing length and radius, 2 is random placement with random length and radius, 3 is a method using splines similar to method 1.
[tRot]: a table containing the X, Y and Z rotation angles (degrees) for the entire object.
[tSeed]: the seed for the random number functions.
The remaining arguments are used internally by the function and should not be modified.


Top

Name: blobAdd1
Description: Creates a network of metaballs, or blobs, based on the formula for electromagnetic fields. Uses distributions.
Syntax: blobAdd1([tPos], [tDst], {[tBlobs], [fThrsh1], [fThrsh2], [tScale],}, [tRot], [tSeed])
Arguments: [tPos]: a table containing the shape's center coordinates.
[tDst]: the distribution table used to populate the shape.
[tPar]: a table containing the following four parameters:
[tBlobs]: a table containing the location coordinates and strength of each blob.
[fThrsh1]: threshold 1 of the blob formula (see below).
[fThrsh2]: threshold 2 of the blob formula (see below).
[tScale]: scale the entire shape by these amounts in the {x,y,z} directions. Scaling occurs before translation and rotation.
[tRot]: a table containing the X, Y and Z rotation angles (degrees) for the entire object.
[tSeed]: the seed for the random number functions.
See "Method 1" at http://www.geogebra.org/en/upload/files/english/Michael_Horvath/Metaballs/geogebra_metaballs.htm for math formula info.


Top

Name: blobAdd2
Description: Creates a network of metaballs, or blobs, based on the formula for electromagnetic fields. Does not use distributions.


Top

Name: blobAdd3
Description: Creates a network of metaballs, or blobs, based on the formula for electromagnetic fields. Creates a regular three-dimensional grid.


Top

Name: fieldAdd
Description: Similar to blobAdd, except it produces a heightmap based on the field strength instead of 3D blobs.
Syntax: fieldAdd([tPos], [tRes], {[tBlobs], [fThrshMin], [fThrshMax], [tScale],}, [tRot], [tSeed])
Arguments: [tPos]: a table containing the shape's center coordinates.
[tRes]: a table containing the parameters of the outputted pebble or asteroid.
[tPar]: a table containing the following five parameters:
[tBlobs]: a table containing the location coordinates and strength of each blob.
[fThrshMin]: minimum threshold in units of field strength.
[fThrshMax]: maximum threshold in units of field strength.
[fFieldSize]: the size of the entire field in X, Y, Z dimensions.
[fStepHeight]: the height of one unit of field strength.
[tRot]: a table containing the X, Y and Z rotation angles (degrees) for the entire object.
[tSeed]: the seed for the random number functions.
See "Method 1" at http://www.geogebra.org/en/upload/files/english/Michael_Horvath/Metaballs/geogebra_metaballs.htm for math formula info.


Top

Name: heightmapAdd
Description: Creates a matrix of dots based on heightmap data.
Syntax: heightmapAdd([tPos], [tRes], {[tData], [tScale]}, [tRot], [tSeed])
Arguments: [tPos]: a table containing the shape's center coordinates.
[tRes]: a table containing the parameters of the outputted pebble or asteroid.
[tPar]: a table containing the following five parameters:
[tData]: the heightmap data in the form of a two-dimensional array.
[tScale]: the amount to scale the heightmap in the X, Y and Z directions.
[tRot]: a table containing the X, Y and Z rotation angles (degrees) for the entire object.
[xNil]: this should always remain "nil". It is ignored and used only to adhere to the API.


Top

Name: flokalAdd
Description: Creates a kaleidoscopic bubble and swirl pattern kind of like a doily. Based on "doodle 4" by bitcraft, http://www.openprocessing.org/sketch/17344
Syntax: flokalAdd([tPos], [tRes], {[iNx], [iNy], [iXmin], [iSx], [iSy], [iSym], [fEcc], [bInside], [fScale],}, [tRot], [xNil])
Arguments: [tPos]: a table containing the shape's center coordinates.
[tRes]: a table containing the parameters of the outputted pebble or asteroid.
[tPar]: a table containing the following nine parameters:
[iNx]: the number of "horizontal" equipotential lines per charge, not taking into account iXmin.
[iNy]: the number of "vertical" flow lines per charge.
[iXmin]: size of the empty hole for each charge, measured in "horizontal" lines.
[iSx]: the number of extra items spaced between "horizontal" lines.
[iSy]: the number of extra items spaced between "vertical" lines.
[iSym]: number of charges arranged around the origin.
[fEcc]: the eccentricity of the shape, i.e. the amount the shape diverges from a circle.
[bInside]: are the curved lines inside or outside of the reference circle?
[fScale]: scale the whole shape by this amount in all directions.
[tRot]: a table containing the X, Y and Z rotation angles (degrees) for the entire object.
[xNil]: this should always remain "nil". It is ignored and used only to adhere to the API.


Top

Name: stitchAdd
Description: Generates a triangle made of crosshatched line segments, like in the art of curvestitching.
Syntax: stitchAdd([tPos], [tRes], {[tPtA], [tPtB], [tPtC], [iNum], [bAll], [bCorners],}, [tRot], [xNil])
Arguments: [tPos]: a table containing the shape's center coordinates.
[tRes]: a table containing the parameters of the outputted pebble or asteroid.
[tPar]: a table containing the following six parameters:
[tPtA]: a table containing the X, Y and Z coordinates of a point on the triangle.
[tPtB]: a table containing the X, Y and Z coordinates of a point on the triangle.
[tPtC]: a table containing the X, Y and Z coordinates of the center point on the triangle.
[iNum]: the number of line segments to generate.
[bAll]: turn this off to generate only the points on the spline defined by the line segments.
[bCorners]: enables/disables generation of points at the corners of the triangle to prevent duplicate overlapping asteroids.
[tRot]: a table containing the X, Y and Z rotation angles (degrees) for the entire object.
[xNil]: this should always remain "nil". It is ignored and used only to adhere to the API.


Top

Name: spline2Add
Description: Creates a quadratic spline-shaped tube connecting any two points using a control point.
Syntax: spline2Add([tPos], [tDst], {[tP1], [tP2], [tP3], [tRad], [tThk]}, [tRot], [tSeed])
Arguments: [tPos]: a table containing the shape's center coordinates.
[tDst]: the distribution table used to populate the shape.
[tPar]: a table containing the following six parameters:
[tP1]: a table containing the coordinates of the starting point.
[tP2]: a table containing the coordinates of the control point.
[tP3]: a table containing the coordinates of the ending point.
[tRad]: a table containing the initial and final radii of the tube.
[tThk]: a table containing the minimum and maximum thickness, as percentages of the radius, of the tube.
[tRot]: a table containing the X, Y and Z rotation angles (degrees) for the entire object.
[tSeed]: the seed for the random number functions.


Top

Name: spline3Add
Description: Creates a Hermite cubic spline-shaped tube connecting any two points using two control points.
Syntax: spline3Add([tPos], [tDst], {[tP1A], [tP1B], [tP2A], [tP2B], [tRad], [tThk]}, [tRot], [tSeed])
Arguments: [tPos]: a table containing the shape's center coordinates.
[tDst]: the distribution table used to populate the shape.
[tPar]: a table containing the following six parameters:
[tP1A]: a table containing the coordinates of the starting point.
[tP1B]: a table containing the coordinates of the first control point.
[tP2A]: a table containing the coordinates of the ending point.
[tP2B]: a table containing the coordinates of the second control point.
[tRad]: a table containing the initial and final radii of the tube.
[tThk]: a table containing the minimum and maximum thickness, as percentages of the radius, of the tube.
[tRot]: a table containing the X, Y and Z rotation angles (degrees) for the entire object.
[tSeed]: the seed for the random number functions.


Top

Name: ringAdd
Description: Creates an elliptical ring centered around one of its foci.
Syntax: ringAdd([tPos], [tDst], {[fAx1], [fAx2], [fThk], [fHgh], [tArc], [iMod],}, [tRot], [tSeed])
Arguments: [tPos]: a table containing the shape's center coordinates.
[tDst]: the distribution table used to populate the shape.
[tPar]: a table containing the following six parameters:
[fAx1]: the length of axis 1.
[fAx2]: the length of axis 2.
[fThk]: the distance from the outer radius to the inner radius (varies according to [iMod]).
[fHgh]: the height of the ring, relative to the plane.
[tArc]: a table containing the beginning and ending degrees of the arc.
[iMod]: if 0, then non-random mode. If 1, then random mode w/ gradual width. If 2, then random mode w/ even width.
[tRot]: a table containing the X, Y and Z rotation angles (degrees) for the entire object.
[tSeed]: the seed for the random number functions.


Top

Name: globeAdd
Description: Creates a series of rings in the shape of a sphere, like the latitudinal and longitudinal lines of a globe.
Syntax: globeAdd([tPos], [tDst], {[fRad], [fLat], [fLon], [fThk], [fHgh], [tArc], [iMod],}, [xNil], [tSeed])
Arguments: [tPos]: a table containing the shape's center coordinates.
[tPar]: a table containing the following seven parameters:
[fRad]: the radius of the sphere.
[fLat]: the number of latitudinal rings.
[fLon]: the number of longitudinal rings.
[fThk]: see the description for the "ringAdd" function.
[fHgh]: see the description for the "ringAdd" function.
[tArc]: see the description for the "ringAdd" function.
[iMod]: see the description for the "ringAdd" function.
[xNil]: this argument should always remain "nil". It is ignored and used only to adhere to the API.
[tSeed]: the seed for the random number functions.
Note: Beware that objects may overlap where the longitudinal rings intersect at the poles.


Top

Name: spiralAdd
Description: Creates a spiral.
Suntax: spiralAdd([tPos], [tDst], {[sLay], [nRad], [nArm], [nRot], [nAng], [nHgh], [nWid], [nThk], [tTim], [iMod],}, [tRot], [tSeed])
Arguments: [tPos]: a table containing the shape's center coordinates.
[tDst]: the distribution table used to populate the shape.
[tPar]: a table containing the following ten parameters:
[sLay]: may be either "Nautilus" or "Archimedes".
[fRad]: depending on [fAng], this is either the minimum or maximum radius of the spiral.
[iArm]: the number of arms the spiral will have.
[fRot]: the number of times the spiral will rotate around the origin.
[fAng]: the angle (degrees) of deviation (90' and 270' makes a circle).
[fHgh]: the height of the spiral above the plane.
[fWid]: the width of the spiral arms.
[fThk]: the thickness of the spiral arms.
[tTim]: a table containing the minimum and maximum values for "t" (time, percent) at which the curve is sampled. (must be a float between 0 and 1)
[iMod]: 0 is non-random, 1 is random, 2 is random-mode with tapering width.
[tRot]: a table containing the X, Y and Z rotation angles (degrees) for the entire object.
[tSeed]: the seed for the random number functions.


Top

Name: literalAdd
Description: Adds the contents of a distribution table to the map without changing any values.
Syntax: literalAdd([tDst])
Arguments: [tDst]: the distribution table used to populate the shape.
Note: This function is the one used to process the "Main" distribution.


Top

Name: randomBackground
Description: Randomly selects the level background.
Syntax: randomBackground([iMod], [tTab], [iLen])
Arguments: [iMod]: may be 0, 1, 2, 3, 4 or 5.
If [iMod] is 0, then this function has been disabled.
If [iMod] is 1, then the level background is selected from only the mission backgrounds.
If [iMod] is 2, then the level background is selected from only the other backgrounds.
If [iMod] is 3, then the level background is selected from both the mission and other backgrounds.
If [iMod] is 4, then the level background is selected from only [tTab].
If [iMod] is 5, then the level background is selected from all of the above.
[tTab]: (optional) a table containing the names of the custom backgrounds.
[iLen]: (optional) the length of [tTab].
Note: This function must be called from within the "NonDetermChunk" portion of a ".level" file.


Top

Name: randomBattleMusic
Description: Randomly selects the level battle music.


Top

Name: randomMusic
Description: Randomly selects the level music.
Syntax: randomMusic([iMod], [tTab], [iLen], [sDir])
Arguments: [iMod]: may be 0, 1, 2, 3, 4 or 5.
If [iMod] is 0, then this function is disabled.
If [iMod] is 1, then the level music is selected from only the ambient tracks.
If [iMod] is 2, then the level music is selected from only the battle tracks.
If [iMod] is 3, then the level music is selected from both the ambient and battle tracks.
If [iMod] is 4, then the level music is selected from only [tTab].
If [iMod] is 5, then the level music is selected from all of the above.
[tTab]: a table containing the names of the custom audio tracks. (table, optional)
[iLen]: the length of [tTab]. (number, optional)
[sDir]: the directory where the extra files can be found. Must have a trailing slash. (string, optional)
Note: This function must be called from within the "NonDetermChunk" portion of a ".level" file.


Top

Name: appendShape
Description: General shape-adding function utilized by the other functions.
Syntax: appendShape([tPos], [i], [tPar], [j], [tCoo], [tRot])
Arguments: [tPos]: a table containing the initial coordinates for the object.
[i]: the position number of the object within the distribution table.
[tPar]: a table containing the object-specific parameters.
[j]: the nth number of this object type spawned.
[tCoo]: a table containing the modified coordinates for the object.
[tRot]: a table containing the Euler rotation angles.