Events

There are a lot of different types of events. Today we will only explain OnEvent and OnOneTimeEvent.

OnEvent

An "OnEvent" executes its actions every time when its conditions block is true. As events are checked 10 times a second, this could mean that an event is executed 10times a second if the conditions block stays "true" the
whole time (which would lead to the problem that no other events of the same script are executed and that the whole game might be dragged down). So the conditions block of an OnEvent must be written in a way, that it is not permanently true.

OnEvent

OnOneTimeEvent

An "OnOneTimeEvent" is an "OnEvent" that is executed only one single time.
There is a hidden flag attached to that event, that is checked in the conditions block and set true when executed for the first time. For security reasons you normally should use "OnOneTimeEvent". Only if you need an event being executed several times you should use an "OnEvent".

OnRespawnEvent

IMPORTANT: This event is only working in the scripts of units (Entity Scripts). It doesn't work in the platform script.
When a creature appears in the game out of nowhere, we call this "spawning".
When a creature was killed and later re-appears again, we call this "respawning".
Units do no longer execute their scripts when they are killed. This is true - but there are exceptions:

The "OnRespawnEvent", and the "OnDeadEvent".
If a unit was killed, it keeps on checking the conditions of its respawn event - but only if this respawn event is in the state the unit was in when it was killed.
If the conditions of the respawn event become true, the unit re-appears again in the game (with full health and mana). There are additional parameters like TargetTag and RespawnDelay.

OnRespawn

If you want that a unit is not on the map right from the beginning, but that it only will appear as soon as some conditions are true, then use the parameter "StartDespawned = true": The unit will spawn only when the conditions are true.

OnRespawn

Well ... at least this is how it seems to the player. Technically, things are a little bit different: Technically when the map starts, the unit appears - but is killed in the first frame. So you don't notice the unit was there.
Please also note, that as long as the unit was not spawned, it is seen as "dead" by the script. If you do a "SquadIsDead" condition on this unit, and the unit did not spawn yet, you will receive a "true" answer.

OnDeadEvent

IMPORTANT: This event is only working in the scripts of units (Entity Scripts). It doesn't work in the platform script.
This event is only executed if and when:

• the unit dies in the State that contains the DeadEvent
• there is a RespawnEvent in that state
• the conditions of the DeadEvent are TRUE

OnDeadEvent

OnIdleGoHomeEvent

If units are not in range of a hostile unit which would draw them into combat and also do not have any task to fulfil (like a "goto" command), for code they are "idle".
The event "OnIdleGoHome" send units that are idle back to their homepoint (as long as the condition block delivers TRUE).
The homepoint is defined by the TargetTag. If this Event is called in an entity-script, the "Tag" parameter can be left out: it automatically gets the name of the entity, to which the script belongs.
Please note: The "OnIdleGoHome" does not mean that the unit won't run to an enemy when it sees one. It just means that the unit will come back to its homepoint after it killed the enemy.

OnIdleGoHome

Why is this useful?

This is a way to control where a unit is.

If you don't have it, a unit can be dragged away by enemies. For example: Unit sees an enemy, runs to it, kills it, sees the next enemy, kills it, sees the next enemy ... and so is dragged over the whole map. If you don't have it, a unit just could be moved from its place by swapping it away. You could swap it over nearly the whole map.

So if you want the orc always to stay near its home (as long as the orc is not in combat), use the "OnIdleGoHome" command.

The unit will try to go to its homepoint, as long as

• the conditions of the event are true.

• the unit is idle.

• it is not at its homepoint.

OnIdleGoHOme

In this example the unit 'Soulguard' will return to its homepoint 'SoulMarker' if it is idle and further away than 8 meters.
More parameters: HomeActions / OneTimeHomeActions.
Every time the unit returns to its homepoint by executing OnIdleGoHome, it executes its HomeActions.
This is a thing to remember (because it gets easily forgotten and can lead to bugs): Even if an unit with an OnIdleGoHome is only swapped away for one gridpoint and then returns to its homepoint, these actions are executed.
If you want actions that are only executed one single time, you should use OneTimeHomeActions: These actions are only executed, when the unit comes to the point for the very first time.

OnIdleGoHome

OnToggleEvent

Toggle events are another type of event.
This event can be "on" or "off" and can toggle between those two phases.
So it has not only one condition block and one action block, but two: it has an OnConditions-Block and an OffConditions-Block, and it has an OnActions-Block and an OffActions-Block.
From the beginning the event is "off".
If the event is "off", it only checks the conditions of the OnConditions-Block. If this condition block gets true, it executes the OnActions and turns "on".
If the event is "on", it only checks the conditions of the OffConditions-Block. If this condition block gets true, it executes the OffActions and turns "off".

OnToggleEvent

In this example a mission outcry is triggered everytime an enemy unit comes into range of 35 meters to the player's 'Monument1'.
Hint: Complementary condition blocks.
Very often scripters want the OnConditions-Block and the OffConditionsBlock to be logically completely complementary (which has a lot of advantages). Sometimes if an condition block is very complex, it seems hard to find the complementary conditions. In fact it's really easy to find them: You just have to negate the boolean operator on the top level.
Let's look at two examples:

OnToggleEvent

Let's look at a more complex example:

OnToggleEvent

So how can we find the logically complementary conditions block to that monster? It's easy: The boolean operator on top level is an OR. So you just copy the whole condition block and transform OR into NotOR:

OnToggleEvent

Hint: Empty action blocks.
Scripters seem to often restrict themselves to use OnToggleEvents only if they have actions to be executed in "Off" and "On". But there's also the possibility that you leave one of the action blocks empty. Why could that be useful?

Let's look at an example:

OnToggleEvent

As you can notice, the OffActions block is empty.
What does the event do? It increases a counter every time, the unit "Goblin" comes into a range 5 meters to the position 'MyHome'. But due to the toggle event, it does not permanently increase this counter when the "Goblin" stays within this range. The counter is only increased, when the "Goblin" leaves the range (so the event toggles from "on" to "off") and then re-enters the range again (so the event toggles from "off" to "on").

OnIntervalEvent

An example of IntervalEvent:

    OnIntervalEvent
    {
        Seconds = 5,
        Conditions =
        {
        },
        Actions =
        {
            AbilitySpawn{TargetTag = "crash", Team = "tm_feu", AbilityId = 2266},
        },
    };

That IntervalEvent will spawn a meteorite every 5 seconds.

back.