Arma 3: Time Trials

From Bohemia Interactive Community
Revision as of 13:24, 29 October 2020 by DnA (talk | contribs) (First part - WIP)
Jump to navigation Jump to search

SideTOC Cfg ref

This guide will describe how to design and implement a custom Time Trial Challenge as available in the vanilla game.

See also:



  • Time Trial (TT) - a simple vehicle race against the clock
  • Competitor - the actor running the trial
  • Marshal - the actor observing the trial and providing feedback / guidance
  • Checkpoint (CP) - a navigation point within a course which a competitor must follow in a fixed sequence (1 consecutive CP may be skipped for a time penalty)
    • The first CP is the start.
    • The last CP is the finish.
  • Time - the time from the start it takes to complete a trial (raw)
    • Time penalties are added to arrive at the final time.
    • The fastest / lowest time is the best and wins.
    • There are bronze, silver and gold medal times to beat.
    • There may be one special time to beat (must be faster than gold).


At time of writing it is not possible to add new Time Trials as independent (Workshop) scenarios; they need to be added as 'mods' with configuration. We do hope to allow this in update 2.02.
  1. Open Eden Editor with the terrain of your choice loaded.
  2. Insert a player character named BIS_TT_Competitor // Fixed system name
  3. Now is a good time to save your scenario a first time. Use a name that is safe to reference as config class, so no spaces - f.e. MyFirstTimeTrial // Referenced later
  4. TODO: insert vehicle
  5. Insert a NPC Marshal character of type TODO named BIS_rangeOfficer // Fixed system name / place in a separate group
  6. Insert a Time Trial module
    1. It's not exposed in Eden Editor, so place any other module. We may change this after this documentation is completed.
    2. Save the scenario (be sure binarization is disabled via the checkbox or preferences).
    3. Close Eden Editor to avoid auto-saves.
    4. Open the scenario SQM file in a text editor.
    5. Replace the module's class by ModuleTimeTrial_F.
    6. Save the SQM.
    7. Re-open the scenario in Eden Editor.
  7. Insert an ellipse trigger with default properties named f.e. BIS_TT // Referenced later
    1. Re-size the trigger to encompass your entire trial and a little extra buffer area (you'll likely re-size it later as you progress).
  8. For each CP (including start and finish), insert a trigger with default properties named f.e. BIS_TT_CP1 // Referenced later
    1. Re-size the trigger to meet your CP activation expectations.
  9. Set up trial properties via description.ext (see below).
  10. Configure your drill via CfgTimeTrials and CfgMissions (see below).

Common Additions




#include "\A3\Missions_F_Kart\Challenges\description.hpp" // This will set up various system default settings, such as custom debriefings

onLoadName = "TT: My First Trial"; // Name of your trial (normally the same as defined in CfgMissions)
onLoadMission = "Can you beat my splendid trial?!"; // Overview text of your trial (normally the same as defined in CfgMissions)
loadScreen = "myfirsttimetrial_overview_CO.paa"; // Overview picture of your trial (normally the same as defined in CfgMissions)
briefingName = "TT: My First Trial"; // Same name as above
overviewPicture = "myfirsttimetrial_overview_CO.paa"; // Same picture as above
overviewText = "Can you beat my splendid trial?!"; // Same text as above
//author = "Marshal Henk"; // You! < this cannot work in the current version due to duplicate definition; fix coming in 2.02

doneKeys[] = {"MyFirstTimeTrial_done"}; // Registers having completed (achieved gold or special) your trial



class CfgTimeTrials
	class MyFirstTimeTrial // This class name must correspond to the missionName(Source) (also CfgMissions class)
		displayName = "TT: My First Trial"; // Vanilla trials use a format like this, but it's not enforced
		// This color is used in many places
		// It can be any color, but for best results pick a fully supported color (see section below)
		color[] = {__EVAL(240/255), __EVAL(130/255), __EVAL(49/255), 1};
		colorName = "orange"; // This version of the color is more restrictive and can only use specific supported colors (see section below)
		objectTT = "BIS_TT"; // The trial area trigger referenced in the setup guide
		looped = 1; // Whether the trial will loop when crossing the finish CP (undefined uses 0 - point-to-point race)
		noDefaultGPS = 1; // Disables showing of the mini-map GPS (undefined uses 0 - showing)
		//statistic = ""; // Steam stats are not supported for user-generated trials (used for Achievements)
		//leaderboard = ""; // Steam Leaderboards are not supported for user-generated trials
		onReset = "reset.sqf"; // This script is executed each time the trial resets (restarts)
		// List any number of objects that you want to be re-colored to the trial color above (f.e. road cones, small flags, etc.)
		recolor[] = 

		// Set up objects that should have special decal textures applied (this was more useful before Eden Editor - see vanilla decals below)
		// This is not used a lot in vanilla trials
		decals[] =
			{ "BIS_TT_decal1", "A3\Missions_F_Beta\data\img\decals\decal_watch_out2_ca", 5 } // Object reference, texture path, hidden selection index

		// Object references to the 2 special targets for drill mechanics, as defined in the setup guide
		restartSelectors[] = {"BIS_TT_restartSelector1"};
		quitSelectors[] = {"BIS_TT_quitSelector1"};
		timesMedals[] = { 60, 45, 30 }; // Bronze, silver, gold medal times (be sure to follow this order or results may glitch)
		timeSpecial = 15; // Optional special time that is faster than gold (when defining this, you do need to also provide the data below)
		nameSpecial = "Nemesis"; // Optional special time label for the HUD
		colorSpecial = "#ffa500"; // Optional special time color for the HUD
		iconSpecial = "\A3\Ui_f\data\GUI\Cfg\Ranks\colonel_gs"; // Optional special time icon for the HUD
		// Legacy class used before Eden Editor to load precise object compositions (should not be needed anymore)
		// class DynOs 
		// {
		//		script = "dyno_myfirsttimetrial.sqf"; // Valid DynO mapper output script
		//		positionAnchor[] = {500, 500}; // DynO mapper anchor position in the world
		// }; 
		// All of the trials's CPs
		class CheckPoints 
			class CP1 // Start
				object = "BIS_TT_CP1"; // The CP trigger referenced in the setup guide
			class CP2 // CP #1
				object = "BIS_TT_CP2";
			class CP3 // CP #2
				object = "BIS_TT_CP3";
			class CP4 // Finish
				object = "BIS_TT_CP4";





Run-Time Tools



Please see the Firing Drills documentation for this information.


Please see the Firing Drills documentation for this information.


  • Balancing a trial can be quite hard, since there is a broad range of skills in the playerbase.
    • You should set appropriate medal times.
    • It's recommended to start harder / more difficult, rather than too easy. It's better to nerf later than to go the other way (since you cannot easily undo recorded times).
    • Start by simply playtesting the trial a lot and determining your own best medal times (or invite other playtesters and record their runs / times - video recordings can also be helpful for spotting issues).
      • Real balancing typically starts towards the end of development, because even slight changes can affect times a lot, let alone adding / removing CPs.
    • Vanilla trials apply the following abstract goals per medal:
      • Bronze: achievable by doing a clean race (perhaps 1 small collision) but not taking many risks. For a typical user it should take 1-3 attempts.
      • Silver: achievable by doing a clean race and taking some risks (using maximum acceleration and cutting some corners). Might take 2-5 attempts for example.
      • Gold: meant to be hard. This needs to be a perfectly clean race, at full speed and taking risks. It may take more than 5 attempts.
      • Special: designed to be extremely hard. Some may never beat this.