ReiLua - Enhanced Edition

A modified version of ReiLua with embedded main.lua, embedded assets, splash screens, and asset loading system

About This Version

This is an enhanced version of ReiLua featuring:

• 🎮 Embedded Lua Support - Bundle all your Lua code into a single executable
• 📦 Embedded Assets - Package images, sounds, and other assets into your game
• 🎨 Splash Screens - Customizable startup screens featuring Raylib and ReiLua
• 📊 Asset Loading System - Beautiful loading screen with progress tracking
• 🔧 Automated Build Scripts - One-command development and release builds
• 🪟 Console Control - Debug logging system for development

What is ReiLua?

ReiLua brings the power and simplicity of Raylib to the beginner-friendly Lua language in a straightforward manner. It is a loose binding to Raylib - some functions are excluded and some are added. The concept of pointing to a "main.lua" file and accessing functions "init", "update", and "draw" is borrowed from the Löve game framework.

Note: ReiLua is lovingly ❤️ handcrafted and will likely contain bugs and documentation errors, so it would be much appreciated if you would report any such findings.

Reilua means "fair" in Finnish.

Attributions

This enhanced version is built upon:

Core Framework

• Raylib (v5.5) - A simple and easy-to-use library to enjoy videogames programming
  • Created by Ray(Ramon Santamaria) (@raysan5)
  • Licensed under the zlib/libpng license
• ReiLua - The original Lua bindings for Raylib
  • Created by Jussi Viitala
  • Licensed under the MIT license
• Lua (v5.4) - Powerful, efficient, lightweight, embeddable scripting language

Enhancements Added

• Embedded Lua and asset support system
• Splash screen implementation
• Asset loading progress API with retro UI
• Build automation scripts
• Console control system
• Comprehensive documentation

Additional Components

• Raygui - Immediate mode GUI library
• Raymath - Math utilities for game development
• Lights - 3D lighting system
• Easings - Easing functions for smooth animations
• RLGL - OpenGL abstraction layer

Font

• Oleaguid - Custom pixel art font for splash and loading screens

Status

ReiLua is WIP and some planned raylib functionality is still missing, but it already has over 1000 functions. Current Raylib version is 5.5.

Included Submodules

• Raygui
• Raymath
• Lights
• Easings
• RLGL

Missing Features

List of some MISSING features that are planned to be included:

• Core
  • VR stereo config functions for VR simulator

Roadmap

• v0.9
  • Stability improvements
  • Additional raylib bindings
• v1.0
  • raylib 6.0 support

Quick Start

For Game Developers

Development Mode (Fast Iteration):

# 1. Create your game files
GameFolder/
├── main.lua
├── assets/
│   ├── player.png
│   └── music.wav

# 2. Run ReiLua pointing to your game folder
ReiLua.exe GameFolder/

# Or from your game folder
cd GameFolder
path/to/ReiLua.exe

# Skip splash screens during development
ReiLua.exe --no-logo

# Enable console for debugging
ReiLua.exe --log --no-logo

Release Mode (Single Executable):

# See "Building for Release" section below

Basic Example

Create a main.lua file:

local textColor = RL.BLACK
local textPos = { 192, 200 }
local textSize = 20
local text = "Congrats! You created your first window!"

function RL.init()
	RL.SetWindowTitle( "First window" )
	RL.SetWindowState( RL.FLAG_VSYNC_HINT )
end

function RL.update( delta )
	if RL.IsKeyPressed( RL.KEY_ENTER ) then
		local winSize = RL.GetScreenSize()
		local measuredSize = RL.MeasureTextEx( RL.GetFontDefault(), text, textSize, 2 )

		textColor = RL.BLUE
		textPos = { winSize[1] / 2 - measuredSize[1] / 2, winSize[2] / 2 - measuredSize[2] / 2 }
	end

	if RL.IsKeyPressed( RL.KEY_SPACE ) then
		textColor = RL.RED
		textPos = { 192, 200 }
	end
end

