Skip to content

Map Script Making Tutorial

Jump to bottom
Cook Green edited this page Dec 26, 2019 · 27 revisions

Main Entry Function

The Main entry function in a script file is WorldLoaded function, you can put some initlization code here, such like get player and create objectives
You may need some codes like this:

WorldLoaded = function()
    .....
end

Create a objective

The objectives in game are some goals need player to finish, some objectives which fail will not effect the game play, but some objectives which fail will cause game over, if you want to create a objective, you can use the following code:


player = Player.GetPlayer("PLAYER NAME")
player.AddPrimaryObjective("Description String")   -[[Add a primary objective]]
player.AddSecondaryObjective("Description String")   -[[Add a secondary objective]]

An objective has three trigger, OnObjectiveAdded, OnObjectiveCompleted and OnObjectiveFailed
OnObjectiveAdded will be triggered when call AddPrimaryObjective or AddSecondaryObjective
OnObjectiveCompleted will be triggered when call MarkCompletedObjective
OnObjectiveFailed will be triggered when call MarkFailedObjective
Such like this:

ObjectiveObject = player.AddPrimaryObjective("blah")
player.MarkCompletedObjective(ObjectiveObject)
player.MarkFailedObjective(ObjectiveObject)


Trigger.OnObjectiveAdded = function(player, function(p, objectiveID))
    --[[ You can use p.GetObjectiveDescription(objectiveID) to get the objective description ]]
end

Trigger.OnObjectiveCompleted = function(player, function(p, objectiveID))
    --[[ You can use p.GetObjectiveDescription(objectiveID) to get the objective description ]]
end

Trigger.OnObjectiveFailed = function(player, function(p, objectiveID))
    --[[ You can use p.GetObjectiveDescription(objectiveID) to get the objective description ]]
end

When any primary objective failed, OnPlayerLost will be triggered, on the opposite, when all primary objectives are completed, OnPlayerWon will be triggered
You can hook these two triggers yourself:

Trigger.OnPlayerLost = (player, LostFunction)  

Trigger.OnPlayerWon = (player, WonFunction)

Reference an actor

All actor defined in map.yaml can be referenced in map script file, for example, we have a map.yaml defined like this:

MapFormat: 11
RequiresMod: example
Title: Placeholder
Author: BlahBlahBlah
Tileset: TILESET
MapSize: 100,200
Bounds: 2,5,96,188
Visibility: Lobby
Categories: Conquest
Players:
	PlayerReference@Neutral:
		Name: Neutral
		OwnsWorld: True
		NonCombatant: True
		Faction: Random
	PlayerReference@Creeps:
		Name: Creeps
		NonCombatant: True
		Faction: Random

Actors:
	Actor0: ACTOR_TYPE
		Location: 95,3
		Owner: Neutral
	Actor1: ACTOR_TYPE
		Location: 114,26
		Owner: Neutral

If we want to reference Actor0 in script file, such like we want to check its dead or not:

if Actor0.IsDead then
    .....
end

We can write the actor's id defined in map.yaml directly in script file, and access all available properties of this actor.
So, you can modify the actor id in map.yaml and make it more readable.

Create an actor

There are two ways to create an actor, one is that use Reinforcements.Reforce function to create an actor(or actors), another one is that use Actor.Create function to create

First way

Reinforcements.Reforce function receive five parameters:

  • Owner, the owner will own this/these actors
  • actor array - an array contains the actor type name which you want to create
  • path array - an array contains the path coordination which actor will follow, first is spawn position, the last is the destination position
  • interval - when will spawn next actor?
  • actionFunc - if this parameter is given, it will execute when an actor reach the destination

Example:
We have an actor arry defined like this:

allies = Player.GetPlayer("Allies")  
allieUints = {"apc", "mig", "ifv"}  
--[[entryCell defined in map.yaml]]

So if we want to use spawn these actors, just write the code like this:

local units = Reinforcements.Reinforce(allies, allieUints , { entryCell }, 20)

Second way

You can use Actor.Create if you just want to spawn one, and don't want to make it move
The Actor.Create receive three parameters:

  • Type - The actor type name will be spawned
  • AddToWorld - Will this actor be added to world?
  • initTable - Some init parameters such like Location or Facing

Example:

player = Player.GetPlayer("player")  
Actor.Create("apc", true, { Location = spawnPoint1.Location, Facing = Facing.NorthEast, Owner = player })

Money

The money in game is very important thing, especially in some maps, whether a game is easy or difficult depends on the start money.
We can easily give player money in script file, just do like the following:

player = Player.GetPlayer("player")  
player.Cash = 1000000

