Take On Mars

Take On Mars

31 ratings
Scenario creating II: Triggers and Events
By dariusz1983
Scenario Creating Part 2

! NOTICE !
This guide is beeing reworked right now. I work on it everytime I have some time on my hands but usually daily for a couple of hours. During this time it is possible some content might feel out of place or other be entirely missing. If you have any questions, post it in the comments, on the forums, or write me a DM and I will get to you fairly quickly.

Triggers and events may be a rather boring topic, but they are what makes scenarios exciting. Sure, an ascend vehicle that actually ascends is awesome, but something has to "trigger" that sort of behaviour. This guide will show you all you need to know about triggers and events, how to use them and explain the pitfalls especially when dealing with the scenario editor.

This modding guide is the second in a series of guides trying to show you guys and gals how to make cool scenarios. I have spent some quality time going through the code and the config files, experimenting etc. and have found some really fun stuff for everyone to try out.

The guide series:
  1. Starting in a landing vehicle
  2. Triggers and Events (this guide)
  3. Displaying messages to the player
  4. Data Pad guide (how to create your own data pad)
  5. Supply Drop with custom goodies.
  6. Mission Objectives

If there's anything you guys would like to see, let me know in the comments. I am going to create a scenario that actually uses all of the mentioned "features" and upload it as a reference.
   
Award
Favorite
Favorited
Unfavorite
Introduction
Making your scenario more engaging and thus interesting all hinges on how dynamic it is. How your scenario reacts to what the player does.

In almost all games this is accomplished by using triggers and events. In Take On Mars, an event can be anything, a sound you hear, an explosion, the weather suddenly changing for the worse, a supply drop appearing above your head, roaring while it splits apart to land the seperate units, hell, it could be even your characters death or a game over.

As the name suggests, such events must be triggered first. Hence triggers and events.

I will talk briefly about triggers first, you won't be able to do anything with that information alone, there won't be any example scenarios for that, simply because a trigger without an event is fairly useless. Only combined they have the power to do cool things...OK, that's a lie. You could, in theory, use them stand alone in a mission script, but that is some advanced stuff I'd rather talk about in Guide VI: Mission Objectives, when we talk about mission objectives. However, I will show you a little example of this in Appendix A: Trigger without events.

After we had a talk about triggers, we'll focus on events, what types there are, how you place and use them, including example scenarios for you to play with, some code (there will be scripting I'm afraid), but I'll provide you with the files you need to get started and explanations where to put what.
Triggers
In a nutshell, a trigger is a mechanism to tell the game when to do something, where as an event is telling the game what to do.
You create the triggers and events in the scenario editor. Afterwards you link them together, but don't worry, I will tell you in detail how to do that (in the event chapter of this guide).

As you can see in the screenshot above, triggers are big cylinders and events are small cubes. A trigger "triggering" an event is linked to it with an arrow. You can also see that the left hand trigger is linked to the player character.

Every trigger can be linked up with several other objects. Those have to be events, vehicles (that also includes player characters), projectiles, ragdolls (cables etc.) or dynamic objects. The maximum amount of linked objects is 16.

There are two reason to link up objects with trigges. A trigger linked to event objects will "execute" those events. A trigger linked to vehicles, characters, ragdolls, projectiles or dynamic objects, will only trigger when set off by one of those objects. The exact mechanics of what happens when a trigger is triggered will be discussed in a moment.

You can link several triggers to the same objects, events etc. There's no restriction, other then the maximum amount of links being 16 (per trigger). That means that if you link a trigger with 6 events, you have 10 links left for other objects like player characters, vehicles, etc.

There are three types of triggers, OnEnter, OnExit and OnStart. Each with it's own mechanics that I will tell you about now:

Trigger_OnStart
The On (scenario) Start trigger goes off the moment the scenario starts. There's no need to link it up with other objects. That information will be ignored entirely, since the game itself triggers them at mission/scenario start.

So if you want to show the player some sort of a greeting or a message the moment the game begins, thats the way to go:


When you place this trigger in the scenario editor, you don't need to pay attention to its position or size, since those are only relevant to the other two trigger types. That shouldn't mean you can hide it somewhere you'll never look again.

