Home | Contact | Download | Reference | Tutorials

Forum

KAMScript New User Tutorial

Introduction
Installation
Using the KAMScript Editor
Using KAMScript Commands
Navigation
Debugging
The End

Introduction

Welcome to KAMScript. This is a program that lets you place 2D images, 3D objects and sounds in a 3D. (Note: images, objects and sounds are all referred to as props that can be put in your scene.) KAMScript's advanced features include lighting options, animation, and variable usage. Once you have created your KAMScript scene it can be run in the CANVAS.

This tutorial is intended to teach new KAMScript users the basics of the program: how to create a new scene, how to put props into that scene, how to debug the scene, and how to find resources to learn more advanced features.

	There are three parts of KAMScript that you should know about. The first part is the data folder (a folder that you name). All of the files that you want to place in the scene must appear in this folder.
	The second part of the program is the data text file (which you also name). This is the file where your scene will be saved.
	The third part is the KAMScript editor (KSeditor.exe). You will use this program to create, open, edit, save, and run your KAMScript scenes.

A note on the files types you can use: You can only use JPEG (.jpg) files for 2D images. You can only use object (.obj) files and their accompanying material (.mtl) files for 3D objects. You can only use MP3 (.mp3) files for sounds.

So how do you use this program?

In order to use KAMScript, you need to download KAMScript from the website and install it, write commands in the KSEditor, and debug your scene to ensure it runs smoothly. This process is discussed in detail below.

Installation

The first step to install KAMScript is to visit the download page. There you have two options.

If you are on a computer that does not allow you to install programs (for instance, a computer in a lab at the University), download the "files only" version (this for KAMScript 004). Simply unzip those files to the desired location on the computer you will be using and KAMScript is ready for you to use.

If you are on a computer that allows you to install programs (for instance, your personal computer at home), you probably want to download the "with setup wizard" version (this for KAMScript 004).

Once you have download the install files, open the zip file and run setup.exe. The installation process is fairly simple from there; in the first window, click "Ok" to indidcate that you do actually want to install this program.

In the next window, click on the picture of the computer to install KAMScript to the directory specified (the default is C:\Program Files\KAMScript004 for KAMScript 004). Once the installation process is complete you can start using KAMScript.

Using KAMScript Editor

KSEditor is basically a text editor (like Notepad) that allows you to create, open, and edit KAMScript files. An example KSEditor window is shown and explained below.



At the top of the KSEditor window are the words KAMScript Editor followed by a dash and the name of your data text file in brackets (in this example, [KAMScript_data.txt*]).

Below this are the program options: File, Edit, Project, Options, and Help. The File menu allows you to: create a new scene; open an existing scene; save the scene that is currently open; save the scene that is currently open under a different name; open a recent scene; and exit the program. The Edit menu allows you to: undo and redo changes you have made to the scene; cut, copy and paste text in the editor window (mentioned below); and find and replace text in the editor window. The Project menu allows you to open the scene data folder (where all of your props are located) and run your scene. The Options menu allows you to change various KSEditor options. The Help menu takes you to the KAMScript reference website or gives you more information about your version of the KSEditor.

Below the program options is the toolbar. Clicking on icons (from left to right) allows you to create a new file, open an existing file, save the file you are working on, undo changes to the file, re-do that you undid, and "play" your file.

The status bar is below the toolbar. This shows you information about the line that the curser is on. In the example, the cursor is on line 1. The status bar will be useful to help you remember what arguments need to go in your KAMScript command.

The editor window is the big white space below the toolbar. This is where you will type in and edit your KAMScript commands.

Below the editor window is the second tool bar. The second tool bar shows you if your capslock and number lock are on your keyboard are on as well as displaying which line the cursor is on.

The column at the left side of the window shows you how many lines are in your KAMScript data file. The line that the cursor is on will be highlighted in bold. In the example, the cursor is on line 1.

To create a new KAMScript file, go to File --> New. To save a KAMScript file for the first time, go to File --> Save As. You can then save your KAMScript data file using whatever name you want. Keep in mind that your data file must be in the same folder as the props you will be using.

