MissionDude Help

How the Maps Work

This editor uses a principle of populating a map with objects stored in containers—called "distributions"—that is carried over from the original Homeworld and Homeworld: Cataclysm. Distributions are an efficient means of storing data and making changes to large numbers of objects, simply and easily.

Distributions exist in the form of tables (or arrays) of information. All map objects are stored in such tables. The tables contain all the information (in the form of parameters) necessary to recreate the map objects. These tables can also contain objects that reference other tables, thereby making it possible to nest objects within each other. Distribution tables are declared at the head of the "DetermChunk" portion of a level file, and are referenced later by the map populating functions.

The map populating functions (such as the "shapeAdd" function) count the number and types of objects within a distribution and place the objects on the map according to an algorithm. Any coordinates specified in the objects' properties are calculated in addition to the results of the algorithm.

Prior Reading

If you've never created a map before, I recommend reading Malignus's mapping tutorial before proceeding any further. It provides a general overview of how to create a map, as well specific information regarding the relevant SCAR functions.

Quick Start

To just add objects without worrying about the other complicated features:

  1. Click the "Add" button below the objects list. This will add the most generic type of object: the Point.
  2. Change the type of object by clicking on the button next to the "Type" field.
  3. Drag the object around the map using the mouse.
  4. Click the "Capture" button below the map.
  5. Hold the SHIFT key and click a bunch of times in different places on the map.

To use the custom shape functions to place objects dynamically based on various mathematical functions:

  1. Create a new distribution in the "Containers" tab. (It's been abbreviated "Cont." in the recent versions.)
  2. Switch to the new distribution and add objects (asteroids, clouds, ships, etc.) to the center of the map.
  3. You can increase the number of each object to more than 1 in the "Amount" field. That way you don't have click until your fingers are sore.
  4. Switch back to the Main distribution.
  5. Add one of the custom objects ("Shape", "Spline", "Branch", etc.).
  6. Make sure the custom object references the distribution you created in Step 1. You do this on the "More..." tab of the object properties pane.

Adding New Objects

If you want to add new types of objects (in a mod for instance), and are willing to do some code diving, you can simply open "define.js" in a text editor and modify the "subtypetable" table. You can find the file in the "\source\jscript" subfolder. It shouldn't be too hard; just don't mess around with the other tables!

Important Things to Remember

  • If you have the Adobe SVG browser plugin installed, you can zoom in on the map by pressing the CTRL key and clicking on the map with the mouse. Use CTRL + SHIFT to zoom out. Holding the ALT key while dragging the mouse will move the map. Right-clicking on the map will bring up a list of additional options. Other browser plugins have not been tested and may work differently.
  • You can import any (uncompiled) HW2 level, but the application is optimized for importing levels generated using version 1.4 or later of MissionDude.
  • Each map MUST have one distribution named "Main". This is the top-level distribution. All objects stored in this distribution are added to the map as entered. Each distribution uses a local coordinate system, so if distributions are nested, then the coordinates from one distribution are added to the coordinates of the other distribution.
  • Object labels are followed by one or more numbers contained within square brackets. The first number always refers to the number of objects being added to the map. Squadrons have two additional numbers: the owner player index, and a boolean flag telling whether the squadron is a normal squadron or a "reactive" squadron (0 is normal, 1 is reactive).
  • Make sure to save all objects after editing their properties! (You will be warned if you don't do this.)
  • Use the "Capture" button to clone the selected object at the mouse's current coordinates.
  • Maps created using this editor probably won't work over multiplayer (from experience they usually cause de-syncs). The solution for this is to manually configure the starting points using a text editor.
  • Objects stored in distributions that later get referenced by the special shape functions should generally all be positioned at the origin of the distribution's local coordinate system. The special functions will later modify the objects' positions dynamically, so there's no need to adjust them. You can experiment by disregarding this tip, however.
  • You can compile an exported ".level" file so that it (in theory) takes less time to download and runs faster. Compiled levels by default are generated with the ".levelc" extension. You'll have to rename them back to ".level" in order for them to work in HW2. Note also that compiled levels cannot be later imported back into MissionDude.
  • Squadron and point names do not increment properly if the distributions they belong to are referenced more than once within the same map. Make sure to reference a distribution that contains any "named" objects (e.g., squadrons, points and spheres) only once if you intend to later add them to sobgroups or paths, or intend to check other objects' positions using volumes in a gamerule.
  • Players are indexed according to the order in which they appear in the "Players" dialog, beginning with zero at the top. Similarly, start points are indexed according to the order in which they get added to the map. For multiplayer maps, players should have matching start points sharing the same index. For singleplayer maps, this is typically not necessary, though a single point named "PlayerStartPoint" may be required for the first player.
    The label for each player (e.g., "Player #1", "Player #2", etc.) is an independant means of tracking the player, but is typically ignored by the game.
  • Objects in the "Main" distribution should generally not have an "Amount" value greater than one (unless you want the objects to overlap).
  • To decrease the size of exported level files, use Lua's "dofilepath" function to read in a single, external copy of "MapFunctions.lua", instead of storing separate copies within each level file.
  • All objects need to have unique labels. Be careful to check whether two objects use the same label. Object labels ending in an underscore and followed by some digits may be considered the same as labels without the underscore and digits. The program uses underscores and digits internally to track objects and values, so take special care not to interfere with this.
  • You can change the visual style of the application from its default state to "blue" in the "Options" dialog.
  • Reactive Squadrons are used only for singleplayer campaigns. They require a "player<X>reinforce.lua" file associated with the mission scripts in order to work. Reactive Squadrons must always be added to a sobgroup, and may never be added to more than one sobgroup.
  • The window zoom feature (CTRL + = and CTRL + -) of Internet Explorer 7 is a bit buggy. It doesn't always fire the "window.onresize" event. As a result, you may witness odd results when using this feature. You can try pressing the F5 key to fix this. Remember to save your work first!
  • The "Scale on Zoom" option can be set to control whether map objects get scaled when the map is zoomed. Disabling this option speeds up the redraw speed when zooming, but slows it down when dragging.
  • You can place a background image over the map. Simply place three images, named "image1.png", "image2.png" and "image3.png", representing the three map views, in your "MissionDude\maps\" folder. You can change the position and dimensions of the images in the "Options" dialog.

Special Functions Reference

"DetermChunk" functions (these go in the "DetermChunk" portion of the level file):
  • easyPatch: Creates a resource patch with minimal effort.
  • shapeAdd: Creates one of several available mathematical shapes.
  • branchAdd: Creates a branching tree.
  • splineAdd: Creates a spline-shaped tube using two end points and two control points.
  • ringAdd: Creates an elliptical ring.
  • globeAdd: Creates a series of rings in the shape of a sphere, like the lattitudinal and longitudinal lines of a globe.
  • spiralAdd: Creates a Nautilus (equiangular) or Archimedes spiral.
  • literalAdd: Plots all objects' positions exactly as entered.
"NonDetermChunk" functions (these go in the "NonDetermChunk" portion of the level file):

Top

Name: easyPatch
Description: Creates a resource patch with minimal effort.
Syntax: easyPatch(<tPos>, <fRUs>)
Arguments: <tPos>: the shape's center coordinates.
<fRUs>: (optional) the percent of the default RU to retain.


Top

Name: shapeAdd
Description: Creates one of several available shapes.
Syntax: shapeAdd(<tPos>, <tDst>, {<sLay>, <fA>, <fB>, ...}, <tRot>)
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 "Lissajous3D":
<fA>: equals the length of the bounding cube.
<fB>: equals the radius of the sphere sweep.
<fD>: equals the speed of the second arc relative to the first.
<fD>: equals the speed of the third arc relative to the first.
<fE>: equals the number of revolutions.
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.
If <sLay> is "Lissajous2D":
<fA>: equals the length of the bounding square.
<fB>: equals the phase shift.
<fC>: equals the radius of the sphere sweep.
<fD>: equals the speed of the second arc relative to the first.
<fE>: equals the number of revolutions.
<tRot>: a table containing the X, Y and Z Euler rotation angles, in degrees, for the entire object.


Top

Name: branchAdd
Description: Creates a branching tree.
Syntax: branchAdd(<tPos>, <tDst>, {<tDiv>, <tInt>, <tFrq>, <tBeg>, <tEnd>, <tRad>, <tLen>, <tThk>, <tAng>, <iMod>,}, <tRot>, ...)
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 bug-ridden method using splines.
<tRot>: a table containing the X, Y and Z rotation angles (degrees) for the entire object.
The remaining arguments are used internally by the function and should not be modified.


Top

Name: splineAdd
Description: Creates a spline-shaped tube connecting any two points using two control points.
Syntax: splineAdd(<tPos>, <tDst>, {<tP1A>, <tP1B>, <tP2A>, <tP2B>, <tRad>,}, <tRot>)
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.


Top

Name: ringAdd
Description: Creates an elliptical ring.
Syntax: ringAdd(<tPos>, <tDst>, {<fAx1>, <fAx2>, <fThk>, <fHgh>, <tArc>, <iMod>,}, <tRot>)
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.


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>,}, <xNull>)
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.
<xNull>: this argument is ignored and is used only to adhere to function call standards.
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>)
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.


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: 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.

