Resource API documentation

Version: alpha

FUNCTIONS
resource.atlas() reference to atlas resource
resource.buffer() reference to buffer resource
resource.create_atlas() create an atlas resource
resource.create_buffer() create a buffer resource
resource.create_texture() create a texture
resource.create_texture_async() create a texture async
resource.font() reference to font resource
resource.get_atlas() Get atlas data
resource.get_buffer() get resource buffer
resource.get_render_target_info() get render target info
resource.get_text_metrics() gets the text metrics for a font
resource.get_texture_info() get texture info
resource.load() load a resource
resource.material() reference to material resource
resource.release() release a resource
resource.render_target() reference to render target resource
resource.set() Set a resource
resource.set_atlas() set atlas data
resource.set_buffer() set resource buffer
resource.set_sound() Update internal sound resource
resource.set_texture() set a texture
resource.texture() reference to texture resource
resource.tile_source() reference to tile source resource

Functions

resource.atlas()

resource.atlas([path])

Constructor-like function with two purposes:

  • Load the specified resource as part of loading the script
  • Return a hash to the run-time version of the resource
This function can only be called within go.property function calls.

PARAMETERS

[path] string optional resource path string to the resource

RETURNS

path hash a path hash to the binary version of the resource

EXAMPLES

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
Load an atlas and set it to a gui:
go.property("my_atlas", resource.atlas("/atlas.atlas"))
function init(self)
  go.set("#gui", "textures", self.my_atlas, {key = "my_atlas"})
end

resource.buffer()

resource.buffer([path])

Constructor-like function with two purposes:

  • Load the specified resource as part of loading the script
  • Return a hash to the run-time version of the resource
This function can only be called within go.property function calls.

PARAMETERS

[path] string optional resource path string to the resource

RETURNS

path hash a path hash to the binary version of the resource

EXAMPLES

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

resource.create_atlas()

resource.create_atlas(path,table)

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.

PARAMETERS

path string The path to the resource.
table table A table containing info about how to create the atlas. Supported entries:
  • texture
    string | hash the path to the texture resource, e.g "/main/my_texture.texturec"
  • animations
    table a list of the animations in the atlas. Supports the following fields:
  • id
    string the id of the animation, used in e.g sprite.play_animation
  • width
    integer the width of the animation
  • height
    integer the height of the animation
  • frame_start
    integer index to the first geometry of the animation. Indices are lua based and must be in the range of 1 .. in atlas.
  • frame_end
    integer index to the last geometry of the animation (non-inclusive). Indices are lua based and must be in the range of 1 .. in atlas.
  • playback
    constant optional playback mode of the animation, the default value is go.PLAYBACK_ONCE_FORWARD
  • fps
    integer optional fps of the animation, the default value is 30
  • flip_vertical
    boolean optional flip the animation vertically, the default value is false
  • flip_horizontal
    boolean optional flip the animation horizontally, the default value is false
  • geometries
    table A list of the geometries that should map to the texture data. Supports the following fields:
  • id
    string The name of the geometry. Used when matching animations between multiple atlases
  • width
    number The width of the image the sprite geometry represents
  • height
    number The height of the image the sprite geometry represents
  • pivot_x
    number The pivot x value of the image in image coords. Default is width / 2.
  • pivot_y
    number The pivot y value of the image in image coords. Default is height / 2.
  • vertices
    table a list of the vertices in image space of the geometry in the form {px0, py0, px1, py1, ..., pxn, pyn}
  • uvs
    table a list of the uv coordinates in image space of the geometry in the form of {u0, v0, u1, v1, ..., un, vn}.
  • indices
    table a list of the indices of the geometry in the form {i0, i1, i2, ..., in}. Each tripe in the list represents a triangle.

RETURNS

path hash Returns the atlas resource path

EXAMPLES