function RL.draw()
	RL.ClearBackground( RL.RAYWHITE )
	RL.DrawText( text, textPos, textSize, textColor )
end

Run it:

ReiLua.exe --no-logo

Framework Functions

ReiLua looks for a 'main.lua' or 'main' file as the entry point. There are seven Lua functions that the framework will call:

• RL.init() - Called once at startup for initialization
• RL.update(delta) - Called every frame before draw, receives delta time
• RL.draw() - Called every frame for rendering
• RL.event(event) - Called when events occur
• RL.log(logLevel, message) - Called for logging
• RL.exit() - Called when the application is closing
• RL.config() - ⚠️ Deprecated in this version

All functionality can be found in "API.md".

Enhanced Features

1. Splash Screens

This version includes customizable splash screens that display at startup:

Screen 1: Custom text - Bold text on Raylib red background (customizable) Screen 2: "Made using" - Displays Raylib and ReiLua logos side-by-side

Each screen fades in (0.8s), displays (2.5s), and fades out (0.8s) for a total of ~8 seconds.

Skip During Development:

ReiLua.exe --no-logo

Customize:

• Change text in src/splash.c
• Replace logos in logo/ folder
• Adjust timing with constants in src/splash.c

See SPLASH_SCREENS.md for full documentation.

2. Asset Loading System

Beautiful loading screen with progress tracking:

function RL.init()
    -- List your assets
    local assets = {
        "assets/player.png",
        "assets/enemy.png",
        "assets/background.png",
        "assets/music.wav",
    }

    -- Start loading with progress
    RL.BeginAssetLoading(#assets)

    -- Load each asset
    for i, path in ipairs(assets) do
        RL.UpdateAssetLoading(path)

        -- Your loading code
        if path:match("%.png$") then
            textures[i] = RL.LoadTexture(path)
        elseif path:match("%.wav$") then
            sounds[i] = RL.LoadSound(path)
        end
    end

    -- Finish loading
    RL.EndAssetLoading()
end

Features:

• Retro 1-bit pixel art aesthetic
• Animated loading text with dots
• Progress bar with dithering pattern
• Shows current asset name
• Progress counter (e.g., "3/10")
• Corner decorations

See ASSET_LOADING.md for full documentation.

3. Embedded Lua Files

Bundle all your Lua code into the executable for easy distribution:

# Copy Lua files to build directory
cd build
copy ..\your_game\*.lua .

# Build with embedding
cmake .. -DEMBED_MAIN=ON
cmake --build . --config Release

Result: Single executable with all Lua code embedded!

4. Embedded Assets

Package images, sounds, fonts, and other assets into your executable:

# Create assets folder and copy files
cd build
mkdir assets
copy ..\your_game\assets\* assets\

# Build with embedding
cmake .. -DEMBED_ASSETS=ON
cmake --build . --config Release

Your Lua code doesn't change! Use the same paths:

-- Works in both development and release
playerImg = RL.LoadTexture("assets/player.png")
music = RL.LoadSound("assets/music.wav")

See EMBEDDING.md for full documentation.

5. Console Control (Windows)

By default, ReiLua runs without a console window for a clean user experience. Enable it for debugging:

# Show console for debugging
ReiLua.exe --log

# Combine with other options
ReiLua.exe --log --no-logo
ReiLua.exe --log path/to/game

This shows:

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

6. Automated Build Scripts

One-command builds for development and release:

Development Build (Fast Iteration):

# Windows
scripts\build_dev.bat

# Linux/Unix
chmod +x scripts/build_dev.sh
scripts/build_dev.sh

• No embedding
• Fast build times
• Edit code without rebuilding

Release Build (Distribution):

# Prepare files first
cd build
copy ..\your_game\*.lua .
mkdir assets
copy ..\your_game\assets\* assets\

# Build release
cd ..

# Windows
scripts\build_release.bat

# Linux/Unix
scripts/build_release.sh

• Embeds all Lua files
• Embeds all assets
• Creates single executable
• Release optimizations

See BUILD_SCRIPTS.md for full documentation.

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)
  --no-logo        Skip splash screens (development)

