Skip to main content
Play With Game Pass
Buy Now
Contact Support
Play With Game Pass
Buy Now

Scripting for Crafted Maps

  • Updated

Overview

Scripting can be used to transform Crafted Maps into mission-like scenarios.

By adding or modifying a number of lines in the main "recipe" of a map's script, you can spawn units, define locations, and dictate AI behaviors. Through this method, units, locations, and objectives can be created and used as a base of a "mission" or similar custom scenario. Dialog lines can also be added around these objectives.

The power of these tools allows you to create almost any Age of Empire IV scenario you can think of.

This guide covers the basic structure of scripting in maps and how to work with them.

If you are looking for an example of a custom scenario created with scripting tools, you can open the Three Villages mission, accessible though the Wizard as a basic mission.

Advanced Mod Design

Implementing scripting elements on a map requires using LUA and can easily break the game or create fatal errors that will need to be debugged.

With the freedom LUA scripting brings, it also comes with opportunities to break everything. For this reason, using scripting in maps is recommend only for experienced mod creators.

Edit Scripts

The Edit Scripts function can be found along the top of the Scenario Tree.

This file is the main SCAR file you will use to create a mission.

Edit Script

Click here to add a basic script to your Crafted Map or to open your previously created SCAR file.

You can add other scar files by adding them from the Asset Explorer (choose Script and name it .scar).

Edit Events

The Edit Events function can be found along the top of the Scenario Tree.

The Events file (.events) is used to store all the dialog events or camera events you need around objectives.

Edit Event

Click here to add a basic Events file to your Crafted Map. It can also be used to open your previously created Events file.

Events File Functions

Events File Functions are used to initiate events.

The following is an example of the introductory event of the template mission.

The event name is defined EVENTS.TEMPLATEMISSION_Intro as a function and is called in the main SCAR file of the mission in the mission recipe.

  1. MUSIC_TENSE_COMBAT sets the music type at mission start.
  2. MissionOMatic_ShowTitleCard() presents a title card described in the main SCAR file to the player.
  3. CTRL.WAIT() is used to wait for the completion of the previous call before the script can go ahead.
  4. CTRL.Actor_PlaySpeech creates a speech line, pulling it from a string and playing it as a robo-voiced actor in the game. If desired, this can be replaced with a recorded speech line.

Events 1

Events 2

You can use this events file to add all the voice over lines you want to occur in the game (i.e. after an objective completes).

SCAR Markers

A SCAR Marker is one of the most important elements when scripting a scenario.

SCAR Markers are used to define locations, the spawning of units, squad movements, and AI behavior.

SCAR Markers can also be used to define objectives, events or direction of troops or even UI elements for those same objectives.
Scar Marker 1

Adding SCAR Markers

To create a SCAR marker, perform the following steps:

  1. Create a single folder to hold all your SCAR markers.
  2. Right-Click on the folder, click on +Add, and select Scar Marker.

 

Defining SCAR Markers

To define a SCAR marker, perform the following steps:

  1. In the Properties panel, give your Scar Marker a name and a type (what it will used for).
  2. This is for your reference so you can find the marker more easily and identify what it does.
    Scar Marker 2
  3. Add a Radius to your Scar Marker.
  4. Right-Click on the Scar Marker, click on +Add, and select Proximity Circle Component.
  5. In the Properties panel for your newly-created Proximity Circle Component, define the Radius.
    Scar Marker 3

Basic Script Functions

Importing Scar Files

At the top of the main scar file you want to import important scar files needed for your mission.

Scar Script 1

MissionOMatic.scar should always be included in a scenario mission as it is a library of functions

  • it contains modules that dictates Ai behaviors that were defined by campaign devs
  • it contains functions to define how objectives work in missions
  • it contains functions to define Locations and more...

Also, import here all your objective scar files you refer to in script.

Note: To see the content of a imported scar file, right click on the file path and click Open Document.

Scar Script 2

Default Functions Setup

There are a variety of default functions available for scripting scenarios.

These functions are described below.

Mission_SetupPlayers:

Allows you to define the number of "players" or armies in the mission in addition to the starting variables.

