HUGE UPDATE: 2/6/25 - Direct USF (Unreal Shader Format) backend is now live! Compile KORE shaders directly to production UE5 code with -t usf. HLSL backend also fully functional.

KORE V1 - Production Compiler

Production-Ready Release: This is the stable, feature-complete V1 compiler with Actor runtime, UE5 shader pipeline, Python FFI, and multiple compilation targets. While the V2 self-hosting compiler (in the root directory) is under active development, V1 is battle-tested and ready for production use.

Philosophy

KORE combines the best ideas from multiple paradigms:

Rust's Safety - Ownership, borrowing, no null, no data races
Python's Syntax - Significant whitespace, minimal ceremony
Lisp's Power - Code as data, hygienic macros, DSL-friendly
Zig's Comptime - Compile-time execution, no separate macro language
Effect Tracking - Side effects in the type system
Actor Concurrency - Erlang-style message passing built-in
Universal Targets - WASM, LLVM native, SPIR-V shaders, Rust transpilation

Quick Start

cargo install kore-lang

That's it. You now have the kore command available system-wide.

Build from Source

If you prefer building from source:

cd kore-v1-stable

cargo build --release

Binary: target/release/kore (or kore.exe on Windows)

CLI Reference

Main Compiler (`kore`)

# Run in interpreter (instant execution)

./target/release/kore example.kr --target run


# Compile to WebAssembly

./target/release/kore example.kr --target wasm -o output.wasm


# Compile to LLVM IR (then link with clang)

./target/release/kore example.kr --target llvm -o output.ll


# Compile to SPIR-V (GPU shader bytecode)

./target/release/kore shader.kr --target spirv -o shader.spv


# Transpile to Rust source code

./target/release/kore example.kr --target rust -o output.rs


# Run tests

./target/release/kore test_file.kr --target test


# Watch mode (auto-recompile on file change)

./target/release/kore example.kr --target wasm --watch

Compilation Targets

Target	Flag(s)	Output	Notes
WASM	`-t wasm`, `-t w`	`.wasm`	Web applications
LLVM/Native	`-t llvm`, `-t native`, `-t n`	`.ll`	Native binaries
SPIR-V	`-t spirv`, `-t gpu`, `-t s`	`.spv`	Cross-platform shaders
HLSL	`-t hlsl`, `-t h`	`.hlsl`	DirectX (direct codegen, no middleman)
USF	`-t usf`, `-t ue5`	`.usf`	Unreal Engine 5 (direct codegen)
Rust	`-t rust`, `-t rs`	`.rs`	Rust transpilation
Interpret	`-t run`, `-t interpret`, `-t i`	stdout	Instant execution
Test	`-t test`, `-t t`	stdout	Unit tests

CLI Options

Flag	Description
`-o, --output <file>`	Output file path
`-t, --target <target>`	Compilation target (default: wasm)
`-r, --run`	Run immediately after compilation
`-w, --watch`	Watch for file changes and recompile
`--emit-ast`	Dump parsed AST for debugging
`--emit-typed`	Dump type-annotated AST
`-v, --verbose`	Verbose output
`--dry-run`	Print planned actions without executing
`--strict`	Treat warnings as errors

Subcommands (Main Compiler)

kore init [path] [--name NAME]    # Initialize a new project

kore lsp                          # Start Language Server Protocol

kore build <file>                 # Compile to WASM (default)

kore run <file>                   # Execute via interpreter

Shader Pipeline

KORE includes two direct shader backends - no intermediate SPIR-V or external tools required.

HLSL Backend (DirectX)

# Direct KORE → HLSL (no middleman)

kore shader.kr --target hlsl -o shader.hlsl

Generated output:

cbuffer with register bindings
Texture2D + SamplerState pairs
VSInput/PSOutput structs with semantics
Full PBR, tonemapping, post-processing

USF Backend (Unreal Engine 5)

# Direct KORE → USF (production UE5 shaders)

kore shader.kr --target usf -o shader.usf

Generated output:

#include "/Engine/Public/Platform.ush"
Scalar parameters (C++ bindable via SHADER_PARAMETER_STRUCT)
Texture2D<float4> + SamplerState pairs with registers
FPSInput/FPSOutput UE5-style structs
[numthreads] compute shader support

Alternative: SPIR-V → Cross-Platform

For multi-platform output, use SPIR-V with naga:

kore shader.kr --target spirv -o shader.spv

naga shader.spv shader.wgsl   # WebGPU

naga shader.spv shader.glsl   # OpenGL

naga shader.spv shader.metal  # Metal

Unreal Engine 5 Integration

Two approaches for UE5 shaders:

Direct USF (Recommended)

# One command - production UE5 shader

kore shader.kr --target usf -o MyShader.usf

Drop the .usf file directly into your plugin's Shaders/ directory.

Example generated output:

#include "/Engine/Public/Platform.ush"

float NormalStrength;   // C++ bindable
Texture2D<float4> albedo_map : register(t0);
SamplerState albedo_mapSampler : register(s0);