One thing of note, this trigger will always "fire" on mission start. It doesn't matter if you set the Trigger Once Only option or not. It will always fire when a scenario starts. Bear that in mind when designing your mission and your mission script.

In detail
This section explains in detail (code level) how a trigger works.

First thing this trigger will do once triggered is to go through all it's linked objects, and trigger all events it is attached to, then, regardless of any event connections, this trigger will also broadcast an universal event OnEvent. It is defined as:
OnEvent( string event, _entity caller )

Here, the event name is "Trigger_OnStart", and the caller is the trigger object itself, being a Trigger_OnStart object. Both, the mission module/mission script and the multiplayer gememode object will be notified of this.

Listening to those events is the way I told you about, how to use triggers without events attached to them. See Appendix A: Trigger without events for an example.
Trigger_OnEnter
The On Enter trigger goes off when a valid entity enters its area of influence. This area is set up in the editor via the radius and the altitude (or rather height) parameter:


If the option "Trigger by Vehicle" is true, everything in the game that's a vehicle will trigger it. That means the player aswell as 'actual' vehicles. The other options basically filter what can trigger it. Imagine if you wish an alarm to sound when someone is shooting at your base in multiplayer. Place an OnEner trigger arond it, set all object filters to FALSE except for projectiles, and link it up with the right event. That's it. The next time a projectile (bullet of some sorts in future upcomming combat addons) enters the trigger, your event will be triggered.

One important thing, if a trigger is set up to trigger only once (Trigger Once Only: TRUE) and you set off the trigger and than save, it won't trigger ever again, even if you load up the scenario again. That's what the RESET button is for. During normal gameplay, that's OK, but it can also happen when you test play your scenario in the editor itself. If you hit play, trigger your "one time" trigger, press pause and save the scenario, that trigger becomes dead weight. To avoid this, click the RESET button and save your scenario to be sure:



The last point I'd like to mention on triggers is that if you want a trigger to be triggered by the player and only the player, you have to link it with the trigger aswell. Here's a editor setup that shows what I mean:


The intention is to show a message when the player aproaches the buggy. Sadly, this won't work, since the trigger activates instantly because it is being triggered by the buggy itself. To avoid that, you have to link the player character to the trigger, just as you would wit an event. Now, the trigger will only activate when the player enters.

To link a trigger ot an object, select the trigger, select the desired object (with SHIFT held) and press CTRL+L on your keyboard. The connection arrow won't show immediately, save the scenario, and it will appear.

In detail
This section explains in detail (code level) how a trigger works.

The trigger is set up to check every 0.25 seconds if it's conditions are met. First, it looks if it is linked with objects, that aren't events, like vehicles, projectiles or dynamic objects. If yes it will go through all of them to check if they are in the zone. Afterwards the check is complete, nothing else will be done. Everytime one of these special objects is determined to be inside the trigger, a special universal event will be broadcasted, namely the OnEntityWithEntity event. The mission module/mission script aswell as the multiplayer game mode will recieve that event. It's parameters are:
OnEntityWithEntity( string event, _entity caller, _entity cocaller )
Param
Description
event
The name of the event
caller
The object to broadcast this event
cocaller
Additional object entity

Here, the event name is "Trigger_EntityInTrigger", the caller is the trigger object itself (class Trigger_OnStart) and the cocaller is the special linked entity that entered the trigger zone.

This happens for every linked object that is inside the trigger zone.

If there are no special objects, the trigger code goes through all entities in the world, looking specifically for vehicles, projectiles and dynamic objects, but only when it's supposed to (See the Trigger by options in the editor). It checks if one of them is inside the trigger. If yes, the same universal event as mentioned above, is broadcasted.

Here is the biggest difference though. If the trigger is set up to fire only once, the code will stop looking after it found one hit. Other wise it will go through all objects in the scene and check if they are in the zone, call the universal event etc. With special objects linked to the trigger, all of those linked objects will be checked, even if the trigger is set to fire only once.

After all that is done, irregardless if we have special objects linked or not, if at least one entity was inside the trigger, two things will happen. The first is that all linked events will be triggered, the second is that the trigger will send out another universal event, this time, the OnEvent event, which is defined as:
OnEvent( string event, _entity caller )

The name is here "Trigger_OnEnter", the caller the actual trigger object, beeing Trigger_OnEnter. Both the mission module/script and the multiplayer game mode object will be notified of this.

