module Scar::Assets
Overview
This module provides a convenient interface for loading different kinds of assets Usage:
#use
a folder or zip file to index their contents- (optional) Use
#cache
(or#cache_zipfile
) to preload assets into memory without instatiating the respective asset types #load
(or#load_all
) the assets you want to use in your application- Use
#[]
or the more specific methods like#text
to retrieve the loaded instances of your assets
Loading the assets should be done in bulk at the start of the application or while a loading screen is shown, so that there are no mid-gameplay slowdowns
Music and Sound
Music and sound are somewhat special kinds of assets. It is recommended to use the Music
and the Sound
(coming soon) module to handle them. See the respective documentation for details.
Hot reloading
The Assets
module supports hot reloading of certain asset types.
The asset types that are reloaded automatically are: Texture
, Sound
, Music
, Font
Components::Tilemap
components can also automatically reload their data if you use their String
constructor (Components::Tilemap#new(String)
)
You can specify a block when retrieving assets, this block will get called when a change is detected. This works for all asset types.
To enable hot-reloading, set App#hotreload
to true
.
Hot-reloading only works if you are loading assets from plain files (not zipped) without caching them.
Exampe usage:
Scar::Assets.use "./assets"
Scar::Assets.load "textures/player.png"
tex = Scar::Assets.texture("textures/player.png") { |new_tex| puts "Player texture was modified" }
playerSprite = Scar::Components::Sprite.new tex
Extended Modules
Defined in:
scar/assets.crClass Method Summary
-
.default_font : Font | Nil
If you set this property,
Components::Text
components can be created without specifying a font. -
.default_font=(default_font : Font | Nil)
If you set this property,
Components::Text
components can be created without specifying a font.
Instance Method Summary
-
#[](name : String, asset_type, on_reload)
Fetches a loaded asset
-
#[](name : String, asset_type, &)
Fetches a loaded asset
-
#[]?(name : String, asset_type, on_reload)
Same as
#[]
, but returns nil if name does not correspond to a loaded asset -
#[]?(name : String, asset_type, &)
Same as
#[]
, but returns nil if name does not correspond to a loaded asset -
#cache(name : String)
Loads an indexed assets' data into memory so it does not need to be loaded from the filesystem
-
#cache_zipfile(fname : String)
Indexes a zip file and caches all its contents.
-
#decache(name : String)
Removes an assets' cache data
-
#font(name) : Font
Same as
#[name, Font]
-
#font(name, &block : Font -> ) : Font
Same as
#[name, Font, block]
-
#font?(name) : Font | Nil
Same as
#[name, Font]?
-
#font?(name, &block : Font -> ) : Font | Nil
Same as
#[name, Font, block]?
-
#json(name) : Json
Same as
#[name, Json]
-
#json(name, &block : Json -> ) : Json
Same as
#[name, Json, block]
-
#json?(name) : Json | Nil
Same as
#[name, Json]?
-
#json?(name, &block : Json -> ) : Json | Nil
Same as
#[name, Json, block]?
-
#load(name : String, asset_type)
Loads an Asset.
-
#load(name : String)
Same as
#load
, but guesses the asset type based upon its file extension -
#load_all
Loads all indexed assets in directories and all cached assets from zip files; both only if they have a known file extension
-
#music(name) : Music
Same as
#[name, Music]
-
#music(name, &block : Music -> ) : Music
Same as
#[name, Music, block]
-
#music?(name) : Music | Nil
Same as
#[name, Music]?
-
#music?(name, &block : Music -> ) : Music | Nil
Same as
#[name, Music, block]?
-
#sound(name) : Sound
Same as
#[name, Sound]
-
#sound(name, &block : Sound -> ) : Sound
Same as
#[name, Sound, block]
-
#sound?(name) : Sound | Nil
Same as
#[name, Sound]?
-
#sound?(name, &block : Sound -> ) : Sound | Nil
Same as
#[name, Sound, block]?
-
#text(name) : Text
Same as
#[name, Text]
-
#text(name, &block : Text -> ) : Text
Same as
#[name, Text, block]
-
#text?(name) : Text | Nil
Same as
#[name, Text]?
-
#text?(name, &block : Text -> ) : Text | Nil
Same as
#[name, Text, block]?
-
#texture(name) : Texture
Same as
#[name, Texture]
-
#texture(name, &block : Texture -> ) : Texture
Same as
#[name, Texture, block]
-
#texture?(name) : Texture | Nil
Same as
#[name, Texture]?
-
#texture?(name, &block : Texture -> ) : Texture | Nil
Same as
#[name, Texture, block]?
-
#tilemap(name) : Tilemap
Same as
#[name, Tilemap]
-
#tilemap(name, &block : Tilemap -> ) : Tilemap
Same as
#[name, Tilemap, block]
-
#tilemap?(name) : Tilemap | Nil
Same as
#[name, Tilemap]?
-
#tilemap?(name, &block : Tilemap -> ) : Tilemap | Nil
Same as
#[name, Tilemap, block]?
-
#unload(name : String)
Unloads (destroys) a loaded Asset
-
#unload_all
Unloads all loaded assets
-
#use(file_or_folder_name : String)
Indexes a folder or zip file containing assets
-
#yaml(name) : Yaml
Same as
#[name, Yaml]
-
#yaml(name, &block : Yaml -> ) : Yaml
Same as
#[name, Yaml, block]
-
#yaml?(name) : Yaml | Nil
Same as
#[name, Yaml]?
-
#yaml?(name, &block : Yaml -> ) : Yaml | Nil
Same as
#[name, Yaml, block]?
Class Method Detail
If you set this property, Components::Text
components can be created without specifying a font. They will use this font as a default.
Example usage:
Assets.default_font = Assets.font "fonts/arial.ttf"
If you set this property, Components::Text
components can be created without specifying a font. They will use this font as a default.
Example usage:
Assets.default_font = Assets.font "fonts/arial.ttf"
Instance Method Detail
Fetches a loaded asset
You have to specify the type of the asset type, or use the more specific functions.
Specify on_reload (type: Proc(asset_type, Nil)
) to execute some code when the asset is modified on disk (see hot-reloading).
Return type is asset_type.
Fetches a loaded asset
You have to specify the type of the asset type, or use the more specific functions.
Specify a block (type: Proc(asset_type, Nil)
) to execute some code when the asset is modified on disk (see hot-reloading).
Return type is asset_type.
Same as #[]
, but returns nil if name does not correspond to a loaded asset
Same as #[]
, but returns nil if name does not correspond to a loaded asset
Loads an indexed assets' data into memory so it does not need to be loaded from the filesystem
This method is for preloading; It does not load the asset, it only stores its raw data in memory for it to be quickly accesible.
Indexes a zip file and caches all its contents.
You can use this to preload all assets in the file at once.
Loads an Asset. See details
You must provide the correct asset_type for this method to work (or you can use the guessing load function).
Accepted types are all types of the Asset
Union.
An asset must be loaded via this method before using it.
This method utilizes cached data if it is available.
Zip entries that are not cached are implicitly cached because Assets cannot be created directly from zip entries (this is not recommended, cache the zipfile first!).
Zip file entries take precedence over plain files.
Same as #load
, but guesses the asset type based upon its file extension
- ".txt" => Text
- ".png" => Texture
- ".wav" => Sound
- ".ogg" => Music
- ".ttf" => Font
".yml", ".yaml" and ".json" are not loaded because these extensions are ambigous.
Loads all indexed assets in directories and all cached assets from zip files; both only if they have a known file extension
Same as #[name, Texture, block]?
Same as #[name, Tilemap, block]?
Unloads (destroys) a loaded Asset
Caution with assets like Textures or SoundBuffers, they could be referenced by Sprites or Sounds!