struct FPSInput { float2 uv : TEXCOORD0; };
struct FPSOutput { float4 Color : SV_Target0; };

FPSOutput ShaderNamePS(FPSInput Input) { ... }

Using in C++:

IMPLEMENT_GLOBAL_SHADER(FMyEffectPS, "/Plugin/MyPlugin/Shaders/MyShader.usf", "ShaderNamePS", SF_Pixel);

Legacy: ue5-shader Pipeline

For SPIR-V workflow with naga conversion:

kore shader.kr --target ue5-shader --plugin MyPlugin

Generates .spv, .hlsl, and .usf wrapper.

Rust Transpiler

KORE can be transpiled to valid Rust source code:

# Transpile to Rust

./target/release/kore logic.kr --target rust -o logic.rs


# Compile with rustc

rustc logic.rs -o logic.exe


# Or integrate into a Cargo project

The generated Rust includes:

Standard derive macros (Debug, Clone)
Proper type mappings (Int → i64, String → String, etc.)
println! macro conversion
Struct and enum definitions

Directory Structure

kore-v1-stable/
├── Cargo.toml              # Compiler manifest
├── README.md               # This file
├── commands.md             # CLI reference
│
├── src/                    # Rust compiler source
│   ├── lib.rs              # Library entry, compile() function
│   ├── main.rs             # CLI entry point
│   ├── lexer.rs            # Tokenizer
│   ├── parser.rs           # Parser (82KB)
│   ├── ast.rs              # AST types
│   ├── types.rs            # Type system
│   ├── runtime.rs          # Interpreter + Actor system (135KB)
│   ├── monomorphize.rs     # Generic instantiation (55KB)
│   └── codegen/            # Code generation backends
│       ├── wasm.rs         # WebAssembly (95KB)
│       ├── llvm.rs         # LLVM IR (66KB)
│       ├── spirv.rs        # SPIR-V shaders (14KB)
│       └── rust.rs         # Rust transpiler (28KB)
│
├── stdlib/                 # KORE standard library
│   ├── runtime.kr          # Runtime utilities
│   ├── wasm.kr             # WASM utilities
│   ├── spirv.kr            # SPIR-V utilities
│   └── ...                 # 12 modules total
│
├── shaders/                # GPU shader examples
│   ├── pbr_material.kr     # PBR shader
│   ├── post_processing.kr  # Post-processing effects
│   └── ...                 # 5 shaders
│
├── examples/               # General KORE examples
├── bootstrap/              # Self-hosting compiler (in KORE)
├── tests/kore/             # Test files
└── runtime/                # C FFI runtime

Codegen Backends

WASM Backend (`codegen/wasm.rs` - 95KB)

Full WebAssembly support:

Struct memory layout computation
Component system for UI
Enum discriminant handling
Lambda/closure collection and function table
String pooling in data segment
Bump allocator for heap memory

LLVM Backend (`codegen/llvm.rs` - 66KB)

Native compilation via LLVM IR:

Struct and actor compilation
Reference counting helpers
Scope-based cleanup (RAII-style)
External C runtime linkage
Debug info generation

SPIR-V Backend (`codegen/spirv.rs` - 14KB)

GPU shader compilation:

Vertex/Fragment/Compute shader stages
Vector types: vec2, vec3, vec4
Matrix types: mat4
Input/Output location decorations
BuiltIn position handling

HLSL Backend (`codegen/hlsl.rs` - 25KB)

Direct DirectX shader generation (no intermediate step):

cbuffer with register bindings
Texture2D + SamplerState pairs
VSInput/PSOutput structs with semantics
Full PBR math, tonemapping, post-processing
SM5.0 compatible output

USF Backend (`codegen/usf.rs` - 20KB)

Direct Unreal Engine 5 shader generation:

#include "/Engine/Public/Platform.ush"
Scalar parameters (C++ bindable via SHADER_PARAMETER_STRUCT)
Texture2D<float4> + SamplerState pairs with registers
FPSInput/FPSOutput UE5-style structs
[numthreads] compute shader support
RWTexture2D UAV bindings

Rust Backend (`codegen/rust.rs` - 28KB)

Transpilation to Rust source:

Full AST transformation
Type mapping (KORE → Rust)
Operator translation
Pattern matching support
Generated Cargo.toml scaffolding

C Runtime

The LLVM backend links against a minimal C runtime (src/runtime/c/kore_runtime.c):

Function	Description
`kore_print_*`	Print functions for all types
`kore_str_*`	String operations (concat, len, eq, substring)
`kore_array_*`	Dynamic array (new, push, pop, get, set, len)
`kore_map_*`	Hash map (new, get, set, contains)
`kore_file_*`	File I/O (read, write)
`kore_alloc/free`	Memory management
`kore_panic`	Runtime panic
`args()`	Command-line arguments

Compiling with Runtime

# Step 1: Compile KORE to LLVM IR

./target/release/kore program.kr --target llvm -o program.ll


