Particleman Introduction

ParticleMan was written for Anachronox by Super Warrior Brain Robot Joey Liaw.
Particleman allows you to create particle definitions, and view and edit models. There is about 1000 models and 1000 particle definitions in Anachronox. See the Appendix for a list of models and particle definitions.
There are really two different particle systems in Anachronox. The original particle system was hard to use and didn't give particles the flexibility that the 'N'ew 'P'article system Joey created did. See AnachroRadiant->Working With Entities for more information about the old particle system and how to use it with brushes.
Any help completing this documentation would be greatly appreciated.

Particleman Interface
This is the window of Doom, where you get to see the particle or model in action. You change the background color under the view menu, and you zoom in\out by RMB+drag. LMB+drag allows you to rotate the view, and MMB+drag centers the view. You can also simulate a low frame rate and high frame rate (slows th' thing down) and an option called "Motion Generator" which shows how the particle holds up while moving.

Useful Commands

Menu: File->import Spew
This allows you to type in an old particle system data string. Doesn't seem to work correctly with any 64bit spew string I type in....

Menu: File->Set Data Directory
This allows you to specify an anoxdata data directory to auto load files from. This is a nice setting if you have multiple Anachronox Projects.

Menu: Particle->Background Color
Selecting this opens a color selection box. Selecting a color will change the Particleman background color to the one selected.

Menu: Particle->Suppress Spawning
This will stop all generator particle spawning. This is useful if you are in model edit mode and do not want to see the particle definition to continue displaying.

Menu: Particle->Scale Reference
Allows you to define the min and max bounding box size for the Generator(See AnachroRadiant for more information).

Menu: Particle->Motion of Generator
Makes the Generator follow a specified motion pattern. This is good to visually see how particle creation holds up while moving in Anachronox.

Menu: View->Fustrum Properties
I have no idea what this does. Wish I did though.

Using Particleman to create particles
All particle definitions are created and modified within the Generator Properties window(Menu: Window->Generator Properties) (f3). This is the window of Destiny, where particle definition generators and it's particle are defined. It is broken into two windows: Particle Properties and Generator properties.
Generators are invisible objects that spew out particles based on the Generator's Properties. Particles are spots of light or bitmaps that a generator spews out, and have their own properties that define what the particle looks like throughout time.
A particle definition can contain one or more generators, each with their own properties and particle properties. The Select Generator drop down box allows you to select which generator you wish to modify. You can add generators to a particle definition by selecting the Insert New button, or you can delete the currently selected generator by selecting the delete button. The Insert Copy button at the bottom of the window allows you to add another generator to the particle definition with the exact same properties as the currently selected one. The Reorder button allows you to change the order in which generators are rendered.

Particle Properties
This is the life of Each particle spawned. The bottom of the Particle Properties shows the timeline in Milliseconds, and is the life of each particle through time.

LMB+click in a property window inserts a node. Inserting nodes allow you to change values for a property over time. LMB+drag up or down will change that nodes value, or RMB click on a node to open a modify property value dialog box, and get more info (color picker, numerical input, etc.). LMB+drag a node to the left or right will allow you to change the position of the node in time. You can delete a node by LMB+click to select it then pressing the delete key.

Alpha specifies the visibility of the particle. A value of 0 is complete transparency and 255 is complete opacity. There must be at least one Value(node) for alpha. You can add more nodes to change a particles Alpha through time.
RMB+click on a node will open the Modify Particle Alpha Data window. This window simply allows you to manually type in an alpha value for the selected node. You can also drag a node up or down to specify the alpha value.
The location of the node relative to the timeline specifies where in time the alpha value transition should take place.

This is the color of the generated particle, and must be at least one node(color). Inserting multiple nodes allow you to transition the color of a particle into different colors over time. RMB+click on a node to bring up the color picker and select the color desired for the node.
The location of the node relative to the timeline specifies where in time a color transition should take place.

Radius specifies the size of the particle to be generated and must contain one value(node). You can LMB+drag up or down to change the value of a node, or RMB+click on a node to open the Modify Particle Radius Data dialog box. Adding multiple nodes allow you to change the radius of the particle overtime.
The location of a node relative to the timeline specifies where in time the radius value transition initiates.

This property only effects a particle that uses a texture. This property allows you to modify the textures coordinates over time. More information about this property is explained in the Advanced Menu.

This is the timeline of the particle. The timeline shows time in milliseconds, and the duration of the spawned particle. A dark red line intersects through all of the particle property values and touches the timeline. This dark red line shows at what point in time(milliseconds) the particle dies.
allows you to scroll the timeline bar to see a desired amount of time, holding CTRL at the same time will slow the scrolling. RMB click on the timeline to zoom in and SHIFT+RMB clicking will zoom out the timeline.

Generator Properties
Think of these as looping scripts that define HOW the generator works. Advanced properties allow you to tell a generator to loop x number of times and die, or loop infinitely. A generator continues to spew the particle defined by it's Particle Properties at a rate defined by it's flow, until it reaches it's death time.

in a property window inserts a node. Inserting nodes allow you to change values for a property over time. LMB+drag up or down will change that nodes value, or RMB click on a node to open a modify property value dialog box, and get more info (color picker, numerical input, etc.). LMB+drag a node to the left or right will allow you to change the position of the node in time. You can delete a node by LMB+click to select it then pressing the delete key.

How many particles\second this baby spews out. Multiple nodes allow you to change the spew rate at various points in time.

Allows you to specify a sudden burst of a specified number of particles at a specific point in time. Multiple nodes allow you to have multiple bursts at different points in time.

Angle Range
This is neato. Right-click on a node for this, and you get the Modify Angle Range Data window. Imagine the window as a cross-section of the particle cloud. You can tell it to emit directly up, down, to the sides, or lerp all those through time. The range means that a particle will emit in a random direction within the upper and lower limits.

Init vel
Initial velocity. Particles spawned will have a random initial velocity within the range of the min and max values specified here... Some shoot out slowly, some FLY. Set the upper and lower limits to the same number, and particles will move at a steady speed. Use the scrollbars to select the upper and lower bounds for the angle range of particle emission.

Another timeline, but this one shows time relative to the Generator. A dark red line intersects through all of the generator property values and touches the timeline. This dark red line shows at what point in time(milliseconds) the generator dies. Notice that if loop indefinitely is set in the Advanced Properties a generator never 'appears' to die. Note also that once a generator dies no more particles will be created, but those that were created before the death of the generator will continue along their path until they reach their death time.
allows you to scroll the timeline bar to see a desired amount of time, holding CTRL at the same time will slow the scrolling. RMB click on the timeline to zoom in and SHIFT+RMB clicking will zoom out the timeline.

Advanced Properties
The Advance Properties button allows you to change advanced values for the currently selected generator. You can add things like air resistance, blending, angles, etc... This will be detailed more in the future.

First Tab: PHYSICS
This displays the Physical Particle Properties... Use Acceleration, Use Air Resistance, and Particle Space Moves.

Use Acceleration
This accelerates the particle in x,y,z dimensions by the amount specified.

Use Air Resistance
This is the deceleration of the accelerated particle(It slows a particle down by the amount specified)

Particle Space Moves
If this particle definition is attached to a model(See Planet->Particles & the Triangle Highlighter), all particles from this generator move with it.

Second Tab: OPENGL
This tab sets the rendering methods of the generator..... I had a document somewhere that explained all of this...

Third Tab: TEXTURE
This tab allows you to specify a bitmap to be spewed by the generator.

Particle Texture
Two options are available here; use default internal texture(which is a filled circle of of color, defined by the particle property 'color'), or graphic file(bitmap) inside the directory tree specified in Menu: File-> Set Data Directory.

This tab allows you to add more variations to each particle to make them a little unique into each other.

Paticle Time Variance
This gives a timescale scale variance in each particle. This causes a particle to cycle through it's lifetime faster, or slower, depending on the value specified.

Movement Based Flow
Not sure yet. Need to run some tests. Appears to variate speed, and/or directional flow of particles.

Specifying a value here designates the percentage chance the particle will flicker off, then back on again. A value of '0' means no flickering for any particles. The Flicker All Particles In Generator At The Same Time check box forces all spawned particles to flicker simultaneously.

Fifth Tab: SPAWN
This tab allows you to specify addition spawn values for the generator.

Generator Loops
Here you can specify if a generator should loop indefinitely, loop a specified number of times, or force all generators in the particle definition that appear after this one to spawn when this generator is at a specified time interval.

Spawn Volume
This constricts the generator to spew particles randomly within a box defined by the AnachroRadiant KEY: Scale(See AnachroRadiant->Working with Entities for more information).

Sixth Tab: ANGLES
This displays the following... Constant Particle Rotation, and Particle Normals.

Constant Particle Rotation

Particle Normals


Using Particleman for Models
Before we get started, just in case you don't know, MD2s are the model files used in Anachronox. What does MD2 stand for? How long has the Md2 format existed, and for how many different games? I jus' wanna give the reader a little background on the format, since I'd like to know that sort of stuff if I was reading something like this.

Open an Md2 in ParticleMan (which is how I'm gonna refer to the Particle Manager from here on out) By doing the following: Go to Menu: File->open, and click on the .md2 you like. (Keep in mind, you can Load an Md2 from anywhere, but if you're not loading it from a under your Anoxdata directory (wherever you installed Anachronox), the texture won't load right.)

You SHOULD now see whatever MD2 you just loaded, with its skin loaded and everything. ParticleMan WAS initially designed for particles, but if you want the particle to go away (this IS, after all, the Md2 tutorial), go to Menu: Particle->Suppress Spawning (CTRL+P), and the particle will go away.

Crack open the Model Properties window(Menu: Window->Model Popup) (f5). The Model Properties window is where ALL the magic happens. Now, there's a LOT of information to cover in the six tabs of the Model Properties window, so I'll take 'em one by one. NOTE: Sometimes when switching tabs the window options do not change. This is a bug in the program and can not be fixed, since we do not have access to the source code. You can either close the Model Properties window or flip back and forth between tabs until the bug stops.

First Tab: MD2 INFO
This displays the following... Base Md2, Delivery, Stats, Skins and Surfaces, and Memory useage.

Base Md2
This is the Md2 you just loaded, path an' all.

We use a program called LW2MD2 to convert Lightwave files and .uv information (how the bitmap applies to the model). When we use this program, we can scale the model, and tell how many bytes to devote to the geometry (basically, if you don't devote enough bytes to the geometry, you get a warbling, as if the model's made out of Jelly.) Anyway, this Delivery box shows what the model was scaled at, and how many bytes were devoted to it. (3 bytes is the default, 5 is usually enough to keep most things from warbling, and 6 is used on things that are VERY big, or that you see very closely.

#/ What the hell is that first number? /# , number of vertices, number of polys in the model (tris), and number of animation frames, if applicable.

Skins and Surfaces
This is divided into two sections, as you'll see... the skins/emits section tells you how many bitmaps the model uses, and it tells you what the bitmaps are named. This is useful for making shaders, but that's another tutorial. The Tag surf window tells you how many surfaces (special polygons) are tagged, or used for a specific function in the game. Typical examples of tagged surfaces are fx_1 (for particles), hand_r (for attaching a weapon to a right hand), etc. #/ We need to have a talk about the difference between skins/surfaces, Tagged surfaces, and all that stuff. I think I'm a bit fuzzy... /#

Memory Usage
#/ Alright, Joey. I'm BLANK. These are just Numbers. Hook me up. /#

Second Tab: MDA INFO
This only REALLY applies when you write an MDA (shader) file. See Visual Effects->Shaders for more information. This tab shows the following... Base Md2, Chunk Properties, and Profile Data.

Base Md2
This is the Md2 used for the Mda. If all you've Loaded is an Md2, it'll show the path of the Md2, same as the Base Md2 window in the last tab.

Chunk Properties

#/ Joey? Dude, what the Hell's going on? Let's include this in our Powwow.../#

Profile Data
In the Select box, you can see all the separate Shader Profiles available for your MDA. This is where you can see all of the skin variants of a model, etc. In the Passes window, there's a hex number that #/More Joey needed here /#

Recompute normals button
#/Grayed out... Joey, is this obsolete? /#

Refresh button
#/ what purpose does this serve? /# Assuming it allows you to reload a model that has been compiled with lw2md2 after you already had it loaded into Particleman.

This handy lil' tab shows the following... Triangle Highlight, Head Triangles, and Tagged Surfaces.

Triangle Hilight
In Anachronox, with the inclusion of the New Particle system (the kind you make with This particle manager), any polygon of a model can emit particles. Which is useful if you can find out which polygons are which. When you click on the "Highlight a specific triangle" button, you'll see some wireframes appear on your model. Additionally, one Polygon (triangle) will be filled in with a teal color. This is the selected triangle, whose number is shown in the window to the right of the highlight button. (if the selected triangle is dark red, it's because you're seeing it from behind. the selected triangle and the wireframes are always visible. (you'll notice that the wireframe around the selected triangle is colored red, green, and blue. This coloring shows the order of the vertices) If you're not content to select a number, there's a slider bar to scroll through in order to find exactly the poly you're looking for. (this is useful if you want a monster's eyes to gout smoke, or for their ears to spit fire, or whatever.) See Planet->Particles & the Triangle Highlighter for more information.

Head Triangles
This part is complicated, and if you don't want your character to do any facial deformation (facial expressions, lip synching), you can skip it. Otherwise, here's the digs.
Now, the finer elements of giving an .md2 facial morphs is plenty of information for another tutorial. So I'll give you the quick version here. Basically, in order for a character to have facial morph positions that it can assume while playing other animations (talking while walking, for example), the md2 has to have some stable frame of reference, some way of knowing that even if the character is moving, some part will stand still. That's where Head Triangles comes in. If, for example, you had a humanoid character, you would want three triangles from his head, since no matter what animations your character plays, his head won't change shape. So you highlight a triangle on the character's head, say the forehead. Then you press the first "set" button. You'll see the triangle number appear in the window next to the words "Triangle 1". So you repeat the process two more times, with different triangles from his head, and you'll have all you need. Once that's done, you press the "BONE" button. Doing this, with the three stable head triangles, will create a bone.
#/ Joey, I'm running out of Bullshit here.. Might need more cold, hard facts... /#

Tagged Surfaces
This little window shows you all the different surfaces of the model that have been specifically tagged for any reason. Remember that bit about fx_1 (for particles), hand_r (for attaching a weapon to a right hand) and all that? This window will tell you what triangle number that best corresponds to any given tagged surface. Just select the surface, press the "goto" button, and the number will appear.

Fourth Tab: FRAMES
For when you load an MD2 or MDA with Animations. This one shows the following... Raw frames and Parsed Animations.

Raw frames
If the object you loaded Doesn't have any animations, There will only be one raw frame. However, if it DOES have animations, the Raw frames window will show the name of every frame of animation that the model contains. Usually in Anachronox, these frames have names such as amb_a_001, where amb_a is the name of the animation, and the three digit number represents where in the animation that particular frame is. To see what any single frame of animation looks like, click on it's name in this window. The model that you've loaded into ParticleMan will show the frame you selected. See Anachrodox->Models for more information

Parsed Animations
This window will show all the animations that Anachronox understands (for a list of the animations that Anachronox understands, Anachrodox->Models). To see what an animation looks like, click on the animation name in this window, and the model you've loaded will loop that animation endlessly.
Note the "Reparse!" button below this window. this button #/Joey? What's this button good for? Has it been obsoleted by the "reload model" command? Also, is it REALLY necessary to explain the purpose of everything in the "frames" panel, when you summarize everything succinctly in your one little sentence of instruction? ug. I suppose the tutorials have to cater to the dumb ones, too./#

Fifth Tab: DISPLAY
How to see everything you want to see. This tab shows the following... Render Modes, Render Passes, and Debugging.

Render Modes
Clicking on one of these will display this element of your model. "Vertices" will display all the vertices in your model, as well as a little line coming off of the vertex that shows the direction of the surface normal (note: the term "Surface Normal" is a complicated term that affects lighting, reflection maps, etc. It really has no bearing on the MD2 viewer, so won't be discussed here. But it's good to know about...).
#/Hey, Joey? Where would be a good place to discuss the concept of Surface Normals? The MDA tutorial, maybie? Where could I get a good, iron clad definition to use? /#
"Wireframe" will draw a wireframe version of the model, showing the edges of all of the polygons.
"Flat-shaded" will display the model you've loaded as flat, gray polygons. This will help you see the shape of the model's geometry, without the skin.
Finally, "Shader/Texture" will show the skin of the model, and if you've opened an MDA with Multi-pass shaders (see Visual Effects->Shaders), the shaders will be displayed as well. Note that combinations of views will work as well, so that you can see (for example) "wireframe" And "shader/texture" at the same time if you want (although "Flat-shaded" will always hide the "shader/texture" when selected).

Render Passes
#/ Joey, this is ALL you. I know you explained it to me, but I'm still leaving it to you to write out the entire render priority spiel... /#

"Highlight Morphs" will draw a yellow dot over each of the affected vertices when you're cycling through facial morphs (facial morphs are covered under Anachrodox->Models)
"Draw Bone Axes" will display a little X,Y,Z axis based on a head bone you've created, if applicable (refer back to 6b if you're confused on Head Bones). The options are on by default, and help you to determine if your facial morphs are working correctly.