Afterwards, the trigger will enter a "lockdown" state that will inhibit it from sending out events etc. This state will be removed if all entities, that might trigger it, leave it's area of influence.

If the trigger is set to trigger only once, it's "tiime tick" of 0.25 seconds will be stopped, there won't be any further checks at all. If you save your game and reload it later, this state will persist. If the option "Trigger Once Only" is set to FALSE however, this entire process will be repeated again after 0.25 seconds.
Trigger_OnExit
The On Exit event is very similar to the On Enter event, except that it triggers when a valid object (as set in the properties) leaves the defined area.

All options etc. are equal to the OnEnter trigger, so there's no need to mention those. What you have to keep in mind is that the seconds nothing is in it's zone, it will trigger.

If the trigger is linked to special entities (vehicles, projectiles, etc.) all of them have to leave the zone in order for the trigger to fire. If there are no special entities linked, all of the allowed objects, according to the properties of the trigger as set in the scenario editor, must be outside the zone in order for the trigger to fire.

So if you place your OnExit trigger somewhere and empty in your world, the seconds your scenario begins, it will trigger.

Personally, I'd only use them to check if the player is leaving a certain area. You could span a massive OnExit trigger around your base and link it to the player. If the player leaves this area, you could give him a side mission (check Guide VI: Mission Objectives), or notifiy him about something. Same could be done to facilitate a game over check, if the player manages to fly away in the mav.

In detail
This section explains in detail (code level) how a trigger works.

The trigger is set up to check every 0.25 seconds if it's conditions are met. First, it looks if it is linked with objects, that aren't events, like vehicles, projectiles or dynamic objects. If yes it will go through all of them to check if they are in the zone. After the check is complete, nothing else will be done.

If there are no special objects, the trigger code goes through all entities in the world, looking specifically for vehicles, projectiles and dynamic objects, but only when it's supposed to (See the Trigger by options in the editor). It checks if one of them is inside the trigger. If yes, the tirgger will make note of that.

If nothing was found to be inside the trigger zone, the trigger will fire, but only if it hasn't fired before. That means. If the trigger fires, it won't again, otherwise it would send 4 trigger events every second. That would be insane. What happens is that it sets an internal value that prohibits it from triggering again, even if the conditions to do so are met. Only after a linked entity or an allowed object enters the triggers zone, will the trigger be ready to fire again...of course once that object leaves it's zone.

Should the trigger fire, it will do two things, it will go through all linked entities and "trigger" all event based objects, the FX, script or timer event. Afterwards it broadcasts an universal signal named:
OnEvent( string event, _entity caller )

The name is here "Trigger_OnExit", the caller the actual trigger object, beeing Trigger_OnExit. Both the mission module/script and the multiplayer game mode object will be notified of this.

If the trigger is set to trigger only once, it's "tiime tick" of 0.25 seconds will be stopped, there won't be any further checks at all. If you save your game and reload it later, this state will persist. If the option "Trigger Only Once" is set to FALSE however, this entire process will be repeated again after 0.25 seconds.
Events
There are three types of events, the FX event, the script event and the timer event.


Actually there is a fourth one. It exists as a mod I've created, it allows you to place a special event in the scenario editor and configure it. Once triggered it will automatically spawn a preconfigured supply drop (1 - 4 stack drop) that spawns contents once you open the hatch. To learn more, go to the Guide V: Supply Drops

You can get it here:
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=838629131




Linking triggers with events
Now, in order to have a trigger execute an event, we have to link it. We do that, by having both, the trigger and the event selected and hitting CTRL+L. This hotkey can be changed in the settings:


I will show you more detailed information on the various event types and how to use them in a bit
FX Event
The FX event is rather simple. When triggered it displays the defined special effect, which is a particle effect, aswell as a sound effect. That's all. There is no coding, nothing. Here's a video of such an event being triggered:

As you can see, nothing happens to the barrell. The FX event simply displays/plays a particle effect and plays a sound effect all in the location of the Event_FX box (the one you placed in the scenario editor). If you want something to happen to the barrell, you need scripting, which I will show you in the next chapter.

Event properties
Once you placed a FX event in your scenario, it will have a standard particle effect and sound already. That way you can quickly test it. It's nothing exciting, but it works straight away.


