1. History

1.1. Monkey

Monkey was released on March 1, 2011^[1] by Mark Sibly of Blitz Research Ltd.^[2]

1.2. Monkey X

In December 2013, Monkey was re-branded as Monkey X.

The free versions of Monkey X included unrestricted use of the HTML5 and GLFW (desktop) targets; see Mojo (framework).^[3] The open source distribution of Monkey's compiler is written in Monkey, and therefore requires a valid binary distribution to be compiled. Before December 2013, Monkey X's compiler (Transcc) could not be compiled and used by those who had not bought full licenses of Monkey X. In late 2014, Blitz Research partnered with Playniax to make a bundle containing the Ignition X framework, as well as a standard "Monkey X Pro" license.^[4]

In January 2015, "Monkey X Studio" was added to the official website's "Store" section. This acts as a bundle of third-party software, as well as the existing software from the official commercial distribution. This bundle includes: Jungle IDE and Font Machine (A third-party IDE, and font generation tool, both respectively by LemonBytes).^[5] The Ignition X framework. And finally, a full "Monkey X Pro" distribution.^[6]

1.3. Monkey 2

Monkey 2 v1.0.0 was released on 30 June 2016.^[7] It expands the capabilities of Monkey X by adding support for generic classes, 'first class' and lamda functions, structs, built-in multi-threading capabilities, and operator overloading.^[8]

1.4. Cerberus X

In June 2017, official support for the original Monkey X was discontinued and the full version and source were made available for free.^[9] It has subsequently been forked by the community and re-branded as Cerberus X.^[10]

2. Mojo (Framework)

Mojo is the official/commercial application framework for the Monkey X programming language. Mojo has been written for all of Monkey X's official game-based targets, this is done using the native programming languages of each target. Mojo is then wrapped using Monkey X's "external-language" system. Mojo was designed primarily for writing simple 2D games in Monkey X, but like many other APIs, it can also be used for other types of programs. Like Monkey X itself, one of Mojo's goals are to make everything it provides as consistent as possible on all of its supported platforms.

Mojo itself is open source, however, not all implementations are provided openly. Currently the GLFW and HTML5 implementations (Native code) of Mojo are open source. Mojo may be implemented using any language by anyone. The official implementations for the other targets are commercial products, sold by Blitz Research on Monkey X's website.^[11]

Along with the application portion of the framework, Mojo provides graphics, sound, and device input functionality on several targets. Mojo's device-input functionality is built to be "virtualizable" through its native implementations. An example of this being the framework's "touch" input functionality, which some targets "virtualize" using traditional mouse input. The same goes for various targets when handling mouse input. Similar examples of this can be found on mobile platforms for keyboard input. Mojo's input functionality also provides several forms of keyboard functionality, accelerometer support, and game controller support. Because of this framework's design philosophies, games made using Mojo tend to look identical when deployed to other platforms, despite sometimes being based on drastically different technologies.

Mojo supports several image and audio formats. Due to the nature of Mojo, some frameworks are only supported on specific platforms. The way resources are used may also change what formats are supported. For example, Mojo provides a specific music framework, separate from its other audio functionality. This framework may support different formats, depending on the target. A brief rundown of supported formats can be found in Monkey X's official documentation.^[12]

Mojo has been implemented officially and unofficially^[13] for several platforms. Underlying technologies vary between targets, however, several of the targets support OpenGL. Because of this, OpenGL modules are available for these platforms. This functionality is currently dependent on the Mojo framework.^[14]

Mojo does not currently use the WebGL framework for its HTML5 and JavaScript versions, however, a member of Monkey X's community known as Devolonter has done it himself. WebGL is in fact delegated as a generic OpenGL implementation when using the HTML5 target.

The Mojo framework has also seen several "extensions" (Official platform-specific functionality) in the past. A good example of this being display-management.^[15] Some of these platform-specific "extensions" were first provided as a part of target-specific modules (External to Mojo).^[16] Future support for target-specific modules' implementations has yet to be commented upon, and may become deprecated. Functionality provided by Mojo can be assumed as the preferred option.

Mojo has become known to Monkey X's community as an effective cross-platform utility; however, some small features can be inconsistent on specific platforms. Such inconsistencies tend to be documented as such, and sometimes "ignored" on compile-time.^[17]

Several third party frameworks take advantage of Mojo, examples of this can be found in several of Monkey X's "user modules". Additionally, it is perfectly possible to write an alternative framework built on the same implementation-level as Mojo. Such a framework would be able to share common functionality with Mojo, by using several of the same modules. For details, please see: Game targets (technical).

3. Development Roadmap

On May 14, 2015, Mark Sibly, the creator of Monkey, announced the development of Mojo2, a new graphics API intended to supersede the first Mojo module's graphical functionality. The first release of the Mojo2 module came to owners of Pro versions of Monkey X on June 14, 2015.^[18] It was released alongside version 84a.^[19]

4. Official Targets

