reilua-enhanced/docs_md/ASSET_LOADING.md

Asset Loading System

ReiLua includes a built-in asset loading system with a loading screen UI that shows progress while assets are being loaded.

Features

• Automatic Progress Tracking - Tracks how many assets have been loaded
• Loading UI with:
  • Animated "Loading..." text with dots
  • Smooth progress bar with shimmer effect
  • Progress percentage (e.g., "3 / 10")
  • Current asset name being loaded
• Easy to Use - Just 3 functions to show loading progress
• Works in development and release builds

API Functions

RL.BeginAssetLoading(totalAssets)

Initialize asset loading progress tracking and show the loading screen.

Parameters:

• totalAssets (integer) - Total number of assets to load

Example:

RL.BeginAssetLoading(10)  -- We're loading 10 assets

---

RL.UpdateAssetLoading(assetName)

Update the loading progress and display current asset being loaded.

Parameters:

• assetName (string) - Name of the asset currently being loaded

Example:

RL.UpdateAssetLoading("player.png")

Call this after each asset is loaded to update the progress bar.

---

RL.EndAssetLoading()

Finish asset loading and hide the loading screen.

Example:

RL.EndAssetLoading()

Quick Example

function RL.init()
    -- List of assets to load
    local assetsToLoad = {
        "assets/player.png",
        "assets/enemy.png", 
        "assets/background.png",
        "assets/music.wav",
    }
    
    -- Begin loading
    RL.BeginAssetLoading(#assetsToLoad)
    
    -- Load each asset
    for i, path in ipairs(assetsToLoad) do
        RL.UpdateAssetLoading(path)  -- Update progress
        
        -- Load the actual asset
        if path:match("%.png$") or path:match("%.jpg$") then
            textures[i] = RL.LoadTexture(path)
        elseif path:match("%.wav$") or path:match("%.ogg$") then
            sounds[i] = RL.LoadSound(path)
        end
    end
    
    -- Done!
    RL.EndAssetLoading()
end

Complete Example

local assets = {}

local assetsToLoad = {
    {type="texture", name="player", path="assets/player.png"},
    {type="texture", name="enemy", path="assets/enemy.png"},
    {type="texture", name="background", path="assets/background.png"},
    {type="sound", name="music", path="assets/music.wav"},
    {type="sound", name="shoot", path="assets/shoot.wav"},
    {type="font", name="title", path="assets/title.ttf"},
}

function RL.init()
    RL.SetWindowTitle("My Game")
    
    -- Start loading with progress
    RL.BeginAssetLoading(#assetsToLoad)
    
    -- Load all assets
    for i, asset in ipairs(assetsToLoad) do
        -- Show current asset name on loading screen
        RL.UpdateAssetLoading(asset.name)
        
        -- Load based on type
        if asset.type == "texture" then
            assets[asset.name] = RL.LoadTexture(asset.path)
        elseif asset.type == "sound" then
            assets[asset.name] = RL.LoadSound(asset.path)
        elseif asset.type == "font" then
            assets[asset.name] = RL.LoadFont(asset.path)
        end
    end
    
    -- Loading complete!
    RL.EndAssetLoading()
    
    print("Game ready!")
end

function RL.update(delta)
    -- Your game logic
end

function RL.draw()
    RL.ClearBackground(RL.RAYWHITE)
    
    -- Use loaded assets
    if assets.background then
        RL.DrawTexture(assets.background, {0, 0}, RL.WHITE)
    end
    
    if assets.player then
        RL.DrawTexture(assets.player, {100, 100}, RL.WHITE)
    end
end

Loading Screen Appearance

The loading screen features a clean 1-bit pixel art style:

Design:

• Pure black and white aesthetic
• Retro pixel art styling
• Minimal and clean design

Elements:

• Title: "LOADING" in bold white pixel text
• Animated Dots: White pixelated dots (4x4 squares) that cycle
• Progress Bar:
  • 200px wide, 16px tall
  • Thick 2px white border (pixel art style)
  • White fill with black dithering pattern
  • Retro/Classic terminal aesthetic
• Progress Text: "3/10" in white pixel font style
• Asset Name: Current loading asset in small white text
• Corner Decorations: White pixel art L-shaped corners in all 4 corners

Background:

• Pure black background (#000000)
• High contrast for maximum clarity

Color Palette:

• White text and UI (#FFFFFF)
• Black background (#000000)
• Pure 1-bit aesthetic (inverted terminal style)

Style Inspiration:

• Classic terminal / console aesthetic
• MS-DOS loading screens
• 1-bit dithering patterns
• Chunky pixel borders
• Retro computing / CRT monitor style

Customization

If you want to customize the loading screen appearance, you can modify the colors and sizes in src/lua_core.c in the drawLoadingScreen() function.

Performance Tips

1. Call UpdateAssetLoading AFTER loading - This ensures the progress updates at the right time
2. Load assets in order of importance - Load critical assets first
3. Group similar assets - Load all textures, then sounds, etc.
4. Use descriptive names - Shows better feedback to users

Example Asset Loading Patterns

Pattern 1: Simple List

local files = {"player.png", "enemy.png", "music.wav"}
RL.BeginAssetLoading(#files)
for i, file in ipairs(files) do
    RL.UpdateAssetLoading(file)
    -- load file
end
RL.EndAssetLoading()

Pattern 2: With Types

local assets = {
    textures = {"player.png", "enemy.png"},
    sounds = {"music.wav", "shoot.wav"},
}
local total = #assets.textures + #assets.sounds

RL.BeginAssetLoading(total)
for _, file in ipairs(assets.textures) do
    RL.UpdateAssetLoading(file)
    -- load texture
end
for _, file in ipairs(assets.sounds) do
    RL.UpdateAssetLoading(file)
    -- load sound
end
RL.EndAssetLoading()

Pattern 3: Error Handling

RL.BeginAssetLoading(#files)
for i, file in ipairs(files) do
    RL.UpdateAssetLoading(file)
    
    if RL.FileExists(file) then
        -- load file
    else
        print("Warning: " .. file .. " not found")
    end
end
RL.EndAssetLoading()

When to Use

Use the loading system when:

• You have more than 5-10 assets to load
• Assets are large (images, sounds, fonts)
• Loading might take more than 1 second
• You want polished loading feedback

You can skip it when:

• You have very few, small assets
• Loading is nearly instant
• You prefer immediate game start

✨ Benefits

• Polished user experience
• User knows the game is loading, not frozen
• Shows progress for large asset sets
• Works with embedded assets
• Minimal code required
• Beautiful default UI

The loading system makes your game feel polished with just a few lines of code!