The particle effect path is the *.ptc file that defines the desired effect. You have to provide the filepath includeing the suffix .ptc. You can locate them in the extracted game data under particles. There's a lot of them, there's no guarantee that all of them found there will work. Some of them are left overs from Carrier Command: GM, some textures might be missing. You can try them out in the workbench. Not only that the workbench also allows you to invent your own, or change existing effects. For a complete list of particle effects that do work, check Appendix B: Particle effects

Now those effects are mute. You have to combine them with a sound, and that's what the second option is good for. You have to enter the sound shader name. The sounds can be found in the extracted game data (or any addons/mods that provide sounds) under sounds. Those include *.h script files that contain a special sound shader definition.

Here's an example of such a sound shader definition, located in the iss.h file
sound "effects/iss/iss_noise1" { "sounds/effects/iss/iss_noise1" type spatial volume 0.800000 range 480.000000 priority 100 minrange 32.000000 freqcontrol true }

I won't explain what all of those mean, what you have to know is that this "sound effect" is named "effects/iss/iss_noise1" and that would be what you have to enter in the property field of the FX event to hear that particular sound effect.

One thing is important to know, there are also music sound effects. Those are sound shaders that play a track on a loop. But you shouldn't use them as ambient music. Here's the deal with the FX event. The sound you hear is located where the event cube is placed in the scenario editor. You can't see it while playing the actual scenario. If you move away from the event position, the sound will grow weaker, you can also determine it's direction (provided you have stereo headphones etc.).

This is quite cool if you want explosions etc...with music it might be a little trickier. There are better ways to play an ambient track, I will show you in the Guide VI: Mission objectives.

Example scenario

This scenario showcases a couple of FX effects and you can have a look at the setup in the scenario editor:

https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=835510130

This is a funny scenario that shows off a very exciting special effect, made by the brilliant Mr. Monochrome [hood certified]. Check out his steam workshop, some exciting things there and surely more to come:
https://steamhost.cn/steamcommunity_com/profiles/76561197992339488/myworkshopfiles/?appid=244030

https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=822072989

You can find all the scenario links and some more in Appendix C: Scenarios.

In the code
When the FX event is triggered, even if it has no particle effect to display or sound to play, it will always broadcast an universal event:
OnEvent( string event, _entity caller )
Here event being "Event_OnTriggered" and caller being the event object itself (Event_FX). The mission script and the current multiplayer game mode object will be notified of this.
Script Event
Now onto the script event. The script event is placed just like the FX event, it's properties are even simpler, yet it is quite powerfull. You may ask yourself, what can I do with it? My asnwer would be: "It's easier to tell you what you couldn't do with it, gamewise, nothing.

The only parameter it knows is the script it invokes, or rather the file path to the script. The script's name is up to you, it doesn't matter. There are several locations you might want to put it. Since it is not a scenario file, you can't upload such an event script with it. You can publish it as an addon or mod. Where you put it is up to you. There are a couple vanilla event scripts that are beeing used in some rover related scenarios. The directory is scripts/entities/eventscripts. You could place your event scripts there.

Hint
The game's engine has access to several filepaths, I won't name all of them, just the important ones. We have the internal path where the actual game is (the folder with the TKOM.exe file), there we have configuration lists, the standard campaign scenarios etc. You could change stuff here, but you have no way of publishing it, so it's of no use to us.

The game data, which is stored in *.pak files, also located where the TKOM.exe file can be found. You access the files in the standard *.pak files like this:
scripts/entities/eventscript/renegade.h

You have only readonly access to the pak files, you can't add anything directly, unless you have a mod. What happens is that on access of the filepath above (renegade.h) the engine checks if a mod exists that provides that filepath.

When you create a mod in the "Addon" section of the game, a special mod folder will be created in your local userdata (See Guide I: Starting in a landing vehicle for more details). Inside this folder you'll find a structure identical to the one in the extracted gamedata. Well, that shouldn't be a surprise. A mod is supposed to modifiy existing stuff. If there's a standard file/script etc. you'd like to change, copy it in the same subdirectory in your mod folder, change it and you have yourself a mod. Browse into your modfolder (where you see subfolders like particles, scripts, etc.). This location can be considered the games root path. Meaning, if you have an event script in your mod in this location:
C:\Program Files\Steam\userdata\YOUR_STEAM_ID\244030\local\addonpacs\mymod\scripts\myeventscripts\myeventscript.h

