cleaned up root folder, organized files into docs/scripts/tools dirs
This commit is contained in:
285
docs/ASSET_LOADING.md
Normal file
285
docs/ASSET_LOADING.md
Normal file
@@ -0,0 +1,285 @@
|
||||
# Asset Loading System
|
||||
|
||||
ReiLua includes a built-in asset loading system with a nice loading screen UI that automatically shows progress while assets are being loaded.
|
||||
|
||||
## 🎨 Features
|
||||
|
||||
- **Automatic Progress Tracking** - Tracks how many assets have been loaded
|
||||
- **Beautiful Loading UI** - Modern, minimal loading screen with:
|
||||
- Animated "Loading..." text with dots
|
||||
- Smooth progress bar with shimmer effect
|
||||
- Progress percentage (e.g., "3 / 10")
|
||||
- Current asset name being loaded
|
||||
- Dark, clean color scheme
|
||||
- **Easy to Use** - Just 3 functions to show loading progress
|
||||
- **Works Everywhere** - 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)
|
||||
|
||||
**Visual Layout:**
|
||||
```
|
||||
[Black Background]
|
||||
|
||||
┌─┐ ┌─┐
|
||||
│ │ LOADING □ □ │ │
|
||||
│ │ │ │
|
||||
│ │ ┌──────────────────┐ │ │
|
||||
│ │ │████████░░░░░░░░░░│ 3/10 │ │
|
||||
│ │ └──────────────────┘ │ │
|
||||
│ │ │ │
|
||||
│ │ player.png │ │
|
||||
│ │ │ │
|
||||
└─┘ └─┘
|
||||
|
||||
[All text and UI elements in WHITE]
|
||||
```
|
||||
|
||||
**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!
|
||||
Reference in New Issue
Block a user