cleaned up root folder, organized files into docs/scripts/tools dirs
This commit is contained in:
230
docs/SPLASH_SCREENS.md
Normal file
230
docs/SPLASH_SCREENS.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# Splash Screens
|
||||
|
||||
ReiLua includes a built-in splash screen system that displays splash screens before your game loads. This gives your game a polished appearance right from startup.
|
||||
|
||||
## Overview
|
||||
|
||||
When you run your ReiLua game, it automatically shows two splash screens in sequence:
|
||||
|
||||
1. **Custom Text** - Clean, bold text on Raylib red background (similar to Squid Game style)
|
||||
2. **"Made using"** - Text with Raylib and ReiLua logos displayed side-by-side
|
||||
|
||||
Each splash screen:
|
||||
- Fades in over 0.8 seconds
|
||||
- Displays for 2.5 seconds
|
||||
- Fades out over 0.8 seconds
|
||||
- Total display time: 8.2 seconds for both screens
|
||||
|
||||
## Features
|
||||
|
||||
### Always Embedded
|
||||
|
||||
The logo images are **always embedded** into the executable in both development and release builds. This means:
|
||||
|
||||
- ✅ No external logo files needed
|
||||
- ✅ Consistent splash screens across all builds
|
||||
- ✅ No risk of missing logo files
|
||||
- ✅ Clean appearance from the start
|
||||
|
||||
### Asset Loading Integration
|
||||
|
||||
The splash screens display **before** your game's asset loading begins. This means:
|
||||
|
||||
1. User starts your game
|
||||
2. Splash screens play (~8 seconds)
|
||||
3. Your `RL.init()` function runs
|
||||
4. Asset loading with progress indicator (if you use it)
|
||||
5. Your game starts
|
||||
|
||||
This creates a smooth, polished startup experience.
|
||||
|
||||
## Skipping Splash Screens (Development)
|
||||
|
||||
During development, you often need to test your game repeatedly. Waiting for splash screens every time can slow down your workflow. Use the `--no-logo` flag to skip them:
|
||||
|
||||
```bash
|
||||
# Windows
|
||||
ReiLua.exe --no-logo
|
||||
|
||||
# Linux/Mac
|
||||
./ReiLua --no-logo
|
||||
|
||||
# With other options
|
||||
ReiLua.exe --log --no-logo
|
||||
./ReiLua --no-logo path/to/game/
|
||||
```
|
||||
|
||||
**Note:** The `--no-logo` flag only works in development. In release builds, users should see the full splash screen sequence.
|
||||
|
||||
## Technical Details
|
||||
|
||||
### How It Works
|
||||
|
||||
The splash screen system is implemented in C and runs before any Lua code executes:
|
||||
|
||||
1. **Logo Embedding**: During build, `scripts/embed_logo.py` converts PNG files to C byte arrays
|
||||
2. **Initialization**: Before calling `RL.init()`, the engine initializes splash screens
|
||||
3. **Display Loop**: A dedicated loop handles timing, fading, and rendering
|
||||
4. **Cleanup**: After completion, resources are freed and Lua code begins
|
||||
|
||||
### Files
|
||||
|
||||
- `src/splash.c` - Splash screen implementation
|
||||
- `include/splash.h` - Header file
|
||||
- `scripts/embed_logo.py` - Python script to embed logo images
|
||||
- `logo/raylib_logo.png` - Raylib logo (embedded)
|
||||
- `logo/reilua_logo.png` - ReiLua logo (embedded)
|
||||
|
||||
### Build Integration
|
||||
|
||||
The CMakeLists.txt automatically:
|
||||
|
||||
1. Runs `scripts/embed_logo.py` during build
|
||||
2. Generates `embedded_logo.h` with logo data
|
||||
3. Defines `EMBED_LOGO` flag
|
||||
4. Compiles `splash.c` with the project
|
||||
|
||||
No manual steps required - it just works!
|
||||
|
||||
## Customization
|
||||
|
||||
### Changing Splash Screen Text
|
||||
|
||||
To change the default text to your studio name:
|
||||
|
||||
1. Open `src/splash.c`
|
||||
2. Find the splash drawing function
|
||||
3. Change the text line:
|
||||
```c
|
||||
const char* text = "YOUR STUDIO NAME";
|
||||
```
|
||||
4. Rebuild the project
|
||||
|
||||
**Note:** Use ALL CAPS for the Squid Game-style aesthetic.
|
||||
|
||||
### Changing Logos
|
||||
|
||||
To use different logos:
|
||||
|
||||
1. Replace `logo/raylib_logo.png` and/or `logo/reilua_logo.png` with your images
|
||||
2. Recommended size: 256x256 or smaller (logos are auto-scaled to max 200px)
|
||||
3. Format: PNG with transparency support
|
||||
4. Rebuild the project - logos will be automatically embedded
|
||||
|
||||
### Changing Timing
|
||||
|
||||
To adjust how long each screen displays:
|
||||
|
||||
1. Open `src/splash.c`
|
||||
2. Modify these constants at the top:
|
||||
```c
|
||||
#define FADE_IN_TIME 0.8f // Seconds to fade in
|
||||
#define DISPLAY_TIME 2.5f // Seconds to display fully
|
||||
#define FADE_OUT_TIME 0.8f // Seconds to fade out
|
||||
```
|
||||
3. Rebuild the project
|
||||
|
||||
### Removing Splash Screens Entirely
|
||||
|
||||
If you don't want any splash screens:
|
||||
|
||||
1. Open `src/main.c`
|
||||
2. Find this block:
|
||||
```c
|
||||
/* Show splash screens if not skipped */
|
||||
if ( !skip_splash ) {
|
||||
splashInit();
|
||||
// ... splash code ...
|
||||
splashCleanup();
|
||||
}
|
||||
```
|
||||
3. Comment out or remove the entire block
|
||||
4. Rebuild the project
|
||||
|
||||
## Example: Complete Startup Sequence
|
||||
|
||||
Here's what a typical game startup looks like with everything enabled:
|
||||
|
||||
```bash
|
||||
ReiLua.exe MyGame/
|
||||
```
|
||||
|
||||
**User Experience:**
|
||||
|
||||
1. **Splash Screen 1** (4.1 seconds)
|
||||
- Custom text displayed in bold (default: "YOUR STUDIO NAME")
|
||||
- Red background (Raylib color #E62937)
|
||||
- Subtle zoom effect
|
||||
|
||||
2. **Splash Screen 2** (4.1 seconds)
|
||||
- "Made using" text at top
|
||||
- Raylib + ReiLua logos side-by-side (max 200px each)
|
||||
- Black background
|
||||
|
||||
3. **Asset Loading** (varies)
|
||||
- Your loading screen with progress bar
|
||||
- Shows "Loading texture1.png", "3/10", etc.
|
||||
|
||||
4. **Game Start**
|
||||
- Your game's main screen appears
|
||||
- Player can interact
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Keep --no-logo for Development**: Always use `--no-logo` during active development
|
||||
2. **Test Without Flag**: Occasionally test without `--no-logo` to ensure splash screens work
|
||||
3. **Customize for Your Studio**: Change the text and logos to match your branding
|
||||
4. **Consider Total Time**: Splash (~8s) + Loading (varies) = Total startup time
|
||||
5. **Optimize Loading**: Keep asset loading fast to maintain a good first impression
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Splash Screens Don't Show
|
||||
|
||||
**Problem**: Game starts immediately without splash screens
|
||||
|
||||
**Solutions**:
|
||||
- Check you're not using `--no-logo` flag
|
||||
- Verify logos exist in `logo/` folder before building
|
||||
- Check console output for embedding errors
|
||||
- Rebuild project completely: `cmake .. && make clean && make`
|
||||
|
||||
### Logos Appear Corrupted
|
||||
|
||||
**Problem**: Logos display incorrectly or not at all
|
||||
|
||||
**Solutions**:
|
||||
- Verify PNG files are valid (open in image viewer)
|
||||
- Check file sizes aren't too large (keep under 1MB each)
|
||||
- Ensure PNGs use standard format (not progressive or exotic encoding)
|
||||
- Rebuild project to regenerate embedded data
|
||||
|
||||
### Compilation Errors
|
||||
|
||||
**Problem**: Build fails with logo-related errors
|
||||
|
||||
**Solutions**:
|
||||
- Ensure Python 3 is installed and in PATH
|
||||
- Check `scripts/embed_logo.py` has correct paths
|
||||
- Verify `logo/` folder exists with both PNG files
|
||||
- Check CMake output for specific error messages
|
||||
|
||||
## Command Reference
|
||||
|
||||
```bash
|
||||
# Development (skip splash)
|
||||
ReiLua --no-logo
|
||||
|
||||
# Development with logging
|
||||
ReiLua --log --no-logo
|
||||
|
||||
# Production/testing (full splash)
|
||||
ReiLua
|
||||
|
||||
# Help
|
||||
ReiLua --help
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
The splash screen system adds a polished touch to your ReiLua games with minimal effort. Customize it to match your studio's branding and give players a great first impression!
|
||||
Reference in New Issue
Block a user