Sixth Tab: MORPHS
This tab is devoted to facial Morphs, so if you don't intend for your character to have facial Expressions or Lip Synching capability, you may ignore it. This tab shows the following... LWO Morph Directory, LWO Morphs, and MDA morphs (Note: Facial Morphs can ONLY exist on an MDA, so technically, the MD2 portion of the lesson is over. However, it IS the sixth tab of the Model Properties window, and since the MDA tutorial is the next in this series, The following will describe the entire process of adding facial expressions and lip synching capability to a model).

LWO Morph Directory
In order for your model to have Facial expressions, you need to have a directory devoted to Facial Expression models. In this directory, Every model must be Identical, except for their facial expressions. Furthermore, they have to be able to use the same UV co-ordinates as your model (see Anachrodox->Models). For Anachronox, we use 18 Lightwave objects, for 20 different facial expressions (you might want to do the same, although you can easily do more or less). For Demonstration purposes, I'll list off the 18 files we use (Remember, these are all in a directory set aside for facial morphs). With Joey's Facial Morph code, all of the files need to have four character file names. The ones we use are:

base.lwo - This is the Still (No facial expression) pose. It must have the same facial expression as the model used when dumping the lightwave animations.
Note: Expressions are denoted with an ex, Mouth positions are denoted with an mp.