The way to address it in the event script property window (the script's path) is:
scripts/myeventscripts/myeventscript.h

Just as if it was a vanilla event script or file.

If you create an addon instead, the generated folder structure will be slightly different. That way it is impossible to overwrite existing files etc. Which makes sense, considered the addon is supposed to "add" "on"-to something else and not modify it. You address those files in the same manner, except the path usually starts with:
data/scripts/myevents/eventscript.h

There's a third approach. This is one is not ment for publishing, but makes it easier to start and test your work. Everytime you create a new scenario in the editor, it will be placed in a special directory: $profile:addons/scenarios/. The $profile is a special placeholder that resolved to the your userdata folder path. In this $profile:addons path you can find other folders, like scripts. You can very well place your event scripts there (or any other path you chose, aslong as it's inside the $profile folder). To reference it in your scenario: (
$profile:addons/script/.../somepath/myscript.h
). And as said, you can't publish it this way. You can of course upload your scenario to steam, which will work fine, but your event script won't be uploaded with it.

From what you've heard so far this basically means that you have to create a mod or addon just to handle your scenario logic etc. You are right. You have to create an addon in order to "install" more then just your scenario file. Once you create your addon, move your scenario files (scenario.scn, scenario.jpg, ...) to your addon folder located in:
$profile:addonpacks/youraddon/data/scenarios
and your eventscripts to where ever you'd like to have them.

I'd like to offer another approach:
You can ship your scenarios with a scenario script file. It is named just like the scenario but with the suffix *.script. It is actually ment for a scenario mission script, which I will talk about in Guide VI: Mission objectives, but there's nothing holding you back from (ab)using it as an event script.

To utilize it in your event, type the "data/scenarios/myscenario.script" path in the script file property window in the scenario editor. That is of course if you have set it up as an addon. If you're still testing, and you placed your script file next to the scenario file (you just created the scenario, it's not in an addon yet), you have to use the same path that is written at the end of the scenario file, namely: "$profile:addons/scenarios/yourscenario.script".

I will give you a working example of this setup in the third Event Script demo scenario (below).

Now that we know where to put our script, we'll talk about what we can put in it.
Script Event Part 2
Script layout
When the script event object is being loaded by the game, the script is read. Three methods inside your event script have a special meaning, since they will be called by the game.

void InitScript (Event_Script eventScript)
This one gets called once each time your event script is beeing loaded by the engine, so basically one time only on scenario load. You can set up variables here, etc. You may leave it out, if there's nothing you'd like to prepare.

void ExecuteScript (Event_Script eventScript)
This method gets called every time your script is beeing "executed", or rather the event that is connected to the script. Here is the magic. Here you put the logic for your scenario or rather that event. A thing of note, all those methods have one parameter, the eventScript object itself. It is an object of the type Event_Script. You can use it's methods and internal variables, as well as of those classes, that Event_Script is derived from, here's a little inheritence chain:

Granted, you'd need programming skills in an object oriented language to fully grasp this. What I'm trying to say is, that you can retrieve the events ID (as given by the scenario editor) to check which of the events has been triggered. That way you only need one script for all your script events in the scene.

To get the ID for the script event, use:
GetID( eventScript );

next thing could be a switch that decides what to do with that call.

void EndScript (Event_Script eventScript)
This method gets called when the engine unloads the script. Clean up is in order here. But, for easy things, like what I show you in the example below, this one is empty as well. You can of course omit this method all together.

What happens here is that a trigger "triggers" the script event, which in turn calls the ExecuteScript() method in my event script. This is how I implemented it to make the barrel disappear and show the little game hint:
void ExecuteScript( Event_Script eventScript ) { TKOM_Entity barrel = GetTKOMEntityByID( 10000011 ); if( barrel ) delete barrel; g_Game.ShowHint( String( "Creepy" ), 8, true ); }


The ID 10000011 is the barrel ID as given by the editor:



I won't get into to much detail here, but for starters there are three main things to be done in event scripts. You could display a message to the player. There are many ways to do so, see Displaying messages to the player. You could spawn vehicles, for example the supply drop, see Supply Drop with custom goodies. or you could handle mission objective and mission related stuff, like check a win/fail condition and quit the scenario, see Guide VI: Mission Objectives for a detailed look into this.

