This is a complex application but you can have some fun just looking at and interacting with the available data files. In order to do this just read down a few paragraphs to the stop reading note below and look out on the forums for new data sets as they become available.
Like the app itself these instructions are a work in progress. If you don't understand something after searching the entire document please hit the forums and ask me.
Use the mouse to change your view direction. Use the W,S,A,D keys to move forwards, backwards and strafe left and right. Pressing the Q key toggles an alternative movement mode where view direction is fixed and the mouse controls lateral movement in conjunction with the W,S,A,D keys.
Continue reading for particle editor instructions. Terrain editor instructions can be found below.
Particle Editor/Simulator
Pushing the left mouse button creates an instance of the object stored in buffer 1 while the right mouse button creates an instance of object 2.
The Backspace key pauses/unpauses the action and the + key advances a paused scene by one time step. Press F1 to reset particles and terrain to the last loaded/saved states. Thus you can view impacts from multiple angles by moving to a new position and then hitting F1
Press Return to step between normal camera view and the current view targets which may include the last objects launched from the left or right mouse button (including loaded objects). When viewing an object pressing the left or right mouse buttons changes zoom.
(stop reading here if you don't actually want to create anything yet)
F2 allows editing of object 1 and F3 allows editing of object 2. You can load or save created objects by selecting "load/save particles" from the menu while in one of the object editors. (If you can't see a newly loaded object press F1 and then F2 or F3 again. I'm still ironing out the kinks.) Pressing F1 will return you to the simulator. Note that you will be returned to the last loaded or saved position so if there is something you want to keep before entering one of the editors you should save it first. The editors however will remember your work between visits until you quit or restart the program.
Within the object editor hold down the A key and move the mouse to rotate the object. Hold down D and push mouse up or down to zoom in and out. Hold down E and move the mouse to pan the object left/right and up/down. Press the left mouse button to add a particle of the current type to the object and press the right mouse button to delete a particle. Objects are edited as a series of layers. Press W to advance a layer and S to retreat a layer. Press the Q button to cycle through the 3 different viewing transparency modes. Note that pressing the A rotate button will temporarily make the object appear one level more solid. Pressing the M key will mirror the object around the currently selected layer. Pressing Delete will delete all particles. Pressing one of the number keys will set the particle create type to that number. Pressing Shift + number will select 10 + that number.
Move the mouse to select a particle or lattice position. Pressing the left mouse button will add a particle of the currently selected type and bond group to the object. Pressing the right mouse button will delete the currently selected particle. You select the current particle type by pressing [SHIFT +] a number key. You can select the current bond group and bond group display using the cursor keys. Bond groups determine which neighbouring particles will be bonded together when the object is first introduced into the environment. Afterwards bonding in the simulation is determined by heating above the melt temperature. Bond groups work like this - Each bond group will bond with itself. In addition White will bond with Red, Blue and Green but not Black.
Outside of the object editor pressing P will bring up the particle properties editor for the currently selected particle type. (select particle type by pressing number key or SHIFT + number key). Press P again to bring up the global properties editor. Press P a final time to bring up the object launch properties.
This applet includes an optimisation which will deactivate particles and particle groups when their speed has dropped below a threshold level for a few frames. This means you can have many more stationary particles in a scene and still maintain a given frame rate. You can see which particles are inactive by using the display setting under global properties.
Load/Save Particles
The operation of the load and save menu items is context sensitive depending on whether you opened the menu from the main simulator/editor (F1) or from one of the object editors (F2 & F3).
When selecting from the simulator all of the particle and particle editor properties (those accessed via hitting P repeatedly) with the exception of the particle erosion and trace display setting, the current camera position and both objects are saved/loaded along with the particle scene in to the one file. When hitting F1 the same thing occurs but the camera position and objects are not reloaded. This means that you will have to save you properties often, if you hit F1 to reset the simulation or after editing objects all of the properties will have returned to their last loaded/saved state.
You can load or save objects seperately by accessing the menu while in the object editor. Particle files saved from the main editor and from the object editor are not compatible and will not be displayed in the file listing when loading for the other type.
Particle Properties:
Note: All temperatures are in Kelvin. Hence 0 is as low as you can go. Velocities are in metres per second. This fixes the diameter of individual spheres at 20cm and the length of the environment at 375 metres. Other units are noted below.
Flex - A modifier to the distance which two linked particles can be stretched before the link between them breaks. This number can be negative to make brittle objects. This modifier only applies to solid objects. Once a particle has passed its melt temperature it always has a Flex of 0.
Bond Strength - The strength of the link between bonded particles when they are at Optimum temperature or below. This value represents the acceleration in ms-2 when the bond is at full extension. Thus it can be compared with gravity. Also it is independent of mass. I did this since at high values the simulation stability breaks down.
Damping - Damping of velocity differences between bonded particles when they are at Optimum temperature or below.
Melt Temp - The temperature at which particles melt. Molten particles can form new bonds with nearby unbonded particles. They also can have a different base colour and can glow.
Low Visc Temp - The temperature at which particles attain their low viscosity properties defined below. Between Optimum and Low Visc Temp particles adopt a weighted blend of properties.
Optimum Temp - The temperature at which particles adopt the Optimum temperature properties defined above and colour defined below.
Bonded Heat Gen - The amount of heat generated by relative motion of bonded particles.
Unbonded Heat Gen - The amount of heat generated by relative motion of nearby unbonded particles.
Solid Ground Friction - Ground friction when particles are at optimum temperature or below.
Melt Ground Friction - Ground friction when particles are at melt temperature or above. Friction at intermediate temperatures is a weighted blend of the two friction amounts.
Low Visc Attract - As with bond strength above but at the higher low viscosity temperature.
Low Visc Bond damp - As with damping above but at the higher low viscosity temperature.
Optim Alpha, Red, Green, Blue - Colour and transparency of particles when they are at or below optimum temperature.
Melt Alpha, Red, Green, Blue - Colour and transparency of particles when they are at or above melt temperature. In between temperatures result in a colour blend.
Melt Glow Red, Green, Blue - An additional glow which is added to the particle as it approaches melt temperature.
Low Visc Glow Red, Green, Blue - The colour the molten glow transforms into as the particle approaches low viscosity temperature.
Mass - Particle density in kg/m3. A density above 1000 means that particles will sink in water. Mass also indirectly affects the strength of objects.
Global Properties:
Ambient Temp - The background temperature. Particles will tend towards this temperature over time. The less particles they are bonded to the faster they will approach this temperature. Bonded particles will conduct their temperature between each other.
Gravity: Acceleration due to gravity in ms-2.
Air Density: Air density in kg/m3. Air Density determines drag, lift and buoyancy. However the equations for these calculations are a little more open to interpretation than others so I've provided the multipliers to these below so that they can be adjusted independent of buoyancy.
Lift: Lift multiplier.
Drag: Drag multiplier.
Vel Size: The increase in size of a particle's collision detection region grows with velocity. A larger value will result in a slow frame rate if there are lots of high speed particles in the scene. Set it to a low value such as 0 to speed up collision detection when you have large high speed objects (eg a plane) in the scene. Set it to a higher value (eg 5) to cope with small high velocity impactors (eg a bullet). Note that you can also compensate for high velocity objects by increasing the number of physics steps below.
Vel Start: The velocity at which the collision detection sphere starts growing.
Vel Max: The velocity at which the collision detection size addition reaches its maximum value and will increase no further.
Display: Normal display gives particles their normal colour and size. Trace display blacks out particles that are inactive. It also shows the size of particles according to the volume swept for their collision detections as determined by Vel Size, Vel Start and Vel Max.
Physics Steps: The number of physics steps per render frame. A larger number will result in you being able to use higher bond stengths and damping without instability. While this allows the modelling of more rigid objects it also slows frame rate. Each "physics step" is itself composed of multiple force calculations and particle move steps but a "physics step" is the smallest decomposable simulation unit.
Particle Erode On/Off: Toggles the influence of particles upon the terrain. Typically you might to turn this off when setting up a scene so that you don't have to save out (and distribute) a new modified terrain after particles cause erosion while they are settling in to place. I've found that mismatched particle positions and terrain files will often result in objects getting pushed up by the terrain when the file is first loaded.
Load Params: When this is off selecting load particles will only load the position, velocity, temperature etc of individual particles. It is a way to propogate a set of global, particle and launch properties across one or more files.
Flight Display: Toggles the display of velocity and Lift/Drag ratio for the currently selected particles.
There are two sets of Object Launch Properties, one for each object. You can access and edit them by pressing the 1 or 2 keys once you have brought up the Object Launch Properties with the P key.
Object orientation: Sets the orientation of the added object. Note that there are only three options. Once you have decided upon the orientation you are going to model an object from you should do a quick test to ensure its not going to be reversed to your expectations.
Add,Delete: Add creates a normal object. Delete creates an "anti" object which eradicates objects it strikes. You can use this as an alternative to the Backspace key which indiscriminantly deletes all particles in the scene.
Vel: The launch speed of the object. Setting this value to zero causes it to stick to the viewer. You can use this in conjunction with the height and depth settings below to lower objects on to the ground. Press the mouse button again to release a zero velocity object. Also any object which touches the ground will be released.
Rate: The rate at which objects are created.
Depth: The distance from the viewer which objects are created.
Height: The height relative to the viewer which the objects are created at.
Temp: The temperature of the object (in Kelvin).
A discourse on rigid objects .....
Unfortunately the objects that you can currently model at interactive frame rates are either quite small or too jelly like to represent the rigid materials required for contraptions such as aircraft or cannons. However by turning down the flex value you can create a reasonable approximation of poor quality concrete :)
The basic problem is that all forces are communicated via the bonds between particles and the more particles there are in a model the longer it takes to communicate forces between distant particles. While gravity is applied evenly at every particle (yes I can simulate a falling rock pretty well) lift, either from wings or ground contact, is only applied at some particles and takes a while to reach non lift producing particles. Its not like the full force leaps from one particle to the next each simulation frame either. Its applied as an acceleration which influences the particle's velocity which in turn influences its position relative to neighbouring particles. The stronger the bond, the greater the force and the faster motions are communicated and the more rigid the resulting material. But you can only push the bond and the associated bond damping so far before the system becomes unstable and models decompose into a froth of violently vibrating particles. Having too high a bond strength relative to damping can also result in a model which takes a long time to stop flexing after an external force.
You can compensate for these problems by increasing the number of physics steps per render. But as you increase this number you must sacrifice either frame rate or total particle numbers. Thus you might be able to make a reasonable aircraft or cannon model if you don't mind seeing it operate in slow motion. As a basic rule of thumb you should be able to set the maximum bond strength to 150 x the Physics steps value and bond damping to 1.75 x physics steps value but try pushing it to see how far you can go. For example a value of 4 should allow a maximum bond strength of 600 (you can push it higher if you don't mind your model vibrating) and a maximum damping of 7 while a value of 8 will allow around 1200 and 14.
I've tried a number of hacks to allow greater apparent rigidity without slowing down the simulation but none have helped. My most recent attempt was to try to artificially distibute external unbonded forces such as gravity and lift around the model in a way that would have resulted in unrealistic turning moments but which may have been acceptable for slow turning objects such as an aircraft in flight but it did little except reduce any accuracy the physics model may have.
One potential solution would be some more advanced integrator but the maths and basic awareness of the state of the art in physical simulation are not currently in my repertoire. I rely more on a highly optimised vector unit friendly assembly coded physics engine and brute force. It should be noted that even with a Physics steps value of 4 and a frame rate of 40 fps each particle is having bond forces with up to 12 neighbours and resultant accelerations calculated 480 times per second and collisions with the ground and unbonded particles calculated 160 times per second. Compare this with just 40 physics iterations (at 40 fps) for my "artistic" and galactic based simulations and you can see why the number of particles must be radically reduced to maintain frame rate.
Another potential solution would be to derive a rigid "ghost" framework of particles which coexists with the actual simulated particles. The simulated particles would be attracted to their ghost partners thus maintaining rigidity and the ghost would be translated and rotated to track the mean position of the actual particles. As particles' links become broken and groups become isolated from the core of the object the influence of the ghost upon them and their influence upon the ghost would be reduced to allow parts to break off. This sounds like a lot of fiddly work and tuning to me and departs from my core concept of decentralised simulation and having the properties of the whole arise from the interaction of its parts.
While it would be nice to create a flying time trial game with user designed rocket powered destructible airplanes I'm putting any hacks like these on hold. I'm more interested in artificial evolution of (neccesarilly) slightly squishy lifeforms. However the situation for rigid bodies should be improved for multi core machines by the optimising I'm undertaking to get the physics simulation running on more than one core simultaneously. That flying game at interactive frame rates will probably be possible on quad core machines once I'm done. And of course the hardware keeps getting faster all the time :)
Terrain Editor
Press the T key to cycle through the various Terrain Editor functions. The currently selected function not only determines what you may edit using the cursor keys it also determines the function of the mouse buttons. The Terrain Editor Functions in order are Erosion/Precipitation, Brush Operations, Display and Global Operations. There are ten save slots for the parameters associated with the functions. To use or edit each of the parameter sets press a numbered key to bring up those parameters. Note that all parameter sets default to set 2 upon program start up. (I can't quite remember why its not 1!) This is of particular importance when setting terrain colours since it is set 2 colours that a user will see when loading up one of your saved data sets.
Erosion/Precipitation
Pressing the left mouse button resets the number of simulation steps and begins the simulation. Pressing the right mouse button stops the simulation. You can use the cursor keys to select and set the following values which influence the simulation.
Simulation Steps: Sets the number of simulation steps that will follow when the left mouse button is pressed.
Soil Slope: Sets the slope threshold at which soil will slip down an incline. Note that a steeply sloped terrain will always cause soil slippage even when the simulation is not running. However you can use this setting to create smoother terrains by setting a lower threshold while the terrain simulation function is running.
Precip Set: The base level of precipitation during the time that precipitation is on.
Precip Var: Variation in precipitation over the base amount.
Precip On: The number of consecutive time steps that precipitation is on.
Precip Off: The number of consecutive time steps that precipitation is off.
Soil Dry: The rate at which soil drys out.
Water Absorb: The rate at which surface water is absorbed into the ground thus reducing surface water level but increasing the soil moisture level.
Grass Grow: The rate at which grass grows in favourable conditions.
Grass Min Soil: The minimum level of soil required for grass to survive.
Grass Max Soil: The soil level at which grass survival is optimised. Note that soil levels above this will also have optimal grass survival.
Moist Grass Start: The minimum soil moisture level at which grass growth can begin.
Moist Grass Peak1: The soil moisture level at which grass growth reaches its maximum.
Moist Grass Peak2: Grass growth remains optimal until this point.
Moist Grass Stop: Grass growth stops at this soil moisture level and above.
Erode Soil 1,2,3: Sets the soil levels at which the different erosion rates kick in.
Erode Rate 1,2,3: Sets the rates of erosion at the three different levels. Erosion rates are multiplied by the quantity of water (sort of) passing over the terrain. Eroded soil is carried along in the water (and discolours it) until the water velocity drops whereupon it is deposited. Unlike most of the other simulation values these values also have an effect outside of the terrain simulation.
Evap: The rate of evaporation of surface water.
Grass Erode: The rate at which erosion destroys grass cover.
Erode Moisten: The degree to which erosion causes the underlying soil to increase its moisture content.
Pressing the left mouse button causes additive brush particles of the current type to be fired towards the centre of the screen. Pressing the right mouse button causes subtractive particles to be fired. You can use the cursor keys to select and set the following values which influence the operation of brushes.
Brush Type: Allows you to set the brush to modify or smooth the 3 terrain levels (in order of depth) water, soil and rock.
Height Size: The size of the brush. Larger numbers of large brushes with low decay can run quite slowly.
Height Strength: The brush intensity.
Jitter: The rapidity with which brushes change direction. Ultimately this will affect the fractal dimension of the terrain produced.
Spread: The arc over which new brushes are fired out.
Inertia: The degree to which the initial velocity of a brush is carried over when it strikes the ground.
Rate: The rate at which new brushes are created when a mouse button is pressed.
Slope: Controls the degree to which brushes run up or down slopes. A negative slope causes brushes to run downhill while a positive slope causes them to run uphill.
Decay: Controls the lifetime of brushes.
Use the cursor keys to set and select the following values.
Display Type: Select between normal, soil and height. Normal is the standard terrain colour display. Soil presents a colour coded representation of soil levels. Height presents a colour coded representation of height.
Soil Scale Min, Soil Scale Max, Height Scale Min, Height Scale Max: Sets the range over which the colour coded display varies when the display type is set to soil or height.
Rock RGB, Soil RGB, Grass RGB: Sets the colour for rock, soil and grass in their dry states. Note that these values are multipliers for the texture colour when texture is on. You will find that there are a separate set of values to set when you have selected texture mode in the menu.
Solid Damp RGB, Grass Damp RGB: Modifiers to the soil and grass colours when they are at full moisture content.
Use the left mouse button to apply the parameter settings below over the entire terrain. The right mouse button applies the reverse transformation.
Soil Add: The amount of soil to add across the entire terrain.
Slope: Sets the target back to front slope of the terrain.
Flatten Str: Sets the strength of the flattening process.
Depress Front: Sets the difference in height between the middle and edges of the terrain at the front end of the terrain.
Depress Rear: Sets the difference in height between the middle and edges of the terrain at the back end of the terrain.