Lua Mod Loader Implementation

1. A Scalable Mod Directory Structure

Before we write any code, we need to decide on a standard file structure for our mods. A clean, predictable structure makes it easy for both our loader to find the mods and for players to manage them.

A common and effective pattern is to give each mod its own folder inside a main mods directory. Within each mod's folder, a specific file, like main.lua or init.lua, serves as the entry point that our game will execute.

Here is an example of the structure we'll use:

game_root/
├── mods/
│   ├── friendly_chat_pack/
│   │   ├── main.lua
│   │   └── another_file.lua  -- (optional, for larger mods)
│   └── simple_trait_mod/
│       └── main.lua
└── ... (your Rust project files)

This structure is organized and scalable. For a more advanced example of how complex games organize mods, including DLCs, consider this file layout:

Your Task:

1. Create a mods directory in the root of your project if you haven't already.
2. Inside mods, create a new folder named friendly_chat_pack.
3. Move the code from your existing conversations.lua file into a new file at mods/friendly_chat_pack/main.lua.
4. Create another folder inside mods called core_tweaks.
5. Inside core_tweaks, create a main.lua file with the following content:

   -- mods/core_tweaks/main.lua
   print('[Lua] core_tweaks mod is loading!')
   
   local observant_trait = {
       id = "observant",
       name = "Observant",
       description = "Notices the little things."
   }
   
   game.register_trait(observant_trait)
   print('[Lua] Registered new trait: observant')
   

2. Building the Mod Loader in Rust

Now, let's update our Rust code to automatically scan this new directory structure. We will modify the initialize_and_run_mods function to iterate through the mods directory, identify each mod folder, and execute its main.lua script.

We'll use Rust's standard library for file system operations, primarily std::fs.

The article "Embedding Lua in sqleibniz with Rust" provides a fantastic, modern Rust example of loading and executing a Lua configuration file. We will use its approach as a model for our mod loader.

Now, let's implement this in src/modding.rs. We'll replace the hardcoded logic in initialize_and_run_mods.

src/modding.rs (Updated initialize_and_run_mods)

// At the top, make sure you have `use std::fs;`

pub fn initialize_and_run_mods() -> mlua::Result<()> {
    // --- Part 1: Initialize Lua and Expose API ---
    let lua = mlua::Lua::new();
    let globals = lua.globals();
    globals.set("game", game_module(&lua)?)?;
    println!("[Rust] Lua environment initialized and 'game' API exposed.");

    // --- Part 2: Scan and Load Mods ---
    println!("[Rust] --- Starting Mod Scan ---");
    let mods_dir = "./mods";

    // Read the contents of the 'mods' directory
    match fs::read_dir(mods_dir) {
        Ok(entries) => {
            for entry in entries {
                let entry = entry.expect("Failed to read directory entry");
                let path = entry.path();

                // We only care about subdirectories
                if path.is_dir() {
                    let mod_name = path.file_name().unwrap().to_str().unwrap();
                    let main_script_path = path.join("main.lua");

                    if main_script_path.exists() {
                        println!("[Rust] Found mod '{}', executing main.lua...", mod_name);
                        
                        // Read the script content
                        let script_content = fs::read_to_string(&main_script_path)
                            .expect("Could not read main.lua");
                        
                        // Execute the script
                        lua.load(&script_content)
                           .set_name(main_script_path.to_str().unwrap()) // For better error messages
                           .exec()?;
                    }
                }
            }
        },
        Err(e) => eprintln!("[Rust] WARN: Could not read mods directory '{}': {}", mods_dir, e),
    }
    println!("[Rust] --- Mod Scan Complete ---");

    // --- Part 3: Verify Results (from previous lesson) ---
    // We can keep this to test that our conversation pack loaded correctly.
    check_interaction_availability(&lua)?;

    Ok(())
}

If you run your project now, you should see the output from both mods! The mod loader successfully finds and executes both main.lua files.

3. Handling Multi-File Mods with require

Our loader works for simple mods, but what if a modder wants to split their code into multiple files for better organization?

For example, a mod might look like this:

• mods/advanced_mod/main.lua
• mods/advanced_mod/utils.lua

And main.lua might try to load utils.lua using require("utils").

If you try this, it will fail. By default, Lua doesn't know to look inside the mods/advanced_mod/ directory. It searches a predefined set of paths stored in a global variable called package.path.

To solve this, we must tell Lua where to find each mod's files. The solution is to dynamically add the mod's directory to package.path before we execute its main.lua.

Let's apply this fix. In our Rust loop, right before executing main.lua, we will execute a small Lua snippet to update package.path.

src/modding.rs (Updated loop inside initialize_and_run_mods)

// ... inside the if path.is_dir() block ...
if main_script_path.exists() {
    println!("[Rust] Found mod '{}', executing main.lua...", mod_name);
    
    // --- NEW: Set up package.path for this mod ---
    if let Some(mod_path_str) = path.to_str() {
        // We need to normalize path separators for Lua
        let mod_lua_path = format!("{}/?.lua", mod_path_str.replace('\\', "/"));
        let set_path_script = format!("package.path = '{}..' .. package.path", mod_lua_path);
        
        lua.load(&set_path_script).exec()?;
    }
    // --- END NEW ---

    // Read the script content
    let script_content = fs::read_to_string(&main_script_path)
        .expect("Could not read main.lua");
    
    // Execute the script
    lua.load(&script_content)
       .set_name(main_script_path.to_str().unwrap())
       .exec()?;
}
// ...

Your Task (to test this):

1. Create a new mod folder mods/path_test.
2. Create mods/path_test/utils.lua:

   -- mods/path_test/utils.lua
   print('[Lua] utils.lua has been required!')
   
   local M = {}
   
   function M.get_message()
       return "It works!"
   end
   
   return M
   

3. Create mods/path_test/main.lua:

   -- mods/path_test/main.lua
   print('[Lua] path_test mod is loading!')
   
   -- This will now work because of our package.path modification
   local utils = require("utils")
   
   print('[Lua] path_test message: ' .. utils.get_message())
   

Run your project one last time. You should now see the output from all three mods, including the successful require call in path_test. Your mod loader is now robust and ready for modders!

Conclusion

Congratulations! You have successfully built a dynamic mod loader. This is a massive step forward, turning a single-script system into a fully-fledged modding platform.

Key Takeaways:

• A standardized directory structure (e.g., mods/<mod_name>/main.lua) is essential for an automatic mod loader.
• Rust's std::fs module provides the tools (read_dir, path, is_dir) needed to scan directories and find mod files.
• You can execute Lua code from a string using lua.load(&code).exec(). Using .set_name() provides clearer error reporting.
• To support multi-file mods that use require, you must dynamically update Lua's package.path to include each mod's directory before executing its entry script.

Preview of the Next Lesson:
Our mod loader is functional, but it's naive. What happens if both core_tweaks and another mod try to register a trait with the id = "observant"? The last one loaded would win, silently overwriting the first. In our next lesson, we will address this by implementing basic conflict detection for mods that register content with the same ID, making our modding system safer and more predictable.