• 'Standard' C++:^[20] Used for console applications and tools; Monkey X's compiler-translator is built using this.
• GLFW: A native C++ based target for Windows, OS X, and Linux. This target has gone through several revisions, with support for version 3 of GLFW, and a backward-compatible target for version 2.^[21] As of 'version 84a', Windows users may target GLFW3 using ANGLE as an OpenGL backend.^[22] This enables hardware acceleration on Windows systems with DirectX driver support.
• Android: A target based on the Java programming language and Android application programming interface (APIs). There are several variants of this target, depending on the version of Monkey. These range from different targeted API versions to separate Android-based targets, like the Ouya target.
• iOS: A target based on the C, C++, and Objective-C programming languages; compiled using Xcode; LLVM.
• PlayStation Vita: A PSS/PSM and C# and Mono based target.
• HTML5: Based on JavaScript and HTML5. Software using the official OpenGL modules uses WebGL.
• Adobe Flash
• Microsoft XNA: A C# based target for Windows, Xbox 360, and Windows Phone 7; powered by XNA framework.
• Windows RT: A DirectX based C++/CX target usually used for Windows Store applications and games. This target supports Windows 8, and Windows 8.1 including mobile phone variants.
• Ouya: Initially based on the official Java-based Android target, this target was originally developed by Monkey's community. The initial project was started by Jochen "Maverick69" Heizmann.^[23] Today, it's an official target, supporting the same functionality as the standard Android target(s). In addition to this, minor work has been done to accommodate the Ouya console.

5. Unofficial Targets

Most Monkey X unofficial and community-driven targets are at the official community's User Targets section.^[24]

6. Notable Games Made with It

• Crypt of the NecroDancer – Developed by Brace Yourself Games.
• New Star Soccer Mobile – Won Sports/Fitness 2013 BAFTA^[25]
• 2Dark - From Alone in the Dark developer Frederick Raynal.

7. Game Targets (Technical)

_{All information provided is based on the official source code released by Blitz Research on GitHub, as well as any other contributed source code in the public repository. For a full list of official targets, please see: Official targets.}

Game targets are defined as targets which have implementations of the 'BBGame' class. The 'BBGame' class is an externally/natively implemented class described by the official 'brl.gametarget' module (GitHub). This class is used by frameworks such as Mojo as a platform for target-specific application-functionality. Functionality provided by the 'BBGame' class is privately imported, then wrapped in a controlled form by Mojo.^[26] The official targets' native 'BBGame' implementations are provided as open source.^[27] This does not directly apply to frameworks like Mojo.

Therefore, it is possible to re-implement open source, or even proprietary backends for the Mojo framework, this would still require several components to be implemented, however. This is generally discouraged on official targets, due to the commercial nature of Mojo.

Monkey X does not need game-targets to work, targets such as the standard C++ tool (STDCPP) target do not explicitly require a BBGame implementation. Also, most of the official targets do not require implementation of BBGame, either. They do require implementations for frameworks such as Mojo, however. This also means that Monkey X's official compiler (external dependencies disregarded) could technically be built with most (If not all) of the official targets.^[28]

8. Sample Code

8.1. Main Function

#Rem
    This example relies on the 'mojo' module, so it will not compile with a non-game target.
    Mojo comes with all versions of Monkey X, and is implemented for most targets.
    Classes and functions such as 'Image', 'App', 'LoadImage', and 'DrawImage' are provided by Mojo.
    
    NOTES:
        * Knowing Java or Visual Basic may help in learning Monkey.
        * Multi-line comments are described with the preprocessor ala "#Rem".
        * Single-line comments are represented with apostrophes. (Similar to Visual Basic)
        * Variable-naming standards are generally user-dictated.
        * Monkey is statically typed, however it does support automatic type resolution.

        * 'End' may be used to end a scope, however, specific forms of 'End'
        may also be used for clarity. ("End Method" for example)

        * Monkey's compiler is generally "multi-pass", so the placement of elements does not matter.
        This can also lead to different stylistic choices, such as placing fields at the end of classes.
        * This is a modular language (Some Java parallels can be made), however,
        Monkey uses files to represent modules, not classes. This example uses a class
        because it's dictated by Mojo. Monkey is also not strictly object-oriented,
        however, it does fully support polymorphism, and similar strategies.
        
        * This example uses spaces instead of tab-characters for the sake of consistency,
        such practices are discouraged in realistic applications.
#End

' This will enable strict-mode. (This makes the compiler less lenient about code structure)
Strict

' Imports:

' Import the standard Mojo module. (Required for this example)
Import mojo

' Like several C-like languages, but unlike most BASIC languages,
' Monkey uses the 'Main' function as an entry point.
Function Main:Int()
  ' By simply creating a new 'Game' object, the application will be started.
  New Game()
  
  ' Return the default response to the system.
  ' Zero: No errors found. This is system specific.
  ' This point may or may not be reached when the application closes.
  Return 0
End

8.2. Main Class

' This will act as our main class. Multiple inheritance is
' not supported in Monkey, however, interfaces are.

