path: root/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:
```lua
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:
```lua
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:
```lua
RL.EndAssetLoading()
```

## Quick Example

```lua
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

```lua
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
```lua
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
```lua
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
```lua
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!