docs-mini/README.xmlparticles

   1 Document started 27/01/2008 by Tiago Gusmão
   2 Updated 02/02/2008 to reflect syntax changes
   3 Updated 03/02/2008 to add trails (connected particles)
   4
   5 This is a short specification/tutorial to define particle systems in FlightGear using XML
   6
   7 Meaningless example (what i had accumulated due to tests):
   8
   9   <particlesystem>
  10     <name>fuel</name>
  11 <!--     <texture>particle.rgb</texture> -->
  12     <emissive>false</emissive>
  13     <lighting>true</lighting>
  14
  15     <offsets>
  16       <x-m>35</x-m>
  17       <y-m>-0.3</y-m>
  18       <z-m>0</z-m>
  19       <!--<pitch-deg>90</pitch-deg>-->
  20     </offsets>
  21
  22     <!--<condition>
  23       <and>
  24         <equals>
  25           <property>engines/engine/smoking</property>
  26           <value>true</value>
  27         </equals>
  28         <less-than>
  29           <property>position/altitude-agl-ft</property>
  30           <value>12000</value>
  31         </less-than>
  32       </and>
  33     </condition>-->
  34
  35     <attach>world</attach>
  36
  37     <placer>
  38       <type>point</type>
  39     </placer>
  40
  41     <shooter>
  42       <theta-min-deg>84</theta-min-deg>
  43       <theta-max-deg>86</theta-max-deg>
  44       <phi-min-deg>-1.5</phi-min-deg>
  45       <phi-max-deg>1.5</phi-max-deg>
  46       <speed>
  47         <value>10</value>
  48         <spread>2.5</spread>
  49       </speed>
  50       <rotation-speed>
  51         <x-min-deg-sec>0</x-min-deg-sec>
  52         <y-min-deg-sec>0</y-min-deg-sec>
  53         <z-min-deg-sec>0</z-min-deg-sec>
  54         <x-max-deg-sec>0</x-max-deg-sec>
  55         <y-max-deg-sec>0</y-max-deg-sec>
  56         <z-max-deg-sec>0</z-max-deg-sec>
  57       </rotation-speed>
  58     </shooter>
  59
  60     <counter>
  61       <particles-per-sec>
  62         <value>1</value>
  63         <spread>0</spread>
  64       </particles-per-sec>
  65     </counter>
  66
  67     <align>billboard</align>
  68
  69     <particle>
  70       <start>
  71         <color>
  72           <red>
  73             <value>0.9</value>
  74           </red>
  75           <green>
  76             <value>0.09</value>
  77           </green>
  78           <blue>
  79             <value>0.09</value>
  80           </blue>
  81           <alpha>
  82             <value>1.0</value>
  83           </alpha>
  84         </color>
  85         <size>
  86           <value>0.25</value>
  87         </size>
  88       </start>
  89
  90       <end>
  91         <color>
  92           <red>
  93             <value>1</value>
  94           </red>
  95           <green>
  96             <value>0.1</value>
  97           </green>
  98           <blue>
  99             <value>0.1</value>
 100           </blue>
 101           <alpha>
 102             <value>0.0</value>
 103           </alpha>
 104         </color>
 105         <size>
 106           <value>4</value>
 107         </size>
 108       </end>
 109
 110       <life-sec>
 111         <value>10</value>
 112       </life-sec>
 113
 114       <mass-kg>0.25</mass-kg>
 115       <radius-m>0.1</radius-m>
 116     </particle>
 117
 118     <program>
 119       <fluid>air</fluid>
 120       <gravity type="bool">true</gravity>
 121       <wind type="bool">true</wind>
 122     </program>
 123 </particlesystem>
 124
 125 Stick this inside any model XML like it was an animation and it should
 126 work (notice the condition requires wheel on the ground)
 127
 128 Specification:
 129
 130 Note:
 131 <VALUEORPROP/> means you can either specify a property with factor and
 132 offset (result = (prop*factor)+offset ) in the usual way
 133
 134
 135
 136 <particlesystem>  = the base tag
 137   <type>string</type> can be "normal" or "trail", normal is the usual quad particles, trail is a string of connected quads, see note near the end
 138   <offsets>  = this places the source of the particles (the emitter) in relation to the perhaps already offsetted model (see model-howto.html for details)
 139     <x-m>float</x-m>
 140     <y-m>float</y-m>
 141     <z-m>float</z-m>
 142     <pitch-deg>float</pitch-deg>
 143     <roll-deg>float</roll-deg>
 144     <heading-deg>float</heading-deg>
 145   </offsets>
 146   <condition> =a typical condition that if not true stops particles from being emitted (PPS=0)
 147     ....
 148   </condition>
 149   <name>string</name> = the name of the particle system (so it can then be referenced by animations)
 150   <attach>string</attach> = can be "world" or "local". "world means the particles aren't "physically linked" to the model (necessary for use outside moving models), "local" means the opposite (can be used for static objects or inside moving objects)
 151   <texture>string</texture> = the texture path relative to the XML file location
 152   <emissive>bool</emissive> = self-explanatory
 153   <lighting>bool</lighting> = yet to be tested, but seems obvious
 154   <align>string</align> = can be "billboard" or "fixed", still being worked, don't use
 155   <placer> = where particles are born
 156     <type>string</type> = can be "sector" (inside a circle), "segments"(user-defined segments) and "point" (default)
 157     *<radius-min-m>float</radius-min-m> = only for sector, inner radius at which particles appear
 158     *<radius-max-m>float</radius-max-m> = only for sector, outer radius at which particles appear
 159     *<phi-min-deg>float</phi-min-deg> = only for sector, starting angle of the slide at which particles appear
 160     *<phi-max-deg>float</phi-max-deg> = only for sector, ending angle of the slide at which particles appear
 161     <segments> = only for segments, encloses sequential points that form segments
 162       <vertex> = specifies one point, put as many as you want
 163         <x-m>float</x-m>
 164         <y-m>float</y-m>
 165         <z-m>float</z-m>
 166       </vertex>
 167       ....
 168       <vertex>
 169       ...
 170       </vertex>
 171     </segments>
 172   </placer>
 173   <shooter> = the shooter defines the initial velocity vector for your particles
 174     *<theta-min-deg>float</theta-min-deg> = horizontal angle limits of the particle cone
 175     *<theta-max-deg>float</theta-max-deg>
 176     *<phi-min-deg>float</phi-min-deg> = vertical angle limits of the particle cone
 177     *<phi-max-deg>float</phi-max-deg>   for an illustration of theta/phi see http://www.cs.clemson.edu/~malloy/courses/3dgames-2007/tutor/web/particles/particles.html
 178     <speed-mps> = the scalar velocity (meter per second)
 179      <VALUEORPROP/> = see note
 180      *<spread> the "tolerance" in each direction so values are in the range [value-spread, value+spread]
 181     </speed-mps>
 182     <rotation-speed> = the range of initial rotational speed of the particles
 183       *<x-min-deg-sec>float</x-min-deg-sec>
 184       *<y-min-deg-sec>float</y-min-deg-sec>
 185       *<z-min-deg-sec>float</z-min-deg-sec>
 186       *<x-max-deg-sec>float</x-max-deg-sec>
 187       *<y-max-deg-sec>float</y-max-deg-sec>
 188       *<z-max-deg-sec>float</z-max-deg-sec>
 189     </rotation-speed>
 190   </shooter>
 191   <counter>
 192     <particles-per-sec>
 193       <VALUEORPROP/> = see note
 194       *<spread> the "tolerance" in each direction so values are in the range [value-spread, value+spread]
 195     </particles-per-sec>
 196   </counter>
 197   <particle> = defines the particle properties
 198     <start>
 199       <color> = initial color (at time of emission)
 200         <red><VALUEORPROP/></red> = color component in normalized value [0,1]
 201         <green><VALUEORPROP/></green>
 202         <blue><VALUEORPROP/></blue>
 203         <alpha><VALUEORPROP/></alpha>
 204       </color>
 205       <size> = as above, but for size
 206         <VALUEORPROP/>
 207       </size>
 208     </start>
 209     <end>
 210       <color> = final color (at the end of the particle life)
 211         <red><VALUEORPROP/></red>
 212         <green><VALUEORPROP/></green>
 213         <blue><VALUEORPROP/></blue>
 214         <alpha><VALUEORPROP/></alpha>
 215       </color>
 216       <size>
 217         <VALUEORPROP/>
 218       </size>
 219     </end>
 220     *<life-sec> = the time the particles will be alive, in seconds
 221       <VALUEORPROP/>
 222     *</life-sec>
 223     *<radius-m>float</radius-m> = each particles is physically treated as a sphere with this radius
 224     *<mass-kg>float</mass-kg> = mass in KG
 225   </particle>
 226   <program> = defines external forces acting upon a particle
 227     <fluid>string<fluid> = can be "air" or "water"
 228     <gravity>bool</gravity> = can be "true" or "false". uses standard gravity
 229     <wind>bool</wind> = can be "true" or "false". uses user position wind (not the model position, but shouldn't be noticeable, you want to disabled it when using local attach)
 230   </program>
 231 </particles>
 232
 233 Remarks:
 234   Don't forget you can use existing animations with particles, so if you want to direct or translate the emitter, just use translate, rotate, spin and so on (other animations might have interesting effects too I guess)
 235   Particle XML should be compatible with plib, as the tags will be ignored (you might get some warning if you attach them to animations though)
 236   Try not to use a lot of particles in a way that fills the screen, that will demand lots of fill rate and hurt FPS
 237   If you don't use any properties nor conditions, your particle system doesn't need to use a callback a so it's slightly better on the CPU (mostly useful for static models)
 238   If your particle lifetime is too big you might run out of particles temporarily (still being investigated)
 239   Use mass and size(radius) to adjust the reaction to gravity and wind (mass/size = density)
 240   Although at the moment severe graphical bugs can be seen in the trails, they are usable. Consider your options correctly! You should consider giving them no initial velocity and most important, no spread, otherwise particles will race and the trail will fold. Start simple (no velocities and forces) and work your way up.
 241