Scripting Guide

From Cube Wiki
Jump to: navigation, search


Your local documentation (README.html) holds all the commands you can use. It is probably the best reference for the release you're using.

With scripting you can achieve a more personalized Sauerbraten experience. In most cases some simple copy/paste will do the trick. But this guide aims at showing some easy techniques to empower gamers and mappers alike.

Any files you find in your game directory (and sub-directories) ending in .cfg contain CubeScript. Check them out to see what the engine already does via scripting... and how!

CubeScript Topics

Documentation Revisited

The basic command structures of CubeScript are explained on the Scripting Syntax page. Some introductory words on selected commands can be found on this Scripting Commands summary. For programming you should be aware of the flow control possibilities.

Getting Started

Do your first steps with:

Map Configuration

Scripting for maps is explained on the Map Config and Scripting.

Menu Personalization

Scripting for menus is explained on the Scripting Menus.

CubeScript 101

What happens at startup

Following files get executed:

if config.cfg doesn't exist:
  only then do we execute data/defaults.cfg
  this will - at regular quit of engine -
  be written into config.cfg

if config.cfg exists:
  execute it

execute data/menus.cfg

if autoexec.cfg exists:
  execute it

What happens on map load

data/default_map_settings.cfg is executed
if they exist
  packages/ ..PATH-to-package.cfg is executed
  packages/ ..PATH-to-Map.cfg is executed

What can I do with scripting myself?

Whatever you can describe as a combination of CubeScript blocks.

autoexec.cfg and config.cfg

The engine automatically saves your configuration in config.cfg. To automatically run scripting on engine start you need only place them in autoexec.cfg.

The scripting newbie

To find out about what you can do, you'll need to know your way around the documentation at least; anything you can break down into single CubeScript commands can be made into a CubeScript Block and thus speed up your everyday use of the engine.

Without being a programmer you might find a lot of this stuff too complicated for your taste, but do not despair! There are some examples on these pages to help you achieve a lot of goals and there are also quite a few scripts ready for download on quadropolis.

But if you really want to get the most out of the engine it is suggested that you at least try getting familiar with some basics of the scripting capabilities! Try reading the page on Scripting Tutorial to see what fundamental know-how this is and how easy it is. Always referr to your local documentation to find basic CubeScript commands and how to use them, anything you want to be executed in sequence can be put inside a CubeScript block - like so:

// The fullscreen command only works on Linux, OS X, and other UNIX systems.
doARecalc = [
fullbright 0
fullscreen 0
calclight 2
fullscreen 1

You can then execute this block simply by calling doARecalc ... for example via the console, or from other CubeScript blocks. Another example of a minimal CubeScript to handle a repetitive task: Scripting Commands#prettyscreenshot or from Quadropolis: Pretty Screenshot