Revision as of 15:20, 26 February 2008

Cubescript is the scripting language utilised within the sauerbraten/cube2 engine. it is used to set aliases, variables, create binds and generate the menu.

List of commands

These are just a list of commands, what they actually do will be covered a bit later in this topic.

General

The following commands are quite often used in a lot of scripts.

• alias
• at
• do
• getalias
• getname
• getteam
• if
• listlen
• loop
• result
• rnd
• sleep
• while

Map Configuration

The following commands are useful in level only aliases

• triggerstate
• level_trigger
  • level trigger is invoked as level_trigger_1 = [] as an example, the end number is the 4th number in the mapmodel's strings
• level_base
  • Used to give bases names in capture mode. This is unfortunately unused in PAS

Binds

The following commands are useful in binds.

• onrelease

Gui Creation

These commands are used to create various menus.

• cleargui
• guibar
• guibutton
• guicheckbox
• guifield
• guiimage
• guilist
• guilistslider
• guirolloveraction
• guirollovername
• guislider
• guistayopen
• guitab
• guitext
• guititle
• newgui

Alias/command comparing and changing

• +
• -
• *
• /
• !
• =
• >
• <
• div
• max
• min
• mod
• strcmp
• strstr

String/text formatting

These commands are used to format aliases which are normally huge bits of text

• concat
• concatword
• format

Shaders

All of the nice graphical effects were programmed in ASL (assembly shading language), and formatted in cubescript themselves.

• altshader
• fastshader
• macro
• setpixelparam
• setuniformparam
• setvertexparam
• shader

Writing in Cubescript

Syntax

Cubescript has many similarities with C, mostly in the way the script is formatted. there's a few key differences, a new line means a ; was placed at the end of a line automatically. so placing on yourself is good practice, but unnecessary. note the examples below do the exact same thing.

one liner example

alias hi [say "hi"; sleep 5000 [say "Hi again"]]

multi liner example

alias hi [
    say "hi"
    sleep 5000 [
        say "Hi again"
    ]
]

it's obvious what the above code does, it'll make your character say hi, and wait 5 seconds before saying hi again.

indenting is done in levels, the Tabulator (TAB) key is usually used to indent the text. while not necessary, it tends to make it bigger, and more legible as seen in the above example (when you get to big stuff, you'll thank yourself for indenting it.

As a rule of thumb, pretty much only [ increases the indentation level. Also note, ", ] and ) can close each other, so make sure you close them off properly

statement enclosers

While not the correct name, by statement enclosers, I mean the bits of ascii you usually use to enclose text with. Which is "" [] and () in cubescript. They all perform different functions too.

• "" is used when you wish to make it print exactly what you typed in it, eg /echo "Hi, my name is John Smith"
• () is used when you want the stuff inside it to be executed. and the results given eg /echo (+ 12 5) will print 17
• [] is the top level one, and should be used when you plan to use either () or "" inside your statement. eg echo [is that "cheese"?]. This is used mostly compared to the rest.

Inserting values and aliases

/echo $fog would place something like 4000 at the top of your screen. without the $ in front, it would've been 'fog'

The other way to do it is via @. you normally add an additional one for each level in you are. like in this example from the menus. it's not necessary as just a single @ will work equally fine, and for most, $ is all they'll ever need

guilistsplit = [
  guilist [
    i = 0
    n = (listlen $arg3)
    z = (div (+ $n (- $arg2 1)) $arg2)
    loop a $arg2 [
      guilist [
        t = (min (+ $i $z) $n)
        while [< $i $t] [
          push $arg1 (at $arg3 $i)
          @@@arg4
          pop $arg1
          i = (+ $i 1)
        ]
      ]
    ]
  ]
]

@ is needed most frequently in menu generation. like in this simple example below

pi = [guitext "3.1415"]

newgui pi [@pi]

Examples

For the sake of being lazy, I may not bother to format them correctly. also I'll be type blah = blahblah instead of alias blah blahblah, it's still the same as aliases can be created both ways.

Loops

loops are used to quickly execute code, and are usually invoked with /loop. the loop is invoked as such /loop alias value-to-stop-at [commands to execute] eg /loop i 10 will loop it 10 times, each time it'll increase i by one. The example will also demonstrate a use of format. which can take up to 10 arguments. the first is the string of text, and the subsequent stuff are what'll replace %1 %2 %3 %4 %5 %6 %7 %8 and %9 respectively. You would've also noticed that the executed function like - + div etc is at the beginning of the (). and not inbetween the two values like we're normally used to. if you want to see the original when there's 100 bottles, use /conskip 99 to go to the top of the history. you can also increase the size of the text displayed with /consize.

loop i 100 [say (format "%1 bottles of juice on the wall, %1 bottles of juice" (- 100 $i))]

you should see similar at the top of your screen by executing that

Sandboxer: 5 bottles of juice on the wall, 5 bottles of juice
Sandboxer: 4 bottles of juice on the wall, 4 bottles of juice
Sandboxer: 3 bottles of juice on the wall, 3 bottles of juice
Sandboxer: 2 bottles of juice on the wall, 2 bottles of juice
Sandboxer: 1 bottles of juice on the wall, 1 bottles of juice

Unfortunately with the above, this'll be executed as fast as possible, so we can revamp the script a bit to this

juicecount = 0
juicecounter = "juicecount = (+ $juicecount 1)"

juice = [
    if (= $juicecount 10) [
        juicecount = 0
    ] [
        say (format "%1 bottles of juice on the wall, %1 bottles of juice. You take one down, pass it around, %2 bottles of juice on the wall" (- 10 $juicecount) (- 9 $juicecount))
        juicecounter
        sleep 1000 [
            juice
        ]
    ]
]

very simple it is. this script will wait a few seconds before execution of each loop. a loop limit is imposed as well, so it'll only go to 10. This is alsop without using the /loop command, so there's more than one way to do things

Getting Input

cubescript is limited to an array of 25 arguments most per alias. To actually do anything with the input, you need to use $ and @, usually appended with an arg to say which of the arguments it accepts

text = [say "$arg1 $arg3"]

then typing /text 1 2 3 in the game should return 1 3

lets try a slightly more complex example

mod10 = [say (mod $arg1 10)]

mod stands for modulus, This'll work an any number, as cubescript it limited to integers (no decimal accuracy). 99 mod 10 is 9, and 90 mod 10 is 0. As you probably just realised, it finds the remainder of a division sum.

so typing /mod10 100 should make you say 0

you also have +, -, *, /, !, =, > and < available to use, so go nuts

See Also

• Map Configuration