Scripting Essentials

Before you start scripting, you need to understand that OverseerScript™, like JScript, is an interpreted language. This means the code you write is stored as simple text files. Any text editor can open and modify or create these files. Your computer hasn't a clue about how to run them, however. To do that, it must read each line of the script then break it into parts it can understand. It then runs computer language code depending on what instructions it finds in the script. As a result, scripting languages are slower than programs written and compiled to run in the native machine language of your computer.

Scripts are broken into two basic parts - variables and functions. Variables are memory locations for storing things. You declare them with the keyword var followed by the name of the variable. Each of the objects you work with in OverseerScript™ has variables attached to them. These are made available to you so that you might change how the object behaves or looks. Such variables are called properties of the object.

Functions are the sections of code that do things to the variables. There are built in functions attached to each of the objects you work with. These built in functions are called methods of the object to differentiate them from other functions that you create. To create a function, first type function, then the name of the function, a list of variables that will be sent to this function when you need it to work, followed by an open brace ({), then some code. Close the function definition with a close brace (}). 

For example, to create a function that squares a number you would write:

function squareANum(num)
{
   return num*num;
}

JScript has a number of built in objects. Refer to the JScript documentation for a list of these and the properties and methods you use to work with them. OverseerScript™ adds many more objects that you can use to control the 3D environment of City Overseer 3D®. 

When City Overseer 3D® first starts, the first set of scripts it loads will be found in a file named Global.js. This file can be found in the City Overseer 3D® program directory. Since this file loads each time City Overseer 3D® loads a map, you should only put scripts in here that are important enough to always be made available. 

The next script that City Overseer 3D® can encounter during the loading of a map is found in the map note <CO3D.Map.PreLoad>. This note is not required and you cannot reference any map objects in it as they have not yet been loaded. You can, however, set program startup options, such as the starting view mode with Overseer.viewMode.

If you are creating a series of maps that form an adventure or campaign, you can create an external text file with a JS extension that contains functions and variables you will use over many maps. Then in the PreLoad note of each of your adventure maps, have City Overseer 3D® load this text file with the Overseer.Include method. You can thus reuse your scripting code. This external JS file would be a great place to script the loading of campaign variables from the registry using Overseer.GetCampaignVar. In this way you ensure that all of the campaign variables are loaded before the map starts.

Following the PreLoad note, if it is included in the map, City Overseer 3D® runs the initialization scripts in any Hotspots it finds and sets up the Activation and DeActivation functions.

After all objects have been loaded, including Hotspots, City Overseer 3D® will process any scripts it finds in map note <CO3D.Map.PostLoad>. Since all of the objects for the map have been loaded at this point, modifying them with script is now possible. You can also include external JS files here.

The 3D cartographer creates scripts using a text editor for external JS files and a set of commands within CC2. CC2 has the ability to hide and show Hotspots and they are hidden by default. If you need to edit Hotspots, make sure CC2 is showing them by selecting Show Hotspots, found on the Info menu. Create Hotspots either with the Make Hotspot command, found on the Info menu, or by typing O3DSCRIPT, a command added when City Overseer 3D® installs that provides a script editor that is larger and accepts more lines than the CC2 editor. Edit Hotspots using either the Edit button () or by typing O3DSEDIT, another command added when City Overseer 3D® installs.

To write and test scripts prior to putting them into a map, open the JScript editor in City Overseer 3D® by either typing CTRL-J or by selecting JScript from the View menu. The JScript console will open where you can enter your script. After entering, click on the Run button to execute it. When you are done, cut and paste the code by highlighting it with the mouse, press CTRL-C to copy it to the clipboard, and then use CTRL-V to either paste it into an external JS file or into a Hotspot on the map.

Copyright© 2001 Thought Guild Inc.