luxe API (2025.1.2)

---

luxe: assets module

• Assets
• Strings

---

Assets

import "luxe: assets" for Assets

The Assets services is how you access loaded assets, and query if an asset is loaded. The primary use for this at the moment is the accessors like Assets.image, and finding out if an asset is loaded via Assets.has_image.

Note that the asset system is a work in progress and is not final. There are several accessors missing, for example, fonts are often referenced as a string, not via Assets.font("fonts/name"). Later, all assets will be unified into this form as intended.

Also, they're supposed to be able to reload dynamically, many can't currently. And remember the input to the asset system is compiled assets, not the assets themselves.

Finally, there are functions in the API that shouldn't be used directly (they aren't listed here.)

• db_init()
• db_commit(db: AssetDB)
• db_default()
• db_default_set(db: AssetDB)
• db_commit_post(db: AssetDB)
• db_commit_refs(db: AssetDB)
• db_add_root_path(db: AssetDB, path: String, subfolder: String, prefix: String)
• db_add_item(db: AssetDB, root: String, path: String, is_directory: Bool)
• db_make_item(db: AssetDB, root: String, path: String, is_directory: Bool)
• db_make_item(db: AssetDB, root: String, path: String)
• db_remove_item(db: AssetDB, asset_id: String)
• db_add_item(db: AssetDB, root: String, path: String)
• db_add_ignore(db: AssetDB, globs: List)
• db_asset_from_path(db: AssetDB, path: String)
• db_asset_from_id(db: AssetDB, asset_id: String)
• db_asset_from_uuid(db: AssetDB, meta_uuid: String)
• db_asset_get_root(db: AssetDB, asset_id: String)
• db_compile(db: AssetDB)
• db_parse(bytes: String)
• db_has(db: AssetDB, asset_id: String)
• db_add_reference(db: AssetDB, from_asset_id: String, to_asset_id: String)
• db_reset_references(db: AssetDB, asset_id: String)
• db_get_references(db: AssetDB, asset_id: String)
• db_get_referenced_by(db: AssetDB, asset_id: String)
• list(db: AssetDB)
• list(db: AssetDB, ext: String, subtype: String)
• list(db: AssetDB, ext: String, subtype: String, root: String)
• list(db: AssetDB, ext: String)
• list_folders(db: AssetDB, root: String, use_path: Bool)
• db_list_tags(db: AssetDB)
• db_get_tags(db: AssetDB, asset_id: String)
• db_get_tagged(db: AssetDB, tag: String)
• db_get_tagged_from_list(db: AssetDB, tags: List)
• db_add_tags(db: AssetDB, asset_id: String, tags: List)
• db_remove_tags(db: AssetDB, asset_id: String, tags: List)
• modified(db: AssetDB, query_id: String)
• modified(db: AssetDB, query_id: String, ext: String, subtype: String)
• modified(db: AssetDB, query_id: String, ext: String, subtype: String, root: String)
• modified(db: AssetDB, query_id: String, ext: String)
• unmodified(db: AssetDB, query_id: String, asset_id: String)
• modify(db: AssetDB, query_id: String, asset_id: String)
• is_modified(db: AssetDB, query_id: String, asset_id: String)
• get_data(type_id: String, id: String)
• get_block(type_id: String)
• get_handle(type_id: String, id: String)
• set_handle(type_id: String, id: String, handle: Num)
• get_dev_version_path(db: AssetDB, asset_id: String)
• get_dev_version_data(db: AssetDB, asset_id: String)
• save_dev_version_data(db: AssetDB, asset_id: String, version_data: Map)
• image(id: String)
• bytes(id: String)
• material(id: String)
• atlas(id: String)
• lx(id: String)
• has_shader_library(id: String)
• has_image(id: String)
• has_material_basis(id: String)
• has_material(id: String)
• has_bytes(id: String)
• has_settings(id: String)
• has_atlas(id: String)
• has_physics(id: String)
• has_prototype(id: String)
• has_scene(id: String)
• has_input(id: String)
• has_anim(id: String)
• has_mesh(id: String)
• has_tiles(id: String)
• has_ui(id: String)
• unload_input(id: String)
• load_input(id: String)

---

Assets.db_init() returns AssetDB

no docs found

Assets.db_commit(db: AssetDB) returns unknown

no docs found

Assets.db_default() returns AssetDB

no docs found

Assets.db_default_set(db: AssetDB) returns None

no docs found

Assets.db_commit_post(db: AssetDB) returns unknown

no docs found

Assets.db_commit_refs(db: AssetDB) returns unknown

no docs found

Assets.db_add_root_path(db: AssetDB, path: String, subfolder: String, prefix: String) returns None

no docs found

Assets.db_add_item(db: AssetDB, root: String, path: String, is_directory: Bool) returns None

