https://github.com/zhuravkovigor/love-sprite-loader
🎮 Automatic sprite loader for Love2D
https://github.com/zhuravkovigor/love-sprite-loader
docs love2d luarocks module sprites
Last synced: about 2 months ago
JSON representation
🎮 Automatic sprite loader for Love2D
- Host: GitHub
- URL: https://github.com/zhuravkovigor/love-sprite-loader
- Owner: zhuravkovigor
- License: mit
- Created: 2025-07-15T06:03:38.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-07-16T09:15:46.000Z (12 months ago)
- Last Synced: 2025-07-31T10:51:49.303Z (11 months ago)
- Topics: docs, love2d, luarocks, module, sprites
- Language: Lua
- Homepage:
- Size: 15.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# love-sprite-loader
🎮 Automatic sprite loader for Love2D
## Description
`love-sprite-loader` is a library for Love2D that automatically loads all images from a specified directory and returns a convenient table with camelCase names.
## Features
- ✨ Automatic conversion of file names from `snake_case` to `camelCase`
- 🖼️ Support for all major image formats (PNG, JPG, JPEG, BMP, TGA)
- 📁 Recursive loading from subdirectories
- 🚀 Simple and convenient API
- ⚡ Fast loading of all sprites with one command
## Installation
### Via LuaRocks:
```bash
luarocks install love-sprite-loader
```
### Via Git:
```bash
git clone https://github.com/zhuravkovigor/love-sprite-loader.git
```
Then copy `init.lua` to your project folder or add the cloned directory to your Lua path.
### Manual:
Download `init.lua` and place it in your project folder.
## Usage
### Basic usage
```lua
local spriteLoader = require("love-sprite-loader")
-- Load all images from "sprites" folder (flat structure, recursive)
local sprites = spriteLoader()
-- Or specify a folder explicitly
local sprites = spriteLoader("assets/images")
-- Now you can use sprites:
-- File "some_tree.png" becomes sprites.someTree
-- File "sprites/player/idle.png" becomes sprites.playerIdle
love.graphics.draw(sprites.someTree, 100, 100)
love.graphics.draw(sprites.playerIdle, 200, 200)
```
### Loading modes
```lua
-- Flat structure (default) - all sprites in one table
local sprites = spriteLoader("flat")
-- or
local sprites = spriteLoader("assets", "flat")
-- Nested structure - creates subtables by folders
local sprites = spriteLoader("nested")
-- or
local sprites = spriteLoader("assets", "nested")
-- Root folder only - doesn't go into subfolders
local sprites = spriteLoader("single")
-- or
local sprites = spriteLoader("assets", "single")
```
### Structure examples
Let's say we have a folder:
```
sprites/
├── background.png
├── player/
│ ├── idle.png
│ └── running.png
└── enemies/
├── goblin.png
└── boss/
└── dragon.png
```
#### "flat" mode (default):
```lua
local sprites = spriteLoader() -- or spriteLoader("flat")
-- Result:
sprites.background -- background.png
sprites.playerIdle -- player/idle.png
sprites.playerRunning -- player/running.png
sprites.enemiesGoblin -- enemies/goblin.png
sprites.enemiesBossDragon -- enemies/boss/dragon.png
```
#### "nested" mode:
```lua
local sprites = spriteLoader("nested")
-- Result:
sprites.background -- background.png
sprites.player.idle -- player/idle.png
sprites.player.running -- player/running.png
sprites.enemies.goblin -- enemies/goblin.png
sprites.enemies.boss.dragon -- enemies/boss/dragon.png
```
#### "single" mode:
```lua
local sprites = spriteLoader("single")
-- Result (only from root folder):
sprites.background -- background.png
-- Files from subfolders are NOT loaded
```
## API
### `spriteLoader([directoryOrMode], [mode])`
Single function for loading sprites with simple and flexible API.
**Call variants:**
- `spriteLoader()` - load from "sprites" in "flat" mode
- `spriteLoader("path")` - load from specified folder in "flat" mode
- `spriteLoader("flat")` - load from "sprites" in flat mode
- `spriteLoader("nested")` - load from "sprites" in nested mode
- `spriteLoader("single")` - load only from "sprites" root
- `spriteLoader("path", "nested")` - load from folder in nested mode
**Parameters:**
- `directoryOrMode` (string, optional) - path to directory or loading mode
- `mode` (string, optional) - loading mode (if first parameter is path)
**Modes:**
- `"flat"` (default) - flat structure, recursive loading
- `"nested"` - nested table structure by directories, recursive loading
- `"single"` - load only from root folder, flat structure
**Returns:** table with loaded sprites
## Supported formats
- PNG
- JPG/JPEG
- BMP
- TGA
## Example project
```lua
-- main.lua
local spriteLoader = require("love-sprite-loader")
local sprites
function love.load()
-- Load all sprites from "assets/sprites" folder with nested structure
sprites = spriteLoader("assets/sprites", "nested")
-- Now we have access to sprites:
-- sprites.background, sprites.player.idle, sprites.enemies.goblin, etc.
end
function love.draw()
love.graphics.draw(sprites.background, 0, 0)
love.graphics.draw(sprites.player.idle, 100, 100)
love.graphics.draw(sprites.enemies.goblin, 300, 200)
end
```
## Requirements
- Love2D 0.10.0+
- Lua 5.1+
## License
MIT License. See LICENSE file for details.
## Contributing
We welcome any suggestions and improvements! Please create issues and pull requests in our [GitHub repository](https://github.com/zhuravkovigor/love-sprite-loader).