ApeScript is a procedural scripting language developed for use with the Noble Ape Simulation. ApeScript is small, memory efficient and highly modular and could easily be ported to other applications. This document describes using both ApeScript and the ApeScript implementation specific to the Noble Ape Simulation.

ApeScript requires an initial execution function which must be located at the physical end of the script file. In the case of the Noble Ape Simulation this function is the being function.

function ( being ) {
}

All other functions must be defined above the being function. There is no function ordering other than placing the being function at the end of the file. Similarly, all other functions can be referenced as variables. This will be expanded on later in the document. But it is important to note that the being function can not be referenced as a variable.

Variables and functions in ApeScript can be made up of any letter or underscore. Numbers or other characters can not be included in variables or functions. It may prove easier as you are learning ApeScript to think of functions as a particular kind of variable. In fact, ApeScript will define the function variable as the point in the interpreted scripting code where the function is defined.

Functions (other than being) are called by the keyword run. For example;

function ( second_time ) {
run ( first_time );
}

function ( first_time) {
}

function ( being ) {
run ( second_time );
}

Similarly, the following would also work;

function ( second_time ) {
run ( which_one );
}

function ( first_time) {
}

function ( being ) {
which_one = first_time;
run ( second_time );
}

Here you see the variable which_one being set at the function location before it is run in second_time. Normal variables can be defined in a single instance between 0 and 65535. This is deemed the normal operating range of definition in ApeScript. You can define a variable;

big_minus = 0 - 65535;

But as you will see this is the limit in a single line.

A variable through use can reach the 32-bit signed min/max of -2147483648 to 2147483647. This can be achieved through cumulative operations.

ApeScript allows a wide variety of mathematical and logical operators. The only limit (currently) in ApeScript is that a line of code can only contain two input variables, one operator, one equality and one output variable.

output_value = input_one + input_two;

The number of operators may be subject to change in the future. Your best source for the current operators is the Noble Ape Manual. Similarly it is possible that the negative definition without the zero subtraction or multiple operators used. All this is possible in the future.

A little naming convention from international English. Brackets refer to this ( and this ).Braces refer to this { and this }. The only use of brackets is run, function, if and while. Similarly, the only place where braces can be used is function, if and while. The check for if and while are based on the same initial premise;

if ( condition ) {
run ( will_be_run );
}

while ( condition ) {
run ( will_be_run );
}

If condition doesn't equal zero, then will_be_run will be run in the if and while operator. The while operator will continue to execute will_be_run until condition equals zero. If condition is zero, then will_be_run will not be executed.

The following example shows both if and while being used in a practical context.

This being function identifies each visible being to the current_being.

It's important to take a step back and ask the question - what is the being function?

Put simply, the being function is run per Noble Ape in the Simulation. The ape that is currently being run is identified by the variable current_being. Initially - at the start of the being function - select_being is set to current_being. However through the script execution select_being can be set to anything from 0 to number_beings - 1.

This page describes the current version of the Simulation's special ApeScript variables and how they link to the Simulation. If you develop ApeScript, print this page. If you have any questions from the page email them directly to tom at nobleape dot com. To date, the ApeScript and the Noble Ape Simulation page has been rewritten based on additional information requests. This digression aside, you need to understand what each of the variables mean. The term, output, means you can't set anything to this variable. It is only useful on the right hand side of an equality assignment.

Scanning down to the Being section of the ApeScript and the Noble Ape Simulation page, you will note that three variables aren't based on select_being. Of the variables that can be changed in the being (aside from the brain values) only facing, speed and energy can be changed. This means that you can only change the direction facing, the speed and the energy an ape has. Not the Ape's location directly. The location is changed through the direction facing and the speed set. The brain values relate to current_being. Obviously one being can not effect the brain of another being directly.

Consider the metaphysics of the individual being functions and the being functions when run together in a single time cycle.

