87 lines
3.6 KiB
Markdown
87 lines
3.6 KiB
Markdown
---
|
|
title: Lua Integration
|
|
description: Reference for writing Lua code in Shulkerscript
|
|
sidebar:
|
|
badge:
|
|
text: WIP
|
|
variant: caution
|
|
---
|
|
|
|
Shulkerscript supports writing Lua code directly in your scripts. This allows you to use Lua's powerful features and libraries to extend the functionality of your scripts.
|
|
|
|
The Lua code is embedded in the Shulkerscript code using the `lua` keyword. You can pass variables from Shulkerscript to Lua, and the Lua code can return values that can be used in Shulkerscript.
|
|
```shulkerscript
|
|
int a = 5;
|
|
int b = lua(a) {
|
|
-- Lua code goes here
|
|
print("The objective is: " .. a.objective);
|
|
print("The target is: " .. a.target);
|
|
return 10;
|
|
};
|
|
```
|
|
|
|
:::caution
|
|
The Lua code is run during **compilation**, not during **execution** of the Shulkerscript. This means that the Lua code can only access the variables that are available at compile time, e.g. therefore receiving the objective and target of an `int` variable, but not the actual value that is only available during execution.
|
|
:::
|
|
|
|
Your Lua code should return a string value when used in combination with the run keyword. This string returned will be included in the output.
|
|
|
|
## Syntax
|
|
|
|
```shulkerscript
|
|
run lua() {
|
|
-- Lua code goes here
|
|
return "Hello, Lua!";
|
|
};
|
|
```
|
|
|
|
## Inputs
|
|
|
|
The variables from Shulkerscript can be passed to lua by putting the variable name in the parentheses of the `lua` keyword. The variable will be available in the Lua code as a global variable with the same name.
|
|
|
|
Depending on the type of the variable, the Lua code will receive a different type of value. The following table shows the mapping of Shulkerscript types to Lua types:
|
|
|
|
| Shulkerscript Type | Lua Type |
|
|
| ------------------------ | ------------------------------------------- |
|
|
| int | table { objective: string, target: string } |
|
|
| bool | table { storage: string, path: string } |
|
|
| macro function parameter | string "$(macro)$ |
|
|
|
|
```shulkerscript
|
|
fn greet(name) {
|
|
run `say Greeting $(name) from Lua:`;
|
|
run lua(name) {
|
|
return {
|
|
value="Hello, " .. name .. "!",
|
|
contains_macro=true
|
|
}
|
|
};
|
|
}
|
|
```
|
|
|
|
:::note
|
|
When returning a value that contains a macro, instead of just returning the value, you have to return a table with the value and a boolean that indicates that the value contains a macro.
|
|
:::
|
|
|
|
## Shulkerscript Module
|
|
|
|
The Lua environment has access to a few globals that are provided by Shulkerscript. These globals are available in the `shulkerscript` table. The following values are available in the `shulkerscript` table:
|
|
|
|
- `version`: The version of Shulkerscript that is being used in string format.
|
|
- `file_path`: The path to the file where the Lua code is written.
|
|
- `start_line`: The line number where the Lua code starts.
|
|
- `end_line`: The line number where the Lua code ends.
|
|
- `start_column`: The column number where the Lua code starts.
|
|
- `end_column`: The column number where the Lua code ends.
|
|
|
|
After variables are introduced in Shulkerscript, it is planned to make them available in the Lua environment as well.
|
|
|
|
:::tip[Feedback Requested]
|
|
If you can think of any other globals that should be available in the Lua environment, please let us know! This could include:
|
|
|
|
- variables with values (like `version`)
|
|
- functions that calculate/modify values (general utility things not provided by Lua or specific to Shulkerscript)
|
|
|
|
Please either write a mail or open an issue on GitHub. The links can be found in the upper right corner of the page.
|
|
:::
|