Introduction to Programming the Noble Ape Simulation

http://www.nobleape.com/sim/

Overview

This document introduces the Noble Ape Simulation to a programmer interested in working with the Noble Ape Simulation. The Noble Ape Simulation is in almost constant development. Where ever possible, I have included historical references of development to give some background to context in the Simulation.

Glossary

Carbon - An Apple term, referring to a linking API which will run on both Mac OS X and Mac OS 9 and maintain the look and feel of both platforms.

CLE - Command Line Environment, a command line interface to the Noble Ape Simulation

Codewarrior - Metrowerks Codewarrior, a popular compiler for the Macintosh

GLUT - A derivate of OpenGL for making stand alone applications within OpenGL

GPI - Generic Platform Interface, a Noble Ape operating system independent development skin, a means of linking Noble Ape's development with a number of different operating systems

GUI - A layer of the graphical user interface version of the Noble Ape Simulation including the Platform interface, the OpenGL interface and the Ocelot interface

Mailout - A monthly post from Noble Ape, subscribed through a link on the front page of the website and archived on the website

Noble Ape - a number of technologies linked through a central website

Noble Apes - the sentient inhabitants of Noble Ape

Noble Ape Simulation- software that simulates biological environments and cognitive behaviour

Noblemake - a pre-compiler which links source files or text files (http://www.nobleape.com/noblemake/)

Ocelot - a realtime colour non-polygonal graphics engine, used with the Noble Ape Simulation to view the landscape environments of the Simulation

Planet Noble Ape - a planetary simulation developed to link in with the Noble Ape Simulation

Platform - an interface to various operating systems

Project Builder - Apple's compiler for Mac OS X

Simulation Core - a set of files which describe the Noble Ape Simulation's Simulation component, operating system and interface independent

Source Log - an updated log of Noble Ape current developments including the Noble Ape Simulation

SourceForge - a repository of Open Source developments

Vector/VectorGraphics/Vect3 - the basic line interface to describe landscapes, developed by Barbalet in the early 1990s

Background

Prior to the Noble Ape

Prior to Noble Ape, a number of the technologies used in the Noble Ape Simulation existed. The landscape visualisation engine, Vect3, was developed in 1992-1993 and followed from the Vect1 and Vect2 engines developed in 1990-1991. The cognitive simulation component was used prior to Noble Ape as were aspects of the Noble Ape movement. The early Noble Ape manuals, found in the documentation section of the Noble Ape website, provide a detailed background on this.

Noble Ape Formed

Noble Ape was formed in June 1996. It initially gathered momentum with the documentation and software integration. The original Noble Ape Simulation was a combination of technologies co-existing through simple component interfaces and working together most of the time. It was fundamentally demo software with a number of features being added exponentially until version 0.32 (early 1997).

Technically, the Noble Ape Simulation was developed on two compilers over this time - THINK C (circa 1988) and Microsoft Visual C (Windows 3.1). The primary compiler, THINK C was a Macintosh 68000 compiler developed roughly eight years before Noble Ape was founded. I used the same version of THINK C for four or five years prior to Noble Ape and cobbled together my own set of feature fixes which effectively upgraded the compiler's features but gave nothing near the compiler technology that was available in 1996.

Following the THINK C legacy, when the development received a grant from the Australian Film Commission in 1997, Symantec C++ (an upgrade to THINK C) was purchased. This opened up sections of the Noble Ape Simulation and promoted a brief multi-window colour Noble Ape Simulation codenamed Iota (Isle of the Apes).

The THINK, Symantec and Microsoft technologies were all drag-and-drop project-based compilers. The legacy of make et al was not replicated on the Mac and thus did not filter through to the Noble Ape Simulation development. An early port of GCC was tested, together with Apple's MPW, for use with Noble Ape on the Mac. Neither provided sufficient documentation or ease of use.

The Noble Ape Simulation code was written to provide a simplicity of source that would be understood by an entry level Computer Science student or an interested programming hobbyist. Sadly, this has not always been replicated on the Operating System interfaces, but a simple interface to the operating system has attempted to reduce this problem.

Development Continues - Source Online Again

In 2000, the Noble Ape Simulation 0.32 source code was dusted off and modified to run with Metrowerks Codewarrior compiler for the Mac. Somewhat romantically, this redevelopment took place on a train trip from Los Angeles to New York. Three days of focused development was finished with the first public display of the Noble Ape Simulation in three years, at New York University.

The newly modified version 0.32 source was put online and got mixed reviews! The source code was poorly structured and the divisions between the numerous technologies were relatively apparent through the code. The code was heavily reworked and the original OS graphics method was replaced with an internal line, point and icon renderer. This sped up the Simulation considerably. The regularly updated graphics was the bottle-neck of the Simulation.

Stockholm Rewrite

In June 2001 - Noble Ape was at a turning point. The website had been frozen for four months and Noble Ape's development was continuing offline and through a page on Geocities. The domain name was offered a five figure sum, and a choice had to be made about the direction of Noble Ape - in particular the Noble Ape Simulation.

I was able to collect my thoughts in Stockholm. I was there for a week with my employer at the time, and spent the afternoon and evenings of my time there reworking the Noble Ape Simulation and listening to the music from Noble Ape 1997-2000. This re-development of the Noble Ape Simulation, referred to as the Stockholm Rewrite, developed the Noble Ape Simulation as a Simulation Core and various interfaces which provided graphics and user assess to the Simulation Core.

The source code was reduced by 40% and the number of functions were halved without reducing any functionality. The modern Noble Ape Simulation file format was born. The new Noble Ape Simulation included a command line version and an OpenGL interface as well as an improved and streamlined Platform graphics interface.

From June 2001 to April 2002, the source code was heavily developed. Components were tested and added and a number of functions were modified and combined. With the new Noble Ape Open Source license, which came out of the Stockholm Rewrite, the Noble Ape Simulation was hosted by SourceForge.

Logging the Simulation

From April 2002, all Noble Ape development was logged online with a source log. This source log contained daily updates on the development of the Noble Ape Simulation. Some highlights from the source log included;

  • the Carbon port of the Noble Ape Simulation on 7 June 2002 (now with an automatic compile to Carbon if detected on the Mac through either Codewarrior or Project Builder),

  • the Noble Ape Simulation Command Line Environment (CLE) running on Windows on 24 July 2002,

  • the four window version of the Noble Ape Simulation (now the standard Platform interface) on 22 August 2002,

  • a fully object-based Noble Ape Simulation on 22 November 2002, and,

  • the Ocelot development including the initial screen shot on 27 August 2002, the Ocelot source going online on 29 September 2002, and the Ocelot interface fully integrated into the active source of the Noble Ape Simulation on 6 December 2002.

    Not to forget;

  • the Windows GPI port on 20 April 2003,

  • the rise of the Noble Ape Developers' Mailing List on 30 April 2003,

  • the GPI Linux port of the Simulation (thanks to Mridul P) in late June 2003, and,

  • Apple's World Wide Developers' Conference port of the Noble Ape Simulation for Altivec and threading on 25 June 2003.

    Code

    The Noble Ape Simulation is written in C. The Simulation Core has been ported to Java in 1997 without much difficulty - this Java version has begun redevelopment and is currently hosted with the other Noble Ape development archives on Sourceforge. The concepts in the Simulation Core translate well to object oriented languages. The legacy of the C development comes with the low-level graphics. These are required to eliminate possible bottle-necks in the Simulation.

    The Noble Ape Simulation is developed under the Noble Ape Open Source License. A copy of the license is atop every source file in the Noble Ape Simulation. The latest source code is available via CVS on SourceForge. There is a link on the Noble Ape Simulation's page. This page also lists zip and hqx versions of source code from recent releases.

    Many sections of the code are in constant development. Very little of the code remains the same even from the June 2001 Stockholm rewrite. The code-base is relatively small and manageable. This is a secondary aim of the Noble Ape Simulation. The code must be small and maintainable. New features do not displace old, but new features are best integrated into the existing methodology.

    In general, macros are used instead of #if points to clarify code or to simplify obscure code. Constants are typically capitalised (not always) and variable names are being expanded for understanding. There are varying levels of comments through the code. This is something still being developed. It is intended that documentation will balance code commenting to give an overview of the structure rather than a comment per two or three lines of code. (Ocelot is the current exception to this with a comment per line!)

    Getting the Source Code

    The CVS and a release archive for the Noble Ape Simulation is hosted on Sourceforge under the UNIX name;

    nobleape

    To get the source from CVS;

    cvs -d:pserver:anonymous@cvs.nobleape.sourceforge.net:/cvsroot/nobleape login

    cvs -z3 -d:pserver:anonymous@cvs.nobleape.sourceforge.net:/cvsroot/nobleape co active

    And hit return when asked for a password. This version is a number of files, which make up the active source. You can compile a GPI version of the Simulation for Windows, Linux or Mac, or Planet Noble Ape, as well as the full Ocelot and VectorGraphics versions for Mac. Interestingly enough, this active source also contains a number of documents - including this one.

    Sourceforge also maintains the legacy code from the Nervana Simulation including the CLE and GLUT version of the Simulation. That CVS can be found here.

    Alternatively, the Noble Ape Simulation page;

    http://www.nobleape.com/sim/

    has the last version's source code in Stuffit/HQX and ZIP compressed archives. For those who are interested, there is also a mailing list for the development of the Noble Ape Simulation;

    https://lists.sourceforge.net/lists/listinfo/nobleape-developer

    The mailing list is a good mix of code and philosophy.

    Structure

    Simulation Core

    All versions of the Noble Ape Simulation use the Simulation Core directory /sim/core/. This contains the Simulation code for the landscape (land.c), the biology (biology.c) and the sentient Noble Apes (being.c). It also contains coreio.c, the data format interface for files or network traffic. It is descriptive and text based. There is some indication to develop an XML version of the Noble Ape Simulation file format in the future.

    The Simulation Core also contains two header files. version.h describes the version of the Simulation. The Simulation is versioned in 0.001 increments. Initially the Noble Ape Simulation was versioned with 0.1 increments until 0.3, then 0.01 increments were used until 0.65. The change in increments reflects the number of features that need to be added before the version 1.0 release. If you do the mathematics, with 0.001 releases and 8 releases/year, I will be 69 years old when we reach version 1.000. If we manage 14 releases/year, I will be a spritely 51 years of age when we reach 1.000. In short, the Noble Ape Simulation is a long term development.

    The second Simulation Core header file is core.h. This contains the structures and constants used through the Simulation Core.

    Data Types in the Simulation Core

    There are four scalar data types used through the Simulation Core. Three of these are integer-defining data types, nv_XintY (where X is u for unsigned or s for signed and Y is 8 or 16 Y-bit integers). You will note there is no signed char, long values nor char. The reduction of integer types comes for two reasons.

  • The original Simulation on the 68000 had problems dealing with more than 8-bit x 8-bit multiplication. This rippled through the mathematics used in the Simulation Core, and,

  • the Simulation Core links directly into the GUI layer on some versions of the Noble Ape Simulation. Here the range and multiplicative range of these values is important too.

    The final scalar value is LANDVAR. Originally the Noble Ape Simulation used a 16-bit signed integer land calculation value, but with a need for a higher resolution and a smoother look, a double floating point was used. This change is set with the define HIRES_Z_ON, which is normally set to 1. On older processors, this can be set to 0 but it will produce rougher land output. There are various defines at the top of core.h which are typically preset. These should only be altered after you have some experience of the Simulation.

    In addition to the scalars noted, there are two important structures defined in core.h. These are noble_land and noble_being defined for land.c and being.c respectively.

    The island values contain two random numbers which change as the Simulation is run. The date and time on the simulated islands in days and minutes respectively. The weather on the island represented by scalar values and the basic genetics that describe the island. These base genetics then give 256 land values which are selectively multiplied to produce the z value at any given point. A lot has been written about the method of creating the island landscape. The Noble Ape Simulation manual online gives information on this.

    In addition to the noble_land values, the Noble Apes' are defined with the noble_being structure. This currently contains the direction the Noble Ape is facing. The location of the Noble Ape in x and y coordinates. The date the Noble Ape was born and a unique ID number which describes each Noble Ape on the island. Also the Noble Ape's brain and the Noble Ape's brain a minute before.

    In addition to this, there is the energy the Noble Ape currently holds and also the speed the Noble Ape is currently travelling. The Ape must stop to eat, so through the day the speed will go to zero when the Ape needs to eat. Then progressively as the Ape eats their energy rises.

    In the future, I would like to add more features to the Noble Ape describing factors which could be represented with scalars and simple vectors.

  • The Noble Ape's present health condition (including any injuries), and,

  • desired location of movement (if applicable), etc

    The Noble Ape Simulation allows for these kind values to be calculated and effected through the Simulation Core.

    Command Line Environment

    The CLE was developed to test components of the Noble Ape Simulation quickly and without the overhead of graphics. When the Simulation was ported to the PC, the CLE was used to test that the same values were being seen through the simulation of a single day. This identified machine specific properties of multiplication which effected the outcome of old random number generation. This has since been fixed.

    The CLE relies heavily on Noblemake, a C and text pre-compiler which takes the Noble Ape Simulation core files and produces a single C file for compilation. Noblemake was also used and tested on an early Platform compile. This development is maintained together with the GPI development which relies heavily on Noblemake for multiple platform pre-compilation.

    The CLE is not maintained to the same level as the Platform implementation of the Noble Ape Simulation. If you require assistance with getting the CLE to compile, please get in contact with me.

    OpenGL - GLUT

    Similar to the CLE, the GLUT implementation of the Noble Ape Simulation was maintained heavily in 2001 but has fallen a little back in development terms in 2002. This interface was developed for UNIX machines and other platforms that had OpenGL implementations present. The interface was relatively basic. It showed the island environment and the biological graphs generated as selected by the user. This code is not heavily maintained through the Noble Ape Simulation. If you need to use this implementation, please get in contact with me.

    GUI - Graphical User Interface to the Noble Ape Simulation

    After this document was initially complete, I wrote a document introducing the graphics in the Noble Ape Simulation in greater detail. This new document, supersedes the information presented here.

    Graphics in the Noble Ape Simulation

    The most developed interface for the Noble Ape Simulation is referred to as GUI (funnily enough). It is a platform independent graphics with keyboard, mouse and menu user input interface. The GUI layer features;

    control.c - main link point from the Platform (or GLUT) interface above to the Simulation Core (Graphics level 3)

    draw.c - draws meters, landscapes, contour maps etc (Graphics level 2), and,

    display.c - the basic primitives of pixels, lines, icons, text-characters and (with Ocelot) skins (Graphics level 1).

    GUI supports single and multiple window implementations of the Noble Ape Simulation and the all new Ocelot interface. Like the Simulation Core, there is a central header file, gui.h. This primary describes the allocation of window memory and how to draw spots on the screen which is platform dependent in memory terms.

    The Noble Ape Simulation has its own internal graphics. The GUI layer defines an array where B&W or colour graphics are written which then gets written directly to the window in the Platform layer. This method was developed to be standardised and to minimise bottle-necks. There are macros that define new window drawing areas of memory. This was developed in early 2002 for the multi-window implementation.

    The GUI layer also has three defined scalar values representing an 8-bit byte, a coordinate value and 32-bit word. A scratch value for general calculations may be added in the future. This was included for particular platforms to test if particular scalar types caused problems (initially Mac 68000 but other operating systems/processor configurations too).

    The Noble Ape Simulation has historically used a Vect3 interface for drawing landscapes or terrain maps (this is replaced by Ocelot in the most part). Vect3 remains in draw.c to allow for monochrome developments in the future and currently through the GPI etc.

    Ocelot

    The Ocelot (colour) interface can be turned on by setting INTERFACE_OCELOT to 1 in gui.h. Ocelot describes an optimised function called na_skin in display.c. It produces a smooth landscape from a 128 x 128 point array and rotation value. It is heavily documented in the source. The Ocelot interface requires some additional colour code in the Platform layer too which is included for both the Mac Classic and Mac Carbon implementations of the Platform layer.

    Platform

    For most implementations of the Noble Ape Simulation, above the GUI interface layer is the Platform layer. As this document is written, there is a Generic Platform Interface (GPI) which is being developed for a single window monochrome version of the Noble Ape Simulation on a number of platforms.

    Currently, the Platform interface is developed for the Mac. A Carbon or 'Classic' version of the Noble Ape Simulation would use;

    /core/
    /gui/
    /mac/

    The project type and compiler is found through #if etc in the code. The Classic version of the Noble Ape Simulation contains file handling too. This feature is being introduced to the Carbon version with testing. Eventually the Classic version of the Noble Ape Simulation will be phased out.

    Generic Platform Interface (GPI)

    The Generic Platform Interface (GPI) was developed to introduce more people to Noble Ape including the Noble Ape Simulation. Maintaining Noble Ape's code base and developing the technology is quite time consuming. The GPI was developed to maximise the number of platforms Noble Ape's software could be ported for.

    The modern GPI provides a monochrome and single window view of the Noble Ape Simulation. It has been developed for Mac, Linux and Windows, and currently provides a Windows and Linux version of the Simulation - albeit through a monochrome, single window. It can be turned on by setting INTERFACE_GPI to 1 in gui.h.

    Apple Distribution

    Aside from the Mac version of the Simulation, two Apple engineers, Sanjay Patel and Nathan Slingerland, developed a version of the Noble Ape Simulation that took advantage of threading (dual processors) and Apple's Altivec vector architecture in the G4/G5 chips.

    This version was displayed by Sanjay and Nathan in late June 2003, at Apple's World Wide Developers' Conference. Following the conference, Nathan and Sanjay donated the source back into the Noble Ape Simulation development. It is currently maintained under a difference CVS directory. To get the Apple Distribution;

    cvs -d:pserver:anonymous@cvs.nobleape.sourceforge.net:/cvsroot/nobleape login

    cvs -z3 -d:pserver:anonymous@cvs.nobleape.sourceforge.net:/cvsroot/nobleape co applesrc

    And hit return when asked for a password. This version is also updated and distributed with Apple's Developer Tools and the CHUD toolkit.

    Scripting

    An additional component to the Simulation which will be introduced in the next couple of versions is scripting. Scripting in the Noble Ape Simulation will allow all the compiler defined functionality to be changed on the fly and a number of new features added to the Simulaiton Core. Early docmentation on scripting the Simulation is available from the documents section of the Noble Ape website.

    The Noble Ape Simulation is Open!

    The Noble Ape Simulation has been developed with many thousands of hours of development time. Your contribution in using the Simulation, reporting problems, integrating the Simulation into your own code or contributing to the Simulation code, helps!

    You can subscribe to the Noble Ape Mailout and get monthly updates on the Simulation and the other software of Noble Ape. If you want to know what has been happening with Noble Ape and the Noble Ape Simulation within the past couple of days, I maintain a Source Log on the Noble Ape site.

    I welcome questions, comments, bugs or contributions. This document was written as a brief introduction. I plan on adding a number of additional documents to build off the various sections here.

    Enjoy!

    Tom Barbalet.
    First Written: 5 December 2002
    Document tracked and updated in CVS


    Noble Ape - Noble Ape Documents - the Noble Ape Simulation