Arma 3 Scripting

Arma 3: Time Trials

  • Also known as Arma 3 Time Trials

Topic · Markdown · JSON · original wiki page

This guide describes how to design and implement a custom Time Trial Challenge (similar to those available in the vanilla game).

See also:

Terminology

Setup

  1. Open the Eden Editor with the terrain of your choice loaded.

  2. Place a player character named BIS_TT_Competitor (this is a fixed system name).

  3. Save the scenario with a name that is safe to reference as a config class (i.e. no spaces) - for example MyFirstTimeTrial.

  4. Place an empty vehicle named BIS_TT_Vehicle (this is a fixed system name; not all types of vehicles have been tested, but cars, helicopters and tanks should work).

  5. If the competitor character is not placed inside the vehicle from the start, ensure that this is done upon trial start, for example via competitor init: this moveInDriver BIS_TT_Vehicle;.

  6. Place a unit of type C_Marshal_F named BIS_rangeOfficer (this is a fixed system name; place the unit in a separate group and at a reasonable distance in order to see the starter pistol firing). Enter the following in BIS_rangeOfficer's init field:

    this disableAI "ANIM";
BIS_TT_handle = this spawn {
    waitUntil {time > 0};
    _this switchMove "Acts_starterPistol_loop";
};

  7. Place a Time Trial module (ModuleTimeTrial_F).

  8. Insert an ellipse trigger with default properties named BIS_TT (this will be referenced later). Resize the trigger to encompass the entire trial and a little extra buffer area (make sure to resize it later as the scenario grows).

  9. Place a Target - Oval (Ground) prop.

    1. Save the scenario (ensure binarization is disabled).
    2. Close the Eden Editor to avoid auto-saves.
    3. Open the scenario's SQM file in a text editor.
    4. Replace the target's class with Land_Target_Oval_NoPop_F (all targets need to use the hidden NoPop variant).
    5. Save the SQM.
    6. Reopen the scenario in the Eden Editor.
    7. Position the target near the finish CP (so that it is visible and accessible to drive to after finishing).
    8. Enter the following in the target's Texture #0 field: A3\modules_f_beta\data\FiringDrills\restart_orange_ca (other colors have corresponding textures - see Colors).

  10. Place a trigger with default properties named BIS_TT_restartSelector1 (this will be referenced later). Resize and orient the trigger so that it encompasses the target from the step above and forms a suitable parking spot for BIS_TT_Vehicle.

  11. Copy and paste the restart target.

    1. Position it near the first target, typically to the right of it (but spaced to comfortably allow BIS_TT_Vehicle to access both).
    2. Enter the following in the target's Texture #0 field: A3\modules_f_beta\data\FiringDrills\quit_ca (this is a fixed texture no matter the drill color).

  12. Place a trigger with default properties named BIS_TT_quitSelector1 (this will be referenced later). Resize and orient the trigger so that it encompasses the target from the step above and forms a suitable parking spot for BIS_TT_Vehicle.

  13. For each CP (including start and finish), insert a trigger with default properties named BIS_TT_CP1 (this will be referenced later; remember to adjust the index at the end of the name).

    • Resizing the trigger does not influence actual CP detection (unlike in Firing Drills), but it can still be resized as a visual aid (see radius configuration below - default 5 meters).
    • It is important to orient most CPs well to determine the valid entry angles (i.e. by rotating it in the direction of the next CP with ⇧ Shift + Left Mouse Button).
    • Alternatively, 3D helpers can be used as CP objects (circles are commonly used for aerial trials).

  15. Note

    BIS_TT_Vehicle needs to start inside BIS_TT_CP1 in order for the time trial to work properly.

  16. Set up trial properties via description.ext (see Configuration).

  17. Configure the trial via description.ext or via CfgTimeTrials and CfgMissions (see Configuration).

Drones

A few adjustments are necessary to make a drone trial:

  1. Place a non-empty (i.e. AI-crewed) drone and name it BIS_TT_Vehicle as above.

  2. Place a fake player competitor character who is supposedly controlling the drone. Do not name this (or any other) character BIS_TT_Competitor!

  3. In the trial's init script, execute:

    enableTeamSwitch false;
BIS_TT_Competitor = driver BIS_TT_Vehicle;
selectPlayer BIS_TT_Competitor;

Common Additions

Configuration

description.ext

#include "\A3\Missions_F_Kart\Challenges\description_custom.inc" // 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!

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

Note

Not all properties in this sample config are needed for every trial; they are included to showcase all options.

// This primary trial configuration can also be implemented via a mod config, but doing so via description.ext is simplest in most cases.}}
class CfgTimeTrials
{
    // When using description.ext, the name of this class does not matter much (the system selects the first class)
    // When using a mod config, this class name must correspond to the missionName(Source) (also CfgMissions class)
    class MyFirstTimeTrial
    {
        displayName = "TT: My First Trial"; // Vanilla trials use a format like this, but it is 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[] =
        {
            "BIS_TT_recolor1",
            "BIS_TT_recolor2"
        };