mp00.lwo - This is the base mouth position, with the mouth Closed. This may or may not be identical to base.lwo. Note that Expressions start with the number 01, whereas Mouth positions begin with a position 00.
mp01.lwo - Phoneme mouth position for C,D,G,J,K,N,S,T,Y,and Z mouth sounds.
mp02.lwo - Phoneme mouth position for F and V mouth sounds.
mp03.lwo - Phoneme mouth position for L and TH mouth sounds
mp04.lwo - Phoneme mouth position for B, M, and P mouth sounds.
mp05.lwo - Phoneme mouth position for Q, R, U, and W mouth sounds.
mp06.lwo - Phoneme mouth position for E mouth sounds.
mp07.lwo - Phoneme mouth position for I and A mouth sounds.
mp08.lwo - Phoneme mouth position for short O sounds.
mp09.lwo - Phoneme mouth position for ooo sounds.
ex01.lwo - Confused facial expression.
ex02.lwo - Happy facial expression.
ex03.lwo - Sad facal expression.
ex04.lwo - Angry facial expression.
ex05.lwo - same as ex01 (confused), but doesn't change the shape of the mouth.
ex06.lwo - same as ex02 (happy), but doesn't change the shape of the mouth.
ex07.lwo - same as ex03 (sad), but doesn't change the shape of the mouth.
ex08.lwo - same as ex04 (angry), but doesn't change the shape of the mouth.

