Function

Functions are reusable sets of effects declared outside of any entity. Other tags serve as functions in a particular context, such as the Death and Effect tags.

##Declaration

Functions must go in their own file, because they need to be contained in a top level Functions tag. Each Function tag has one attribute - name.

<Functions>
    <Function name="EnemyDeath">
        <Spawn name="DeathPop" />
        <Sound name="EnemyDeath" />
        <Trigger condition="Random &lt; 0.1">
            <Effect><Spawn name="SmallHealth" /></Effect>
        </Trigger>
        <Trigger condition="Random >= 0.1 And Random &lt; 0.2">
            <Effect><Spawn name="SmallBolt" /></Effect>
        </Trigger>
        <Trigger condition="Random >= 0.2 And Random &lt; 0.25">
            <Effect><Spawn name="BigHealth" /></Effect>
        </Trigger>
    </Function>
</Functions>

Here is a list of the types of things functions can contain:

###Spawn

This tag is used to create a new entity, with this entity as the parent. It can take two parameters: name and state.

Attribute	Required?	Type	Description
name	Yes	String	The name of the entity to spawn.
state	No	String	Tells the spawned entity in what state to begin. Defaults to the Start state.

Specifying the state attribute is useful for single entities with multiple configurations, such as the metal blade flying in different directions.

Additionally, the Spawn tag can contain X and Y tags within it, which function exactly like the initialization tags for the Position Component. They will adjust the starting position of the spawned entity.

###Trigger

You'll find most of the information you need on the Triggers page.

You will also notice that triggers contain effects, which are basically functions. So yes, you could nest them if you want. But I've never run into any situation where you would want to do that.

###Component Commands

You can insert any commands that would affect a component here as well, such as collision and movement. Just remember they still need to be wrapped with the name of the component, with the exception of sound effects, which only require a Sound tag to use.

###Func

The Func tag is confusingly named, but its purpose is to call an actual function within the engine itself. These are useful for performing more complex, specific tasks. The only engine functions you can call are those within an entity component.

While these tasks could easily have been written to use an XML tag like everything else, there's a good reason they are this way: the available methods match exactly the ones that can be used in a trigger condition. So if you're going to access them there, you might as well use them here too.

See the Available Engine Methods page for the full list.

An example:

<Func>Health.Add(20)</Func>

Simple, right?

##Usage

To add to the confusion described above, the tag for executing your XML functions is Call. It has no attributes, and takes your function's name as its content:

<Death>
    <Call>EnemyDeath</Call>
</Death>

This particular example is used in enemies, who all act the same way when they die. "EnemyDeath" is the function given at the top of this page. The Death tag is described on the Entity page.