That's all I'm going to tell you about the event script, please have a look at the tutorial/demo scenarios for this section. They include the example above plus some more. By the way, Appendix C: Scenarios contains all of the linked scenarios in one place and Appendix D: Script template contains a script template you can always use as a starting point.

Example scenarios

https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=835585983
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=836804500
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=837861814

Made by Mr. Monochrome:
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=821743616

In the code
When the script event is triggered, even if it has no configured script to execute, it will always broadcast an universal event:
OnEvent( string event, _entity caller )
Here event being "Event_OnTriggered" and caller being the event object itself (Event_Script). The mission script and the current multiplayer game mode object will be notified of this.
Timer Event
Let's talk about the timer event...or how I like to call it..."how to blow ♥♥♥♥ up".
The timer event is kind of an underdog. It's kind of obscure, but it packs a punch, let me tell you. We've seen an explosion placed onto a barrel and and event that makes the barrel disappear. Of course we could link both of those events to a trigger, giving us this:

But that is it. That's the limit of what can be done without timer events. Now a timer event defines a, well, timer, a countdown if you will. It can be zero, in which case it triggers right away, or any number of seconds (and fractions of seconds of course). We also have the ability to define a repition count. Zero means it happens only once, a repition count of one means the event will trigger repeatadly. Now, what will it trigger? That's the beauty of it. You can link other event objects (FX, script or other timers) to it. Thus creating a really dynamic scene. In order to link a timer event with another event, simply click on the timer event in the editor, hold shift while clicking the intended target event, and then hit CTRL+L (the hotkey can be changed in the game settings).

To sum up, a timer event, when triggered by a trigger, or another timer event, it will count down from the predefined time span. Then it goes through it's list of linked events and executed them, just like a trigger would.

And if you'd like an example of what can be done...here it is:
Imagine you enter an area with your buggy, this triggers two things, the sound of a distant howitzer firing and a timer event that counts down a couple of seconds and sets of a chain of timers that each create an explosion in front of you, simulating an artillery strike. How cool would that be...you know what...here it is, that's how my this setup looks in a scenario editor:
The trigger is activated by a vehicle, and triggers the first timer, which. after 2 seconds, triggers the first flak FX and the next timer, which in turn waits 0.35 seconds, triggers his flak FX and the next timer event, and so on and so on. The one responsible for the barrel triggers actually two events, the flak FX plus another timer, which after 0.2 seconds triggers the explosion FX and a script event that makes the barrel disappear.

I assume you won't believe me this works without evidence, fiiiine! ;)

Event properties
Setting up the timer event, you get two optioins:

[Add screenshot]

You have the Timer counter, that can have a value between 0 and 1000 and a Repeat value, which can have a value between -1 and 1000.

Timer value
This value tells the timer how long to wait before triggering all linked events. If the value is 0, the timer event will trigger all linked events in the first 50 milli seconds, so basically instantly.

Repeat value
If set to 0 (default) the timer event will count down the time set in the timer value, trigger all linked events and that's it. If set to a positive value (1,2,3,...,1000) it will repeat the countdown etc. up to as many times as you configured here. If the value however is set to -1 the timer event will be counting down indefinitely. Be carefull with this setting, especially if your timer value is very small.

Example scenarios

In the code
Now let's take a look at what happens in the code. You can skip this part if you don't care...but wave your hands accordingly.

When triggered, this event broadcasts the universal event:
OnEvent( string event, _entity caller )
where event is "Event_OnTriggered" and the caller is the timer event object itself.

It also sets up a tick, that will go off every 50 milliseconds. Each time in adds 50 millisecond to a variable that is being compared to with the set timer value. If the set value is reached (if timer value is 0 it happens instantly, or rather during the first 50ms), two things happen. All linked events will be triggered (whatever they are, the could be timer events themselves, FX events, scripts, etc.) and another universal event will be broadcasted, same as at the beginning but this time the event name is "EventTimer_OnTime".

If the repeat value is set to -1 the event timer will repeat indefinitely...hope you haven't set the timer value to 0, or you have yourself a spam machine and probably an FPS killer.