no docs found

Assets.db_make_item(db: AssetDB, root: String, path: String, is_directory: Bool) returns Map

no docs found

Assets.db_make_item(db: AssetDB, root: String, path: String) returns None

no docs found

Assets.db_remove_item(db: AssetDB, asset_id: String) returns Bool

no docs found

Assets.db_add_item(db: AssetDB, root: String, path: String) returns None

no docs found

Assets.db_add_ignore(db: AssetDB, globs: List) returns None

no docs found

Assets.db_asset_from_path(db: AssetDB, path: String) returns Map

no docs found

Assets.db_asset_from_id(db: AssetDB, asset_id: String) returns Map

no docs found

Assets.db_asset_from_uuid(db: AssetDB, meta_uuid: String) returns Map

no docs found

Assets.db_asset_get_root(db: AssetDB, asset_id: String) returns String

no docs found

Assets.db_compile(db: AssetDB) returns String

no docs found

Assets.db_parse(bytes: String) returns AssetDB

no docs found

Assets.db_has(db: AssetDB, asset_id: String) returns Bool

no docs found

Assets.db_add_reference(db: AssetDB, from_asset_id: String, to_asset_id: String) returns None

no docs found

Assets.db_reset_references(db: AssetDB, asset_id: String) returns None

no docs found

Assets.db_get_references(db: AssetDB, asset_id: String) returns List

no docs found

Assets.db_get_referenced_by(db: AssetDB, asset_id: String) returns List

no docs found

Assets.list(db: AssetDB) returns List

no docs found

Assets.list(db: AssetDB, ext: String, subtype: String) returns List

no docs found

Assets.list(db: AssetDB, ext: String, subtype: String, root: String) returns List

no docs found

Assets.list(db: AssetDB, ext: String) returns List

no docs found

Assets.list_folders(db: AssetDB, root: String, use_path: Bool) returns List

no docs found

Assets.db_list_tags(db: AssetDB) returns List

no docs found

Assets.db_get_tags(db: AssetDB, asset_id: String) returns List

no docs found

Assets.db_get_tagged(db: AssetDB, tag: String) returns List

no docs found

Assets.db_get_tagged_from_list(db: AssetDB, tags: List) returns List

no docs found

Assets.db_add_tags(db: AssetDB, asset_id: String, tags: List) returns None

no docs found

Assets.db_remove_tags(db: AssetDB, asset_id: String, tags: List) returns None

no docs found

Assets.modified(db: AssetDB, query_id: String) returns List

no docs found

Assets.modified(db: AssetDB, query_id: String, ext: String, subtype: String) returns List

no docs found

Assets.modified(db: AssetDB, query_id: String, ext: String, subtype: String, root: String) returns List

no docs found

Assets.modified(db: AssetDB, query_id: String, ext: String) returns List

no docs found

Assets.unmodified(db: AssetDB, query_id: String, asset_id: String) returns None

no docs found

Assets.modify(db: AssetDB, query_id: String, asset_id: String) returns None

no docs found

Assets.is_modified(db: AssetDB, query_id: String, asset_id: String) returns Bool

no docs found

Assets.get_data(type_id: String, id: String) returns String

no docs found

Assets.get_block(type_id: String) returns Block

no docs found

Assets.get_handle(type_id: String, id: String) returns Num

no docs found

Assets.set_handle(type_id: String, id: String, handle: Num) returns None

no docs found

Assets.get_dev_version_path(db: AssetDB, asset_id: String) returns unknown

no docs found

Assets.get_dev_version_data(db: AssetDB, asset_id: String) returns Map

no docs found

Assets.save_dev_version_data(db: AssetDB, asset_id: String, version_data: Map) returns None

no docs found

Assets.image(id: String) returns Image

Return a loaded image by id.

var image = Assets.image("image/player")
Log.print("width: %(Image.get_width(image))")

Assets.bytes(id: String) returns String

Returns the data stored as bytes. A Wren String is also a byte sequence, used via string.bytes.

Note That unlike other assets, bytes are stored by name with extension. For example if you put a file called data/hello.txt in your project, you would access it via var data = Assets.bytes("data/hello.txt").

This is because the extension might be meaningful to the user of the bytes, for example loading an image based on png vs jpg extension would be impossible if we don't know the extension of the data. Because bytes are "opaque", as in, we don't care what they store, we just store them for you to access, we keep the extension.

var text = Assets.bytes("data/hello.txt")
Log.print(text) //prints the contents of the file (the contents at compile time).

Assets.material(id: String) returns Material

Returns a loaded material by id.

var material = Assets.material("material/player")
Sprite.set_material(player, material)

Assets.atlas(id: String) returns Atlas

Returns a loaded atlas by id.

var atlas = Assets.atlas("atlas/example")

