Contents 1 Scripting 1.1 Introduction 1.2 LUA 1.3 Tables 1.4 Numbers 1.5 Security 2 Scorched Scripts 2.1 Script Types 2.2 Script Libraries

Scripting

Introduction

Scorched 3D supports the use of scripts to both enhance the engine and to create new and funky weapons. Scripting support was introduced in Scorched3D version 42.

Scripting is useful when you want to perform actions based on complex decisions, or simply when an alternative is not available via the XML configuration files. For example, you may want to find all the players in a given team and give them some money, or kill all players below a certain amount of health. Scripting makes all of this possible.

LUA

Scripts are written in the LUA scripting language. Scripts are saved as 'plain text files' usualy with the lua file extension. 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

All of the standard libraries are documented in the LUA Documentation.

Scorched3D adds some new functions and structures to LUA so the script can interact with the scorched engine. For example, some of these functions allow you to fire weapons or send messages to other players. These Scorched specific libraries and functions are documented later.

Tables

LUA makes heavy use of tables to store structured data. Scorched3D represents most of its complex information as tables. For example the position and velocity vectors are represented as tables containing three entries (x, y & z). You can access these entries by using the fullstop, e.g. table.x.

See LUA Documentation for a more detailed explanation of table operations.

Numbers

Its probably worth noting that internaly Scorched3D uses fixed point maths. All numbers used by the engine are stored as fixed point, including those used by the LUA library. This ensures that all maths operations (and so the simulation) remains consistent accross different architectures.

But don't worry this completely is hidden from you at all times, and other than a slightly reduced maths accuracy it shouldn't be noticable. The fixed point numbers used currently support up to four decimal places (.0001) and numbers up to two hundred thousand (200000).

Security

LUA is a fully functioning programming (scripting) language (LUA Documentation). However LUA scripts run within a virtual machine that only allows it to perform specified operations. When LUA was added to Scorched3D any operation that was deemed to be unsecure was removed from the language. Removed functions include any that accessed the operating system and all file reading/writing functions.

Scorched Scripts

Script Types

Scorched3D currently allows two types of scripting -

• Server Side Scripts - Scripts used to alter the way the server plays the game
• Weapon Scripts - Scripts used to create fancy weapons

Script Libraries

Scorched3D provides two scripting libraries -

• LUA s3d library for the general scorched3d library.
• LUA s3dweapon library for the scorched3d weapons library containing functions specific to creating and manipulating weapons. (can only be used from weapon scripts)