Using KAMScript Commands

Note: The file described in the rest of the User Guide is a KAMScript scene that you can download here. You can open that file in KSEditor and follow along with the guide if you wish.

The best way to learn how to use KAMScript commands is to see some examples. Below is a working example of a KAMScript data file that has been opened in KAMScript Editor. Some lines are explained below the image; some lines are broken up into columns to make explaining them easier.


Note: The format of the command lines includes parentheses ( ), commas , , and brackets [ ]. The brackets are there to make reading the information in the line easier and are not actually necessary, but the parentheses and commas must be in the format shown in order to work.

Line one is completely unnecessary to the program and is there to identify the columns that are discussed below.

Lines one, three, four and five start with //; this means that those lines are comments. A comment is a line that the program will not read and you can write anything you want there. This is useful if, for instance, you want to write a description of the scene you're creating.

The actual text of lines three, four and five is a model of how to write lines in the KAMScript data file (similar in function to the status bar). What each part of these lines does is explained below.

column one - OBJECT, IMAGE, SOUND

column two - (filename.obj;-.jpg;-.mp3,

column three - [x pos, y pos, z pos],
column four - [rot x, rot y, rot z],
column five, line three - [scale x, scale y, scale z])
column five, line four - [width, height])
line seven - BACKGROUND(#000000)/(0,0,0)/(0)
Lines one through fourteen are fairly basic commands. Lines 16 though 22 are slightly more complicated and will be explained below.

line sixteen - COLOR(#339933)
line seventeen - BOX([0,0,-20],[0,0,0],[10,0.2,40])
line eighteen - BOX([0,13,-20],0,0,0],[10,0.2,40])

line twenty - SPIN(.5,1,.5)
line twenty-one - OBJECT(3dDog.obj,[0,7,-37.25])
line twenty-two - STATIC()


If you've understood these explanations up to this point, you should understand what you need to do to start placing your own props. If you do, that's good. You probably want to check out the section on navigation next. Also, make sure to look at debugging before you're done.

If you're still not sure what's going on, check out the rest of the website (especially the reference section). Also, it would be a good idea to just change around some of the information in the example KAMScript data file just to get a feel for things. Make sure to look at navigation and debugging as well.
Feel free to contact us if you have any questions or would like assistance.

Navigation

Right now, the navigation of KAMScript is a bit tricky. When you run your scene in KAMScript you probably notice something that looks like the picture below in the lower right corner of the KAMScript window (note: the KAMScript window is titled szg or KAMScript #0).

This is the Simulator and it is a graphical representation of where you "are" in your scene. The white outline (which is actually a cube) represents the 3D space of your scene. The yellow thing is actually a head and is supposed to show your position in that space and where you are looking. The white box with the green circle below all the numbers represents the a joystick is used to navigate. The green and blue cross with the purple circle is the wand. The wand represents the controller that is used with the CANVAS to navigate around your scene. The numbers in the red circles represent the different modes you can use to navigate your scene.

There are seven different modes used to navigate through your space. You access each of these modes by pressing the numbers on your keyboard (as far as KAMScript is concerned, 0 does nothing). Use each mode by pressing down the left or right mouse buttons and moving your mouse.

	The default screen, which is what comes up when you first run your scene, is shown here. No translations or rotations have been made in this scene. Each of the seven navigation modes is explained below. Note: To make the Simulator invisible, press SHIFT-S. To make it re-appear, press SHIFT-S again.
	[1] Move head (formerly Translate head) This mode does not work in KAMScript 004. This mode allows you to move the head in the x and y directions if you left-click and move the mouse; if you right-click and use the mouse, you can move the head in the x and z directions. You can move the head out of the white cube space. Note the changed position of the head in the simluator in the screenshot.
	[2] Turn head (formerly Rotate head) This mode does not work in KAMScript 004. When you left-click and move the mouse, this mode allows you to rotate the head around the y-axis and is equivalent to turning your head to look at something. Right-clicking and moving the mouse rotates the head around the x-axis and is equivalent to looking up and down. Note the changed rotation of the head in the screenshot.
	[3] Move wand In this mode, the left mouse button allows you to move the wand in the x and y directions. The right mouse buttons allows you to move the wand in the x and z directions. Note the changed position of the wand in the screenshot.
	[4] Move wand + buttons This mode allows you to use certain features on the CANVAS that you will not use in your scenes (so you don't need to worry about it).
	[5] Turn wand + buttons This mode allows you to point the wand in the direction you want to use. You do not press any mouse buttons; just move the mouse around. (If you press '5' a few times, the wand will return to its default rotation. This is useful if you get confused as to how your wand is pointed.) Note the changed rotation of the wand in the screenshot.
	[6] Use joystick This mode allows you to move through your scene in the direction that the wand is pointed. Also note that if you try to move left or right you will also move forward or backwards a little bit. The left and right mouse buttons do the same thing in this mode. Note that your position in the scene has changed the screenshot.
	[7] Turn Simulator This mode allows you to rotate your view of the simulator. It does not change how you view your scene but will change how you navigate through it. The right and left mouse buttons both do the same thing in this mode.

The best way to navigate around a KAMScript scene is to use [6] Use joystick. In this mode, clicking and holding down a mouse button acts the same as pushing a joystick to navigate.
Note that this mode alone does not let you move up and down the y-axis. To do that, use [5] Rotate wand + buttons to point the wand either straight up or straight down and switch to [6] Use joystick and click and hold to go in the direction you chose. After that, press 5 a few times to reset the want position, and use [6] to navigate around again.


Once you have navigation figured out, look at line 15 in the demo KAMScript data file. Take out the '//'s; this will make line 15 a command instead of a comment so the object will appear in the scene. (Note: This particular object blocks the lighting of some of the images so you will not be able to see them.) Use the [5] Rotate wand + buttons and [6] Use joystick modes to navigate over to the object for practice. Navigate back to the area with the four images for more practice. If you can do that, you know just about all there is to KAMScript navigation (until it changes, of course).

Debugging

Two windows pop up when you run your scene. The title of one screen is szg (or KAMScript #0 for versions of KAMScript before 004). This is the navigation window and is not discussed here. The other window, titled something like C:\KAMScript\KAMScript.exe (depending on where your KAMScript folder is located), is the debugging window.



The image above is what the window looks like when your program has no errors (notice the ***ERRORS: 0 line). This window also shows you what props you have placed and where you have placed them. Another nice feature of the debugging window is that it shows Current Head Position with the x, y and z coordinates of where you are located in your scene. These coordinates update every few seconds (depending on your computer speed).
Note: Everything above the WELCOME message is not important so don't worry about it.

Here is an example of a KAMScript data file that has errors in it.


This is what your debugging window would look like if you tried to run that code.

In KAMScript, errors occur when commands are not typed in correctly. Errors include: typing in too many numbers for coordinates, rotation and scale/size; not putting // before a comment; and not putting commas and parentheses in the correct places.

If your program has errors, your debugging window will tell you what the errors are and in what lines they occur. You should go back, look at the lines that are causing errors, and fix them.

In the example, errors are as follows:

Line 7: Because it is neither a proper command nor a comment, that text should not be there.
Line 11: There is an extra number added to the rotation numbers.
Line 12: The line does not end in a ).
Line 13: There needs to be a comma between 15] and [0.
Line 16: Sounds can only have x, y and z coordinates. They cannot be rotated or scaled.

Note: If an error occurs when trying to place a prop, that prop will not be placed but other non-erroneous props will still be placed in the scene.
Note: Current Head Position is not displayed when an error occurs to make the debugging process easier.

The End

This is the end of the new user tutorial. If you have any questions, comments or would like clarification on anything in this guide, please visit the contact page and let us know.

To learn about the advanced features of KAMScript, please visit the reference page.