openclonk/docs/sdk/script/fn/GetEffect.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE funcs
  SYSTEM '../../../clonk.dtd'>
<?xml-stylesheet type="text/xsl" href="../../../clonk.xsl"?>
<funcs>
  <func>
    <title>GetEffect</title>
    <category>Effects</category>
    <version>4.9.5.0 CE</version>
    <syntax>
      <rtype>any</rtype>
      <params>
        <param>
          <type>string</type>
          <name>name</name>
          <desc>Name of the effect without preceding 'Fx'. You can use '*' and '?' wildcards.</desc>
          <optional />
        </param>
        <param>
          <type>object</type>
          <name>target</name>
          <desc>Target object in which to access effects. If 0, the global effects are accessed.</desc>
          <optional />
        </param>
        <param>
          <type>int</type>
          <name>index</name>
          <desc>Effect index. With name specified and multiple matches for the search this will give you the indicated effect from the list of results. If name is not specified, this index is the effect number. Effect numbers do not necessarily run continuously from 0 to the number of effects. When using the index, this continuity is ensured.</desc>
          <optional />
        </param>
        <param>
          <type>int</type>
          <name>query_value</name>
          <optional />
          <desc>Index of the value to be retrieved. See remarks.</desc>
        </param>
        <param>
          <type>int</type>
          <name>max_priority</name>
          <optional />
          <desc>If not 0, only those effects are counted which have the specified priority or lower.</desc>
        </param>
      </params>
    </syntax>
    <desc>Retrieves effect data or determines whether a certain effect is present. The return value depend on the requested value. If an effect cannot be found the return value is always 0.</desc>
    <remark>
      Using the parameter query_value the following values can be retrieved:<br/><br/>
      <table>
        <rowh>
          <col>query_value</col>
          <col>Value</col>
        </rowh>
        <row>
          <col>0</col>
          <col>Effect</col>
        </row>
        <row>
          <col>1</col>
          <col>Name</col>
        </row>
        <row>
          <col>2</col>
          <col>Priority</col>
        </row>
        <row>
          <col>3</col>
          <col>Timer interval</col>
        </row>
        <row>
          <col>4</col>
          <col>Command target</col>
        </row>
        <row>
          <col>5</col>
          <col>Command target id</col>
        </row>
        <row>
          <col>6</col>
          <col>Duration of the effect</col>
        </row>
      </table>

    </remark>
    <examples>
      <example>
        <code>var obj, i, effect;
// Alle Objekte durchsuchen
<funclink>while</funclink> (obj=<funclink>FindObject</funclink>(0, 0,0,0,0, 0, 0,0, 0, obj))
  {
  // Von Effektzahl abwärts zählen, da Effekte entfernt werden
  i = <funclink>GetEffectCount</funclink>(0, obj);
  <funclink>while</funclink> (i--)
    <funclink>if</funclink> (effect = GetEffect(&quot;*Spell&quot;, obj, i))
      <funclink>RemoveEffect</funclink>(0, obj, effect);
  }
// Globale Effekte entfernen
i = <funclink>GetEffectCount</funclink>();
<funclink>while</funclink> (i--)
  <funclink>if</funclink> (effect = GetEffect(&quot;*Spell&quot;, 0, i))
    <funclink>RemoveEffect</funclink>(0, 0, effect);</code>
        <text>Removes all magic effects from all objects and the global list.</text>
      </example>
    </examples>
    <related>
      <emlink href="script/Effects.html">Effects Documentation</emlink>
      <funclink>AddEffect</funclink>
      <funclink>ChangeEffect</funclink>
      <funclink>CheckEffect</funclink>
      <funclink>GetEffectCount</funclink>
      <funclink>EffectCall</funclink>
      <funclink>RemoveEffect</funclink>
    </related>
  </func>
  <author>Sven2</author><date>2004-03</date>
</funcs>