Jump to: navigation, search

Tutorial Scripting

The scripting language

Cubiverse "runs" any world through the execution of Javascript on the server. This Javascript is written by you and controls almost every aspect of the world from cubes to the environment. This section gives a brief overview of how scripts make the world come alive; and how you can create almost (hopefully) any game you desire :)

Cubiverse has a number of precautions and safe guards to prevent illegal scripts from executing. For example if you create a infinite loop in a script, the world will fail to start (if the infinite loop is inside the initialisation code) or will be killed (if the infinite loop is inside an event or some timer). Please note that when any of the safe guards kick in I will be notified and repeat offenders will be banned from Cubiverse.

How do worlds exist?

When the world is first created, usually by a player typing a published CubiURL, the system will spin up a world instance matching the CubiURL. From this point on the world instance will exist until the last player leaves that world, and all other's who type the CubiURL will join the same instance. If the instance is "full" (I'm not quite sure what full is atm) then the system will spawn another instance of the world. When new players join the same world (and there are free slots on either world) they will be given a choice as to which world to join (usually based on the best ping or latency).

Different script types

It's impossible to represent all the functionality through a single script type (or to be technically correct, Java-script object).

Cubiverse has various types of scripts, most common are scripts attached to cubes, players, mobs or some generic script (which exists inside a "generic script entity").

How scripts are structures

In order to fully understand how scripts work, we need to pull apart a sample script to show its structure. In this case we will look at a script that is normally attached to a cube. These scripts inherit from an object created by Cubiverse itself, namely the "CubeScript".

This CubeScript provides lots of build-in properties and methods, for example the position of the cube (as a property) or the ability to teleport the player (as a method).

   liftCubeObject.prototype = new CubeScript() ;

   function liftCubeObject() 
   {
      this.name = "my little cube"
   } ;
 
   liftCubeObject.prototype.onWalkOn = function() 
   {
      log("The name of this cube is " + this.name) ;
   }

   var liftCube = new liftCubeObject() ;

   registerCubeScript(liftCube)  ;

Let's start by breaking down the script and explaining its individual parts.

  liftCubeObject.prototype = new CubeScript() ;

This next step "inherits" the CubeScript object and is REQUIRED in all cube scripts. The Cubescript object is key here, it adds all the default properties that the CubeScript has (such as position information, texture settings, etc.) to the lifeCubeObject.

  function liftCubeObject() 
  {
     this.name = "my little cube"
  } ;

This is the initial declaration of our object (I suppose you could think of it as the constructor) allows you to set variables or run functions (such as setting the initial time of day for the world).

  liftCubeObject.prototype.onWalkOn = function() 
  {
     log("The name of this cube is " + this.name) ;
  }

The "onWalkOn" event occurs when any player ways on the cube, in this case we use the debug API call "log" to display a message. This message is only visible when editing the world (in the server console) and normal players will never see it. The log statement simply output's the string "The name of this cube is" along with the contents of the "this.name" variable, which would show "The name of this cube is my little cube".

  var liftCube = new liftCubeObject() ;

This line actually turns the definition of the "lifeCubeObject" into a real object using the Javascript "new" command.

  registerCubeScript(liftCube)  ;

The final, and REQUIRED, line tells Cubiverse that the current Cube (i.e. the one you are editing, and entering this script for) has the script "lifeCube" attached to it.


Spinning up world and script initialisation

Scripts are just chunks of Javascript code and like all Javascript code they have stuff you want to run at initialisation, in this case world initialisation.

All scripts (regardless if they are connected to cubes, players, environment, etc) can do anything they want during init, most of the time its setting up initial values for variables (like the this.name variable in the example above).

When a world is first instigated (or you "run" the world by exiting the world editor) all scripts are compiled and executed, this means your initialisation code get called at that point. Care should be taken that your init code's do not take a long time to return, as the world will be killed if it takes too long (you will get an error messsage).

Changing the world

When you enable the world editor the server will place the world into edit mode, all scripts will be instantly killed. The contents of any run-time information (like Javascript variables and objects) are STALLED (note: they are not erased, or reset like when a world is first started). The main reason for the "pause" is so you correctly think about what happens when new players join the world, in the middle of what might be your game state.

If there is want for the world to be "paused" instead of reset then please talk to me, there is going to be issues with paused world (like editing a script so use another scripts contents, so that there is a mismatch).

Where next?

Its probably best to read the Scripting API this gives you all the events and API calls that can be made for each type of entity in the world.