Examples

# Run game in current directory
ReiLua.exe

# Run game in specific folder
ReiLua.exe path/to/game/

# Development mode (no splash, with console)
ReiLua.exe --log --no-logo

# Interpreter mode (run single script)
ReiLua.exe -i script.lua

# Show help
ReiLua.exe --help

# Show version
ReiLua.exe --version

Object Unloading

Some objects allocate memory that needs to be freed when no longer needed. By default, objects like Textures are unloaded by the Lua garbage collector. However, it's generally recommended to handle this manually in more complex projects:

RL.SetGCUnload()

Interpreter Mode

ReiLua can run single Lua files using interpreter mode:

ReiLua -i hello.lua

The given file will be called with dofile.

Generate API Documentation

Generate API.md and ReiLua_API.lua from the build folder:

ReiLua -i ../tools/docgen.lua

Tip: Use tools/ReiLua_API.lua in your project folder to provide annotations when using "Lua Language Server".

Building from Source

Prerequisites

You'll need to statically link Raylib and Lua to create the executable. This simplifies distribution, especially on Linux where different distros use different library versions.

• Raylib: https://github.com/raysan5/raylib
• Lua: https://github.com/lua/lua or https://github.com/LuaJIT/LuaJIT
• CMake: https://cmake.org/download/
• Build tools: MinGW (Windows), GCC/Make (Linux)

Note: Lua header files are from Lua 5.4.0. If using a different version, replace them.

Windows

1. Install Tools

• Download w64devkit from https://github.com/skeeto/w64devkit
• Download CMake from https://cmake.org/download/ (install with PATH environment variables set)

2. Build Raylib

# Download Raylib source
# Run w64devkit.exe and navigate to raylib/src
cd raylib/src
mingw32-make

# Copy libraylib.a to ReiLua/lib folder
copy libraylib.a path\to\ReiLua\lib\

3. Build Lua

Download Lua source from https://github.com/lua/lua

Modify Lua's makefile:

# Change this:
MYCFLAGS= $(LOCAL) -std=c99 -DLUA_USE_LINUX -DLUA_USE_READLINE
# To this:
MYCFLAGS= $(LOCAL) -std=c99

# Comment out or remove:
MYLIBS= -ldl -lreadline

Build:

# In w64devkit, navigate to Lua folder
mingw32-make

# Copy liblua.a to ReiLua/lib folder
copy liblua.a path\to\ReiLua\lib\

4. Build ReiLua

Quick Method (Recommended):

cd ReiLua
scripts\build_dev.bat

Manual Method:

cd ReiLua\build
cmake -G "MinGW Makefiles" ..
mingw32-make

5. Test

cd build
ReiLua.exe ..\examples\snake\

If you see a low-res snake racing off the window, success! Press Enter to reset.

Linux

1. Install Dependencies

sudo apt install build-essential cmake

2. Build Raylib and Lua

Compile Raylib and Lua by following their instructions. They will compile to libraylib.a and liblua.a by default.

Move both .a files to the ReiLua/lib folder.

3. Build ReiLua

Quick Method (Recommended):

cd ReiLua
chmod +x scripts/build_dev.sh
scripts/build_dev.sh

Manual Method:

cd ReiLua/build
cmake ..
make

4. Test

./ReiLua ../examples/snake/

MacOS

Not tested, but should work similarly to Linux.

Raspberry Pi

Works best when Raylib is compiled using PLATFORM=DRM. See Raylib build instructions for Raspberry Pi.

Compile ReiLua with:

cmake .. -DDRM=ON

Note: DRM should be launched from CLI, not in X.

Web (Emscripten)

Compile Raylib for web following its instructions: https://github.com/raysan5/raylib/wiki/Working-for-Web-(HTML5)

1. Compile Lua for Web

Modify Lua's makefile:

# Change:
MYCFLAGS= $(LOCAL) -std=c99 -DLUA_USE_LINUX -DLUA_USE_READLINE
# To:
MYCFLAGS= $(LOCAL) -std=c99

# Change:
MYLIBS= -ldl -lreadline
# To:
MYLIBS= -ldl

# Change:
CC= gcc
# To:
CC= emcc

# Change:
CFLAGS= -Wall -O2 $(MYCFLAGS) -fno-stack-protector -fno-common -march=native
# To:
CFLAGS= -Wall -O2 $(MYCFLAGS) -fno-stack-protector -fno-common

# Change:
AR= ar rc
# To:
AR= emar

# Change:
$(AR) $@ $?
# To:
$(AR) rcs $@ $?

Build with make if emsdk environmental variables are correct.

2. Prepare Libraries

Put libraylib.a and liblua.a into ReiLua/lib/web/.

3. Create Resources Folder

cd ReiLua/build
mkdir resources
# Copy main.lua to resources/
# Copy assets to resources/

Structure:

ReiLua/
└── build/
    └── resources/
        ├── main.lua
        └── assets/

4. Build

cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=<YOUR_PATH>/emsdk/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake -DPLATFORM=Web
make

5. Test

python -m http.server 8080

Access in browser: localhost:8080/ReiLua.html

Complete Release Workflow

Step 1: Prepare Your Game

MyGame/
├── main.lua
├── player.lua
├── enemy.lua
├── assets/
│   ├── player.png
│   ├── enemy.png
│   └── music.wav

Step 2: Copy Files to Build Directory

cd ReiLua/build

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

# Copy assets
mkdir assets
copy ..\MyGame\assets\* assets\
# Or: xcopy /E /I ..\MyGame\assets assets

Step 3: Build Release

cd ..
scripts\build_release.bat
# Or: scripts/build_release.sh on Linux

Step 4: Test

cd build
ReiLua.exe --log

Verify:

• ✅ No file loading errors
• ✅ Game runs correctly
• ✅ All assets load properly

Step 5: Distribute

mkdir Distribution
copy ReiLua.exe Distribution\YourGameName.exe

Your game is now a single executable ready for distribution!

Customizing Your Executable

Change Executable Name

Edit CMakeLists.txt:

project( YourGameName )  # Change from "ReiLua"

Add Custom Icon

Replace icon.ico with your own icon file, then rebuild.

Edit Executable Properties

Edit resources.rc:

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

Customize Splash Screens

Edit src/splash.c:

const char* text = "YOUR STUDIO NAME";  // Change this

Replace logos:

# Replace these files before building
logo/raylib_logo.png
logo/reilua_logo.png

Setting Up Zed Editor

Zed is a modern, high-performance code editor. Here's how to set it up for ReiLua development:

Install Zed

Download from: https://zed.dev/

Setup Lua Language Support

1. Open Zed
2. Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
3. Type "install language server" and select Lua
4. Zed will automatically install the Lua Language Server

Configure for ReiLua

Create .zed/settings.json in your project root:

{
  "lsp": {
    "lua-language-server": {
      "settings": {
        "Lua": {
          "runtime": {
            "version": "Lua 5.4"
          },
          "diagnostics": {
            "globals": ["RL"]
          },
          "workspace": {
            "library": ["ReiLua_API.lua"]
          }
        }
      }
    }
  },
  "languages": {
    "Lua": {
      "format_on_save": "on",
      "formatter": "language_server"
    }
  }
}

Copy ReiLua API Definitions

Copy tools/ReiLua_API.lua to your project folder. This provides autocomplete and documentation for all ReiLua functions.

copy path\to\ReiLua\tools\ReiLua_API.lua your_game\

Keyboard Shortcuts

Useful Zed shortcuts for Lua development:

• Ctrl+P / Cmd+P - Quick file search
• Ctrl+Shift+F / Cmd+Shift+F - Search in files
• Ctrl+. / Cmd+. - Code actions
• F12 - Go to definition
• Shift+F12 - Find references
• Ctrl+Space - Trigger autocomplete

