khafile.js · Kode/Kha Wiki · GitHub
Skip to content

khafile.js

Jump to bottom Edit New page
Robert Konrad edited this page Apr 7, 2026 · 42 revisions

Kha uses a javascript file called khafile.js where you configure your project. A basic khafile.js looks like this:

var project = new Project('ProjectName');

project.addAssets('Assets/**');
project.addSources('Sources');

resolve(project);

This set the Assets and Source folders, and uses the default configuration for other options.

Adding Assets

Basic

Set the Assets folder:

project.addAssets('Assets/**');

Advanced

khamake will flatten your directory structure during preprocessing. Suppose you have some non-unique files like map.txt in folder1 and folder2.

Using the basic version will actually give you an error during preprocessing, as khamake will try to create kha.Assets.blobs.map_txt twice. To fix that, specify some patterns to actually keep the folder structure in the generated sources.

Asset folder layout

/assets
   /folder1
      map.txt
   /folder2
      map.txt

khafile.js

project.addAssets('assets/**', {
    nameBaseDir: 'assets',
    destination: '{dir}/{name}',
    name: '{dir}/{name}'
});

Now access them with

kha.Assets.blobs.folder1_map_txt
kha.Assets.blobs.folder2_map_txt

Caveat

Do not create files with names that are haxe keywords (default.png is bad, _default.png is fine).

Add a Custom Icon

Add the icon.png file to the root project directory to use it as a new icon. The desired resolution is 512x512 or 1024x1024 for high-dpi monitors. You can also set custom path:

project.icon = 'path/icon.png';

Add a Source folder

project.addSources('Sources');

You can use multiple source folders, including external folders.

Add a library to the project

project.addLibrary('Kha2D');

The library needs to be in a folder called 'Libraries' in the root of your project, or can be a haxelib library.

You may also define your own libraries folder with:

project.localLibraryPath = 'libs';

Add a Subproject

await project.addProject(pathToProject);

khamake can integrate other Kha projects, it will parse their khafiles and include all sources, shaders and assets. Be aware that addProject is asynchronous - use await to synchronize execution.

Add a Shader folder

project.addShaders('Sources/Shaders/**');

Add a Compiler Flag 

project.addParameter('-dce full');
project.addParameter('-main Main');

Add a Conditional Compilation Flag

project.addDefine('debug_collisions');

Add a Conditional Compilation Flag for Kore builds

project.addCDefine('SOME_DEFINE=1');

Register callbacks for build events

khafiles can react to specific events during the build process:

callbacks.preAssetConversion = () => { };
callbacks.preShaderCompilation = () => { };
callbacks.preHaxeCompilation = () => { };
callbacks.postHaxeCompilation = () => { };
callbacks.postHaxeRecompilation = () => { };
callbacks.postCppCompilation = () => { };
callbacks.postAssetReexporting = (filePath: string) => { };
callbacks.postBuild = () => { };
callbacks.onFailure = (error: any) => { };

Set specific options for the HTML5 target

project.targetOptions.html5.disableContextMenu = true;
project.targetOptions.html5.canvasId = 'my-custom-canvas-id';
project.targetOptions.html5.scriptName = 'my-custom-script-name';
project.targetOptions.html5.webgl = false;

Set the initial window size in HTML5

project.windowOptions.width = 1366;
project.windowOptions.height = 768;

Set specific options for the Android target

const android = project.targetOptions.android;
android.package = 'com.example.app';
android.versionCode = 1;
android.versionName = '1.0';
// https://developer.android.com/guide/topics/manifest/activity-element.html#screen
android.screenOrientation = 'portrait';
android.permissions = ['android.permission.VIBRATE'];
// https://developer.android.com/guide/topics/manifest/manifest-element#install
android.installLocation = "internalOnly";
// https://developer.android.com/guide/topics/manifest/meta-data-element
android.metadata = [];
// same as <meta-data android:name="disableStickyImmersiveMode" android:value="true"/>
android.disableStickyImmersiveMode = true;
android.globalBuildGradlePath = 'data/android/build.gradle';
android.buildGradlePath = 'data/android/app/build.gradle';
android.proguardRulesPath = 'data/android/app/proguard-rules.pro';
// for files in Android Studio project-level dir
android.customFilesPath = 'data/android/files';

Set specific options for the iOS target

project.targetOptions.ios.bundle = 'com.example.$(PRODUCT_NAME:rfc1034identifier)';
project.targetOptions.ios.organizationName = 'Your Awesome Organization';
project.targetOptions.ios.developmentTeam = 'XXXXXXXXXX';
project.targetOptions.ios.version = '1.0';
project.targetOptions.ios.build = '1';

(to find your development team ID, visit https://developer.apple.com/account/#/membership and use the alphanumeric code under Team ID)

Add a custom footer

Table of Contents

Clone this wiki locally