Main Page » Server Side Scripts

Revision as of 15:30, 3 March 2009

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.

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.

Hooks Files

The server hooks 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 hooks are configured via XML files in this 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.

Script Files

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.

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.

Console Commands

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.

There are also 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

Configuration