From e908e4d564480e42dbcb6a5ddc16d60b323b6243 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Moritz=20H=C3=B6lting?=
 <87192362+moritz-hoelting@users.noreply.github.com>
Date: Sat, 6 Apr 2024 19:08:53 +0200
Subject: [PATCH] Add Lua integration and run keyword

---
 src/content/docs/guides/syntax.md | 36 +++++++++++++++++++++++++------
 src/content/docs/reference/lua.md | 22 +++++++++++++++++++
 2 files changed, 51 insertions(+), 7 deletions(-)
 create mode 100644 src/content/docs/reference/lua.md

diff --git a/src/content/docs/guides/syntax.md b/src/content/docs/guides/syntax.md
index a66b4a1..d005e2d 100644
--- a/src/content/docs/guides/syntax.md
+++ b/src/content/docs/guides/syntax.md
@@ -8,7 +8,7 @@ sidebar:
 ---
 
 ## Comments
-Single line comments start with `//` and continue until the end of the line.
+Single-line comments start with `//` and continue until the end of the line.
 Multiline comments start with `/*` and end with `*/`.
 
 ```shulkerscript
@@ -17,8 +17,8 @@ Multiline comments start with `/*` and end with `*/`.
 multiline comment */
 ```
 
-These comments are completely ignored by the compiler and will not show up in the generated datapack.
-If you want to include a comment in the datapack, you can use the doccomment syntax.
+These comments are completely ignored by the compiler and will not show up in the generated data pack.
+If you want to include a comment in the data pack, you can use the doccomment syntax.
 ```shulkerscript
 /// This is a doccomment
 ```
@@ -32,6 +32,10 @@ They start with a `/` and are followed by the command.
 
 This will result in `say Hello, world!` being included in the `.mcfunction` file.
 
+:::note
+Literal commands are just syntactic sugar for the [`run`](#run) keyword.
+:::
+
 ## Functions
 Functions are blocks of code that can be executed.
 They start with `fn` followed by the name of the function, parenthesis and a block of code.
@@ -51,10 +55,9 @@ ShulkerScript always requires a `main` function to be present in the code.
 ### Annotations
 Annotations are special attributes that can be attached to functions.
 They start with `#` followed by the name of the annotation in square brackets. Some annotations can have arguments assigned to them with the `=` operator.
-
-Currently the following annotations are supported:
+Currently, the following annotations are supported:
 - `#[tick]`: The function will be executed every tick.
-- `#[load]`: The function will be executed when the datapack is loaded.
+- `#[load]`: The function will be executed when the data pack is loaded.
 - `#[deobfuscate]`: The function will keep the original name in the output (path of the `.shu`-file followed by the function name).
 - `#[deobfuscate = "path/to/function"]`: The function will be named as specified in the argument.
 
@@ -84,11 +87,30 @@ if ("block ~ ~-1 ~ minecraft:stone") {
 ```
 
 ## Groupings
-Groupings are used to group multiple commands together into one `mcfunction` file without declaring a new function.
+Groupings are used to group multiple commands into one `mcfunction` file without declaring a new function.
 This can be used for commands that need to be executed atomically.
 ```shulkerscript
 group {
     /say Hello
     /say World
 }
+```
+
+## Run
+The `run` keyword is used to evaluate the following expression and include the resulting command in the output.
+```shulkerscript
+run "say Hello, world!"
+```
+
+:::tip
+In most cases, you can use [literal commands](#literal-commands) instead of the `run` keyword.
+:::
+
+## Lua Code
+The `lua` keyword is used to embed Lua code in your ShulkerScript code. It can be combined with the `run` keyword to include the result of the Lua code in the output.
+```shulkerscript
+run lua() {
+    // Lua code goes here
+    return "Hello, Lua!";
+}
 ```
\ No newline at end of file
diff --git a/src/content/docs/reference/lua.md b/src/content/docs/reference/lua.md
new file mode 100644
index 0000000..a7f8f1c
--- /dev/null
+++ b/src/content/docs/reference/lua.md
@@ -0,0 +1,22 @@
+---
+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. In the future, you will be able to pass arguments to the Lua code, but for now, you can only write Lua code without arguments.
+
+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!";
+}
+```
\ No newline at end of file