So, our player will have 1000000 in this game

Tick Function

The tick function in script is a function which will be called by engine when engine update the game, so it means tick function will be called everytime
So if you want to do something all the time, such like checking some actor's state, or sending forces over and over again, you can write your function in Tick function
A tick function usually like this:

Tick = function()
    ......
end

Map.yaml

The map.yaml file is a very important file in OpenRA Map System, you can define the basic Information of this map like name, author and etc. And you can also define the Players and Actors in this map.
Especially, you can define custom rules in this file, and overwrite the defination in rules file.

Basic Information

The basic information contains all the basic information of a map which includes:
MapFormat - The Map Yaml File Format, always is 11
RequiresMod - The Mod of this map can use
Title - Map name shown in the map browser
Author - Map author shown in the map browser
Tileset - Map used tileset
MapSize - Map Size
Bounds - The Map Bounds
Visibility - Where the map will be shown, three possible values: Lobby, Shellmap and MissionSelector

  • Lobby - The map will be shown in map browser
  • Shellmap - The map will be used as a start map
  • MissionSelector - The map will be shown in mission list

Categories - Map Group, you can write anything you want

Players Defination

The players are very important, they are the souls of a map, all game play happened between these players, a player not mean a faction, in fact, two player can be one faction. A player defination usually like this:

PlayerReference@Greece:
	Name: Greece
	Playable: True
	AllowBots: False
	Required: True
	LockFaction: True
	Faction: allies
	LockColor: True
	Color: ABB7E4
	LockSpawn: True
	LockTeam: True
	Allies: England
	Enemies: USSR

PlayerReference@Greece - It means we will start Player Defination Block, and its id is Greece
Name: Greece - It means this player's name is Greece Playable: True and AllowBots: False - It means this is a human player not a bot Required: True - It means this slot must be assigned or we can't start game
LockFaction: True - It means system will lock its faction
Faction: allies - It means its faction is allies(which defined in world.yaml)
LockColor: True - It means its color will not change
Color: ABB7E4 - If you set LockColor is True, you must assign a color
LockSpawn: True - It means system will lock its spawn
LockTeam: True - Its team will not change
Allies - This player will not be attacked by the players defined in this line, for example, its Allies is England, so this player will not be attacked by the player named England
Enemies - This player will be attacked by the players defined in this line, for example, its Enemies is USSR, so this player will be attacked by the player named USSR

Once you defined player in map.yaml, you can use them in script by the follow code:

player = Player.GetPlayer("PLAYERNAME")

If you want to get the player above, you can try this:

greece = Player.GetPlayer("Greece")

Actors Defination

All actors will be defined under Actors:

ACTORID: ACTOR_TYPE
    Location: 0, 0
    Facing: 100
    Owner: PLAYERNAME

ACTORID - The actor id you want to define for it, it can be used directly in script file
ACTOR_TYPE - The actor type name which you defined in rules file
Location - The location of this actor in map
Facing - The Oritentation of this actor in map
Owner - Who owns this actor, need a player name

Rules Defination

If you want to limit something when player play this map, or want to make Soviet Factory build Allies things, you can use this, it can overwrite the rules defined in rules file for current map.
All rule defination must under the Rules:

ACTORTYPE:
    Trait List....

or you can use a external rules file, you can use like this:

Rules: map-rules.yaml

It will find the map-rules.yaml in the same directory with map.yaml

Weapons Defination

Sometimes we hope we can make weapon system do something special, but don't want to effect other maps, we can use the Weapon Overwrite in map.yaml
Weapon defination is the same like the weapon defination in weapons file
And Weapon defaination in map.yaml also support external file defination

Weapons: map-weapons.yaml

It will find the map-weapons.yaml in the same directory with map.yaml

Lua

Assign a value:

variable = 1

Condition

if condition-expression then
    ....
end

Loop

while condition-expression do
    .....
end

or

for x in arr do
    ....
end

or use openra version

Utils.Do(arr, function(element)
    ....
end)

Comment

Single-line Comment

--[[This is a comment]]

Multi-line Comment

--[[
These are comments
--]]

Array

arr = {"element1", "element2", "element3"}

Table

tb = {}
tb["key"]="value"

Access an element of an array

element  = arr[index]

Define a function

FunctionName = function(Parameters)
   ....
end

Call a function

FunctionName(Parameters)

Return

return

See Also

OpenRA Lua API: /~https://github.com/OpenRA/OpenRA/wiki/Lua-API

OpenRA Yuri's Revenge Thread —— OpenRA Yuri's Revenge Discord

Clone this wiki locally