Assets.lx(id: String) returns Any

Returns the LX parsed representation of a bytes asset. This is convenience for Assets.bytes followed by LX.parse. Returns null if the asset isn't found, or if parsing failed.

See Assets.bytes, as bytes require an extension.

//assuming our data contains { speaker="sara" message="follow me." }
var dialog = Assets.lx("dialog/hello.lx")
var speaker = dialog["speaker"]
var message = dialog["message"]
Log.print("%(speaker): %(message)")

Assets.has_shader_library(id: String) returns Bool

Returns true if a shader library with this id is loaded, or false otherwise.

var exists = Assets.has_shader_library("assets/shaders")

Assets.has_image(id: String) returns Bool

Returns true if an image with this id is loaded, or false otherwise.

var exists = Assets.has_image("image/player")

Assets.has_material_basis(id: String) returns Bool

Returns true if a material basis with this id is loaded, or false otherwise.

var exists = Assets.has_material_basis("basis/example")

Assets.has_material(id: String) returns Bool

Returns true if a material with this id is loaded, or false otherwise.

var exists = Assets.has_material("material/player")

Assets.has_bytes(id: String) returns Bool

Returns true if a bytes asset with this id is loaded, or false otherwise.

var exists = Assets.has_bytes("data/hello.txt")

Assets.has_settings(id: String) returns Bool

Returns true if a settings asset with this id is loaded, or false otherwise.

var exists = Assets.has_settings("settings/area1")

Assets.has_atlas(id: String) returns Bool

Returns true if an atlas asset with this id is loaded, or false otherwise.

var exists = Assets.has_atlas("atlas/example")

Assets.has_physics(id: String) returns Bool

Returns true if a physics asset with this id is loaded, or false otherwise.

var exists = Assets.has_physics("physics/ice")

Assets.has_prototype(id: String) returns Bool

Returns true if a prototype with this id is loaded, or false otherwise.

var exists = Assets.has_prototype("proto/tree")

Assets.has_scene(id: String) returns Bool

Returns true if a scene with this id is loaded, or false otherwise.

var exists = Assets.has_scene("scene/area1")

Assets.has_input(id: String) returns Bool

Returns true if an input asset with this id is loaded, or false otherwise.

var exists = Assets.has_input("input/player")

Assets.has_anim(id: String) returns Bool

Returns true if an animation with this id is loaded, or false otherwise.

var exists = Assets.has_anim("anim/jump")

Assets.has_mesh(id: String) returns Bool

Returns true if a mesh with this id is loaded, or false otherwise.

var exists = Assets.has_mesh("mesh/cube")

Assets.has_tiles(id: String) returns Bool

Returns true if a tilemap with this id is loaded, or false otherwise.

var exists = Assets.has_tiles("tiles/caves")

Assets.has_ui(id: String) returns Bool

Returns true if a ui asset with this id is loaded, or false otherwise.

var exists = Assets.has_ui("ui/menu")

Assets.unload_input(id: String) returns None

Unload the input asset, which undefines any nodes or events

Assets.load_input(id: String) returns None

Load an input asset, which defines any nodes or events within it

Strings

import "luxe: assets" for Strings

When dealing with data like assets, storing a string directly can take up a lot of space. Instead, what we can do is store the strings once, in a shared place, and then reference that string later.

At runtime, strings can also be more expensive than is ideal (like needing to iterate the characters individually, or taking up more memory).

In both cases, what we store instead of a string is a string id, which is just a number.

Comparing two numbers, looking up numbers in an array or map and so on, it's much faster with a number than using the string itself. Operating on numbers is both faster and simpler, and has a fixed size in memory. This is commonly called "string interning".

In luxe, the Strings class is how you interact with the strings available to your game. For example, var name_id = Entity.get_name(entity) will return a string id, not a string. To get the string, you can use var name = Strings.get(name_id). Note that if the name is unknown to Strings, it will return null, so handle that appropriately.

To add a string, use Strings.add("string").

For debugging strings, if you look inside .luxe/luxe.strings.lx, this lists all the strings your assets reference, and what their key is.

//Assuming this string hasn't been added before:
Log.print( Strings.get("hello") ) //prints null
var key = Strings.add("hello") //key is 1335831723
Log.print( Strings.get("hello") ) //prints 'hello'

• add(value: String)
• get(key: Num)

---

Strings.add(value: String) returns Num

Adds a string to the Strings service and returns the key.

Log.print(Strings.add("hello")) //prints 1335831723

Strings.get(key: Num) returns String

Return the value associated with the given key. This will return null if the string is not found.

var name_id = Entity.get_name(entity)
var name = Strings.get(name_id)
if(name) {
  Log.print("entity name is %(name)")
} else {
  Log.print("entity name is not known (or it has no name)")
}