neru

neru-logo

CI Release

A scripting language for the visual novel engine nerune-engine.

Designed with a two-layer architecture so both scenario writers and programmers can work comfortably.

日本語版 README

Warning

This project is under active development. The language specification and API are subject to breaking changes without notice. Do not use in production.

Quick Start

Download the latest binary from Releases, then:

# Logic-only script
cat <<'EOF' > hello.nerul
fn fib(n) {
 if n <= 1 { return n }
 return fib(n - 1) + fib(n - 2)
}
let result = fib(10)
EOF
neru run hello.nerul
# => 55
# Scenario script — use --mock to drive the built-in auto-responder
cat <<'EOF' > hello.neru
@speaker Alice
Hello, traveler!
@wait 500
Where are you heading today?
EOF
neru run --mock hello.neru
# => [speaker] Alice
# [text] Alice: Hello, traveler!
# [wait] 500ms
# [text] Alice: Where are you heading today?
# Compile to bytecode
neru compile hello.nerul
# => hello.neruc

More runnable examples live under examples/.

Features

• Scenario Layer (.neru) — Text lines, @speaker/@wait/@clear, @bg/@show/@bgm/@se/@transition with --key=value options, #label + @goto, #choice with conditional entries, @if/@elif/@else/@end, @call/@eval, and {expression} interpolation
• Logic Layer (.nerul) — Expressions, let, fn, if/else, for/while/for-in, break/continue, recursive calls, compound assignments, arrays, maps, closures, string methods, @import modules
• Bytecode VM — Stack-based virtual machine implemented in Zig. Emits engine-independent events (text, choices, effects) instead of executing them directly
• Mock Engine — neru run --mock drives a script end-to-end without an engine, auto-acking events and printing them to stdout
• Cross-platform — Linux, macOS, Windows binaries are shipped from CI

What's still coming

• State management, save/load, macros, i18n (Phase 4)
• LSP, debugger, formatter (Phase 5)

Examples

Scenario (.neru)

@bg forest.png --fade=slow
@bgm theme.ogg --volume=0.8
@show taro --pos=center
@speaker Taro
It's quiet in the forest today.
@wait 500
#choice
 - "Call out" -> call
 - "Stay silent" -> silent
 - "Secret option" -> secret @if 1 == 1
#call
@speaker Taro
Hello!
@goto done
#silent
@speaker Narrator
(Taro keeps walking.)
@goto done
#secret
@speaker Narrator
You unlocked the hidden branch.
@goto done
#done
@bgm_stop

Logic (.nerul)

fn factorial(n) {
 if n <= 1 { return 1 }
 return n * factorial(n - 1)
}
let x = factorial(5) // 120
// Arrays and maps
let items = ["sword", "shield"]
items.push("potion")
let stats = {"hp": 100, "mp": 50}
// For-in iteration
for item in items {
 debug.log(item)
}
// Closures
fn make_adder(x) {
 fn adder(y) { return x + y }
 return adder
}
let add5 = make_adder(5)
add5(10) // 15
// Built-in modules
let abs_val = math.abs(-42)
debug.assert(abs_val == 42)

Build from Source

Requires Zig 0.15.2+.

zig build # Build
zig build run # Build and run CLI
zig build test # Run all tests

Use as a Zig library

Add the dependency

Fetch the package into your project's build.zig.zon:

zig fetch --save=neru git+https://github.com/NaruseNia/neru#v0.2.0

Then wire the module into build.zig:

constneru_dep=b.dependency("neru",.{.target=target,.optimize=optimize});exe.root_module.addImport("neru",neru_dep.module("neru"));

Usage

constneru=@import("neru");// Compilevardiags=neru.compiler.DiagnosticList.init(allocator);varnodes=neru.compiler.NodeStore.init(allocator);varlexer=neru.compiler.Lexer.init(source,&diags,.scenario);// or .logicvarparser=neru.compiler.Parser.init(allocator,&lexer,&nodes,&diags);constroot=tryparser.parseProgram();varcompiler=neru.compiler.Compiler.init(allocator,&nodes,&diags);constmodule=trycompiler.compile(root);// Run in event-driven mode (scenario-friendly)varvm=neru.vm.VM.init(allocator);defervm.deinit();vm.load(module);while(tryvm.runUntilEvent())|event|{// handle event and send a Response backvm.resumeWith(.{.none={}});}

Documentation

User Guide

• 01. Introduction
• 02. Scenario Layer
• 03. Logic Layer Basics
• 04. Data Structures
• 05. Functions & Closures
• 06. String Operations
• 07. Built-in Modules
• 08. Module System

Reference

• API Reference
• Language Specification
• Architecture
• Implementation Plan
• EBNF Grammar

Roadmap

License

MIT