Usage & Installation¶

ktox-lua is distributed as a Gradle plugin. This guide will help you set it up in your Kotlin project.

Installation¶

Add the following to your build.gradle.kts file:

1. Apply the Plugin¶

plugins {
    id("com.isycat.ktox.lua") version "1.0.0"
}

2. Configure the Transpiler¶

Use the kotlinToLua block to configure the transpiler. All options use standard Kotlin DSL assignment syntax.

Minimal:

kotlinToLua {
    // Directory where generated .lua files are written. 
    // Defaults to <buildDir>/generated/lua
    outputDirectory = layout.projectDirectory.dir("outputDir/vscripts")
}

Full:

kotlinToLua {
    // Directory where generated .lua files are written. 
    // Defaults to <buildDir>/generated/lua
    outputDirectory = layout.projectDirectory.dir("outputDir/vscripts")

    // Root package namespace. Strips this prefix from require() and output paths.
    // Example: "com.example.app" -> generated files start at "app/"
    rootNamespace = "com.example"

    // Lua file (relative to outputDirectory) executed by the `runLua` task.
    luaEntryPoint = "Main.lua"

    // Directory containing Lua tests (.lua) executed by `runLuaTests`.
    // Defaults to `src/test/lua`.
    luaTestDirectory = layout.projectDirectory.dir("src/test/lua")

    // Optional list of package prefixes to include (empty = all).
    includePackages = listOf("com.example.features")

    // Package prefixes that should NOT generate require() calls (e.g. game APIs).
    skipRequirePackages = setOf("com.example.game.api.", "native.")

    // File-level marker annotations that EXCLUDE a file from transpilation.
    // A file whose header carries any of these (e.g. `@file:KvSource`) is treated as
    // build-time DATA consumed by other tooling, not code - no .lua is generated for it.
    excludeFileAnnotations = setOf("KvSource")

    // Copies `ktox-lib.lua` runtime to the output directory. Defaults to true.
    copyKtoxLib = true

    // Fails the build if Kotlin compilation has errors. Defaults to true.
    failOnKotlinErrors = true

    // Writes a `mappings.yaml` source-map for offline debugging tools.
    writeMappingsYaml = false
}

Project Structure¶

Typically, your Kotlin source files should be located in src/main/kotlin. The plugin will mirror the package structure in the specified outputDir.

For example, com.example.features.ControlFlowDemo.kt will be transpiled to outputDir/vscripts/features/ControlFlowDemo.lua.

Gradle Tasks¶

The plugin adds several tasks to your Gradle project:

Task	Description	Group
`transpileKotlinToLua`	Transpiles Kotlin sources to Lua. Wired into `assemble`.	`build`
`runLua`	Runs the Lua entry point (set by `luaEntryPoint`).	`build`
`runLuaTests`	Executes Lua tests in `luaTestDirectory`. Wired into `check`.	`verification`
`checkLuaOutput`	Compile-checks every emitted `.lua` file (load only) with the bundled LuaJ. Wired into `check`.	`verification`

runLua¶

This task depends on transpileKotlinToLua. It uses the bundled LuaJ interpreter to execute your code. Ensure you have set luaEntryPoint in the configuration.

runLuaTests¶

This task searches for all .lua files in your luaTestDirectory and executes them. It is an excellent way to verify your transpiled logic using a real Lua environment.

Runtime Support¶

All transpiled code requires ktox-lib.lua to be available in the Lua path. The plugin automatically copies this library to your outputDir.

require("ktox-lib")