Battlefront2_scripting_system

SCRIPTING

Architecture

ScriptPreInit, ScriptInit, and ScriptPostLoad are the only scripting functions that the application will call for you automatically, during mission load. Events drive any other script logic that takes place during the mission, in the form of Callbacks. The application will not call any sort of Update function every frame.

Events

An Event is any important action that occurs during the game, usually when something significantly changes state. Associated with this Event are the Actor, the Context, and a number of Callbacks.

Actor

The Actor is the instance that triggered the Event.

Context

The Context is any other information relevant to the Event, often the other party involved in the Event. Some Events have no Context.

Callback

A Callback is a function that the Event Manager calls in response to an Event. Its first parameter is the Actor, and its second is the Context, if any. An Event may have any number of Callbacks associated with it.

Instance

Some Events only make sense for a specific instance of an Actor, and require an additional parameter to specify which instance.

Filters

By default, the Event calls all registered Callbacks any time an Actor triggers it. However, a Callback may only care about Events that match some sort of condition (team, name, or whatever). While the Callback itself could reject Events that it does not care about, the script should let the Event apply a Filter to avoid calling the Callback in the first place.

Scripting In Action

Registering an Event Callback

To register a function as a Callback, the script calls one of the Event registration functions. These functions all have names that start with "On" followed by the name of the Event, and optionally by the name of a Filter:

"On" + Event Name

"On" + Event Name + Filter Name

For example, the registration function for the Command Post Event "BeginCapture" and the Command Post Filter "Team" has the name "OnBeginCaptureTeam".

The Event part of the registration function expects a Lua function to call, whether by reference or inline definition. If the Event is instance-specific, it also expects an additional parameter to specify which instance.

The Filter part of the registration function expects a data parameter specific to that Filter. The Filter definitions below describe what parameters the Filter requires.

For the previous example, the call would look like this:

OnFinishCaptureTeam(CaptureTeam1, 1)

The FinishCapture Event receives the parameter CaptureTeam1, while the Team Filter receives the parameter 1. After this registration, the Event Manager will then call the function CaptureTeam1 whenever Team 1 captures a Command Post.

Alternatively, the Lua function can appear inline:

OnFinishCaptureTeam(function (post) ... end, 1)

Lua treats functions just like numbers, strings, tables, or any other data type. You can define them anywhere, assign them to variables, pass them as parameters, or return them from functions. In fact, defining a function remembers the values of all local variables in its environment, creating a "closure" or "function object"; this is a very useful and powerful language feature.

Inside an Event Callback

When an Actor triggers an Event, the Event calls every associated Callback that passes the Filter. The Event always passes the Actor as the first parameter to the Callback. It passes related Context (if any) as the second parameter. The Callback may perform any action it wants before it returns.

Character

Events

CharacterDeath: function (player, killer)

This event occurs whenever a character (human or AI) dies.

CharacterSpawn: function (player)

This event occurs whenever a character (human or AI) spawns.

CharacterDispensePowerup: function (player, powerup)

This event occurs whenever a character drops a health/ammo pickup

CharacterDispenseControllable: function (player, controllable)

This event occurs whenever a character drops a controllable item (such as a remote droid or a mini-turret). If you want to check exactly what kind of controllable was dropped, use GetEntityClassName(controllable).

CharacterLandedFlyer: function (player, flyer)

This event occurs whenever a character lands a flyer. If you wanted to check if the player landed within a region, use

IsCharacterInRegion(player, "regionName"). If you want to check if the flyer matches a particular type of flyer, use this:

if GetEntityClass(flyer) == FindEntityClass("flyerClassName") then

end

CharacterEnterVehicle: function (player, vehicle)

This event occurs whenever a character enters a vehicle. It also works for turrets!

CharacterChangeClass: function (player)

This event occurs whenever the player presses the OK button in the spawn display. It is not intended to be a robust thing that can be used in either multiplayer or to check when the AI change classes. If you need to get the player’s class, use

GetCharacterClass(player), which will return a class index. If you need the class name, you can use GetEntityClassName(GetCharacterUnit(player))

CharacterIssueAICommand: function (player, command_id)

This event occurs whenever a player issues a command to the AI. The command ID that is passed in must be translated into a string by calling TranslateAICommand(command_id). This function will return one of the following strings:

"getintovehicle"

"getoutofvehicle"

"waitforpickup"

"followchr"

"stopfollowchr"

Filters

Name: name

This Filter matches any Character with the specified name.

Team: team

This Filter matches any Character on the specified team.

Class: config

This Filter matches any Character with the specified config.

Command Post

Properties

Name

This property is the name of the Command Post, and should be unique.

Team

This property is the team that currently owns the Command Post. The Command Post will not be neutral (team 0) at the time it triggers a Capture or Neutralize Event, even though it will be neutral before (Capture) or after (Neutralize).

Value

This property is the number of points the Command Post contributes to its owner. Neutral Command Posts contribute one point to every team instead.

Instance Properties

Any instance property defined in an Object Definition File or in the World File also applies from the Script.

Label

Description

CaptureRegion

ControlRegion

KillRegion

SpawnPath

AllyPath

AllyCount

Radius

VO_All_AllCapture

VO_All_AllLost

VO_All_AllInDispute

VO_All_AllSaved

VO_All_AllInfo

VO_All_ImpCapture

VO_All_ImpLost

VO_All_ImpInDispute

VO_All_ImpSaved

VO_All_ImpInfo

VO_Imp_AllCapture

VO_Imp_AllLost

VO_Imp_AllInDispute

VO_Imp_AllSaved

VO_Imp_AllInfo

VO_Imp_ImpCapture

VO_Imp_ImpLost

VO_Imp_ImpInDispute

VO_Imp_ImpSaved

VO_Imp_ImpInfo

VO_Rep_RepCapture

VO_Rep_RepLost

VO_Rep_RepInDispute

VO_Rep_RepSaved

VO_Rep_RepInfo

VO_Rep_CISCapture

VO_Rep_CISLost

VO_Rep_CISInDispute

VO_Rep_CISSaved

VO_Rep_CISInfo

VO_CIS_RepCapture

VO_CIS_RepLost

VO_CIS_RepInDispute

VO_CIS_RepSaved

VO_CIS_RepInfo

VO_CIS_CISCapture

VO_CIS_CISLost

VO_CIS_CISInDispute

VO_CIS_CISSaved

VO_CIS_CISInfo

ValueBleed

Value_ATK_Alliance

Value_ATK_CIS

Value_ATK_Empire

Value_ATK_Republic

Value_ATK_Locals

Value_DEF_Alliance

Value_DEF_CIS

Value_DEF_Empire

Value_DEF_Republic

Value_DEF_Locals

SoldierBan

HoverBan

SmallBan

MediumBan

HugeBan

FlyerBan