Introduction to Programming with the Noble Ape Simulation

Version 2.1

Please note, this document assumes you have read the Noble Ape Manual;

      https://www.nobleape.com/man/

The manual contains additional information on the Noble Ape file format and ApeScript that may be required to understand this document.

Overview

The Noble Ape Simulation runs on a number of platforms through a number of different interfaces. The term platform here means major OSes like Windows or Macintosh and the term interfaces means command line interface, Noble Ape's Generic Platform Interface (GPI) or the colour Ocelot interface.

If you are developing with the Noble Ape Simulation on Macintosh or Windows, you will probably want the colour Ocelot interface as your interface to the Simulation. For Macintosh, you will need the following directories;

      sim/mac/
      sim/gui/
      sim/script/
      sim/core/
      sim/noble/

And for Windows;

      sim/win/
      sim/gui/
      sim/script/
      sim/core/
      sim/noble/

The source code will compile through GCC, Project Builder, XCode (PPC and INTEL) and VC++ etc. It is periodically tested with all these compilers. The directories can contain legacy make files. These should always be ignored in favour of 'drag and drop' directory compilation.

sim/noble - The Noble Toolkit

The Noble Toolkit fulfills four functions.

  • Provides basic data-structures and types used throughout the Simulation including error handling primitives.

  • Does all the low-level drawing for the Simulation including the Ocelot landscape skin technology.

  • Provides the file handling and string manipulation for the Simulation.

  • Handles a number of low-level functions used through-out the Simulation like random number generation and Bresenham line 'walking'.

    The Toolkit was developed to further modularise some of the Simulation's functionality for porting to Noble Warfare and other third-party applications.

    sim/core - The Simulation Core

    The Core currently fulfills four functions.

  • Maintains the Simulation version number.

  • Provides a number of important constants and structures for the Simulation

  • Creates and models the spatial and temporal aspects of the Simulation. This includes the shape of the land and the time and weather cycles environment.

  • Simulates the Noble Apes in the environment. This includes their movement, sleep and brain functions.

    sim/script - The ApeScript Interpreter

    The ApeScript Interpreter currently fulfills two functions.

  • Syntax-checks and parses the ApeScript. It checks the language logic and then extracts this language logic to a smaller symbolic code.

  • Interprets or ''runs'' the ApeScript code.

    ApeScript allows the user to program the Noble Ape's movements. It was important that ApeScript had a level of control and stability that would allow users to tinker with the code, even create erroneous code, without crashing the Simulation.

    sim/gui - The Simulation GUI Interface

    The GUI interface also fulfills two functions. It;

  • Provides the central platform independent control structure for the Simulation. This includes user IO interaction and a thin layer of file handling to pass into the Noble Ape Toolkit for low-level file handling.

  • Provides the platform independent high-level drawing descriptions of the various windows.

    sim/win or sim/mac - The Simulation Platform Layer

    The final platform (OS) specific code is relatively small versus the substantial platform independent code. This has been achieved over a number of years development. The similarities between platforms allows a minimal translation layer and platform specific code to be the only component of this section.

    Coding Overview

    The Noble Ape Simulation has been developed exclusively in C since 1996. The code base has changed dramatically over this time. With the advent and split of 32-bit and 64-bit machines, the development faces many of the same problems it did through the split of 16-bit and 32-bit machines. The basic types in the Noble Ape Simulation are defined in sim/noble/noble.h as;

          n_byte - type-defined as unsigned char (one byte)
          n_byte2 - type-defined as unsigned short (two bytes)
          n_int - type-defined as long (could be four bytes or eight bytes)
          n_byte4 - four bytes, type-defined unsigned long on 'compatible' platforms

    The n_int value was introduced as the native mathematical integer type. This avoids a lot of type declarations between short and long etc. n_byte2 is typically used for information that is passed into the low-level file handling. There is no negative number handling in the file information extraction and the current coordinate system is based around n_byte2 values. This could change in the future.

    Function Naming

    In general function names will start with the file name they exist within. The main two exceptions to this - the platform specific code which has the plat_ abbreviation (purely historically) and the GUI/control which has currently inherited a number of additional functions through the transition to the Noble Toolkit and ApeScript.

    Some files contain explicit _init, _cycle and _close functions (the 'life of the Simulation') for handling the initialisation conditions and the delta-time (cycle) functions, and the closing of the Simulation.

    Graphics

    All the graphics in the Simulation are generated by the Simulation. The Simulation generates low-level platform dependent set graphics in the Noble Ape Toolkit. The organisation and 'second layer' application of these graphics are defined in GUI/draw and this in turn is driven by GUI/control.

    There are two types of window and thus through the single graphics buffer there are two types of window described. The distinction is simply B&W and colour. The colour windows are 8-bit colour and thus a byte is used per pixel. The B&W windows are byte packed and thus there are eight pixels to the byte.

    The TIME(/METER) and the BRAIN windows are B&W and the TERRAIN and VIEW(/MAP) windows are colour. The TERRAIN window uses the MAP window's offscreen buffer for generating it's image. Basically it skin stretches the MAP window over the dimensional information of the landscape.

    Additional Assistance

    Please don't hesitate to get in contact if you have any questions or comments;

          https://www.nobleape.com/tom/

    There is also a friendly mailing list for introducing developers to Noble Ape;

          https://www.nobleape.com/mailman/listinfo/developer_nobleape.com

    Enjoy!

    Tom Barbalet. Created: 10 November 2004
    Last Modified: 20 August 2005

    • Noble Ape - Noble Ape Documents - the Noble Ape Simulation