Program Hotkeys

Alt + TSwitch between objects, containers and level settings.
Alt + PSwitch between properties.
Alt + VSwitch between map views.
Alt + HView help.
Alt + NNew map.
Alt + LLoad map.
Alt + SSave map.
Alt + DDelete map.
Alt + EExport map.
Alt + IImport map.
Alt + FCompile map.
Alt + OView options.
Alt + GToggle map legend.
Alt + CToggle point-capturing.
Alt + -Move the selected object down in the list.
Alt + =Move the selected object up in the list.
TabSwitch to the next dialog.
Shift + Alt + KeyReverse direction of switching.
Ctrl + -Zoom the entire window out. (Sometimes buggy due to IE7 quirk.)
Ctrl + =Zoom the entire window in. (Sometimes buggy due to IE7 quirk.)
Ctrl + MousewheelZoom the entire window in or out. (Sometimes buggy due to IE7 quirk.)
Ctrl + 0Set the entire window to its default zoom state. (Sometimes buggy due to IE7 quirk.)
Ctrl + Left-clickZoom in on the map.
Ctrl + Left-click + DragZoom map in on a specific area of the map.
Shift + Ctrl + Left-clickZoom out of the map.
Alt + Left-click + DragPan map.
Alt + F4Exit the program without saving.

About this program

This program was written by me, Michael Horvath (Mikail on the RelicNews forums). Visit my homepage, here. You can reach me via email from this website. The discussion thread for this program can be found here.

Credits

  • The excellent SVG tutorials at carto:net and KevLinDev.
  • JScript performance tips by Peter Gurevich at IE Blog.
  • The JavaScript memory leak tutorial at JavaScript Kit.
  • Malignus, for getting me started with his mapping tutorial.
  • MathWorld and Wikipedia for many of the mathematical functions used in the scripts.
  • The sample chapter of Optimizing JavaScript for Execution Speed, by Andrew B. King.
  • Some of the SVG filters are modified versions of ones originally written by Adobe.
  • cj at the KiXtart forums for providing "cjDialogs.dll".
  • JMScomp and maxdamage for bug reports and feature suggestions.
  • cybersam for bug reports.

Software License

Copyright (C) 2009 Michael Horvath

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see .