openclonk/docs/sdk/particle/index.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE doc
  SYSTEM '../../clonk.dtd'>
<?xml-stylesheet type="text/xsl" href="../../clonk.xsl"?>
<doc>
  <title>Particle</title>
  <h>Particle</h>
  <part>
    <text>Particles are lightweight objects which are not synchronized in a network game. This means that on the one hand you can create huge amounts of particles without slowing down the game too much but on the other hand there are only limited options for control of particle behaviour. If the particles are not sufficient for a given effect you have in mind, you can always use true objects instead.</text>
    <text>If a particle is defined in a ocd group, any object definition located in the same group is ignored.</text>
    <text>Particles are not stored in savegames and are designed for temporary visual effects only.</text>
    <h id="PartikelKomponentenOCD">Particle Components (ocd)</h>
    <dl>
      <dt><img height="16" src="../../images/icon_text.png" width="16"/>Particle.txt</dt>
      <dd>
        <text>Particle properties.</text>
      </dd>
      <dt id="Graphicspng"><img height="16" src="../../images/icon_image.png" width="16"/>Graphics.png</dt>
      <dd>
        <text>Particle graphics.</text>
        <text>The particle definition can also contain the known components of <emlink href="definition/index.html">object definitions</emlink> for describing the particle (e.g. Title.png, DescDE/US.txt, etc.)</text>
      </dd>
    </dl>
    <h id="Particletxt">Particle.txt</h>
    <text>This component contains the properties of the particle - as <emlink href="definition/defcore.html">DefCore.txt</emlink> does for <emlink href="definition/index.html">object definitions</emlink>.</text>
    <text>
      <table>
        <caption id="SektionDefCore">Section [Particle]</caption>
        <rowh>
          <col>Value</col>
          <col>Data type</col>
          <col>Description</col>
        </rowh>
        <row>
          <col>Name</col>
          <col>String (max. 30 chars)</col>
          <col>Name of the particle definition. This name is also used to refer to this particle type in scripts.</col>
        </row>
        <row>
          <col>Face</col>
          <col>4 integers</col>
          <col>Target rectangle for the graphics within Graphics.png. See <a href="#face">particle graphics</a>.</col>
        </row>
      </table>
    </text>
	<h id="face">Graphics</h>
    <text>The coordinates for the source rectangle within Graphics.png of a particle specify the first phase of the particle graphics the other phases should follow to the right and can be continued in the next row. The animation length is then automatically determined from the image size.</text>
	<h id="properties">Properties</h>
    <text>Each particle has different attributes like position, lifetime, size and more. These are set by script when creating the particle.</text>
    <text>The following properties can be contained in a proplist passed to <funclink>CreateParticle</funclink>. For an example, see <funclink>CreateParticle</funclink></text>
	<text>You can assign either constants to the properties (f.e. <code>R = 200</code>) or use certain value provider functions (f.e. <code>R = <funclink>PV_Linear</funclink>(200, 0)</code>). Available value provider functions are:
	  <funclink>PV_Linear</funclink>
      <funclink>PV_Direction</funclink>
      <funclink>PV_Random</funclink>
      <funclink>PV_Step</funclink>
      <funclink>PV_Speed</funclink>
      <funclink>PV_KeyFrames</funclink>
      <funclink>PV_Wind</funclink>
      <funclink>PV_Gravity</funclink>
	  </text>
    <text>
      <table>
        <caption id="particledef">Particle definition proplist</caption>
        <rowh>
          <col>Name</col>
          <col>Values</col>
          <col>Description</col>
        </rowh>
        <row>
          <col>R</col>
          <col>0 to 255</col>
          <col>Red part of the color modulation.</col>
        </row>
		<row>
          <col>G</col>
          <col>0 to 255</col>
          <col>Green part of the color modulation.</col>
        </row>
		<row>
          <col>B</col>
          <col>0 to 255</col>
          <col>Blue part of the color modulation.</col>
        </row>
		<row>
          <col>Alpha</col>
          <col>0 to 255</col>
          <col>Alpha part of the color modulation.</col>
        </row>
		<row>
          <col>Size</col>
          <col>pixels</col>
          <col>Size of the particle in pixels.</col>
        </row>
		<row>
          <col>Stretch</col>
          <col>factor</col>
          <col>The vertical stretch of the particle. 1000 equals no stretch.</col>
        </row>
		<row>
          <col>Phase</col>
          <col>Index of phase</col>
          <col>The displayed phase of the particle from the Graphics.png. The index starts at 0 and will be wrapped.</col>
        </row>
		<row>
          <col>Rotation</col>
          <col>0 to 360</col>
          <col>Rotation of the particle.</col>
        </row>
		<row>
          <col>ForceX</col>
          <col>Integer</col>
          <col>Force in x-direction that is constantly applied to the particle's speed. Can f.e. simulate wind.</col>
        </row>
		<row>
          <col>ForceY</col>
          <col>Integer</col>
          <col>Force in y-direction that is constantly applied to the particle's speed. Ca f.e. simulate gravity.</col>
        </row>
		<row>
          <col>DampingX</col>
          <col>0 to 1000</col>
          <col>Damping of the particle's speed in x-direction. 1000 means no damping, 0 means instant stop.</col>
        </row>
		<row>
          <col>DampingY</col>
          <col>0 to 1000</col>
          <col>Damping of the particle's speed in y-direction. 1000 means no damping, 0 means instant stop.</col>
        </row>
		<row>
          <col>BlitMode</col>
          <col>0 or GFX_BLIT_Additive</col>
          <col>The particle's blit mode. Currently only additive blitting is supported.</col>
        </row>
		<row>
          <col>CollisionVertex</col>
          <col>0 to 1000</col>
          <col>The offset of the particle's hit point relative to its width. When set, the particle will collide with the landscape. 0 means the particle will collide with its center.</col>
        </row>
		<row>
          <col>OnCollision</col>
          <col><funclink>PC_Die</funclink>, <funclink>PC_Bounce</funclink>, <funclink>PC_Stop</funclink></col>
          <col>Defines what happens when the particle collides with the landscape.</col>
        </row>
		<row>
          <col>Attach</col>
          <col>bit mask</col>
          <col>Defines the attachment of the particles to the calling object. Can be a combination of ATTACH_Front, ATTACH_Back, and ATTACH_MoveRelative. For example <code>ATTACH_Front | ATTACH_MoveRelative</code></col>
        </row>
      </table>
    </text>
  </part>
  <author>Zapper</author><date>2013-10</date>
</doc>