If the repeat value was set to 0, the event timer will remove it's tick timer, and stop running. It will have to be triggered again to repeat this procedure.

If the repeat value was positive, it will restart the setup countdown and do everything again, as many times as have been configured (max. 1000).
MOD: Supplydrop Event
This event allows you to spawn a landing supply drop with a custom loadout:

[h1]Event properties[/h1] The supply drop event has four properties. Those four properties are filepaths to a supply drop loadout config file. Where to find them etc. will be discussed in detail in Guide V: Custom Supply Drops. You can enter one to four paths. They can point to the same file or different files. The order in which you place them doesn't matter. You can leave the first one blank and provide a path for the third line. That's irrelevant. What is important how many paths you've entered. When the event is triggered it will spawn a 1, 2, 3 or 4 stack supply drop (depending on how many config paths you've provided). Once landed you can open their hatches and they will spawn the configured contents. Where to find those config files and how to make your own: Guide V: Custom Supply Drops. If you don't enter any paths, nothing will happen. There will be no supply drop (not even an empty one). The mod you need for this special event is here: https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=838629131 [h1]Example scenario[/h1] [h1]In the code[/h1] Similar to the other events, when triggered, this event will broadcast an universal event: [code]OnEvent( string event, _entity caller )[/code] where [b]event[/b] is "Event_OnTriggered" and the [b]caller[/b] is the timer event object itself. Then it will count how many paths have been entered. If that number is zero, nothing further will hapen. If not it will decide (depending on the number of paths) if to spawn the 1You place it like any other event. It can be triggered by any trigger (OnStart, OnEnter, OnExit) or a timer event. Similar to a FX event, it's placement is relevant. When this event is triggered it will spawn a landing supply drop that will land more or less (there's a random component to it) where you've placed the supply drop event.
Event properties
The supply drop event has four properties. Those four properties are filepaths to a supply drop loadout config file. Where to find them etc. will be discussed in detail in Guide V: Custom Supply Drops. You can enter one to four paths. They can point to the same file or different files. The order in which you place them doesn't matter. You can leave the first one blank and provide a path for the third line. That's irrelevant. What is important how many paths you've entered.When the event is triggered it will spawn a 1, 2, 3 or 4 stack supply drop (depending on how many config paths you've provided). Once landed you can open their hatches and they will spawn the configured contents. Where to find those config files and how to make your own: Guide V: Custom Supply Drops.If you don't enter any paths, nothing will happen. There will be no supply drop (not even an empty one).The mod you need for this special event is here:https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=838629131
Example scenario
In the code
Similar to the other events, when triggered, this event will broadcast an universal event:
OnEvent( string event, _entity caller )
where event is "Event_OnTriggered" and the caller is the timer event object itself.Then it will count how many paths have been entered. If that number is zero, nothing further will hapen. If not it will decide (depending on the number of paths) if to spawn the 1,2,3 or 4 stack supply drop. This vehicle will be spawned landing at the position of the event object itself (it's there in the scenario, even if you only see it in the editor). It's GENSTRING values will be set to the config filepaths, so that the supply drop vehicle controller script can spawn the right contents when you open the hatch.
Appendix A: Trigger without events
This section is ment for those who aren't afraid of some coding. Now I have told you that we need a trigge (OnStart, OnEnter, OnExit) to trigger an event and then have something happen. This is of course true but there's another way.

Every trigger (and every event if you have been paying attention) sends out universal event signals when triggered. A universal event is basically a method call to a special function in the scripts of the game that end up calling a special method in:
  • The mission module script, if you have one
  • The multiplayer game mode (when playing MP)

The latter case is only interesting if you're trying to make your own multiplayer game. We'll talk a little about the first case.

Since a not so recent update of the game, each scenario contains an entry line for a mission/scenario script. Each time a scenario is being started by a player the game looks for that file (as provided in the scenario file), loads it up, and tries to execute a certain method that creates your Mission script module. This module is suitable to handle objectives etc. and will be informed when certain things happen in the world. How to make one, what you can find out there etc. will be discussed in greated detail in Scenario Creating VI: Mission Objectives.

One of those things you get informed about in this mission script is: when a trigger fires. So you can setup triggers in your scenario, that aren't linked to any events. They of course can be linked to other objects (vehicles, player characters, ragdolls and projectiles). Even more so, now you can use the full amount of available links to link it up with up to 16 non event objects.

In your mission script you will get informed about a trigger firing and you can decide what to do next. Set a objective as complete, create a new objective, spawn stuff, finish the game, anything. A very simple example scenario will show you how it's done. Again, I will not explain what what is, that will all happen in Scenario Creating VI: Mission Objectives.

Example Scenario
Appendix B: Particle effects
A list of all particle effects
Appendix D: Script templates
Use this template to create your own event scripts. The Init() and the Exit() method is not mandatory. They can be deleted if not needed.

The comments can be omitted...but I strongly suggest you use them to make sure everyone else (including you yourself) knows what your script does.

/******************************************************************************* * \file scripttemplate.h * * \brief Executes an event script. * * \author * * \version ******************************************************************************/ /******************************************************************************* * \brief Is being called once when the script object is loaded. * * Happens when the scenario starts. * * \brief eventScript The Event_Script object that executes this script. *******************************************************************************/ void InitScript( Event_Script eventScript ) { // Can be omitted if not needed. Place one time initialisations here. } /******************************************************************************* * \brief Executes the event script. * * Is being called when the Event object is triggered. * * \brief eventScript The Event_Script object that executes this script. *******************************************************************************/ void ExecuteScript( Event_Script eventScript ) { g_Game.ShowHint( String( "My Script is working." ), 4, false ); } /******************************************************************************* * \brief Is being called once when the script object is deleted. * * Happens when the scenario ends. * * \brief eventScript The Event_Script object that executes this script. *******************************************************************************/ void EndScript( Event_Script eventScript ) { // Can be omitted if not needed. Clean up here. }
27 Comments
Kerry 29 Mar, 2019 @ 3:52pm 
Hey Dariusz1983, can we chat? I'm looking at setting up a multiplayer campaign using my DRASA scenarios but it's gonna require some serious event scripting.

Even the basics, like when the first scenario ends and the next begins, will need to be scripted in. The difficulty is in the duration (each mission is designed to last three weeks real time.)

Having a trigger that will cause the campaign to advance next scenario is one thing - but having it do so after such a long time is quite another.

Fortunately there's only two scenarios.
Ghostmooner 8 Dec, 2017 @ 3:10pm 
how do i make it so once i land in a lander, 5 minutes later my supply drops come??
Ghostmooner 8 Dec, 2017 @ 1:46pm 
how do u link stuff together??
Pepethecat 23 Apr, 2017 @ 12:05pm 
Hey do you mind making me a simple script that when the senario starts it shows on the center of the screen in big font a text like a title screen. (I want it to be triggerable with the event triggers) Thanks!
INFIDEL 17 Feb, 2017 @ 11:37am 
@dariusz - I discovered a possible redundancy in the way I implemented a supplydrop using an event script. I found an eventscript for flight spawning a supply drop and used it as a template. Within it, it specifies Genstrings for the spawning of contents. However, the vehicle config I selected already has Genstrings defined. During game play, the supplydrop works fine and contents spawn... but I'm curious where the Genstrings should be specified; in the eventscript or in the vehicle config... or does it not matter. I highly doubt they need to be specified in both locations and would like to remove any dead weight and potential conflicts (even though the game is apparently able to deal with the redundancy). Thanks
INFIDEL 17 Feb, 2017 @ 11:27am 
@Pepethecat - You do realize that this guide is being written by a community member and not the game studio. Even if it was written by the design studio, adding agitation to your questions and critisizing the guide is not a good way to get assistance. That being said, I'm happy to offer some assistance if you're are still having difficulty with implementation.
Pepethecat 21 Jan, 2017 @ 12:13pm 
I did, Guess I didnt read it in the right context.
dariusz1983  [author] 21 Jan, 2017 @ 12:11pm 
How about you read the whole thing? The path scripts/entities/eventscripts points to pak file (as explained in the guide). There is no full path pointing towards it.
Pepethecat 21 Jan, 2017 @ 12:03pm 
Can I get a full directory to put the event files. Instead of just a useless "scripts/entities/eventscripts"
dariusz1983  [author] 2 Jan, 2017 @ 11:41pm 
This guide will be reworked very soon, hopefully answering all your questions.