' The 'Final' specifier works similarly to Java, and is not explicitly needed.
Class Game Extends App Final
  ' Fields:
  Field player:Player
  
  ' Methods:
  
  ' These override the 'App' class's methods (Your own methods may also be written in this class):
  
  ' Though, technically 'OnCreate' is a method, some consider it a type of constructor, and may label it as such.
  ' 'OnCreate' is called automatically when an 'App' object is created.
  Method OnCreate:Int()
#Rem
        Most media should be stored in a folder called "ProjectNameHere.data".
        The 'LoadImage' command will load an 'Image' object from the path specified.
        Mojo assumes that what you're loading is in the "ProjectNameHere.data" folder by default.
        
        Variables, especially local variables may also use the ":=" operator,
        in order to use automatic type deduction.
#End
    
    Local img:Image = LoadImage("player.png")
    ' Alternative: Local img:= LoadImage("PathHere.png")
    
#Rem
        Create a new instance of our 'Player' class using the image we loaded.
        As you can see, 'player' is a field, and because of this, an implicit
        use of 'Self' can be assumed if there is no name conflict.
        People familiar with languages similar to C++ would
        know this pointer/reference as 'this'.
        
        Monkey is garbage collected, so there is no
        need to deallocate this object from the heap later on.
#End
    
    player = New Player(img, 100, 100)
    
#Rem
      This will set the update-rate to the rate we specify (X times per-second).
      
      This update rate is also implicitly applied to the draw/render rate;
      however, uses of 'OnRender' are target and system defined, and are
      therefore decoupled from the main update routine.
      
      Setting this to zero will result in a system-defined update-rate.
      Doing such a thing will hint to Mojo that it should attempt to make
      this application update and render, as many times as possible.
#End
    
    SetUpdateRate(60)

    ' The return values of the 'App' class's commands are currently placeholders.
    ' Monkey's documentation advises that you return zero by default.
    ' Returning can technically be optional under certain conditions. (Not always recommended)
    Return 0
  End
    
#Rem
    The 'OnUpdate' method is called automatically several times per second.
    The number of times this is called is based on the update-rate.
    
    Mojo is generally good about implementing fixed-rate behavior,
    it will attempt to update the application more than render if profitable.
    This does not "save you" from the use of delta-timing, or similar techniques, however.
#End
  
  Method OnUpdate:Int()
    ' Add '1.0' to the player object's 'x' variable.
    ' Adding ".0" to the end of a literal can be used to
    ' explicitly describe it as floating-point ('Float').
    player.x += 1.0

    ' If the value of 'x' exceeds the number we specify (In case a literal), set it to zero:
    ' This could also be done using 'Mod', the modulus operator.
    ' (Represented by '%' in several C-like languages)
    If (player.x > 100) Then
      player.x = 0 ' Once again, 'Self' is implicit.
    Endif ' 'End' could also be used here, instead.

    ' Everything went according to plan, now return zero.
    Return 0
  End

#Rem
    The 'OnRender' method is usually called as many times as 'OnUpdate',
    however, this is system and target dependent, the update-rate
    is used as a hint for this, not a demand. For this reason,
    having any code that mutates "in-application" data is
    considered variable and in some ways non-standard.
    
    Normally, all graphical/drawing operations must be done in here.
    However, a non-standard target-dependent way of rendering in 'OnUpdate'
    can be done using the 'BeginRender' and 'EndRender' commands. (Not recommended)
    
    Actions such as loading resources should be done in 'OnCreate' or 'OnUpdate'.
#End
  
  Method OnRender:Int()
    ' Clear the screen, then display a color based on the values specified(RGB, floating-point).
    ' Explicit usage of ".0" is not needed here, as there is no integer overload.
    ' An alternate overload may be used, which clears the screen using a system/Mojo defined color.
    Cls(32.0, 64.0, 128.0)
    
    ' Call our 'player' object's 'Draw' command.
    ' In the event that 'player' is 'Null', this will throw an error.
    player.Draw()

    ' Everything went according to plan, now return zero.
    Return 0
  End
End

8.3. Player Class

' The 'Player' class, as referenced previously (Placement does not matter):
Class Player
  ' Declare all of our fields (Class-local variables):
  
  ' These two variables will act as our position on the screen.
  ' (Alternatively, an 'Array or third-party class could be used)
  Field x:Float, y:Float
  
  ' This will be a reference to an 'Image' object we'll specify.
  Field image:Image
  
  ' Constructor(s):
  
  ' Overloading 'New' mainly works the same way as constructors in other languages.
  ' Returning is generally not recommended for constructors.
  Method New(img:Image, x:Float=100, y:Float=100)
    ' Due to the arguments using the same names, 'Self'
    ' is required to resolve our fields' names:
    Self.image = img
    
    Self.x = x
    Self.y = y
  End
  
  ' Methods:
  
  ' This will be our main render-method for this object:
  Method Draw:Void()
    ' Draw the 'image' object to the screen using our 'x' and 'y' fields.
    DrawImage(image, x, y)
    
    ' Returning in a 'Void' function is not required. (Some still recommend it)
    Return
  End
End