Main Page » Weapon Scripts

Revision as of 22:46, 21 February 2009

Weapon Scripts

Introduction

Scorched3D supports configurable weapons via its XML accessory definition files, see current scorched3d weapons. The XML definitions allow you to make an almost limitless number of complex weapons, and in most cases this is the easiest way to create new weapons.

In some cases the XML accessory definition files don't allow you to create the weapons you want, perhaps the weapons are very complex or the XML syntax doesn't exist. For these occasions you can Weapon Scripts.

Instead of XML Weapon scripts use the LUA scripting language to define Scorched3D weapons. See Scorched3D scripting home for an introduction to scripting on Scorched3D.

LUA

Weapon scripts are written as normal text files containing LUA code. See LUA Documentation for documentation on the LUA scripting language.

The LUA interpreter imbeded in Scorched3D supports the following standard libraries-

Basic functions

String manipulation

Table manipulation

Mathematical functions

Scorched3D specific functions

All of the standard libraries are documented in the LUA Documentation, with the exception of the Scorched3D functions. The Scorched3D functions allow scripts to interact with and manipulate the Scorched3D engine.

Weapon Scripts

Entry Function

Weapon scripts are just normal LUA scripts. However there must be one function in the LUA script that takes a playerId, a position and a velocity. Simply put, one function in the script must look like this:-

  function runWeapon(playerId, position, velocity)

This is the function that will be called when ever this weapon is executed. You can have as many other functions as you need in the file but this one is mandatory.

The three arguments to this function are as follows-

playerId - An integer id of the player that fired this weapon

position - A table containing the coordinates of the current weapon

velocity - A table containing the velocity factors for the current weapon

Here is a very simple weapon script:

 function runWeapon(playerId, position, velocity)
   print(playerId);
   print(position.x, position.y, position.z);
   print(velocity.x, velocity.y, velocity.z);
 end

As you can see it implements the runWeapon function. When executed the script will print the playerId, position and velocity to the Scorched3D console. You can access the console by pressing the ` key.

Scripts Pitfalls

Using the print function can be a simple way of debugging scripts, however print statements slow down the game and should not be present in the final version of the script.

Too many weapons.

Global variables.

WeaponScript AccessoryAction

In fact the configuration for the Weapon Scripts is in the existing XML file (accessories.xml), but this is purely used to tell Scorched where to find the script and when to use it. Weapon scripts are defined in new type of accessoryaction called WeaponScript. This WeaponScript is just a 'normal' accessoryaction and can be used interchangably with other accessoryactions in the accessories.xml.

Here is an example WeaponScript accessory action:

 <accessoryaction type="WeaponScript">
   <filename>data/lua/accessories/test.lua</filename> 
   <entrypoint>runWeapon</entrypoint> 
   <variable>
     <name>testvar1</name> 
     <value>10</value> 
   </variable>
 </accessoryaction>

The above accessoryaction has two mandatory parts, the filename and the entrypoint:

• filename is the path to the LUA script that you want to run when the accessoryaction is executed.
• entrypoint is the LUA function in the script to execute when the accessoryaction is executed.
• variable is a *optional* list of variables that may be passed into the script.

Here is an example use of a WeaponScript:

 <accessory>
   <name>Test Script</name> 
   <bundlesize>2</bundlesize> 
   <cost>10</cost> 
   <accessoryaction type="WeaponScript">
     <filename>data/lua/accessories/test.lua</filename> 
     <entrypoint>runWeapon</entrypoint> 
   </accessoryaction>
 </accessory>

The above accessory creates a weapon called 'Test Script'. When the tank fires this weapon the runWeapon function in the data/lua/accessories/test.lua script will be executed.

Obviously this is a very simple example and as stated earlier you can use WeaponScripts anywhere that you can use an accessoryaction.

Weapon Scripts Walkthrough