As things are currently ApeScript is an interpreted language. It is integrated in the Noble Ape Simulation but there are still conditions that will cause ApeScript to substantially slow down. Particular variables take longer time to process than others. The biology_output variable is relatively time consuming. is_visible is extremely time consuming. Getting and setting brain_value may be slightly more time consuming than addition.

If you experience lock conditions, rework the code to create fewer loops over less variables. Be mindful of the variables that are really pseudo variables (like is_visible or biology_output) which in fact result in substantial code in the Simulation being run to produce a single value.

There are some properties of ApeScript that may prove useful in practical applications. Whilst the ApeScript specification is simple, the underlying elements of the specification allow a number of features common to more complex languages.

The switch statement is common in many languages - it allows from an input variable a number of possible choices based on that variable. Consider the case with four possibilities.

This works because each case function decomposes to the same number of interpreted bytes. This idea of interpreted bytes is rather subtle, but it is the basis of functions as variables representing points in the interpreted bytes. Now suppose there are a variety of lengths in each function. The functions do distinctly different things and can't be guaranteed to have the same number of interpreted bytes.

Here the functions of the same number of bytes is put in a tight block. This block has the same number of bytes but they refer to different functions that have different numbers of bytes. Applications of if functions may be preferable;

For folks looking for traditional array memory, the brain memory provides this for ApeScript. The initial complication is that the Noble Ape brain memory has a time and space based function to move information through it. To stop this effect the brain constants (that govern this spreading of information through the brain) can be set to zero through the variable file. Looking at the Noble Ape source code;

Each memory entry is a single byte. If you want to put larger variables into memory, such as the full range of an ApeScript variable, you will need to write code to spread the variable through the bytes. For example;

ApeScript has a debugger built into it. Currently this provides a file of the Script code being run for a single cycle of the first being being simulated. Using some of the example code from the first set of notes.

What this shows is the numerical representation of the first_time function set to which_one. The function second_time is run, then which_one is run successfully. Relatively uneventful. But an accurate indication of the code run.

Quite luckily the time & 3 resulted in 3 for which_function. Relatively uneventful with a straight pass-through for number_a = number_b; But still, the debug output is quite useful to verify the method works and the output is exactly as expected in terms of picking the correct function.

As you can see, an error is fired and recorded in the debug output. This is very useful for novice and expert ApeScript authors alike. You will find yourself writing long bits of code and the debugger may be the only indication that the code won't run correctly.

ApeScript allows you to create variables on the fly. Please consider including additional debug values that immediately identify the section of the script information.

The Noble Ape Simulation currently has two types of files it reads and one type of file it writes. The Simulation reads and writes variable files. These contain the immediate variables bar the 64k of brain values. These values may be included with future variable input and output files, but at this time, there is little practical use for such large additions to the relatively minimalist variable files. The variable file format is described in great detail here.

In addition to variable files used for input and output, there are script files. These script files are the subject of the ApeScript Notes documents. It is important to think about how the variable files and the scripting files can work together - both in terms of debugging and testing.

For example, if you want a particular part of a script to run with a specific ape, the apes ID number (id_number based on select_being) should be the best test for running specific code for a specific ape.

It is important to note that the current version of ApeScript has two parts - a parser and an interpreter. The parser takes the text information present in the script file and converts it to ApeScript interpretable byte codes. Aside from actual code, these byte codes contain the constant number values used through the script.

It is possible to generate a parser error such as using an unrecognizable character or a set of symbols that are not recognized, ++ for example, that won't result in an error that will be shown in a debug file. Please be mindful of this. If you require this information to feature in a debug file, please make contact (tom at nobleape dot com).

To explain the logic of why parser errors are not treated as interpreter errors comes in part from the handling of variable files. If a variable file fails to load, it shouldn't display an error. Users may load dud files accidentally and it should effect the Simulation's running in any way. Similarly, a parser error typically indicates that the file loaded is not a script file and not that the logic of the script file will be compromised.

In the case of genuine errors, ApeScript will either produce an error or in the case of extreme logic errors - like an infinite loop for example - the interpreter will allow the user to quit or create a new simulation environment.