地图脚本制作指南

入口函数

一个地图脚本文件的入口函数是WorldLoaded, 你可以在这个函数里面加入一些初始化代码，比如获取玩家，添加任务目标等等 你可以使用如下代码定义这个入口函数:

WorldLoaded = function()
    .....
end

创建任务目标

任务目标就是玩家需要在这个任务完成的一些目标，有些任务目标失败不会影响游戏进程，但是有些任务目标失败将会导致游戏结束, 如果你想要创建一个任务目标的话，你可以使用下面的代码：

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

一个任务目标有三个触发器, OnObjectiveAdded, OnObjectiveCompleted和OnObjectiveFailed
当 AddPrimaryObjective或者AddSecondaryObjective被调用的时候OnObjectiveAdded会被触发
当调用MarkCompletedObjective的时候OnObjectiveCompleted会被触发
当调用MarkFailedObjective的时候OnObjectiveFailed会被触发
像这样：

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


Trigger.OnObjectiveAdded = function(player, function(p, objectiveID))
    --[[ 你可以使用 p.GetObjectiveDescription(objectiveID) 方法去获取任务目标的描述 ]]
end

Trigger.OnObjectiveCompleted = function(player, function(p, objectiveID))
    --[[ 你可以使用 p.GetObjectiveDescription(objectiveID) 方法去获取任务目标的描述 ]]
end

Trigger.OnObjectiveFailed = function(player, function(p, objectiveID))
    --[[ 你可以使用 p.GetObjectiveDescription(objectiveID) 方法去获取任务目标的描述 ]]
end

当任意主要任务目标失败, OnPlayerLost触发器将会被触发, 相反地,当所有主要任务目标完成的时候, OnPlayerWon将会被触发
你可以自己挂钩这两个触发器

Trigger.OnPlayerLost = (player, LostFunction)  

Trigger.OnPlayerWon = (player, WonFunction)  

引用一个Actor

所有在map.yaml定义的Actor都可以在地图脚本文件中被引用, 比方说, 我们有一个像这样的map.yaml文件:

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

如果我们想要在脚本文件中引用Actor0以检测其是否死亡，我们可以这样做:

if Actor0.IsDead then
    .....
end

我们可以直接使用在map.yaml定义的Actor的ID在地图脚本文件中使用, 并且可以访问这个Actor的所有属性.
因此，你最好把在map.yaml定义的Actor的ID修改得可读性强一些.

Tick方法

在脚本文件中Tick方法将会被引擎调用当引擎要更新游戏的时候，因此这意味着我们可以将一些我们需要持续调用的方法放在Tick方法里面，比如检测Actor状态，或者循环发送部队。 一个tick方法像如下这样:

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

Map.yaml

map.yaml文件在OpenRA地图系统中很重要, 你不仅可以在这个文件中定义基本信息，比如作者，名称等等. 你还可以定义这个地图中存在的玩家已经Actor
尤其是, 你可以在这个文件重写规则文件和武器文件（就像在红警地图编辑器里面一样）.

地图基本信息

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

玩家定义信息

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")

Actor定义信息

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

规则重写

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

武器重写

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

参加

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