Welcome to Twinspire, a collection of software tools developed in the programming language, Haxe and built on top of Kha.

If you have never used Haxe before, we recommend taking some tutorials on this language by following this link.

Once you have familiarised yourself with Haxe, we can begin understanding and using Kha.

Pre-Requisites

Like most tools, we will be required to first download some important libraries before we can begin.

If you have not downloaded and installed Haxe, we recommend doing so. We will be using Haxe 4 in these tutorials, so any one of these versions or later will do. If you are using an earlier version, if perhaps you have already got Haxe projects on your computer using legacy code, note the following:

  • Anonymous functions can now be declared shorthand using () -> {} syntax. In Haxe 3 or earlier, anonymous functions are declared like this: function() { }. The arrow does not exist in earlier versions.
  • We can use enum abstract in Haxe 4. In earlier versions, you needed to use the @:enum meta tag before the abstract keyword to create inline variables that are globally accessed. Abstracts are normally used to create a new type using an underlying standard type. We will be using this primarily to refer to enumerations C-style instead of using the actual enum feature of Haxe for simple enumeration variables.

Once we have Haxe installed, we will need the following components/libraries downloaded and installed.

Kha

To install Kha, we will use git. Navigate to GitHub and install using git clone like so:

git clone https://github.com/Kode/Kha.git

It also has submodules that need to be installed and initialised, so make sure to do this:

git submodule update --recursive --init

Twinspire

Once Kha is installed, we can then install Twinspire. Navigate to GitHub once again and install with git, only this time we will use haxelib.

haxelib git twinspire https://github.com/twinspire/Core.git

Why do we use two different methods to install these libraries? Well, there is a slight gripe with Kha which we will explain with the next tool we need installed.

NodeJS

Unlike most libraries with Haxe which you can install and get away with compiling use the Haxe compiler directly, Kha opted to use it's own build tool and system which forces you to install NodeJS, as without it it can be a hassle developing for Kha.

There is good news, however, if you prefer to install their own editor (Kode Studio) which makes installing NodeJS optional, but we still think it is a good idea as debugging system calls using the JavaScript target does make working with Kha a lot easier, and we will be using system calls throughout our tutorials.

While this does mean installing more tools (and rather unnecessarily), they do provide benefits even if they are not immediately obvious. You can install NodeJS and we will discuss how to build your kha projects without Kode Studio.

To install NodeJS, go to their website and install for your operating system.

If you would like to, you can optionally download and install Kode Studio.

Building Projects

If we are using Kode Studio (a derivative of Visual Studio Code), we can use the in-built tools to build and debug our projects. This is the option we will use but you do not have to.

If you have a different editor you would prefer to use, you can instead debug and build using NodeJS. Make sure you place Kha under the project you wish to build rather than installed under the main Haxe directory. This is what we recommend and so does Kha. This will make sure that each Kha project you have on your computer will work regardless of what version of Kha you use between these projects.

Creating a New Project

To test our environment, make sure to have the following structure in the folder you wish to place your new project in:

- Assets/
- Shaders/
- Libraries/
- Sources/
-- Main.hx
khafile.js

In khafile.js, we need the following code:

let project = new Project('New Project'); // creates a new project with the following title
project.addAssets('Assets/**'); // Use the entire assets folder to obtain the assets
project.addSources('Sources/**'); // Use the entire sources folder to obtain the source code
project.addShaders('Shaders/**'); // Use the entire shaders folder to obtain shader code
project.addLibrary('twinspire'); // Use the library twinspire.
resolve(project); // Build the project.

Most of the options above are self-explanatory, but let's also explain addLibrary.

addLibrary will first attempt to find the directory of the given name inside of the folder Libraries if it exists, otherwise it will assume you have it installed via haxelib. The project will fail to compile if a given library doesn't exist.

You may also need additional libraries if attempting to compile to a target other than JavaScript, such as hxcpp for C++.

In our Main.hx file, enter or copy the following code:

package;

import twinspire.Application;

import kha.System;
import kha.Framebuffer;
import kha.Color;

class Main
{
    public static function main()
    {
        Application.create(
        {
            title: "New Project",
            width: 1280,
            height: 720
        }, () ->
        {

            System.notifyOnFrames(render);
        });
    }

    static function render(buffers:Array<Framebuffer>)
    {
        var app = Application.instance;
        var g2 = buffers[0].g2;

        while (app.pollEvent())
        {

        }

        g2.begin(true, Color.Black);

        g2.end();
    }
}

To build this code, making sure Kha is cloned into our project from GitHub and NodeJS is installed, we can open terminal or command prompt and enter the following:

node kha/make html5

kha/make points to the file make.js in the kha folder, and builds our project to the HTML5 target. We can specify what target we wish to build to, whether that be windows, linux, android, ios or others. It is important to note that there may be additional libraries or information required to deploy to specific platforms, especially on mobile.

Building with Kode Studio

Unlike above, building with Kode Studio is a little easier as it completes these command line executions itself. Using the native debugger, you can launch and test your application as you work with the project versus the non-debug environment of a different editor that may not have Haxe integrated.

It may still be worth following the code above as a starting point and we will start explaining code from here on.

Next Tutorial -> Using the Static Builder