mapbuilding.markdown

layout	title	icon
default	FAQ	general.svg

Building Complex Maps

The Stratagus engine is very flexible when it comes to custom maps, even though most of the flexibility is not exposed in the map editor. This document aims to provide a bit of guidance if you want to create custom missions with complex setups, triggers, and/or objectives.

1. Build the map in the map editor

1.1 Create the basics

The first step should be to build the basic map in the map editor. This includes setting up how many factions you need and of which colors, their units, the terrain etc. Basically, anything that can be done in the editor, should be done in the editor

1.2 Touch up appearances

The map editor comes with a feature to draw "decoration" tiles, that is, to draw tiles without automatically changing and adjusting the tiles around it. This feature is really for the last touch ups, since afterwards the tiles cannot be reverted to automatic updates from the UI. So, if you are sure you are done with the terrain, you can use this touch-up feature to draw single tiles of specific variant to have the maximum control over the terrain.

2. Adapt the Scripts

A map is saved into two files a .smp and a .sms file. The .smp file you should not touch - it is really only meant for presenting the basic aspects of the map in the game lobby, including name and number of factions.

2.1 Custom events and objectives

In-game events and objectives are coded the same way. Open the .sms file in an editor of your choice and go to the end of the file. All objectives and events are done using "Triggers". Triggers are pairs of functions that are run at regular intervals by the game. A complex victory condition trigger can look like this:

local victoryTimer = -1

AddTrigger(
  function()
    if GetNumUnitsAt(
         GetThisPlayer(), "any",
         {Map.Info.MapWidth / 2 - 5, Map.Info.MapHeight / 2 - 5},
         {Map.Info.MapWidth / 2 + 5, Map.Info.MapHeight / 2 + 5}) > 5 then
      return true
    else
      return false
    end
  end,
  function()
    AddMessage("5 Units in the center!")
    victoryTimer = 10
    return false
  end
)

AddTrigger(
  function()
    if victoryTimer > 0 then
      victoryTimer = victoryTimer - 1
      AddMessage("Time remaining until victory: " .. victoryTimer)
    end
    return victoryTimer == 0
  end,
  function()
    return ActionVictory()
  end
)

Let's unpack this. We are defining two triggers. The first function is the "condition function" of the trigger. The second function is the actual trigger. The first function is run at regular intervals during the game until it returns true. Only then is the second function run. If the second function returns false, then that trigger will be removed and will never run again.

The first trigger condition here checks if the number of units of the active player in the map center (in a 10x10 grid around the map center) is larger than 5. If this is true, the condition returns true and the second function runs. The second function shows a message that 5 units are now at the center and sets the variable victoryTimer to 10.

The second trigger just keeps checking the victoryTimer variable. As long as that variable is less than 0, nothing happens. But when the first trigger has fired and set the variable to 10, then the second trigger will start counting it down and show that as an in-game message. Once the victoryTimer has counted down to 0, the condition of the second trigger returns true and the action function runs. The action function in this case just calls ActionVictory. What that means is the game ends with a victory.

For conditions where the game should be lost, ActionDefeat is used.

Note how powerful this can be. Of course, now we are just using a trigger to show some message and set a variable, but you could have triggers that spawn or transform units, change diplomacy, scroll the map somewhere, pause the game and show an "in-game dialogue", or even change tiles on the map to have something like a "natural disaster event" that changes the face of the earth. For all the things you can do, check the Lua functions that are available: https://stratagus.com/lua_bindings.html

2.1 Custom alliances

A common request for complex games is to be able to declare custom alliances, like some AI players being in a team with the player or player co-op against AI. This can be achieved using a custom startup function.

After the game is loaded and everything is ready to start running, Stratagus calls one last Lua function to do any last minute setup. This Lua function is GameStarting.

As an example, you can add this to the end of your .sms file:

local OldGameStarting = GameStarting
function GameStarting()
        OldGameStarting()
        SetDiplomacy(0, "allied", 2)
        SetSharedVision(0, true, 2)
        SetDiplomacy(2, "allied", 0)
        SetSharedVision(2, true, 0)
        GameStarting = OldGameStarting
end

This will ensure that at the beginning of the game, players 0 and 2 are always allied. Just as with triggers, all the Lua functions are available to you here, so anything can be done at this point.