reilua-enhanced/docs/EMBEDDING.md

Embedding main.lua into Executable

When you're ready to ship your game, you can embed all Lua files and asset files directly into the executable.

Development vs Release Workflow

Development Build (Fast Iteration)

During development, use external files for quick iteration.

Setup:

GameFolder/
├── ReiLua.exe
├── main.lua
├── player.lua
└── assets/
    ├── player.png
    └── music.wav

Build:

cd build
cmake ..
cmake --build .

Benefits:

• Edit Lua files and re-run immediately
• Edit assets and reload
• Fast development cycle
• Debug with --log flag

Release Build (Single Executable)

For distribution, embed everything into one file.

Setup:

cd build

# Copy Lua files to build directory
copy ..\main.lua .
copy ..\player.lua .

# Create assets folder and copy files
mkdir assets
copy ..\player.png assets\
copy ..\music.wav assets\

Build:

# Configure with embedding
cmake .. -DEMBED_MAIN=ON -DEMBED_ASSETS=ON

# Build release
cmake --build . --config Release

Result:

Distribution/
└── YourGame.exe  (Everything embedded!)

Benefits:

• Single executable file
• No external dependencies
• Users can't modify game files
• Smaller download (no separate files)

Quick Start

Embedding Lua Files

1. Copy your Lua files to the build directory:

   copy main.lua build\main.lua
   copy player.lua build\player.lua
   

2. Build with EMBED_MAIN option:

   cd build
   cmake .. -DEMBED_MAIN=ON
   cmake --build . --config Release
   

Command Line Options

ReiLua supports several command-line options:

ReiLua [Options] [Directory to main.lua or main]

Options:
  -h, --help       Show help message
  -v, --version    Show ReiLua version
  -i, --interpret  Interpret mode [File name]
  --log            Show console window for logging (Windows only)

Console/Logging

By default, ReiLua runs without a console window for a clean user experience. To enable console output for debugging:

# Run with console for debugging
ReiLua.exe --log

# You can also combine with other options
ReiLua.exe --log path/to/game

# Or with interpret mode
ReiLua.exe --log -i script.lua

This is useful during development to see:

• TraceLog output
• Print statements
• Lua errors
• Debug information

Complete Release Workflow

Here's a complete step-by-step guide to prepare your game for release:

Step 1: Organize Your Project

Ensure your project has this structure:

MyGame/
├── main.lua
├── player.lua
├── enemy.lua
├── player.png
├── enemy.png
├── music.wav
└── icon.ico (optional)

Step 2: Customize Branding (Optional)

Change executable icon:

# Replace ReiLua's icon with yours
copy MyGame\icon.ico ReiLua\icon.ico

Edit executable properties: Open ReiLua\resources.rc and modify:

VALUE "CompanyName", "Your Studio Name"
VALUE "FileDescription", "Your Game Description"
VALUE "ProductName", "Your Game Name"
VALUE "LegalCopyright", "Copyright (C) Your Name, 2025"

Change executable name: Edit ReiLua\CMakeLists.txt:

project( YourGameName )  # Change from "ReiLua"

See CUSTOMIZATION.md for full details.

Important: Asset Paths

Keep your paths consistent! The embedding system now preserves the assets/ prefix, so use the same paths in both development and release:

--  Correct - works in both dev and release
playerImage = RL.LoadTexture("assets/player.png")
backgroundImg = RL.LoadTexture("assets/background.png")
musicSound = RL.LoadSound("assets/music.wav")

Your Lua code doesn't need to change between development and release builds!

Step 3: Prepare Build Directory

cd ReiLua\build

# Copy all Lua files
copy ..\MyGame\*.lua .

# Create assets folder
mkdir assets

# Copy all asset files (images, sounds, etc.)
copy ..\MyGame\*.png assets\
copy ..\MyGame\*.wav assets\
copy ..\MyGame\*.ogg assets\
# Or copy entire folders
xcopy /E /I ..\MyGame\images assets\images
xcopy /E /I ..\MyGame\sounds assets\sounds

Step 4: Build Release

# Configure with embedding enabled
cmake .. -DEMBED_MAIN=ON -DEMBED_ASSETS=ON

# Build in release mode
cmake --build . --config Release

Step 5: Test Release Build

# Test with console to verify everything loaded
YourGameName.exe --log

# Test production mode (no console)
YourGameName.exe

Check console output for:

• "ReiLua x.x.x" version info
• No file loading errors
• Game runs correctly

Step 6: Package for Distribution

# Create distribution folder
mkdir ..\Distribution
copy YourGameName.exe ..\Distribution\

# Optional: Add README, LICENSE, etc.
copy ..\README.txt ..\Distribution\

Your game is now ready to distribute as a single executable!

Workflow Summary

Stage	Build Command	Files Needed	Result
Development	cmake .. && cmake --build .	Lua + assets external	Fast iteration
Testing	cmake .. -DEMBED_MAIN=ON && cmake --build .	Lua in build/	Test embedding
Release	cmake .. -DEMBED_MAIN=ON -DEMBED_ASSETS=ON && cmake --build . --config Release	Lua + assets in build/	Single .exe

Troubleshooting

Problem: "No .lua files found in build directory"

# Solution: Copy Lua files to build directory
copy ..\*.lua .

Problem: "No files found in assets folder"

# Solution: Create assets folder and copy files
mkdir assets
copy ..\*.png assets\

Problem: Game crashes on startup

# Solution: Run with --log to see error messages
YourGameName.exe --log

Problem: Assets not loading

• Verify assets are in build/assets/ before building
• Check asset filenames match in your Lua code
• Use --log to see loading errors

Notes

• .lua files in the build directory root are embedded when using EMBED_MAIN=ON
• Asset files in build/assets/ folder (and subfolders) are embedded when using EMBED_ASSETS=ON
• main.lua must exist and is always the entry point
• Asset embedding works with subdirectories: assets/images/player.png → Load with LoadImage("player.png")
• Both Lua and asset embedding can be used independently or together
• The system falls back to file system if embedded file is not found
• No code changes needed - all raylib functions work automatically with embedded assets

Customizing Your Executable

Want to add your own icon and version info to the executable? See CUSTOMIZATION.md for details on:

• Adding a custom icon
• Setting exe properties (company name, version, description)
• Renaming the executable