This is a discussion document for the creation of ApeScript about two years following this document. A lot of the discussion remains current to this day - Tom Barbalet, 9 September 2005.

Scripting the Noble Ape Simulation

Introduction

The motivation to write a scripting language for the Simulation came from two primary sources;

(1) Feedback from users, and,
(2) A personal desire to make the Simulation more programmable.

To date the Simulation has been programmable through two very different means. The first has been through getting the Simulation source code, making modifications and re-compiling the source code. There are rough numbers on the source code downloads that indicates only a fractional percentage of users download the source code. A release, when left for a month, will get about 3,000 downloads for the Macintosh. From this, less than 20 downloads of the source code occur. From that group roughly an email every two months comes in relating to the source code.

The other method of programming the Simulation is through the file format. To date, I have not received an email about the file format. The file format was launched with the Carbon version with a minor bug in the file saving. More than 2,000 people downloaded this version and none reported a problem with the file format. I suspect this was a feature that just wasn't used.

So this begs the question, why add an additional interface to the Simulation that people won't use?

Scripting has actually been a request for the Simulation through a post on download sites. Independently of this, I have also been thinking about scripting the Simulation as a means to solve the Planet Noble Ape as a module of the Noble Ape Simulation problem.

Function Pointers and Plugins

The solution I initialled worked through with the Planet Noble Ape module, was that the functions relating to land and space which moved the planer landscape to a sphere would be workable through function pointers and a plugin-interface. This worked in some way, but it dis-empowered users to create their own environments.

A function-pointer/plugin module required the user to create their own plugins through a C or similar language plugin interface, compile this and then run this on a compatible system. This seemed to play back to the idea of elite users and a large user base that didn't or couldn't get access to the tools required to make an environment.

Breaking this analysis down into haves and have nots, made it clear that the Simulation could be considerably more accessible if it didn't rely exclusively on traditional compiler development.

Speed and Optimisation

On modern operating systems and machines speed was not a problem. On the Macintosh, the main delaying factor in the Simulation was the regularity of the graphics redraw and the fact that certain components of the Simulation were tied to the 72 FPS redraw for scanning. So a relatively low-level scripting language could be easily run in concert with the existing Simulation and graphics.

If the Simulation had one strength, it was its size. A large part of this optimisation had come through extensive code-review and re-writing know as the Stockholm Rewrite, because of where it took place. The Stockholm Rewrite had reduced the code-base by 40% which had reflected directly in the size of the Simulation. Part of this rewrite - in code reduction terms - came in reducing the number of functions used in the Simulation. The introduction of a three-layer maximum in any direction, meant the Simulation rarely had functions, in functions, in functions.

Code Re-Use

The basis of the scripting engine already existed. It was coreio.c. This was a very light-weight but still relatively powerful file format parser/syntaxer and outputter. Although two weren't symmetric, they offered a level of control that could be reused in scripting - at least initially.

The file format in coreio.c could have been XML. Historically it wasn't XML because the XML parser would have been slightly larger to write and the syntax whilst being of a similar level of detailed required notions of completeness that the Noble Ape file format avoided.

The limits to the file format were;

(1) two entities, variables and objects,
(2) three letter identification for variables and objects,
(3) only numerical, positive integer variables, and,
(4) a relatively strict structure.

(1) and (3) were historical anomalies, not part of the original format. In fact (3) was not part of the original format because signed integer values were used. Yet (2) and (4) were definitely there from the start.

So the scripting would utilise the existing file format both through the actual file scripting and through the scripting window.

Scripting Window

One of the initial remits of the Simulation was that it would never contain a text editor. When I wrote compilers, I experimented with writing compilers that contained text editors and command line windows. I found that this took a lot more time than actually writing the compiler and devoting time to optimising the compiler was secondary to fixing the text paste/re-format bug.

A central remit of the Simulation mentioned already in this document is size. The Simulation is not like a word processor or a web browser or most standard feature requiring software. The additional features for the Simulation, things like colour, Ocelot, full operating system integration. These things should come with virtually zero code increase. The largest increase in the development of the Simulation has come through the new file format in 2001. It added about 8-10k to the Simulation. This has been reduced progressively. but it was a sizeable addition. Removing audio from the Simulation reduced its size dramatically too. From the princely size of roughly 100k with audio it fell to 32k without.

From this, an additional window must reuse a substantial component of the existing code. Fortunately the scripting window does this. The basics of console text drawing exist. Monochrome windows and event driven window updates, the Simulation already handles. So with the window and the background aside. What is the scripting language all about?

Features of Scripting: Running the Simulation

The most basic feature of scripting must be 'Run the Simulation until X occurs.' X can be a number of possibilities. These include;

(1) the Simulation is paused,
(2) all the Apes die,
(3) the Simulation advances 102 days,
(4) the Simulation reaches the first day of the fourth year of Simulation,
(5) an Ape reaches a particular point on the Island,
(6) an Ape is drowning, or,
(7) run the Simulation indefinitely.

Another important point is file I/O. The scripting needs to include some functionality to read and write files and to load files through open/save dialogs if need-be. Automated scripting and running additional files following a currently executed file should also be available through scripting.

Features of Scripting: Defined Features become Scripted Features

To-date, the Simulation has been compiled with features that are defined before compilation. These features are known as defined features. The current defined features in the Simulation include;

Whether the ape's brain is simulated
If the land values are rendered with 16-bit integers or floating point
Number of apes in the Simulation
The graphical environment of the Simulation (Ocelot or monochrome)

In addition to these features the brain dynamics have been hard-coded into the Simulation. These will be opened as variables for each ape to allow an added diversity and degree of control. Although this may appear quite academic the ape's personalities can be developed from the brain characteristics. Six values will initially be converted to variables. These govern the asleep and awake states and the competing ideas of fear and desire represented in the brain equations.

Expanding Scripting

The development of scripting with the Simulation is a two stage process. The first stage is described in this document - a parameterisation of existing features as well as adding a greater diversity in the brain simulation. The future development of the Simulation requires additional scripting features. For example the brain states of various apes could be hinged on environmental variables. Hypoglycaemic apes could have different brain dynamics when hungry. Apes with particularly reactions could be programmed for these circumstances through scripting.

The development of this kind of scripting relies on the success of the initial scripting implementation. As this document is only an introduction it is difficult to predict the optimisation and discovery that will come through the initial scripting implementation.

User feedback plays some part with the scripting progression. Scripting will be a passive/background feature in the graphical version of the Simulation, however it will be central for the command-line environment (CLE) version of the Simulation.

Concluding Thoughts

Scripting the Simulation has been discussed through this document in terms of the positive effects it will bring to the Simulation. The intention of adding scripting to the Simulation is to take the existing Simulation and make it more accessible to non-programmers and to those that are interested in tinkering with the Simulation for their own uses. A technical document will be incorporated into the Simulation manual that will detail how to program the Simulation through scripting.

Peace,

Tom Barbalet, 29 June 2003.

Planet Noble Ape - Noble Ape - Noble Ape Documents - the Noble Ape Simulation