# YueScript
**Repository Path**: ippclub/YueScript
## Basic Information
- **Project Name**: YueScript
- **Description**: 一门编译到 Lua 表达力强且简洁的语言。
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://yuescript.org
- **GVP Project**: No
## Statistics
- **Stars**: 20
- **Forks**: 2
- **Created**: 2020-01-13
- **Last Updated**: 2026-03-05
## Categories & Tags
**Categories**: ci
**Tags**: Lua, transpiler, Cpp
## README
# YueScript
|
A delightful language that compiles to Lua
Dynamic, expressive, and concise syntax for Lua development.
Docs ·
Try Online ·
Discord
|
Xiaoyu (小玉) · Official YueScript Mascot
[](https://ippclub.org) [](https://github.com/pigpigyyy/Yuescript/actions/workflows/ubuntu.yml) [](https://github.com/pigpigyyy/Yuescript/actions/workflows/windows.yml) [](https://github.com/pigpigyyy/Yuescript/actions/workflows/macos.yml) [](https://discord.gg/cRJ2VAm2NV)
YueScript is a language that compiles to Lua. It is derived from [MoonScript](https://github.com/leafo/moonscript) `0.5.0` and continues to adopt new features to stay up to date.
## Quick Links
- Website:
- Documentation:
- Changelog: [`CHANGELOG.md`](./CHANGELOG.md)
- Discord:
## Overview
MoonScript has been used to build real-world projects such as [Lapis](https://github.com/leafo/lapis), [itch.io](https://itch.io), and [streak.club](https://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](https://github.com/ippclub/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](https://github.com/axilmar/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`](./CHANGELOG.md) for more details.
## Installation
### Lua Module
Build `yue.so` with:
```sh
> 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](https://luarocks.org):
```sh
> luarocks install yuescript
```
Then require the YueScript module in Lua:
```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:
```sh
> make install
```
Build YueScript tool without macro feature:
```sh
> make install NO_MACRO=true
```
Build YueScript tool without built-in Lua binary:
```sh
> make install NO_LUA=true
```
Use YueScript tool with:
```sh
> yue -h
Usage: yue
[options] [] ...
yue -e [args...]
yue -w [] [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 , --execute Execute a file or raw codes
-m, --minify Generate minified codes
-r, --rewrite Rewrite output to match original line numbers
-t , --output-to
Specify where to place compiled files
-o , --output 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 [], --watch []
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 Specify the Lua version that codes will be generated to
(version can only be 5.1 to 5.5)
--path Append an extra Lua search path string to package.path
--= 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](https://yuescript.org/doc/extras/mascot.html)
- Artwork by [Tyson Tan](https://tysontan.com)
## Editor Support
- [Vim](https://github.com/pigpigyyy/YueScript-vim)
- [ZeroBraneStudio](https://github.com/pkulchenko/ZeroBraneStudio/issues/1134) (Syntax highlighting)
- [Visual Studio Code](https://github.com/pigpigyyy/yuescript-vscode) (Supports diagnostics and completion using [Lua Language Server](https://github.com/LuaLS/lua-language-server))
## License
MIT