Contents 1 Server Side Scripts 1.1 Introduction 1.2 Server Scripts Directory 1.3 Server Side Hooks 1.3.1 Introduction 1.3.2 Example Hooks File 1.4 Server Side Scripts 1.4.1 Introduction 1.4.2 Excample Script File 1.4.3 Global variables 1.5 Debugging 1.5.1 Scorched Client 1.5.2 Console Commands

Server Side Scripts

Introduction

Scorched3D supports a huge amount of functionality "out of the box". However, sometimes you may wish to perform some actions that are specific to your server, and are so specific they will never be in an actual release of Scorched3D. Perhaps you wish to reward players with a certain clan tag, or award more points for different objectives, or even implement a betting system.

Scorched3D allows the server to be enhanced through the use of server side scripts written in the LUA scripting language. These scripts are plugged into the engine and are called when the engine makes certain decisions or performs certain operations.

See Scorched3D scripting home for an introduction to scripting on Scorched3D.

Note: Currently the framework is in place but the library functions available mean that server side scripting has limited functionality. This will be changed if people show an interest.

Server Scripts Directory

The server hooks and scripts need to be placed into a directory called serverhooks in your scorched3d user settings directory. This directory is usualy in :

c:\documents and settings\<user name>\.scorched\serverhooks   - for windows
~/.scorched/serverhooks   - for unix

The server hooks directory structure is as follows:

 .scorched     - The scorched3d user settings directory
     |
     +----> serverhooks    - The server hooks directory
                  |
                  +--->  testscript.lua   - A server script file
                  |
                  +--->  testhook.xml     - A server hook file

Server Side Hooks

Introduction

As previously mentioned Scorched3D can be configured to call a server script (or many scripts) when a specific action occurs. The scripts are hooked into the server by registering them with a hook name. The server has a set of pre-defined hook names that it already knows about. When the server performs certain actions it also executes the scripts registered agains the action's hook name.

The hooks are configured via XML files in the scripts directory (these files must have the .xml file extension).

Example Hooks File

Here is an example hook file:

 <hooks>
   <hook>
     <filename>testscript.lua</filename>
     <hook>
       <hookname>server_channeltext</hookname>
       <entrypoint>server_channeltextmethod</entrypoint>
     </hook>
     <hook>
       <hookname>server_newgame</hookname>
       <entrypoint>server_newgamemethod</entrypoint>
     </hook>
   </hook>
 </hooks>

This file registers two hooks, both with the same script file:

1. When the server sends any channel/talk messages to a client the server_channeltextmethod method in the testscript.lua file will be called.
2. When the server starts a new game the server_newgamemethod method in the testscript.lua file will be called.

A hook file can register any number of hooks.

See server_side_hooks for the hooks currently available.

Server Side Scripts

Introduction

Script files are the files that contain the actual lua code. There is nothing special about these files except that they must contain the method(s) that were specified in the hooks file.

The scripts are written as LUA files in the scripts directory (these files usualy have the .lua file extension).

Excample Script File

Here is an example script file:

 function server_channeltextmethod(playerid, channel, text) 
   print("--server_channeltextmethod---called---");
 end
 
 function server_newgamemethod() 
   print("--server_newgamemethod---called---");
 end

This script implements the two methods mentioned in the earlier hook configuration file. The script prints some debugging text to the console whenever these methods are called.

Global variables

Unlike weapon scripts it is fine to use global variables in server scripts for any purpose.

Debugging

Scorched Client

You can use the Scorched3D client (the 3D graphical game) to test your scripts. Since the client also has a server imbedded in it, it will behave the same way as a standalone server.

Currently there is no debugger for scripts.

Console Commands

There are several console commands you can use to manage the hooks (see Useful_Console_Commands for information on how to access the console).

• scriptHook server clear - remove all hooks (to stop the server from calling any scripts)
• scriptHook server load - reload all of the hooks (to load changes after hook/script files have changed)
• scriptHook server list - lists all of the available hook names