Assets

This module defines various methods for loading and using assets. It can use assets from a folder or a zip file.

Any asset has three stages. It can be indexed, cached and loaded:

• An indexed asset has its location saved and can be cached or loaded easily.

• A cached assets raw data is stored in memory for fast access. Thus it can be loaded very fast.

• A loaded asset is ready to be used in a program. It could be a e. g. be aSF::Texture instance.

Currently supported file types are:

• .txt for text => String

• .png for textures => SF::Texture

• .wav for sounds => SF::SoundBuffer

• .ogg for music => SF::Music

• .ttf for fonts => SF::Font

• .yml or .yaml for yaml data => YAML::Any

• .json for json data => JSON::Any

All Asset types are aliased and in the Scar::Assets::Asset union.

alias Text = String
alias Texture = SF::Texture
alias Sound = SF::SoundBuffer
alias Music = SF::Music
alias Font = SF::Font
alias Yaml = YAML::Any
alias Json = JSON::Any

alias Asset = Text | Texture | Sound | Music | Font | Yaml | Json

Usage

First of all, you have to index all of your assets, so they can be found by the asset manager. To do this, just call Assets.use(file_or_folder_name) with the path to your asset folder or zipfile.

After indexing, each file is available via its path relative to the indexed folder or zipfile as root. .../indexed_folder/subfolder/asset.txt => subfolder/asset.txt.

After that, it is recommended to cache assets so they can be loaded more quickly. When using a zipfile this is required because sfml cannot load assets from a zipfile, only from a regular file or from memory.

To get an asset, you can either get it via the #[] method, where you have to provide the filename and asset type to get the desired asset, or you can use the shortcuts for each asset type: #text, #texture, #sound, #music, #font, #yaml, #json

Sound

You should only use Sounds given to you by Assets#sound, as Sounds have to be unloaded manually before destroying their underlying soundbuffer. Assets takes care of that, but only if you create them though the shortcut method. Read the SFML wiki for further explaination.

Note that caching obviously consumes more memory than just loading assets from the file system. If your assets consume much space, you should rather just load them without caching. Just keep loading times in mind.

Assets.use "assets" # Must be in working directory

# This indexes and caches all assets inside the zipfile
Assets.cache_zipfile "assets2.zip" 

Assets.cache "wall.png"

Assets.load "wall.png"
Assets.load_all # Use that to load all indexed assets

# For [] you have to provide the type so you can use it as such
# and do not have to type check it like
# do_sth if wall_tex.is_a? Assets::Texture
# 
wall_tex = Assets["wall.png", Assets::Texture]
# a simpler way is to use the shortcut:
wall_tex = Assets.texture "wall.png"
wall_sprite = Components::Sprite.new wall_tex

# This removes the asset data from the cache
Assets.dechache "wall.png"
Assets.unload "wall.png" # This unloads the asset
Assets.unload_all