LuaMC: A Lua 5.1 Bytecode to Minecraft Datapack Translator

English | 简体中文

LuaMC is an innovative tool that brings the power of Lua 5.1 scripting into the world of Minecraft datapacks, allowing you to execute complex logic between the blocks.

By translating compiled Lua 5.1 bytecode (.luac files) into a series of Minecraft functions, LuaMC opens up entirely new possibilities for in-game programming—from sophisticated automation systems to custom game mechanics and interactive experiences, anything is possible.

---

🚀 Project Highlights

• Powerful Scripting: Run Lua 5.1 scripts directly in Minecraft, leveraging its robust logic-handling capabilities.
• Virtual Execution: Ingeniously uses Minecraft's command system as a virtual machine to interpret and execute Lua bytecode instruction by instruction.
• Highly Extensible: Designed as a robust and extensible framework that faithfully maps Lua's semantics into the Minecraft environment.
• For the Community: Provides a powerful tool for Lua and Minecraft enthusiasts to explore the boundaries of in-game programming.

Important Note: This project currently only supports bytecode generated by the official luac compiler for Lua 5.1.

---

🚧 Work In Progress

Please note that LuaMC is under development. While many core features have been implemented and are usable, some functionalities are still being refined, and a few of the less common Lua 5.1 bytecode instructions are not yet supported.

We warmly welcome community contributions and feedback! If you have any ideas or suggestions, please don't hesitate to share them.

---

📖 How to Use

Follow these steps to run your Lua scripts in your Minecraft world:

1. Compile Your Lua 5.1 Script

Use the luac compiler (must be for Lua 5.1) to compile your .lua script into a bytecode file.

# Use the default luac (ensure it's version 5.1)
luac -o your_script.luac your_script.lua

# Or explicitly call luac5.1
luac5.1 -o your_script.luac your_script.lua

2. Translate the Bytecode to a Datapack

Run the main.py script to convert the compiled .luac file into a Minecraft datapack.

python main.py your_script.luac -o my_lua_datapack

This will generate a datapack folder named my_lua_datapack in your current directory.

3. Install the Datapack in Minecraft

Copy the generated my_lua_datapack folder into the datapacks directory of your Minecraft world save.

4. Execute Lua Code In-Game

Enter your world and execute the following commands in order to manage and run your Lua code:

• ① Initialize the VM (Run Once): After first loading the datapack or after a /reload, run this command to set up all necessary internal variables.

  /function luamc:vm/internal/reset

• ② Execute a Lua "Tick": To advance the Lua VM's execution, you can choose to run a single step or execute in batches.

  # Execute one Lua "tick" (typically corresponds to a small set of instructions)
  /function luamc:tick
  
  # For faster execution, run 1000 Lua "ticks" at once
  /function luamc:tick1k

  You will need to run the tick function repeatedly until your script finishes.

Example: "Hello, Minecraft!"

Let's say you have a hello.lua script:

-- hello.lua
print("Hello from Lua in Minecraft!")

1. Compile: luac -o hello.luac hello.lua
2. Translate: python main.py hello.luac -o hello_world_datapack
3. In Minecraft:
   • Install the hello_world_datapack and load your world.
   • First, run /function luamc:vm/internal/reset.
   • Then, repeatedly run /function luamc:tick or /function luamc:tick1k.
   • You should see "Hello from Lua in Minecraft!" printed in the game chat or server console.

---

⚙️ Supported Lua 5.1 Bytecode Opcodes

Click to expand/collapse the list of implemented opcodes

• MOVE: Moves a value between registers.
• LOADK: Loads a constant into a register.
• LOADBOOL: Loads a boolean value, with an optional jump.
• LOADNIL: Loads nil into a range of registers.
• GETGLOBAL: Retrieves a global variable's value into a register.
• GETTABLE: Retrieves a table element's value into a register.
• SETGLOBAL: Sets the value of a global variable.
• SETTABLE: Sets a table element's value.
• NEWTABLE: Creates a new empty table.
• SELF: Prepares a method call.
• ADD, SUB, MUL, DIV, MOD, POW: Arithmetic operations.
• UNM: Unary minus (negation).
• NOT: Logical NOT operation.
• LEN: Calculates the length.
• CONCAT: Concatenates strings.
• JMP: Unconditional jump.
• EQ, LT, LE: Comparison operations.
• TEST: Tests a condition and potentially skips the next instruction.
• TESTSET: Tests a condition and conditionally moves a value.
• CALL: Calls a Lua function.
• RETURN: Returns from a function.
• FORLOOP, FORPREP: Numeric for loops.
• CLOSURE: Creates a new closure (function).
• SETLIST: Sets a list of table elements.

---

❌ Unimplemented Opcodes

The following opcodes are not yet implemented due to their complexity or limitations within the current Minecraft datapack architecture:

• GETUPVAL: Retrieves an upvalue's value.
• SETUPVAL: Sets an upvalue's value.
• TAILCALL: Performs a tail call optimization.
• CLOSE: Closes upvalues.
• VARARG: Handles variable arguments.
• TFORLOOP: Handles the loop body for generic for loops.

---

🤝 How to Contribute

Contributions of any kind are welcome! Whether it's reporting an issue, fixing a bug, or implementing a new feature, your help is greatly appreciated.

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.