YueScript

<table align="center"> <tr> <td align="center" valign="middle" width="150" height="150"> <img src="doc/docs/.vitepress/public/image/yuescript.png" alt="YueScript logo"/><br/> </td> <td valign="middle"> <strong>A delightful language that compiles to Lua</strong><br/> _{Dynamic, expressive, and concise syntax for Lua development.}<br/> _{<a href="https://yuescript.org/doc">Docs</a> · <a href="https://yuescript.org/try">Try Online</a> · <a href="https://discord.gg/cRJ2VAm2NV">Discord</a>} </td> </tr> </table> <p align="center"> <img src="doc/docs/.vitepress/public/image/mascot/electrichearts_20260211A_yuescript_xiaoyu.png" width="360" alt="Xiaoyu, the YueScript mascot"/> </p> <p align="center"> _{<b>Xiaoyu (小玉)</b> · Official YueScript Mascot} </p>

YueScript is a language that compiles to Lua. It is derived from MoonScript 0.5.0 and continues to adopt new features to stay up to date.

Quick Links

• Website: https://yuescript.org
• Documentation: https://yuescript.org/doc
• Changelog: CHANGELOG.md
• Discord: https://discord.gg/cRJ2VAm2NV

Overview

MoonScript has been used to build real-world projects such as Lapis, itch.io, and streak.club. MoonScript itself was also influenced by languages such as CoffeeScript. As the original implementation became harder to evolve without risking compatibility, YueScript was created as a modernized code base for pushing the language forward.

YueScript is both a production-ready compiler and a playground for exploring new syntax and programming paradigms that make Lua development more expressive and productive.

Yue (月) is the Chinese word for moon and is pronounced [jyɛ].

About Dora SSR

YueScript is being developed and maintained alongside the open-source game engine Dora SSR. It has been used to create engine tools, game demos and prototypes, validating its capabilities in real-world scenarios while enhancing the Dora SSR development experience.

Features

• Based on a modified parserlib with performance enhancements. lpeg is no longer required.
• Written in C++17.
• Supports most MoonScript features and generates Lua code in a style compatible with the original compiler.
• Preserves source line numbers in generated Lua to improve debugging.
• Adds features like macros, existential operator, pipe operator, JavaScript-like export syntax, and more.
• See CHANGELOG.md for more details.

Installation

Lua Module

Build yue.so with:

> make shared LUAI=/usr/local/include/lua LUAL=/usr/local/lib/lua

Then get the binary file from bin/shared/yue.so.

Or install via LuaRocks:

> luarocks install yuescript

Then require the YueScript module in Lua:

require("yue")("main") -- require `main.yue`

local yue = require("yue")
local codes, err, globals = yue.to_lua([[
f = -> print "hello world"
f!
]],{
  implicit_return_root = true,
  reserve_line_number = true,
  lint_global = true
})

Binary Tool (CLI)

Clone this repo, then build and install executable with:

> make install

Build YueScript tool without macro feature:

> make install NO_MACRO=true

Build YueScript tool without built-in Lua binary:

> make install NO_LUA=true

Use YueScript tool with:

> yue -h
Usage: yue
       [options] [<file/directory>] ...
       yue -e <code_or_file> [args...]
       yue -w [<directory>] [options]
       yue -

Notes:
   - '-' / '--' must be the first and only argument.
   - '-o/--output' can not be used with multiple input files.
   - '-w/--watch' can not be used with file input (directory only).
   - with '-e/--execute', remaining tokens are treated as script args.

Options:
   -h, --help                 Show this help message and exit.
   -e <str>, --execute <str>  Execute a file or raw codes
   -m, --minify               Generate minified codes
   -r, --rewrite              Rewrite output to match original line numbers
   -t <output_to>, --output-to <output_to>
                              Specify where to place compiled files
   -o <file>, --output <file> Write output to file
   -p, --print                Write output to standard out
   -b, --benchmark            Dump compile time (doesn't write output)
   -g, --globals              Dump global variables used in NAME LINE COLUMN
   -s, --spaces               Use spaces in generated codes instead of tabs
   -l, --line-numbers         Write line numbers from source codes
   -j, --no-implicit-return   Disable implicit return at end of file
   -c, --reserve-comments     Reserve comments before statement from source codes
   -w [<dir>], --watch [<dir>]
                              Watch changes and compile every file under directory
   -v, --version              Print version
   -                          Read from standard in, print to standard out
                              (Must be first and only argument)
   --                         Same as '-' (kept for backward compatibility)

   --target <version>         Specify the Lua version that codes will be generated to
                              (version can only be 5.1 to 5.5)
   --path <path_str>          Append an extra Lua search path string to package.path
   --<key>=<value>            Pass compiler option in key=value form (existing behavior)

   Execute without options to enter REPL, type symbol '$'
   in a single line to start/stop multi-line mode

Common Usage

• Recursively compile every YueScript file with extension .yue under current path: yue .
• Compile and save results to a target path: yue -t /target/path/ .
• Compile and reserve debug info: yue -l .
• Compile and generate minified codes: yue -m .
• Execute raw codes: yue -e 'print 123'
• Execute a YueScript file: yue -e main.yue

Mascot (Xiaoyu / 小玉)

Xiaoyu (小玉) is YueScript's official mascot, a cyber rabbit often seen perched on a crescent moon and coding on a laptop.

• English page: here
• Artwork by Tyson Tan

Editor Support

• Vim
• ZeroBraneStudio (Syntax highlighting)
• Visual Studio Code (Supports diagnostics and completion using [Lua Language Server](h