Create a backing texture and an atlas
function init(self)
    -- create an empty texture
    local tparams = {
        width          = 128,
        height         = 128,
        type           = graphics.TEXTURE_TYPE_2D,
        format         = graphics.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',
                width = 128,
                height = 128,
                pivot_x = 64,
                pivot_y = 64,
                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

resource.create_buffer()

resource.create_buffer(path,[table])

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.

PARAMETERS

path string The path to the resource.
[table] table A table containing info about how to create the buffer. Supported entries:
  • buffer
    buffer the buffer to bind to this resource
  • transfer_ownership
    boolean optional flag to determine wether or not the resource should take over ownership of the buffer object (default true)

RETURNS

path hash Returns the buffer resource path

EXAMPLES

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

resource.create_texture()

resource.create_texture(path,table,buffer)

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.

PARAMETERS

path string The path to the resource.
table table A table containing info about how to create the texture. Supported entries:
type
number The texture type. Supported values:
  • graphics.TEXTURE_TYPE_2D
  • graphics.TEXTURE_TYPE_CUBE_MAP
  • graphics.TEXTURE_TYPE_IMAGE_2D
width
number The width of the texture (in pixels). Must be larger than 0.
height
number The width of the texture (in pixels). Must be larger than 0.
format
number The texture format, note that some of these formats might not be supported by the running device. Supported values:
  • graphics.TEXTURE_FORMAT_LUMINANCE
  • graphics.TEXTURE_FORMAT_RGB
  • graphics.TEXTURE_FORMAT_RGBA
These constants might not be available on the device:
  • graphics.TEXTURE_FORMAT_RGB_PVRTC_2BPPV1
  • graphics.TEXTURE_FORMAT_RGB_PVRTC_4BPPV1
  • graphics.TEXTURE_FORMAT_RGBA_PVRTC_2BPPV1
  • graphics.TEXTURE_FORMAT_RGBA_PVRTC_4BPPV1
  • graphics.TEXTURE_FORMAT_RGB_ETC1
  • graphics.TEXTURE_FORMAT_RGBA_ETC2
  • graphics.TEXTURE_FORMAT_RGBA_ASTC_4x4
  • graphics.TEXTURE_FORMAT_RGB_BC1
  • graphics.TEXTURE_FORMAT_RGBA_BC3
  • graphics.TEXTURE_FORMAT_R_BC4
  • graphics.TEXTURE_FORMAT_RG_BC5
  • graphics.TEXTURE_FORMAT_RGBA_BC7
  • graphics.TEXTURE_FORMAT_RGB16F
  • graphics.TEXTURE_FORMAT_RGB32F
  • graphics.TEXTURE_FORMAT_RGBA16F
  • graphics.TEXTURE_FORMAT_RGBA32F
  • graphics.TEXTURE_FORMAT_R16F
  • graphics.TEXTURE_FORMAT_RG16F
  • graphics.TEXTURE_FORMAT_R32F
  • graphics.TEXTURE_FORMAT_RG32F
You can test if the device supports these values by checking if a specific enum is nil or not:
if graphics.TEXTURE_FORMAT_RGBA16F ~= nil then
    -- it is safe to use this format
end
flags
number Texture creation flags that can be used to dictate how the texture is created. The default value is graphics.TEXTURE_USAGE_FLAG_SAMPLE, which means that the texture can be sampled from a shader. These flags may or may not be supported on the running device and/or the underlying graphics API and is simply used internally as a 'hint' when creating the texture. There is no guarantee that any of these will have any effect. Supported values:
  • graphics.TEXTURE_USAGE_FLAG_SAMPLE - The texture can be sampled from a shader (default)
  • graphics.TEXTURE_USAGE_FLAG_MEMORYLESS - The texture can be used as a memoryless texture, i.e only transient memory for the texture is used during rendering
  • graphics.TEXTURE_USAGE_FLAG_STORAGE - The texture can be used as a storage texture, which is required for a shader to write to the texture
max_mipmaps
number optional max number of mipmaps. Defaults to zero, i.e no mipmap support
compression_type
number optional specify the compression type for the data in the buffer object that holds the texture data. Will only be used when a compressed buffer has been passed into the function. Creating an empty texture with no buffer data is not supported as a core feature. Defaults to graphics.COMPRESSION_TYPE_DEFAULT, i.e no compression. Supported values:
  • COMPRESSION_TYPE_DEFAULT
  • COMPRESSION_TYPE_BASIS_UASTC
buffer buffer optional buffer of precreated pixel data

RETURNS

path hash The path to the resource.

EXAMPLES

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           = graphics.TEXTURE_TYPE_2D,
       format         = graphics.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

resource.create_texture_async()

resource.create_texture_async(path,table,buffer)

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.

PARAMETERS

path string The path to the resource.
table table
A table containing info about how to create the texture. Supported entries:
type
number The texture type. Supported values:
  • graphics.TEXTURE_TYPE_2D
  • graphics.TEXTURE_TYPE_CUBE_MAP
width
number The width of the texture (in pixels). Must be larger than 0.
height
number The width of the texture (in pixels). Must be larger than 0.
format
number The texture format, note that some of these formats might not be supported by the running device. Supported values:
  • graphics.TEXTURE_FORMAT_LUMINANCE
  • graphics.TEXTURE_FORMAT_RGB
  • graphics.TEXTURE_FORMAT_RGBA
These constants might not be available on the device:
  • graphics.TEXTURE_FORMAT_RGB_PVRTC_2BPPV1
  • graphics.TEXTURE_FORMAT_RGB_PVRTC_4BPPV1
  • graphics.TEXTURE_FORMAT_RGBA_PVRTC_2BPPV1
  • graphics.TEXTURE_FORMAT_RGBA_PVRTC_4BPPV1
  • graphics.TEXTURE_FORMAT_RGB_ETC1
  • graphics.TEXTURE_FORMAT_RGBA_ETC2
  • graphics.TEXTURE_FORMAT_RGBA_ASTC_4x4
  • graphics.TEXTURE_FORMAT_RGB_BC1
  • graphics.TEXTURE_FORMAT_RGBA_BC3
  • graphics.TEXTURE_FORMAT_R_BC4
  • graphics.TEXTURE_FORMAT_RG_BC5
  • graphics.TEXTURE_FORMAT_RGBA_BC7
  • graphics.TEXTURE_FORMAT_RGB16F
  • graphics.TEXTURE_FORMAT_RGB32F
  • graphics.TEXTURE_FORMAT_RGBA16F
  • graphics.TEXTURE_FORMAT_RGBA32F
  • graphics.TEXTURE_FORMAT_R16F
  • graphics.TEXTURE_FORMAT_RG16F
  • graphics.TEXTURE_FORMAT_R32F
  • graphics.TEXTURE_FORMAT_RG32F
flags
number Texture creation flags that can be used to dictate how the texture is created. Supported values:
  • graphics.TEXTURE_USAGE_FLAG_SAMPLE - The texture can be sampled from a shader (default)
  • graphics.TEXTURE_USAGE_FLAG_MEMORYLESS - The texture can be used as a memoryless texture, i.e only transient memory for the texture is used during rendering
  • graphics.TEXTURE_USAGE_FLAG_STORAGE - The texture can be used as a storage texture, which is required for a shader to write to the texture
You can test if the device supports these values by checking if a specific enum is nil or not:
if graphics.TEXTURE_FORMAT_RGBA16F ~= nil then
    -- it is safe to use this format
end
max_mipmaps
number optional max number of mipmaps. Defaults to zero, i.e no mipmap support
compression_type
number optional specify the compression type for the data in the buffer object that holds the texture data. Will only be used when a compressed buffer has been passed into the function. Creating an empty texture with no buffer data is not supported as a core feature. Defaults to graphics.COMPRESSION_TYPE_DEFAULT, i.e no compression. Supported values:
  • COMPRESSION_TYPE_DEFAULT
  • COMPRESSION_TYPE_BASIS_UASTC
buffer buffer optional buffer of precreated pixel data

RETURNS

path hash The path to the resource.
request_id handle The request id for the async request.

EXAMPLES

Create a texture resource asyncronously without a callback
function init(self)
    -- Create a texture resource async
    local tparams = {
        width          = 128,
        height         = 128,
        type           = graphics.TEXTURE_TYPE_2D,
        format         = graphics.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

resource.font()

resource.font([path])

Constructor-like function with two purposes:

  • Load the specified resource as part of loading the script
  • Return a hash to the run-time version of the resource
This function can only be called within go.property function calls.

PARAMETERS

[path] string optional resource path string to the resource

RETURNS

path hash a path hash to the binary version of the resource

EXAMPLES

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
Load a font and set it to a gui:
go.property("my_font", resource.font("/font.font"))
function init(self)
  go.set("#gui", "fonts", self.my_font, {key = "my_font"})
end

resource.get_atlas()

resource.get_atlas(path)

Returns the atlas data for an atlas

PARAMETERS

path hash, string The path to the atlas resource

RETURNS

data table A table with the following entries:
  • texture
  • geometries
  • animations
See resource.set_atlas for a detailed description of each field

resource.get_buffer()

resource.get_buffer(path)

gets the buffer from a resource

PARAMETERS

path hash, string The path to the resource

RETURNS

buffer buffer The resource buffer

EXAMPLES

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

resource.get_render_target_info()

resource.get_render_target_info(path)

Gets render target info from a render target resource path or a render target handle

PARAMETERS

path hash, string, handle The path to the resource or a render target handle

RETURNS

table table A table containing info about the render target:
handle
handle the opaque handle to the texture resource
'attachments'
table a table of attachments, where each attachment contains the following entries:
handle
handle the opaque handle to the texture resource
width
integer width of the texture
height
integer height of the texture
depth
integer depth of the texture (i.e 1 for a 2D texture and 6 for a cube map)
mipmaps
integer number of mipmaps of the texture
type
number The texture type. Supported values:
  • graphics.TEXTURE_TYPE_2D
  • graphics.TEXTURE_TYPE_CUBE_MAP
  • graphics.TEXTURE_TYPE_2D_ARRAY
buffer_type
number The attachment buffer type. Supported values:
  • resource.BUFFER_TYPE_COLOR0
  • resource.BUFFER_TYPE_COLOR1
  • resource.BUFFER_TYPE_COLOR2
  • resource.BUFFER_TYPE_COLOR3
  • resource.BUFFER_TYPE_DEPTH
  • resource.BUFFER_TYPE_STENCIL
  • texture
    hash The hashed path to the attachment texture resource. This field is only available if the render target passed in is a resource.

EXAMPLES

Get a texture attachment from a render target and set it on a model component
function init(self)
    local info = resource.get_render_target_info("/my_render_target.render_targetc")
    local attachment = info.attachments[1].texture
    -- you can also get texture info from the 'texture' field, since it's a resource hash
    local texture_info = resource.get_texture_info(attachment)
    go.set("#model", "texture0", attachment)
end

resource.get_text_metrics()

resource.get_text_metrics(url,text,[options])

Gets the text metrics from a font

PARAMETERS

url hash the font to get the (unscaled) metrics from
text string text to measure
[options] table A table containing parameters for the text. Supported entries:
width
integer The width of the text field. Not used if line_break is false.
leading
number The leading (default 1.0)
tracking
number The tracking (default 0.0)
line_break
boolean If the calculation should consider line breaks (default false)

RETURNS

metrics table a table with the following fields:
  • width
  • height
  • max_ascent
  • max_descent

EXAMPLES

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

resource.get_texture_info()

resource.get_texture_info(path)

Gets texture info from a texture resource path or a texture handle

PARAMETERS

path hash, string, handle The path to the resource or a texture handle

RETURNS

table table A table containing info about the texture:
handle
handle the opaque handle to the texture resource
width
integer width of the texture
height
integer height of the texture
depth
integer depth of the texture (i.e 1 for a 2D texture and 6 for a cube map)
mipmaps
integer number of mipmaps of the texture
flags
integer usage hints of the texture.
type
number The texture type. Supported values:
  • graphics.TEXTURE_TYPE_2D
  • graphics.TEXTURE_TYPE_IMAGE_2D
  • graphics.TEXTURE_TYPE_CUBE_MAP
  • graphics.TEXTURE_TYPE_2D_ARRAY

EXAMPLES

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

resource.load()

resource.load(path)

Loads the resource data for a specific resource.

PARAMETERS

path string The path to the resource

RETURNS

buffer buffer Returns the buffer stored on disc

EXAMPLES

-- read custom resource data into buffer
local buffer = resource.load("/resources/datafile")
In order for the engine to include custom resources in the build process, you need to specify them in the "game.project" settings file:
[project]
title = My project
version = 0.1
custom_resources = resources/,assets/level_data.json

resource.material()

resource.material([path])

Constructor-like function with two purposes:

  • Load the specified resource as part of loading the script
  • Return a hash to the run-time version of the resource
This function can only be called within go.property function calls.

PARAMETERS

[path] string optional resource path string to the resource

RETURNS

path hash a path hash to the binary version of the resource

EXAMPLES

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
Load a material resource and update a named material with the resource:
go.property("my_material", resource.material("/material.material"))
function init(self)
  go.set("#gui", "materials", self.my_material, {key = "my_material"})
end

resource.release()

resource.release(path)

Release a resource. This is a potentially dangerous operation, releasing resources currently being used can cause unexpected behaviour.

PARAMETERS

path hash, string The path to the resource.

resource.render_target()

resource.render_target([path])

Constructor-like function with two purposes:

  • Load the specified resource as part of loading the script
  • Return a hash to the run-time version of the resource
This function can only be called within go.property function calls.

PARAMETERS

[path] string optional resource path string to the resource

RETURNS

path hash a path hash to the binary version of the resource

EXAMPLES

Set a render target color attachment as a model texture:
go.property("my_render_target", resource.render_target("/rt.render_target"))
function init(self)
  local rt_info = resource.get_render_target_info(self.my_render_target)
  go.set("#model", "texture0", rt_info.attachments[1].texture)
end

resource.set()

resource.set(path,buffer)

Sets the resource data for a specific resource

PARAMETERS

path string, hash The path to the resource
buffer buffer The buffer of precreated data, suitable for the intended resource type

EXAMPLES

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)

resource.set_atlas()

resource.set_atlas(path,table)

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.

PARAMETERS

path hash, string The path to the atlas resource
table table A table containing info about the atlas. Supported entries:
  • texture
    string | hash the path to the texture resource, e.g "/main/my_texture.texturec"
  • animations
    table a list of the animations in the atlas. Supports the following fields:
  • id
    string the id of the animation, used in e.g sprite.play_animation
  • width
    integer the width of the animation
  • height
    integer the height of the animation
  • frame_start
    integer index to the first geometry of the animation. Indices are lua based and must be in the range of 1 .. in atlas.
  • frame_end
    integer index to the last geometry of the animation (non-inclusive). Indices are lua based and must be in the range of 1 .. in atlas.
  • playback
    constant optional playback mode of the animation, the default value is go.PLAYBACK_ONCE_FORWARD
  • fps
    integer optional fps of the animation, the default value is 30
  • flip_vertical
    boolean optional flip the animation vertically, the default value is false
  • flip_horizontal
    boolean optional flip the animation horizontally, the default value is false
  • geometries
    table A list of the geometries that should map to the texture data. Supports the following fields:
  • vertices
    table a list of the vertices in texture space of the geometry in the form {px0, py0, px1, py1, ..., pxn, pyn}
  • uvs
    table a list of the uv coordinates in texture space of the geometry in the form of {u0, v0, u1, v1, ..., un, vn}
  • indices
    table a list of the indices of the geometry in the form {i0, i1, i2, ..., in}. Each tripe in the list represents a triangle.

EXAMPLES

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

resource.set_buffer()

resource.set_buffer(path,buffer,[table])

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.

PARAMETERS

path hash, string The path to the resource
buffer buffer The resource buffer
[table] table A table containing info about how to set the buffer. Supported entries:
  • transfer_ownership
    boolean optional flag to determine wether or not the resource should take over ownership of the buffer object (default false)

EXAMPLES

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

resource.set_sound()

resource.set_sound(path,buffer)

Update internal sound resource (wavc/oggc) with new data

PARAMETERS

path hash, string The path to the resource
buffer string A lua string containing the binary sound data

resource.set_texture()

resource.set_texture(path,table,buffer)

Sets the pixel data for a specific texture.

PARAMETERS

path hash, string The path to the resource
table table A table containing info about the texture. Supported entries:
type
number The texture type. Supported values:
  • graphics.TEXTURE_TYPE_2D
  • graphics.TEXTURE_TYPE_CUBE_MAP
width
number The width of the texture (in pixels)
height
number The width of the texture (in pixels)
format
number The texture format, note that some of these formats are platform specific. Supported values:
  • graphics.TEXTURE_FORMAT_LUMINANCE
  • graphics.TEXTURE_FORMAT_RGB
  • graphics.TEXTURE_FORMAT_RGBA
These constants might not be available on the device: - graphics.TEXTURE_FORMAT_RGB_PVRTC_2BPPV1 - graphics.TEXTURE_FORMAT_RGB_PVRTC_4BPPV1 - graphics.TEXTURE_FORMAT_RGBA_PVRTC_2BPPV1 - graphics.TEXTURE_FORMAT_RGBA_PVRTC_4BPPV1 - graphics.TEXTURE_FORMAT_RGB_ETC1 - graphics.TEXTURE_FORMAT_RGBA_ETC2 - graphics.TEXTURE_FORMAT_RGBA_ASTC_4x4 - graphics.TEXTURE_FORMAT_RGB_BC1 - graphics.TEXTURE_FORMAT_RGBA_BC3 - graphics.TEXTURE_FORMAT_R_BC4 - graphics.TEXTURE_FORMAT_RG_BC5 - graphics.TEXTURE_FORMAT_RGBA_BC7 - graphics.TEXTURE_FORMAT_RGB16F - graphics.TEXTURE_FORMAT_RGB32F - graphics.TEXTURE_FORMAT_RGBA16F - graphics.TEXTURE_FORMAT_RGBA32F - graphics.TEXTURE_FORMAT_R16F - graphics.TEXTURE_FORMAT_RG16F - graphics.TEXTURE_FORMAT_R32F - graphics.TEXTURE_FORMAT_RG32F You can test if the device supports these values by checking if a specific enum is nil or not:
if graphics.TEXTURE_FORMAT_RGBA16F ~= nil then
    -- it is safe to use this format
end
x
number optional x offset of the texture (in pixels)
y
number optional y offset of the texture (in pixels)
mipmap
number optional mipmap to upload the data to
compression_type
number optional specify the compression type for the data in the buffer object that holds the texture data. Defaults to graphics.COMPRESSION_TYPE_DEFAULT, i.e no compression. Supported values:
  • COMPRESSION_TYPE_DEFAULT
  • COMPRESSION_TYPE_BASIS_UASTC
buffer 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!

EXAMPLES

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   = graphics.TEXTURE_TYPE_2D,
         format = graphics.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

resource.texture()

resource.texture([path])

Constructor-like function with two purposes:

  • Load the specified resource as part of loading the script
  • Return a hash to the run-time version of the resource
This function can only be called within go.property function calls.

PARAMETERS

[path] string optional resource path string to the resource

RETURNS

path hash a path hash to the binary version of the resource

EXAMPLES

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

resource.tile_source()

resource.tile_source([path])

Constructor-like function with two purposes:

  • Load the specified resource as part of loading the script
  • Return a hash to the run-time version of the resource
This function can only be called within go.property function calls.

PARAMETERS

[path] string optional resource path string to the resource

RETURNS

path hash a path hash to the binary version of the resource

EXAMPLES

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