RDNWiki: DOWScar/Tutorials/Beginning/Tutorial6 ...

Functions and Rules

Note: this information is from ScarDoc as a placeholder, until it can be rewritten.

Functions

A function is a predefined action that can be called in a script. They can either set values within the game or return information about the game. Then can be used in conjunction with Lua arguments to create script logic. Scardoc forms the library of functions from which Rules can be composed. If the a desired function does not reside in Scardoc, chances are, it can not be performed via script in game.

For clarity, functions are often given prefixes to help identify what kind of action they are meant to perform. Some examples:

• Cmd_ – a command function

• Cpu_ – an AI function

• SGroup_ – an squad group function

• Util_ – a utility function designed to facilitate a set of sub functions

Rules

A Rule is simply a user-defined function that, once “added”, is then evaluated by the game every interval. The Rule is added by using the Rule_Add( “name of Rule” ) function, and passing in the name of the Rule that you wish to add. The interval that the Rule is evaluated at can either be the default (every frame) or can be set (every x seconds), using the Rule_AddInterval function in place of the Rule_Add. The interval can be defined on a per-Rule basis, allowing you to specify a different interval for every Rule that you have.

For example, if we wanted a Rule that printed out “Hello world!” to the console every frame, we would have something along the lines of:

-- add the Rule_HelloWorld to the queue of Rules being evaluated
-- here the Rule_HelloWorld function is defined, in the LUA standard
Rule_Add( Rule_HelloWorld )

function Rule_HelloWorld()
  print( "Hello world!" )
end

This will then print the words “Hello world!” to the console every frame.

Once a Rule has been added, every interval the contents of that Rule will be executed by the game. If the first statement in a Rule is a conditional, such as an if statement, this will ensure that the Rule is only executed once the conditions are met.

Lets use a conditional statement to print the words “Hello World!” only when the player is of the race Eldar.

Rule_Add( Rule_HelloWorld )

function Rule_HelloWorld()
  -- use the Player_GetRace function to determine if player 0 is Hiigaran
  if ( Player_GetRace( 0 ) == "elder_race" ) then
    print( "Hello world!" )
    Rule_Remove( Rule_HelloWorld )
  end
end

Notice the call that's being made to Rule_Remove. This removes the Rule from the queue, meaning that it will not be evaluated on the next interval. If you don't remove the Rule after it has been used, it will continue to be evaluated every specified interval. By adding the Rule_Remove, we ensure that this Rule will only be executed once whenever it's conditional statement is met.

A Rule can be removed at any stage during your script, but it will not be completely removed until the next Interval. So if you remove a Rule in the middle of the Rule, the remaining calls of that Rule will still be executed in this Interval.

This looks good, but what happens if the player's ID isn't 0, or perhaps there are multiple players and we want to check each one? We can wrap our conditional statement in a for loop, which will then go through every player in the game and check to see if they are Eldar or not.

Rule_Add( Rule_HelloWorld )

function Rule_HelloWorld()
  -- we use the for loop, an functionality provided by Lua
  for i=1,Universe_PlayerCount() do
    if ( Player_GetRace( i ) == "elder_race" ) then
      print( "Hello world!" )
    end
    -- once all players are checked, remove this rule
    if ( i == Universe_PlayerCount() ) then
      Rule_Remove( Rule_HelloWorld )
    end
  end
end

In this Rule, the for loop checks every player in the game to see if they are Eldar, printing “Hello World!” if they are. When the loop iterator (i) is equal to the number of players, the Rule is removed.

See how quickly a very simple Rule can turn into a very useful one? This is the inherent power of SCAR. At its most basic level, it can be quite functional. However by applying some more advanced scripting techniques, it will quickly become a powerful and versatile tool.

As you can see, a Rule is simply a function. The only thing that makes it a Rule is we append it with Rule_ (this is simply a naming convention employed for clarity) and the fact that it is “added” to the list of Rules being evaluated as opposed to called directly from the script. This means that you can also create simple functions inside your script to enable you to perform repetitive functions, instead of needing to have dozens of Rules all performing the same function.

Here is another example:

--here we're going to add the rule in every 30 seconds Rule_AddInterval( Rule_GivePlayerMoney, 30 )
function Rule_GivePlayerMoney( )

  --this checks to see how much requisition the indicated player has 

  if Player_GetResource(playerID, RT_Requisition) < 1000 then

    Player_AddResource(playerID, RT_Requisition, 500)

  else
    Rule_Remove(Rule_GivePlayerMoney )

  end
end

This example, if implemented, would check every 30 seconds to see how much Requisition the indicated player had. If the amount is less than 1000 units it will add 500 more on. If the player has more than 1000 Requisition points, the Rule will remove itself.

• NOTE – By creating an 'autoexec.lua' file in your Warhammer\Root directory and inserting the command line [ dofile(«Dev/ScarDebugBindings.lua") ] you can call up the SCAR Rule Profiler in-game by using the hot-key CTRL + P.

Links

ScarDoc
LUA Wiki
SCAR
Wiki Home

End of Page