You can set the Starting Age of the armies and the Maximum Age they can reach during the mission.

This would prevent the player from seeing abilities or buildings beyond a certain age and will prevent the AI from going beyond that Age.

Mission 1

Mission_SetupVariables:

Allows you to define the variables you need throughout your script.

This includes:

  • Defining the egroups used to represent buildings or locations
  • Defining the sgroups used to represent units or gaia
  • Defining global variables needed for functions or states of the mission

Mission 2

Mission_SetRestrictions:

Allows you to add/remove all the players buildings or abilities restrictions

Mission 3

Mission_Preset():

Allows you to set the specific details before your mission starts:

  • Sets the player colors for each army
  • Place to initialize all the Objectives of the mission
  • Can be a good place to start Rules or even spawn units (which we can do in the recipe)

Mission 4

Mission_Start():

This function is triggered after the intro camera, if any, as control is given back to the player.

Here you can:

  • start your first objective
  • script the main content of the mission
  • Call functions defined in the script
  • start Rules...

Mission Start

GetRecipe() :

The recipe can let you setup:

  • the first event to start the mission
  • define all the locations of the mission
  • spawn units at locations and type of ai modules used
  • presentation aspect of the mission

Get Recipe 1

Get Recipe 2

 

Objectives

Objectives can be created to give directions to a story mission using a crafted map as a base.

There are several different types of objectives to choose from that have been set up with a variety of UI icons.

These objective types are listed below.

  • ObjectiveType_Capture: To be used when the player has to enter a defined location and kill all defending units and gain the whole area as a reward.
  • ObjectiveType_Optional: Used for optional objective doesnt need to be completed for mission to complete.
  • ObjectiveType_Battle: When an objective give direction to kill enemies or destroy a location or something.
  • ObjectiveType_Information: When you want to highlight something the player has to avoid or some tips about the mission.
  • ObjectiveType_Build: When an objective gives the direction for economic changes.
  • ObjectiveType_Primary: Used for other types of objectives that are not covered with others.

How to Define your Objectives

To define your Objectives, perform the following steps:

  1. Create a new scar file to add each objective and name it "obj_[nameOfObjective].scar"
  2. Define the function that creates your objective, including the definitions below:
    Add the Title (name) of objective (can be localized)
    Add the Type of objective it is
    Set up the UI needed for that objective type in another function
    Add events call for pre or post objective calls as an optional thing
    Add completion requirement for that objective.
  3. Register your objective.

Objective 1
Objective 2
Objective 3

Initialize Objective

To start the objective, the Mission_Preset function must call it.

Objective 4

Objective Important Functions

A number of additional functions are detailed below.

  • Objective_Start:
  • Objective_Complete
  • Objective_IsStarted
  • Objective_AreSubObjectivesComplete
  • Objective_AddUIElements
  • Objective_SetCounter()
  • Objective_IncreaseCounter
  • Mission_Complete

 

Rules

A rule is simply a function that can be defined, similar to the functions detailed above.

However, "adding" this function as a rule will set the function up to be called in the future. This can be done either once or repeatedly at regular intervals.

Adding rules

  • Rule_Add(myFunc)
    When you call this, the function myFunc will be called every simtick from then on.
  • Rule_AddOneShot(myFunc, delay)
    This will execute the function myFunc, once and once only, in delay seconds time.
  • Rule_AddInterval(myFunc, interval)
    This will execute your function myFunc, every interval seconds, until you tell it to stop with one of the removal functions (below).

Removing rules

  • Rule_Remove(myFunc)
    Calling this will stop the function myFunc from being called again.
  • Rule_RemoveMe()

 

Using Group References

When scripting a mission, as mentioned before, you will need defined variables or groups and pass them into functions for them to use that data.

For example, if you want to spawn units during the mission then you will need to create a function to be called when needed, use a function to spawn the units and use defined groups to add them to and get a hand to it for later references and will need scar markers setup in the map.

Group Preferences

Here "sg_clermont_army" is a defined sgroup and the marker mkr_player_sp_pursuit_01_dest will be the location to spawn the units.


Further Reading...

Related articles