Once you have made all the facial expression and mouth position LWOs you want, copy the name of the directory they're in, and paste it into the "LWO Morph Directory" window there. If you scaled your md2 when you delivered it (see Delivery_101), use the "Pre-scale LWO data by:" window to adjust the facemorph objects. You'll note that the default scale by amount is 1.3. This is also explained in Delivery_101. Anyway, once you've pasted in the directory where your facemorphs are located, and you've adjusted the scale correctly, press the "Import!" button. The names of all your Lightwave Morph frames should now appear in the "LWO Morphs" window. If not, Check the console for an explanation.
After you have imported all of your model morphs, save the newly modified Model for use in Anachronox.

Lwo Morphs
This window, if you followed the last step correctly, will now display all the loaded facemorph frames. If you click on one of the frames, you'll see a wireframe version of that facial position object superimposed over the object that you currently have loaded. Additionally, you'll notice lines being drawn from every point on the facemorph wireframe to the corresponding point on your loaded model. This is useful for determining that the points on the hands of your morph frame, for example, correspond with the points on the hands of your model. If everything seems appropriate, press the "----GO--->" button, and the morph frames will show up in the "MDA Morphs" window. The "Threshold:" window you see is for #/Joey? what's Threshold/Reset/Debug output for? Need a bit of explainey...

MDA Morphs
This window shows your final Morph frames. Clicking on them will cause your loaded model to change facial expressions. That's It. Save your MDA, and it's Done.
Now you can use Magpie to create lip synch script files for use in APE, and Planet. See Anachrodox->Models for more information.