        // 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
            {
                // The CP trigger referenced in the setup guide
                // Note that TT CPs don't use these actual triggers for CP detection; they are only used as reference (unlike in Firing Drills)
                object = "BIS_TT_CP1";
            };
            class CP2 // CP #1
            {
                object = "BIS_TT_CP2";
                penaltyMissed = 200; // Increasing the default penalty for skipping this CP to 20 seconds
            };
            class CP3 // CP #2
            {
                object = "BIS_TT_CP3";
                radius = 20; // Forces a non-default CP radius in meters (undefined uses 5)
                height = 300.5; // Only use this ASL forced height for CPs above ground, such as for aerial vehicles
                onActivate = "CP3_onActivate.sqf"; // Script executed when this CP is activated (passed [CP object])
                onDeactivate = "CP3_onDeactivate.sqf"; // Script executed when this CP is deactivated (passed [CP object])
                onClear = "CP3_onClear.sqf"; // Script executed when this CP is cleared (passed [CP object])
                // Especially aerial trials sometimes need artificial helper objects to visualize a CP in the world
                // These object references are shown / hidden when the CP is active
                // Typically use 3D helper objects, such as spheres
                helpers[] = {"BIS_TT_CP3_Helper1", "BIS_TT_CP3_Helper2", "BIS_TT_CP3_Helper3", "BIS_TT_CP3_Helper4"};
            };
            class CP4 // CP #3
            {
                object = "BIS_TT_CP4";
                omnidirectional = 1; // This CP may be entered from any angle (undefined uses 0 - only allowing entry from the correct side)
                onGround = 1; // This CP requires the vehicle to be on the ground / landed (undefined uses 0 - no ground contact needed)
                timeout = 3; // This CP requires the vehicle to meet the CP conditions for 3 seconds
            };
            class CP5 // CP #4
            {
                object = "BIS_TT_CP5";
                slingLoadLoad = 1; // This CP requires the vehicle to have an externally slung load attached
                slingLoadObject = "BIS_TT_SL1"; // Object reference for the specific object that must be slung
            };
            // Finish
            // Even for a looped trial, the Start and Finish are separate CPs!
            class CP6
            {
                object = "BIS_TT_CP6";
            };
        };
    };
};

CfgMissions

Note

This is only needed for trials configured via mod config (not via description.ext).

class CfgMissions
{
    // This will expose the trial in the SINGLEPLAYER > CHALLENGES > Time Trials menu
    class Challenges
    {
        class Time_Trials
        {
            class MyFirstFiringDrill // This class should correspond to the class in CfgTimeTrials above
            {
                directory = "myfirsttimetrial.stratis"; // Full path to your trial's scenario folder
                briefingName = "TT: My First Trial"; // Name of your trial (normally the same as defined in CfgTimeTrials)
                overviewText = "Can you beat my splendid trial?!"; // Overview text of your trial (idem)
                overviewPicture = "myfirsttimetrial_overview_CO.paa"; // Overview picture of your trial (idem)
                overviewScript = "\A3\Modules_F_Beta\FiringDrills\scripts\overviewScript.sqf"; // Standard system script to handle the pause menu properly - don't change
                author = "Marshal Henk"; // You!
            };

            // Alternatively you can list your trial in one of the vanilla theme categories: Karts, Helicopters, IDAP, Tanks
            // class Karts
            // {
            //         Define your trial here instead for example
            // };
    };
};

CfgTimeTrials

Important

The system-level configuration could be adjusted by a mod, but consider if that is not going to confuse players who may be trained on vanilla trials.

class CfgTimeTrials
{
    // Below point bonuses and penalties are multiplied by this factor to determine time bonuses and penalties
    pointTimeMultiplier = 0.1;

    penaltyMissed = 100; // Pentalty for missing / skipping a CP (so this is 10 seconds)

    // HUD icons for the medal times
    iconsMedals[] =
    {
        "A3\modules_f_beta\data\FiringDrills\medal_bronze_ca", // Bronze
        "A3\modules_f_beta\data\FiringDrills\medal_silver_ca", // Silver
        "A3\modules_f_beta\data\FiringDrills\medal_gold_ca" // Gold
    };
    // HUD colors for the medal times
    colorsMedals[] =
    {
        "#A0522D", // Bronze
        "#C0C0C0", // Silver
        "#FFD700" // Gold
    };

    // Music tracks used in the TT 'jukebox'
    music[] =
    {
        "BackgroundTrack01_F",
        "BackgroundTrack01_F_EPB",
        "BackgroundTrack01_F_EPC",
        "BackgroundTrack02_F_EPC",
        "BackgroundTrack03_F",
        "BackgroundTrack04_F_EPC"
    };
};

Steam Workshop

When a trial is self-contained (i.e. configured via description.ext), it can be published to Steam Workshop as Scenario. When players subscribe to such trial, it will be listed in their CHALLENGES menu.

Run-Time Tools

Note

Some things are exposed and possible to change or use run-time, f.e. to make special unlocks or events happen.

Colors

Please see the Firing Drills documentation for this information.

Decals

Please see the Firing Drills documentation for this information.

Tips