Functions and constants to access resources.
Constructor-like function with two purposes:
[path] - optional resource path string to the resource
path - a path hash to the binary version of the resource
Load a material and set it to a sprite:
go.property("my_material", resource.material("/material.material"))
function init(self)
go.set("#sprite", "material", self.my_material)
end
go.property("my_material", resource.material("/material.material"))
function init(self)
go.set("#gui", "materials", self.my_material, {key = "my_material"})
end
Constructor-like function with two purposes:
[path] - optional resource path string to the resource
path - a path hash to the binary version of the resource
Load a font and set it to a label:
go.property("my_font", resource.font("/font.font"))
function init(self)
go.set("#label", "font", self.my_font)
end
go.property("my_font", resource.font("/font.font"))
function init(self)
go.set("#gui", "fonts", self.my_font, {key = "my_font"})
end
Constructor-like function with two purposes:
[path] - optional resource path string to the resource
path - a path hash to the binary version of the resource
Load a texture and set it to a model:
go.property("my_texture", resource.texture("/texture.png"))
function init(self)
go.set("#model", "texture0", self.my_texture)
end
Constructor-like function with two purposes:
[path] - optional resource path string to the resource
path - a path hash to the binary version of the resource
Load an atlas and set it to a sprite:
go.property("my_atlas", resource.atlas("/atlas.atlas"))
function init(self)
go.set("#sprite", "image", self.my_atlas)
end
go.property("my_atlas", resource.atlas("/atlas.atlas"))
function init(self)
go.set("#gui", "textures", self.my_atlas, {key = "my_atlas"})
end
Constructor-like function with two purposes:
[path] - optional resource path string to the resource
path - a path hash to the binary version of the resource
Set a unique buffer it to a sprite:
go.property("my_buffer", resource.buffer("/cube.buffer"))
function init(self)
go.set("#mesh", "vertices", self.my_buffer)
end
Constructor-like function with two purposes:
[path] - optional resource path string to the resource
path - a path hash to the binary version of the resource
Load tile source and set it to a tile map:
go.property("my_tile_source", resource.tile_source("/tilesource.tilesource"))
function init(self)
go.set("#tilemap", "tile_source", self.my_tile_source)
end
Sets the resource data for a specific resource
path - The path to the resource
buffer - The buffer of precreated data, suitable for the intended resource type
Assuming the folder "/res" is added to the project custom resources:
-- load a texture resource and set it on a sprite
local buffer = resource.load("/res/new.texturec")
resource.set(go.get("#sprite", "texture0"), buffer)
Loads the resource data for a specific resource.
path - The path to the resource
buffer - Returns the buffer stored on disc
-- read custom resource data into buffer
local buffer = resource.load("/resources/datafile")
[project]
title = My project
version = 0.1
custom_resources = resources/,assets/level_data.json
Creates a new texture resource that can be used in the same way as any texture created during build time. The path used for creating the texture must be unique, trying to create a resource at a path that is already registered will trigger an error. If the intention is to instead modify an existing texture, use the resource.set_texture function. Also note that the path to the new texture resource must have a '.texturec' extension, meaning "/path/my_texture" is not a valid path but "/path/my_texture.texturec" is. If the texture is created without a buffer, the pixel data will be blank.
path - The path to the resource.
table - A table containing info about how to create the texture. Supported entries:
type
resource.TEXTURE_TYPE_2D
resource.TEXTURE_TYPE_CUBE_MAP
width
height
format
resource.TEXTURE_FORMAT_LUMINANCE
resource.TEXTURE_FORMAT_RGB
resource.TEXTURE_FORMAT_RGBA
resource.TEXTURE_FORMAT_RGB_PVRTC_2BPPV1
resource.TEXTURE_FORMAT_RGB_PVRTC_4BPPV1
resource.TEXTURE_FORMAT_RGBA_PVRTC_2BPPV1
resource.TEXTURE_FORMAT_RGBA_PVRTC_4BPPV1
resource.TEXTURE_FORMAT_RGB_ETC1
resource.TEXTURE_FORMAT_RGBA_ETC2
resource.TEXTURE_FORMAT_RGBA_ASTC_4x4
resource.TEXTURE_FORMAT_RGB_BC1
resource.TEXTURE_FORMAT_RGBA_BC3
resource.TEXTURE_FORMAT_R_BC4
resource.TEXTURE_FORMAT_RG_BC5
resource.TEXTURE_FORMAT_RGBA_BC7
resource.TEXTURE_FORMAT_RGB16F
resource.TEXTURE_FORMAT_RGB32F
resource.TEXTURE_FORMAT_RGBA16F
resource.TEXTURE_FORMAT_RGBA32F
resource.TEXTURE_FORMAT_R16F
resource.TEXTURE_FORMAT_RG16F
resource.TEXTURE_FORMAT_R32F
resource.TEXTURE_FORMAT_RG32F
if resource.TEXTURE_FORMAT_RGBA16F ~= nil then
-- it is safe to use this format
end
max_mipmaps
compression_type
COMPRESSION_TYPE_DEFAULT
COMPRESSION_TYPE_BASIS_UASTC
buffer - optional buffer of precreated pixel data
path - The path to the resource.
How to create an 128x128 floating point texture (RGBA32F) resource from a buffer object
function init(self)
-- Create a new buffer with 4 components and FLOAT32 type
local tbuffer = buffer.create(128 * 128, { {name=hash("rgba"), type=buffer.VALUE_TYPE_FLOAT32, count=4} } )
local tstream = buffer.get_stream(tbuffer, hash("rgba"))
-- Fill the buffer stream with some float values
for y=1,128 do
for x=1,128 do
local index = (y-1) * 128 * 4 + (x-1) * 4 + 1
tstream[index + 0] = 999.0
tstream[index + 1] = -1.0
tstream[index + 2] = 0.5
tstream[index + 3] = 1.0
end
end
-- Create a 2D Texture with a RGBA23F format
local tparams = {
width = 128,
height = 128,
type = resource.TEXTURE_TYPE_2D,
format = resource.TEXTURE_FORMAT_RGBA32F,
}
-- Note that we pass the buffer as the last argument here!
local my_texture_id = resource.create_texture("/my_custom_texture.texturec", tparams, tbuffer)
-- assign the texture to a model
go.set("#model", "texture0", my_texture_id)
end
Creates a new texture resource that can be used in the same way as any texture created during build time. The path used for creating the texture must be unique, trying to create a resource at a path that is already registered will trigger an error. If the intention is to instead modify an existing texture, use the resource.set_texture function. Also note that the path to the new texture resource must have a '.texturec' extension, meaning "/path/my_texture" is not a valid path but "/path/my_texture.texturec" is. If the texture is created without a buffer, the pixel data will be blank. The difference between the async version and resource.create_texture is that the texture data will be uploaded in a graphics worker thread. The function will return a resource immediately that contains a 1x1 blank texture which can be used immediately after the function call. When the new texture has been uploaded, the initial blank texture will be deleted and replaced with the new texture. Be careful when using the initial texture handle handle as it will not be valid after the upload has finished.
path - The path to the resource.
table -
type
resource.TEXTURE_TYPE_2D
resource.TEXTURE_TYPE_CUBE_MAP
width
height
format
resource.TEXTURE_FORMAT_LUMINANCE
resource.TEXTURE_FORMAT_RGB
resource.TEXTURE_FORMAT_RGBA
resource.TEXTURE_FORMAT_RGB_PVRTC_2BPPV1
resource.TEXTURE_FORMAT_RGB_PVRTC_4BPPV1
resource.TEXTURE_FORMAT_RGBA_PVRTC_2BPPV1
resource.TEXTURE_FORMAT_RGBA_PVRTC_4BPPV1
resource.TEXTURE_FORMAT_RGB_ETC1
resource.TEXTURE_FORMAT_RGBA_ETC2
resource.TEXTURE_FORMAT_RGBA_ASTC_4x4
resource.TEXTURE_FORMAT_RGB_BC1
resource.TEXTURE_FORMAT_RGBA_BC3
resource.TEXTURE_FORMAT_R_BC4
resource.TEXTURE_FORMAT_RG_BC5
resource.TEXTURE_FORMAT_RGBA_BC7
resource.TEXTURE_FORMAT_RGB16F
resource.TEXTURE_FORMAT_RGB32F
resource.TEXTURE_FORMAT_RGBA16F
resource.TEXTURE_FORMAT_RGBA32F
resource.TEXTURE_FORMAT_R16F
resource.TEXTURE_FORMAT_RG16F
resource.TEXTURE_FORMAT_R32F
resource.TEXTURE_FORMAT_RG32F
if resource.TEXTURE_FORMAT_RGBA16F ~= nil then
-- it is safe to use this format
end
max_mipmaps
compression_type
COMPRESSION_TYPE_DEFAULT
COMPRESSION_TYPE_BASIS_UASTC
buffer - optional buffer of precreated pixel data
path - The path to the resource.
request_id - The request id for the async request.
Create a texture resource asyncronously without a callback
function init(self)
-- Create a texture resource async
local tparams = {
width = 128,
height = 128,
type = resource.TEXTURE_TYPE_2D,
format = resource.TEXTURE_FORMAT_RGBA,
}
-- Create a new buffer with 4 components
local tbuffer = buffer.create(tparams.width * tparams.height, { {name=hash("rgba"), type=buffer.VALUE_TYPE_UINT8, count=4} } )
local tstream = buffer.get_stream(tbuffer, hash("rgba"))
-- Fill the buffer stream with some float values
for y=1,tparams.width do
for x=1,tparams.height do
local index = (y-1) * 128 * 4 + (x-1) * 4 + 1
tstream[index + 0] = 255
tstream[index + 1] = 0
tstream[index + 2] = 255
tstream[index + 3] = 255
end
end
-- create the texture
local tpath, request_id = resource.create_texture_async("/my_texture.texturec", tparams, tbuffer)
-- at this point you can use the resource as-is, but note that the texture will be a blank 1x1 texture
-- that will be removed once the new texture has been updated
go.set("#model", "texture0", tpath)
end
Release a resource. This is a potentially dangerous operation, releasing resources currently being used can cause unexpected behaviour.
path - The path to the resource.
Sets the pixel data for a specific texture.
path - The path to the resource
table - A table containing info about the texture. Supported entries:
type
resource.TEXTURE_TYPE_2D
resource.TEXTURE_TYPE_CUBE_MAP
width
height
format
resource.TEXTURE_FORMAT_LUMINANCE
resource.TEXTURE_FORMAT_RGB
resource.TEXTURE_FORMAT_RGBA
resource.TEXTURE_FORMAT_RGB_PVRTC_2BPPV1
- resource.TEXTURE_FORMAT_RGB_PVRTC_4BPPV1
- resource.TEXTURE_FORMAT_RGBA_PVRTC_2BPPV1
- resource.TEXTURE_FORMAT_RGBA_PVRTC_4BPPV1
- resource.TEXTURE_FORMAT_RGB_ETC1
- resource.TEXTURE_FORMAT_RGBA_ETC2
- resource.TEXTURE_FORMAT_RGBA_ASTC_4x4
- resource.TEXTURE_FORMAT_RGB_BC1
- resource.TEXTURE_FORMAT_RGBA_BC3
- resource.TEXTURE_FORMAT_R_BC4
- resource.TEXTURE_FORMAT_RG_BC5
- resource.TEXTURE_FORMAT_RGBA_BC7
- resource.TEXTURE_FORMAT_RGB16F
- resource.TEXTURE_FORMAT_RGB32F
- resource.TEXTURE_FORMAT_RGBA16F
- resource.TEXTURE_FORMAT_RGBA32F
- resource.TEXTURE_FORMAT_R16F
- resource.TEXTURE_FORMAT_RG16F
- resource.TEXTURE_FORMAT_R32F
- resource.TEXTURE_FORMAT_RG32F
You can test if the device supports these values by checking if a specific enum is nil or not:
if resource.TEXTURE_FORMAT_RGBA16F ~= nil then
-- it is safe to use this format
end
x
y
mipmap
compression_type
COMPRESSION_TYPE_DEFAULT
COMPRESSION_TYPE_BASIS_UASTC
buffer - The buffer of precreated pixel data To update a cube map texture you need to pass in six times the amount of data via the buffer, since a cube map has six sides!
Update a texture from a buffer resource
go.property("my_buffer", resource.buffer("/my_default_buffer.buffer"))
function init(self)
local resource_path = go.get("#model", "texture0")
-- the "my_buffer" resource is expected to hold 128 * 128 * 3 bytes!
local args = {
width = 128,
height = 128,
type = resource.TEXTURE_TYPE_2D,
format = resource.TEXTURE_FORMAT_RGB
}
-- Note that the extra resource.get_buffer call is a requirement here
-- since the "self.my_buffer" is just pointing to a buffer resource path
-- and not an actual buffer object or buffer resource.
resource.set_texture(resource_path, args, resource.get_buffer(self.my_buffer))
end
Gets texture info from a texture resource path or a texture handle
path - The path to the resource or a texture handle
table - A table containing info about the texture:
handle
width
height
depth
mipmaps
type
resource.TEXTURE_TYPE_2D
resource.TEXTURE_TYPE_CUBE_MAP
resource.TEXTURE_TYPE_2D_ARRAY
Get the meta data from an atlas resource
function init(self)
local my_atlas_info = resource.get_atlas("/my_atlas.a.texturesetc")
local my_texture_info = resource.get_texture_info(my_atlas_info.texture)
-- my_texture_info now contains the information about the texture that is backing the atlas
end
Gets render target info from a render target resource path or a render target handle
path - The path to the resource or a render target handle
table - A table containing info about the render target:
handle
handle
width
height
depth
mipmaps
type
resource.TEXTURE_TYPE_2D
resource.TEXTURE_TYPE_CUBE_MAP
resource.TEXTURE_TYPE_2D_ARRAY
buffer_type
resource.BUFFER_TYPE_COLOR0
resource.BUFFER_TYPE_COLOR1
resource.BUFFER_TYPE_COLOR2
resource.BUFFER_TYPE_COLOR3
resource.BUFFER_TYPE_DEPTH
resource.BUFFER_TYPE_STENCIL
Get the metadata from a render target resource
function init(self)
local info = resource.get_render_target_info("/my_render_target.render_targetc")
-- the info table contains meta data about all the render target attachments
-- so it's not necessary to use resource.get_texture here, but we do it here
-- just to show that it's possible:
local info_attachment_1 = resource.get_texture_info(info.attachments[1].handle)
end
This function creates a new atlas resource that can be used in the same way as any atlas created during build time. The path used for creating the atlas must be unique, trying to create a resource at a path that is already registered will trigger an error. If the intention is to instead modify an existing atlas, use the resource.set_atlas function. Also note that the path to the new atlas resource must have a '.texturesetc' extension, meaning "/path/my_atlas" is not a valid path but "/path/my_atlas.texturesetc" is. When creating the atlas, at least one geometry and one animation is required, and an error will be raised if these requirements are not met. A reference to the resource will be held by the collection that created the resource and will automatically be released when that collection is destroyed. Note that releasing a resource essentially means decreasing the reference count of that resource, and not necessarily that it will be deleted.
path - The path to the resource.
table - A table containing info about how to create the atlas. Supported entries:
texture
animations
id
width
height
frame_start
frame_end
playback
fps
flip_vertical
flip_horizontal
geometries
id
vertices
uvs
indices
path - Returns the atlas resource path
Create a backing texture and an atlas
function init(self)
-- create an empty texture
local tparams = {
width = 128,
height = 128,
type = resource.TEXTURE_TYPE_2D,
format = resource.TEXTURE_FORMAT_RGBA,
}
local my_texture_id = resource.create_texture("/my_texture.texturec", tparams)
-- optionally use resource.set_texture to upload data to texture
-- create an atlas with one animation and one square geometry
-- note that the function doesn't support hashes for the texture,
-- you need to use a string for the texture path here aswell
local aparams = {
texture = "/my_texture.texturec",
animations = {
{
id = "my_animation",
width = 128,
height = 128,
frame_start = 1,
frame_end = 2,
}
},
geometries = {
{
id = 'idle0',
vertices = {
0, 0,
0, 128,
128, 128,
128, 0
},
uvs = {
0, 0,
0, 128,
128, 128,
128, 0
},
indices = {0,1,2,0,2,3}
}
}
}
local my_atlas_id = resource.create_atlas("/my_atlas.texturesetc", aparams)
-- assign the atlas to the 'sprite' component on the same go
go.set("#sprite", "image", my_atlas_id)
end
Sets the data for a specific atlas resource. Setting new atlas data is specified by passing in a texture path for the backing texture of the atlas, a list of geometries and a list of animations that map to the entries in the geometry list. The geometry entries are represented by three lists: vertices, uvs and indices that together represent triangles that are used in other parts of the engine to produce render objects from. Vertex and uv coordinates for the geometries are expected to be in pixel coordinates where 0,0 is the top left corner of the texture. There is no automatic padding or margin support when setting custom data, which could potentially cause filtering artifacts if used with a material sampler that has linear filtering. If that is an issue, you need to calculate padding and margins manually before passing in the geometry data to this function.
path - The path to the atlas resource
table - A table containing info about the atlas. Supported entries:
texture
animations
id
width
height
frame_start
frame_end
playback
fps
flip_vertical
flip_horizontal
geometries
vertices
uvs
indices
Sets atlas data for a 256x256 texture with a single animation being rendered as a quad
function init(self)
local params = {
texture = "/main/my_256x256_texture.texturec",
animations = {
{
id = "my_animation",
width = 256,
height = 256,
frame_start = 1,
frame_end = 2,
}
},
geometries = {
{
vertices = {
0, 0,
0, 256,
256, 256,
256, 0
},
uvs = {
0, 0,
0, 256,
256, 256,
256, 0
},
indices = { 0,1,2,0,2,3 }
}
}
}
resource.set_atlas("/main/test.a.texturesetc", params)
end
Returns the atlas data for an atlas
path - The path to the atlas resource
data - A table with the following entries:
Update internal sound resource (wavc/oggc) with new data
path - The path to the resource
buffer - A lua string containing the binary sound data
This function creates a new buffer resource that can be used in the same way as any buffer created during build time. The function requires a valid buffer created from either buffer.create or another pre-existing buffer resource. By default, the new resource will take ownership of the buffer lua reference, meaning the buffer will not automatically be removed when the lua reference to the buffer is garbage collected. This behaviour can be overruled by specifying 'transfer_ownership = false' in the argument table. If the new buffer resource is created from a buffer object that is created by another resource, the buffer object will be copied and the new resource will effectively own a copy of the buffer instead. Note that the path to the new resource must have the '.bufferc' extension, "/path/my_buffer" is not a valid path but "/path/my_buffer.bufferc" is. The path must also be unique, attempting to create a buffer with the same name as an existing resource will raise an error.
path - The path to the resource.
table - A table containing info about how to create the buffer. Supported entries:
buffer
transfer_ownership
path - Returns the buffer resource path
Create a buffer resource from existing resource
function init(self)
local res = resource.get_buffer("/my_buffer_path.bufferc")
-- create a cloned buffer resource from another resource buffer
local buf = reource.create_buffer("/my_cloned_buffer.bufferc", { buffer = res })
-- assign cloned buffer to a mesh component
go.set("/go#mesh", "vertices", buf)
end
gets the buffer from a resource
path - The path to the resource
buffer - The resource buffer
How to get the data from a buffer
function init(self)
local res_path = go.get("#mesh", "vertices")
local buf = resource.get_buffer(res_path)
local stream_positions = buffer.get_stream(buf, "position")
for i=1,#stream_positions do
print(i, stream_positions[i])
end
end
Sets the buffer of a resource. By default, setting the resource buffer will either copy the data from the incoming buffer object
to the buffer stored in the destination resource, or make a new buffer object if the sizes between the source buffer and the destination buffer
stored in the resource differs. In some cases, e.g performance reasons, it might be beneficial to just set the buffer object on the resource without copying or cloning.
To achieve this, set the transfer_ownership
flag to true in the argument table. Transferring ownership from a lua buffer to a resource with this function
works exactly the same as resource.create_buffer: the destination resource will take ownership of the buffer held by the lua reference, i.e the buffer will not automatically be removed
when the lua reference to the buffer is garbage collected.
Note: When setting a buffer with transfer_ownership = true
, the currently bound buffer in the resource will be destroyed.
path - The path to the resource
buffer - The resource buffer
table - A table containing info about how to set the buffer. Supported entries:
transfer_ownership
How to set the data from a buffer
local function fill_stream(stream, verts)
for key, value in ipairs(verts) do
stream[key] = verts[key]
end
end
function init(self)
local res_path = go.get("#mesh", "vertices")
local positions = {
1, -1, 0,
1, 1, 0,
-1, -1, 0
}
local num_verts = #positions / 3
-- create a new buffer
local buf = buffer.create(num_verts, {
{ name = hash("position"), type=buffer.VALUE_TYPE_FLOAT32, count = 3 }
})
local buf = resource.get_buffer(res_path)
local stream_positions = buffer.get_stream(buf, "position")
fill_stream(stream_positions, positions)
resource.set_buffer(res_path, buf)
end
Gets the text metrics from a font
url - the font to get the (unscaled) metrics from
text - text to measure
[options] - A table containing parameters for the text. Supported entries:
width
line_break
is false.leading
tracking
line_break
metrics - a table with the following fields:
function init(self)
local font = go.get("#label", "font")
local metrics = resource.get_text_metrics(font, "The quick brown fox\n jumps over the lazy dog")
pprint(metrics)
end
2D texture type
Cube map texture type
2D Array texture type
luminance type texture format
RGB type texture format
RGBA type texture format
RGB_PVRTC_2BPPV1 type texture format
RGB_PVRTC_4BPPV1 type texture format
RGBA_PVRTC_2BPPV1 type texture format
RGBA_PVRTC_4BPPV1 type texture format
RGB_ETC1 type texture format
RGBA_ETC2 type texture format
RGBA_ASTC_4x4 type texture format
RGB_BC1 type texture format
RGBA_BC3 type texture format
R_BC4 type texture format
RG_BC5 type texture format
RGBA_BC7 type texture format
RGB16F type texture format
RGB32F type texture format
RGBA16F type texture format
RGBA32F type texture format
R16F type texture format
RG16F type texture format
R32F type texture format
RG32F type texture format
COMPRESSION_TYPE_DEFAULT compression type
BASIS_UASTC compression type