Extensions

Install useful extensions:

1. Press Ctrl+Shift+X / Cmd+Shift+X
2. Search and install:
   • Lua - Syntax highlighting and language support
   • Better Comments - Enhanced comment highlighting
   • Error Lens - Inline error display

Workspace Setup

Create a workspace for ReiLua projects:

1. Open your game folder in Zed
2. File → Add Folder to Workspace
3. Add the ReiLua source folder (for reference)
4. File → Save Workspace As...

This lets you easily reference ReiLua source while developing your game.

Debugging

For debugging Lua code with Zed:

1. Use print() statements liberally
2. Run ReiLua with --log flag to see output
3. Use RL.TraceLog() for more detailed logging:

RL.TraceLog(RL.LOG_INFO, "Player position: " .. x .. ", " .. y)
RL.TraceLog(RL.LOG_WARNING, "Low health!")
RL.TraceLog(RL.LOG_ERROR, "Failed to load asset!")

Terminal Integration

Run ReiLua directly from Zed's terminal:

1. Press Ctrl+` / Cmd+` to open terminal
2. Run your game:

path\to\ReiLua.exe --log --no-logo

Tips for ReiLua Development in Zed

1. Use Multiple Cursors: Alt+Click to add cursors, great for batch edits
2. Split Views: Ctrl+\ to split editor for side-by-side editing
3. Symbol Search: Ctrl+T / Cmd+T to search for functions
4. Zen Mode: Ctrl+K Z for distraction-free coding
5. Live Grep: Ctrl+Shift+F to search across all files

Documentation

Comprehensive Guides

• EMBEDDING.md - Complete guide to embedding Lua and assets
• ASSET_LOADING.md - Asset loading API and loading screen documentation
• SPLASH_SCREENS.md - Splash screen customization guide
• BUILD_SCRIPTS.md - Build scripts documentation
• API.md - Complete API reference (1000+ functions)
• UPGRADE_SUMMARY.md - Technical details of enhancements

Quick References

• docs/API.md - All ReiLua/Raylib functions
• tools/ReiLua_API.lua - Lua annotations for IDE autocomplete
• examples/ - Example games and demos

Troubleshooting

Common Issues

Game doesn't start:

• Run with --log to see error messages
• Check that main.lua exists
• Verify all required assets exist

Assets not loading:

• Check file paths (use forward slashes or escaped backslashes)
• Verify files exist in the correct location
• Use --log to see loading errors

Splash screens don't show:

• Check you're not using --no-logo flag
• Verify build completed successfully
• Rebuild project: cmake --build . --config Release

Lua files not embedded:

• Ensure Lua files are in build/ directory before building
• Check main.lua exists
• Verify -DEMBED_MAIN=ON was used

Assets not embedded:

• Create build/assets/ folder
• Copy assets before building
• Verify -DEMBED_ASSETS=ON was used

Build fails:

• Check CMake and compiler are installed and in PATH
• Verify libraylib.a and liblua.a are in lib/ folder
• Try clean build: scripts\build_dev.bat clean

Getting Help

1. Check documentation files listed above
2. Review the examples in examples/ folder
3. Use --log flag to see detailed error messages
4. Check your file paths and directory structure

Contributing

Contributions are welcome! This is an enhanced version with additional features. When contributing:

1. Test thoroughly with both development and release builds
2. Update documentation if adding features
3. Follow existing code style
4. Test on multiple platforms if possible

License

ReiLua is licensed under the zlib/libpng license. See LICENSE file for details.

Third-Party Licenses

• Raylib - zlib/libpng license
• Lua - MIT license
• Oleaguid Font - Check font documentation for licensing

Contact & Links

• Original ReiLua: https://github.com/Gamerfiend/ReiLua
• Raylib: https://github.com/raysan5/raylib
• Lua: https://www.lua.org/

Version Information

• ReiLua Version: Based on original ReiLua with enhancements
• Raylib Version: 5.5
• Lua Version: 5.4

---

Happy Game Development! 🎮