# 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 a`SF::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. ```ruby 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](https://www.sfml-dev.org/tutorials/2.5/audio-sounds.php) for further explaination. {% hint style="info" %} 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. {% endhint %} ```ruby 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 ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://vypxl.gitbook.io/scar/builtin-features/assets.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.