Lumen
A modern Minecraft scripting language that compiles scripts into native Java for near-plugin performance.
Install / Use
/learn @LumenLang/LumenREADME
The scripting side will change heavily. Patterns and syntax will be reworked, and most of the current ones will likely not stay the same. A lot of internal systems will also be modified to improve how things behave and to remove current limitations.
There are many incremental fixes planned, and the current TODO list is quite large, so changes will happen across multiple parts of the project over time, not just in one area.
Because of this, things may break between versions for a while. This is expected during this phase.
If you plan on using Lumen right now, it is recommended to mainly experiment with it or explore its capabilities.
</details>What Makes Lumen Different?
Lumen does not interpret scripts at runtime.
Instead, it:
- Parses your
.lumafiles on load - Generates native Java code
- Makes that code execute like a normal plugin
There is no continuously running interpreter. There are no runtime logic trees evaluated on every event.
Once processed, scripts behave like compiled server code, enabling near-native performance.
Which means you can write complex scripts without worrying about performance degradation as your server grows.
Example Script
on join:
message player "Welcome to the server!"
if player is op:
message player "Hello, admin!"
if chance 50%:
give player diamond 1
- Save it as a
.lumafile in thescriptsfolder - It will automatically detect a new file creation, and run it without any additional setup.
That is it.
The syntax is designed to be simple and readable, and the behavior does not require you to run commands like /reload, restart, or script reloads.
It will also detect changes to the file and update the behavior on the fly, so you can iterate quickly.
Independent Design
Lumen is built from the ground up and is not a fork, wrapper, or extension of any existing scripting engine.
The language, compiler pipeline, and runtime were designed specifically for Lumen. Scripts are not interpreted or translated directly into Java API calls. They go through a full compilation pipeline before they run.
At a high level, this is how a script is processed:
- Pattern matching: Statements are matched against registered patterns using typed placeholders and recursive matching.
- Statement classification: Matched statements are categorized so the compiler knows how code should be generated.
- Expression parsing and resolution: Expressions are analyzed and resolved with compile time type information.
- Type binding execution: Placeholder tokens are validated and converted into Java source fragments.
- Symbol tracking: A compile time environment tracks local, global, and stored variables across scopes.
- Code emission: The AST is walked and Java source code is generated.
Following this, a new Pipeline Documentation will be released with detailed explanations of each stage for those interested in contributing to Lumen or understanding how it works internally.
Current Status
Lumen is currently in beta.
The core system is stable, but there are still edge cases where a script may fail to compile unexpectedly. In many situations, these should instead be reported as parse errors. Receiving a raw compiler error is considered a bug at this stage.
If you encounter compilation failures, incorrect behavior, patterns not working as expected, or any unexpected issues, please report them through the issue tracker. Even if the script can be manually fixed, those cases are still valuable to report.
We also appreciate any feedback on the syntax, features, or anything else related to the project. The goal is to make Lumen as user-friendly and powerful as possible, and your input is crucial in achieving that.
Tradeoffs
Tradeoffs are inevitable with Lumen, as no scripting system is perfect.
-
Smaller Ecosystem: Lumen is still a relatively new project. Compared to more established scripting systems, the ecosystem is still growing.
-
Different Scripting Model: While Lumen may feel somewhat familiar to users coming from systems like Skript, its design and usage are fundamentally different. Scripts follow Lumen's own pattern system and compilation model, which may require adjusting to a new workflow.
-
Documentation Is Still Expanding: Documentation is continuously improving. If you encounter missing information, unclear behavior, or patterns that are not properly documented, please report it through the project's issue tracker so it can be addressed.
