Hello World!
Good day ladies and gents. This is the first in hopefully a long series of tutorials related to learning the Anim8or Scripting Language (
ASL for short). In this tutorial, you will learn how to print the traditional "Hello World!" statement in the console while discovering some basics about programming in general.
What you needGetting StartedBefore we can dive straight into writing ASL, there are a few things you need to do first to prepare yourself.
Set up your development folderEven if you already have a Scripts directory set up with Anim8or, I recommend making a new folder elsewhere strictly for script development. This way you will eliminate the clutter that all the other scripts will cause. Clutter = stress & confusion, especially when debugging code.
I recommend also that you keep this development folder in the cloud. Dropbox is a good first choice, as there is a form of version control that allows you to pull up previous versions of the same files. This might save you some headaches! There are also other cloud services such as Microsoft's OneDrive and Google Drive. Alternatively, if you have your own server, you can install Bittorrent Sync.
Define your development folder in Anim8orDepending on what type of script you're developing, you'll need it to automatically load in Anim8or. To do so, open Anim8or and go to File->Configure...
And click on the '...' next to the Scripts input field. Navigate to your development folder and press OK. While still in the Configure dialog, enable the "Preload Scripts" option. While you're at it, make sure "Script Console" is also enabled, and press OK.
Restart Anim8or to see the changes take effect.
Set up your ASL editorAny text editor will do for editing ASL scripts, but here are three that I can recommend to varying degrees:
- Notepad: The most basic text editor of all time. You type in text, you save text. No formatting or line numbers or anything even remotely fancy. Useful for Hello World tutorials, and that's about it. Hit your Windows key and type in "Notepad" in the search field, and there you go.
- ASL Editor: Written by Kubajzz, one of our own, this is an editor specifically for ASL. It includes cool features such as Syntax Highlighting, Line Numbers, Auto-Complete, and even a Parametric Shape Button editor. Unfortunately, it is no longer being developed, so it does have some bugs and hiccups, and is not up-to-date with v0.98+ ASL changes. I recommend this program for basic editing at best.
- Notepad++: This is a popular text editor, and has many extensions for various file formats. It also supports themes, so you can darken the colors for less stress on the eyes. I recommend this program for those who want more barebones control. Attached to this post is a ASL.xml file that can kick-start your ASL experience in Notepad++. Just go to Language->Define your language, then click on Import, and import the ASL.xml file. Afterwards, files with the ".a8s" extension should automatically have syntax highlighting. Note: This file is for darker themes.
Creating your Hello World!Let's dive straight in! As we go along, I'll give a quick explanation of what each line does. More detailed explanations on the various elements of code can be found in the
ASL Specification and in future tutorials.
First, open your text editor and save a blank file as "Hello World.a8s" to your development folder. The .a8s file format is automatically recognized and compiled by Anim8or when it opens. If it's a shape script, it will show up in your shapes toolbar. If it's a command script (such as this Hello World script), it'll show up in your Scripts menu. If it's an export script, it'll show up in the Object->Export dialog box. If you save it as a .txt file, it won't be automatically detected nor show up anywhere, but you can execute it at any time by going to Scripts->Run Script File.
Alright, to start with, let's make a comment! Type in something like this:
ASL Snippet
/* Wow! This is a block-style comment! Anything between the asterisks
will be ignored, even if on more than one line!!! */
// This is an inline, or end-of-line comment. Only text on this line will be ignored!
That's fun and all, but comments serve a very useful purpose. They help you organize your code and let you and others know what's going on. You should get into the habit of commenting everything! For example, look at this block of code:
ASL Snippet
float $getFaceArea(shape $s, int $f)
{
int $i;
float $a, $b, $c, $perimeter;
for $i = 2 to $s.GetNumSides($f) - 1 do
{
$a = length($s.GetPoint($s.GetFacePointIndex($f, 0)) - $s.GetPoint($s.GetFacePointIndex($f, $i - 1)));
$b = length($s.GetPoint($s.GetFacePointIndex($f, $i - 1)) - $s.GetPoint($s.GetFacePointIndex($f, $i)));
$c = length($s.GetPoint($s.GetFacePointIndex($f, $i)) - $s.GetPoint($s.GetFacePointIndex($f, 0)));
$perimeter = ($a + $b + $c)/2;
return sqrt($perimeter*($perimeter - $a)*($perimeter - $b)*($perimeter - $c));
}
}
Do you know what's going on? You can guess by the name of the function, $getFaceArea, that it gets a face's area, but what if you had to go in there and edit the code? Imagine this except with hundreds of lines of code! Horrible!
Below is the same code except with comments. Now with just a glance you know what each part of the function does, and helps you to figure out what each line is trying to accomplish.
ASL Snippet
/* float $getFaceArea
Retrieves a face and calculates the surface area
*shape $s - Shape that contains the face
*int $f - Index of the face to be calculated
*/
float $getFaceArea(shape $s, int $f)
{
int $i;
float $a, $b, $c, $perimeter;
/* Loop through each point of the face */
for $i = 2 to $s.GetNumSides($f) - 1 do
{
/* Get the lengths of each side of each triangle, one point is always the first */
$a = length($s.GetPoint($s.GetFacePointIndex($f, 0)) - $s.GetPoint($s.GetFacePointIndex($f, $i - 1)));
$b = length($s.GetPoint($s.GetFacePointIndex($f, $i - 1)) - $s.GetPoint($s.GetFacePointIndex($f, $i)));
$c = length($s.GetPoint($s.GetFacePointIndex($f, $i)) - $s.GetPoint($s.GetFacePointIndex($f, 0)));
$perimeter = ($a + $b + $c)/2; /* Calculate perimeter */
/* Now calculate the area using Heron's Formula */
return sqrt($perimeter*($perimeter - $a)*($perimeter - $b)*($perimeter - $c));
}
}
Alright, enough scary-looking code, let's get back to Hello World! At the start of every script, it's useful to explain what the script does, who wrote it, who else might deserve credit, any dates or bugs or changelogs, etc. So clear the file and put this as your header:
ASL Snippet
/*
* Hello World! Script
* Author: [Your Name]
* Version: 1.0
* Date: [Current Date]
*
* This script prints out "Hello World!" in the console. Yay!
*/
Now run the script file in Anim8or. You can either restart Anim8or every time and go to Scripts->Hello World or just go to Scripts->Load Script File and select the script (then go to Scripts menu and find another Hello World menu item added to it). You can also run it directly since it's a command script, by going to Scripts->Run Script File. Whenever you load a script after making changes, check the console for error messages!
You may come across an error message that says
missing or invalid directive, script not installed. Oh no!
What's a directive? Well, a directive is a line of code preceded by the "#" symbol. All .a8s scripts require a directive before any line of code (excluding comments) in the script, to tell Anim8or what type of script it is. If this were a .txt script that you wanted to run using Scripts->Run Script File, you would not need a directive. Add this line to the code, below the header:
The #command directive tells Anim8or to place the script in the Scripts menu for easy access. "object" indicates that this is for the Object editor. Therefore this script will be located in the Scripts menu of the Object editor.
Next, let's make a string variable! A variable is a data type that stores information. A string is a series of characters such as the letters in the statement, "Hello World!". So a string variable is a data type that stores a series of characters. But first, we must declare that variable before we can use it. You have to declare variables beforehand so that Anim8or will allocate the memory needed to store it. So add this line to your code:
What does this do? First, "string" precedes the variable when declaring it, to tell Anim8or what type it is. In Anim8or, you can declare multiple string variables on one line by separating the variables with commas.Such as below:
Variable names in ASL are preceded by the dollar sign ($). All statements must end with the semicolon (
. This is called a terminator (or separator), that tells Anim8or that the statement has ended.
A side note: camelCase is a common practice when creating variable names. The first word is lowercase, while the next words are uppercase without spaces or underscores between the words. Spaces are illegal in a variable name. Also, variable names cannot be preceded with a number. For example, "$1_apple" is illegal and would throw up an error.
Now let's assign some text to that variable!
ASL Snippet
$helloWorld = "Hello World!";
are very basic functions that perform operations on elements in the statement. What is 1 + 2? The 1 and 2 are operands, and the
+ is an
operator. Other operators include =,-, *, /, <, >, %, ||, &&, and are explained in the ASL specification.
So = is an assignment operator that assigns the "Hello World!" characters to the $helloWorld variable. All strings, when typed out in code, must be enclosed in quotation marks ("").
Now, how do we get this printed out in the console? If you run the script,
ASL Snippet
/*
* Hello World!
*
* Author: [Your Name]
* Version: 1.0
* Date: [Current Date]
*
* This script prints out "Hello World!" in the console. Yay!
*/
#command("object");
string $helloWorld;
$helloWorld = "Hello World!";
Nothing shows up! Well, we need to initialize the console and send a print command to it. So first, let's create a file variable. For the sake of organization, try to declare your variables in one location. So let's declare it immediately after the string declaration:
ASL Snippet
string $helloWorld;
file $output;
Files in Anim8or are exactly what you might suspect. Anim8or treats the console window as a file, allowing you to open, print, and close access to the console just like you might with a file on your hard drive (save that for another tutorial
). So first, we must open the console using the following statement (place it after the variable declarations):
ASL Snippet
$output.open("$console", "w");
.open() is a member function of the $output object we created. Member functions are basically preprogrammed actions that activate when called. Parameters are passed in the parenthesis when required. In this case, "$console" tells Anim8or that the target is the console rather than some file on the hard drive. "w" is the mode, and in this case tells Anim8or to open the console for
writing.
Almost done! Now we need to tell Anim8or to print the contents of the string into the console. Let's use this line:
ASL Snippet
$output.print("\n%s\n\n", $helloWorld);
Woah hey, what's all the \n's and %s's? ASL uses a C-like print function, meaning that you map out the formatting and variables in a string using special characters.
Let's break it down a bit further.
\n is a newline character. It creates a new line, and everything afterwards is placed on that new line. So \n\n makes a double spacing. %s represents the content of the first variable in the list of variables following the string. In our script, there's only one variable indicated afterwards, called $helloWorld. So when printed out, %s will get swapped with the contents of $helloWorld.
If we weren't using variables, we'd do something simpler like this:
ASL Snippet
$output.print("Hello World!");
If we wanted to use two variables, one a string and one an integer, it'd look like this:
ASL Snippet
$name = "Bob";
$numApples = 3;
$output.print("%s says there are %d apples in the basket!", $name, $numApples);
The output of the above statements would look like this:
Bob says there are 3 apples in the basket!Anyway, let's get back on track. Whenever we open a file, we must close it. So at the very end, add this line:
The final script should look something like this:
ASL Snippet
/*
* Hello World!
*
* Author: [Your Name]
* Version: 1.0
* Date: [Current Date]
*
* This script prints out "Hello World!" in the console. Yay!
*/
/* Directive */
#command("object");
/* Declare variables */
string $helloWorld;
file $output;
/* Assign string to the variable */
$helloWorld = "Hello World!";
/* Initialize the console, ready for writing */
$output.open("$console", "w");
/* Print to the console */
$output.print("\n%s\n\n", $helloWorld);
/* Close the console */
$output.close();
When you run it, the output will look like this:
Congratulations! You made Anim8or say Hello to the world!