# Step 2: Compile C runtime

clang -c src/runtime/c/kore_runtime.c -o kore_runtime.o


# Step 3: Link everything

clang program.ll kore_runtime.o -o program.exe

Self-Hosted Compiler

The src/compiler/ directory contains the self-hosted KORE compiler written in KORE itself (Project Ouroboros).

Components

File	Lines	Description
`main.kr`	284	Compiler driver, CLI parsing
`lexer.kr`	~400	Tokenizer
`parser.kr`	~800	Recursive descent parser
`codegen.kr`	~800	LLVM IR generation
`codegen_rust.kr`	684	Rust transpilation

Running Self-Hosted

# The self-hosted compiler runs through the interpreter

./target/release/kore src/compiler/main.kr --target run -- input.kr --target rust

KORE Utilities (Written in KORE)

The src/other/ directory contains utilities written in KORE itself:

File	Lines	Description
`repl.kr`	432	Interactive REPL with history, commands
`formatter.kr`	751	Code formatter (`kore fmt`)
`lsp.kr`	~300	Language Server Protocol
`test_runner.kr`	~200	Test framework
`suggestions.kr`	~150	Error message suggestions
`import_resolver.kr`	~200	Module import resolution
`packager.kr`	~250	Package management

Runtime Features

Interpreter (`runtime.rs` - 135KB)

Full expression evaluation
Pattern matching with destructuring
Async/await support with futures
Import resolution for modules
Hot reload capability

Actor System

Erlang-style concurrency:

actor Counter:
    var count: Int = 0
    
    on Increment(n: Int):
        count = count + n
    
    on GetCount -> Int:
        return count

Python Interop

Via pyo3:

let result = py_call("math.sqrt", [16.0])  # Returns 4.0

Standard Library

Built-in functions:

I/O: print, println, read_line, read_file, write_file
Collections: push, pop, len, map, filter, reduce
Math: abs, min, max, sqrt, pow
String: split, join, trim, replace, substring
JSON: json_parse, json_stringify
HTTP: http_get, http_post

Build Configuration

Default Build (No LLVM linking required)

cargo build --release

With LLVM Backend (requires LLVM 17 installed)

cargo build --release --features llvm

Dependencies

Crate	Purpose
`logos`	Lexer generator
`chumsky`	Parser combinator
`clap`	CLI argument parsing
`ariadne`	Pretty error reporting
`inkwell`	LLVM bindings (optional)
`walrus`	WASM manipulation
`rspirv`	SPIR-V generation
`tokio`	Async runtime
`flume`	Actor message channels
`pyo3`	Python FFI
`tower-lsp`	Language Server Protocol
`notify`	File watching for hot reload
`reqwest`	HTTP client for stdlib

Example Code

Basic Function

fn factorial(n: Int) -> Int with Pure:
    match n:
        0 => 1
        _ => n * factorial(n - 1)

fn main():
    let result = factorial(5)
    println("5! = {result}")

Shader

shader vertex MainVS:
    in position: vec3
    in color: vec4
    out out_color: vec4
    
    fn main():
        gl_Position = vec4(position, 1.0)
        out_color = color

shader fragment MainPS:
    in in_color: vec4
    out frag_color: vec4
    
    fn main():
        frag_color = in_color

Actor

actor ChatRoom:
    var messages: Array<String> = []
    var users: Array<String> = []
    
    on Join(name: String):
        push(users, name)
        broadcast("{name} joined")
    
    on Message(from: String, text: String):
        push(messages, "{from}: {text}")
        broadcast("{from}: {text}")

Development Status

Component	Status	Notes
Lexer	Production	Full token coverage
Parser	Production	82KB of parsing logic
Type Checker	Production	Effect inference included
Interpreter	Production	Primary development target
WASM Codegen	Production	Full feature support
LLVM Codegen	Stable	Requires feature flag
SPIR-V Codegen	Stable	Shader pipeline functional
HLSL Codegen	Production	Direct DirectX output
USF Codegen	Production	Direct UE5 shader output
Rust Transpiler	Stable	Bootstrap compiler
Self-hosted Compiler	See V2	Project Ouroboros (root dir)
LSP	Working	Basic features
Actor System	Production	Channel-based
Python FFI	Working	Via pyo3
REPL	Planned	Framework exists
Formatter	Planned	Framework exists

Troubleshooting

SPIR-V Validation Errors

If naga fails with validation errors:

Error	Cause	Fix
`Type isn't compatible with address space`	Wrong storage class	Check uniform handling
`Vertex shaders must return @builtin(position)`	Missing BuiltIn decoration	Ensure Vec4 output
`Global variable is invalid`	Missing Block decoration	Wrap uniform in struct

Rust Transpiler Borrow Errors

Generated Rust may need manual fixes:

Add mut or & as needed
Check ownership patterns
Report issues for codegen improvement

Build Performance

# Fast syntax check (no binary output)

cargo check


# Build only the binary

cargo build --release --bin kore

License

MIT

kore-lang 0.1.6