Mission development

Missions can be created by writing mission scripts.

A new campaign and mission system is being discussed here : http://spring.clan-sy.com/phpbb/viewtopic.php?f=12&t=15320

Mission scripts are added to the startscripts directory, and are written in Lua.

1 Using mission scripts
2 missionbuilder
3 How scripts are located and named
4 How to create a lua script
5 How to require a specific map and mod
6 How to say things
7 How to create units
8 How to know if a unit is dead
9 How to order units around
10 Using AIs within mission scripts
11 Full list of functions available
12 Mission Development Guide

Using mission scripts

The script will appear if Spring is started directly ,rather than from the lobby. A list of available scripts will appear. You can use the up and down keys to select the one you want, then enter to start it.

Try "Lua missiontest" to see what is possible.

missionbuilder

Run spring.exe and start script "missionbuilder". You have functionalities available to dump lua commands to infolog.txt, sufficient to recreate all currently selected units.

Missionbuilder makes it relatively quick to create a mission with fixed place units, such as gun towers.

You can use .cheat with .give to give yourself lots of mobile fusions, metal mohos, and builder planes to make building units within the missionbuilder as easy as possible.

How scripts are located and named

Several scripts are compiled into Spring itself. This is why you see scripts such as "Air Test" and "Commanders".

A "normal" game is actually a game where the script is set to "Commanders". However the script.txt now also reads the optional value: scriptname=...; This means you can easily start with 1000 1000 res, or do just about anything else thats possible with the lobby as well by manually editing your script.txt and then starting spring via a shortcut with the argument script.txt. (in easyspeak that is: make a shortcut to the spring.exe, open its properties, and then change its target to "[wherever you have spring]\Spring\spring.exe script.txt " . Then use the shortcut and viola!). See also this thread The lobby does not yet support choosing startscripts, though this may come in the future.

The name of the script that you see in the spring menu is the name passed to the Script constructor. In Lua, this looks like:

 function TestScript:__init() super('LUA mynewmission')

This script would appear in the menu as "LUA mynewmission"

How to create a lua script

Create a class that derives from Script:

     class 'MyMission' (Script)
     end

Create a constructor function, passing the script's display name to the base class constructor:

     function MyMission:__init() super('LUA mynewmission')
       -- Set to true to not have to press enter at start
       self.onlySinglePlayer = true
     end

Add an Update function. This is called every frame, thirty times a game-second:

     -- This function is executed every simulated frame (30 times/sec)
     function TestScript:Update()
     end

Instantiate the class, at the bottom of the script add:

     -- Instantiate the class so that it is registered and shown
     mymission = MyMission()

How to require a specific map and mod

Add the functions GetMapName() and GetModName():

 -- Return the mapname this script wants
 function MyMission:GetMapName()
   return "supcom.smf"
 end

 -- Return the modname this script wants
 function MyMission:GetModName()
   return "xtape.sd7"
 end

How to say things

 print("hello world!")

You can see the results in the chat history, and by opening infolog.txt in the Spring directory

How to create units

 self.myunit1 = units.Load("ARMPNIX", float3(985.0, 90.5, 14332.5), 0, false),
 self.myunit2 = units.Load("ARMFIG", float3(762.3, 86.8, 14335.0), 0, false),
 self.myunit3 = units.Load("ARMTHUND", float3(803.5, 91.9, 14307.7), 0, false),
 self.myunit4 = units.Load("ARMFIG", float3(797.3, 94.3, 14267.2), 0, false),

The first argument is the name. The second is the position, the third is the teamnumber.

How to know if a unit is dead

 if( self.myunit1.IsValid( self.myunit1 ) then
   print( "unit1 is alive")
 else
   print( "unit1 is dead")
 end

How to order units around

 local c = Command()
 c.id = Command.PATROL
 c:AddParam(13500)
 c:AddParam(94)
 c:AddParam(400)
 self.myunit1.GiveCommand( c )

Other commands available:

Command.STOP
Command.WAIT
Command.MOVE
Command.FIGHT
Command.ATTACK
Command.AREA_ATTACK
Command.GUARD
Command.LOAD_UNITS
Command.UNLOAD_UNITS

Using AIs within mission scripts

You can add an AI within a mission script by doing, eg:

AIs.CreateGlobalAI( 0, "AI/Bot-libs/csailoader.dll" )

This will load the CSAI AI as team 0's AI.

Full list of functions available

For an up-to-date list of functions of the current development version of spring, open the file rts/System/Script/LuaBinder.cpp. About half way down there is a section that starts with

	// Define the useful spring classes to lua
	module(luaState)
	[

and ends with

];

This contains the functions available to Lua. When you read this, the bits to notice are the names in quotes (""). These are the names of classes, methods and properties available to Lua.

For example, there is a class "Unit" with properties such as "id" and "health". This is the class we are using when we do things like:

   self.radar = units.Load("ARMRAD", float3(4832.0, 132.7, 10560.0), 0, false),
   print( self.radar.id )
   print( self.radar.health )