Getting Started

To use Kha you need to install git and node (v8.9+). Once those are installed you can use Kha any way you want but the easiest option to get started is Visual Studio Code.

Visual Studio Code

Simply installing the Kha Extension Pack in the extensions panel of Visual Studio Code sets everything up to directly get started with Kha development. It features convenient debugging support based on VSCode's Chrome debugger, Haxe's JavaScript target, and a modified Kha HTML5 target.

To get started, from within vscode open an empty directory on your file system. Press F1 to open the vscode command palette, then search for and execute Init Kha Project. A project template should now be set up in your project directory.

To build and run the project hit F5. If everything was set up correctly in the previous steps an empty black window should open up. Congratulations, you have just built your first Kha project! The result should be located in the build directory at the root of your project folder. Kode Studio contains two debuggers, an HTML5 based debugger which is used by default and the Krom debugger which is more advanced but not yet as stable. You can switch the debugger in the debug panel which you can select on the left side. To build for any other target hit Ctrl+Shift+B which brings up a list of the available targets. You can also change which target is used for code completion via a small drop down menu at the bottom of the window (HTML5 is selected by default).

Visual Studio Code can be configured to use a version of Kha which you handle manually instead of using the one that the Kha extension downloads automatically. This is done by opening up the vscode user settings (File > Preferences > User Settings > Extensions > Kha configuration) and setting the Kha Path to the path of your desired Kha library version. An even more robust way of handling you Kha versions is to put a Kha-subdirectory in each of your Kha-projects - vscode will automatically prefer this version of Kha to the version set with the khaPath-option and the automatically downloaded version.

Command Line

Download Kha using git like so

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

The get_dlc-script downloads the required binary tools for your current system which are setup as git-submodules in the Kha/Tools-directory and the Kha/Kinc/Tools-directory. Be aware that when you use git clone --recursive this will download all tools for all operating systems and CPU-types which works fine, too but results in a very big download.

To create a new Kha project run node /path/to/Kha/make --init inside of an empty directory. Now you can create some project files using for example node /path/to/Kha/make (which will create a project for the system you're currently running) or node /path/to/Kha/make html5 (html5 projects compile and run very fast). Project files are by default created inside of a build subdirectory.

When using Windows and the Direct3D9 backend (by default it uses a Direct3D11 backend) you will eventually have to install Microsoft's dxwebsetup.exe. This is included in Kha's Kore/Tools/krafix subdirectory.

As with Visual Studio Code it is recommended to use a Kha-subdirectory in each Kha-project. You can use a Git-submodule to do this and thereby make the versioning of your project and its dependencies very robust:

git submodule add https://github.com/Kode/Kha
git submodule update --init
Kha/get_dlc

You can also clone the Empty project and start from it - but make sure to update Kha afterwards like so:

git clone https://github.com/Kha-Samples/Empty.git
git submodule update --init
Kha/get_dlc

Updating Kha

If you want to update Kha follow this procedure:

cd Kha
git pull origin main
get_dlc

You can alternatively update each submodule to the latest commit on its respective branch:

cd Kha
git pull origin main
get_dlc_dangerously

This can in rare cases break Kha when you get a module which was recently updated but not yet tested within Kha but most of the time Kha points to the latest revisions of all of its submodules anyway.

As a general safety measure please consider running git status in your Kha directory to see what's going on. This will also show when Kha's submodules are at different revisions than the ones Kha points to.