Version: alpha
FUNCTION | |
---|---|
resource.material() | reference to material resource |
resource.font() | reference to font resource |
resource.texture() | reference to texture resource |
resource.atlas() | reference to atlas resource |
resource.buffer() | reference to buffer resource |
resource.tile_source() | reference to tile source resource |
resource.set() | Set a resource |
resource.load() | load a resource |
resource.create_texture() | create a texture |
resource.release() | release a resource |
resource.set_texture() | set a texture |
resource.create_atlas() | create an atlas resource |
resource.set_atlas() | set atlas data |
resource.get_atlas() | Get atlas data |
resource.set_sound() | Update internal sound resource |
resource.create_buffer() | create a buffer resource |
resource.get_buffer() | get resource buffer |
resource.set_buffer() | set resource buffer |
resource.get_text_metrics() | gets the text metrics for a font |
resource.get_current_manifest() | return a reference to the Manifest that is currently loaded |
resource.store_resource() | add a resource to the data archive and runtime index |
resource.store_manifest() | create, verify, and store a manifest to device |
resource.store_archive() | register and store a live update zip file |
resource.is_using_liveupdate_data() | is any liveupdate data mounted and currently in use |
resource.material([path])
Constructor-like function with two purposes:
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
resource.font([path])
Constructor-like function with two purposes:
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
go.property("my_font", resource.font("/font.font"))
function init(self)
go.set("#gui", "fonts", self.my_font, {key = "my_font"})
end
resource.texture([path])
Constructor-like function with two purposes:
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.atlas([path])
Constructor-like function with two purposes:
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
go.property("my_atlas", resource.atlas("/atlas.atlas"))
function init(self)
go.set("#gui", "textures", self.my_atlas, {key = "my_atlas"})
end
resource.buffer([path])
Constructor-like function with two purposes:
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.tile_source([path])
Constructor-like function with two purposes:
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
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.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")
[project]
title = My project
version = 0.1
custom_resources = resources/,assets/level_data.json
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.
PARAMETERS
path |
string |
The path to the resource. |
table |
table |
A table containing info about how to create the texture. Supported entries:
|
buffer |
buffer |
optional buffer of precreated pixel data |
RETURNS
path |
hash | The path to the resource. |
EXAMPLES
How to create an 128x128 RGBA texture resource and assign it to a modelfunction init(self)
local tparams = {
width = 128,
height = 128,
type = resource.TEXTURE_TYPE_2D,
format = resource.TEXTURE_FORMAT_RGBA,
}
local my_texture_id = resource.create_texture("/my_custom_texture.texturec", tparams)
go.set("#model", "texture0", my_texture_id)
end
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.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:
|
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
How to update a specific region of an atlas by using the x,y values. Assumes the already set atlas is a 128x128 texture.function init(self)
self.x = 16
self.y = 16
self.height = 128 - self.x * 2
self.width = 128 - self.y * 2
self.buffer = buffer.create(self.width * self.height, { {name=hash("rgb"), type=buffer.VALUE_TYPE_UINT8, count=3} } )
self.stream = buffer.get_stream(self.buffer, hash("rgb"))
for y=1,self.height do
for x=1,self.width do
local index = (y-1) * self.width * 3 + (x-1) * 3 + 1
self.stream[index + 0] = 0xff
self.stream[index + 1] = 0x80
self.stream[index + 2] = 0x10
end
end
local resource_path = go.get("#model", "texture0")
local args = { width=self.width, height=self.height, x=self.x, y=self.y, type=resource.TEXTURE_TYPE_2D, format=resource.TEXTURE_FORMAT_RGB, num_mip_maps=1 }
resource.set_texture( resource_path, args, self.buffer )
end
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 texture. Supported entries:
|
RETURNS
path |
hash | Returns the atlas resource path |
EXAMPLES
Create a backing texture and an atlasfunction 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 = {
{
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.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:
|
EXAMPLES
Sets atlas data for a 256x256 texture with a single animation being rendered as a quadfunction 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.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:
|
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.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:
|
RETURNS
path |
hash | Returns the buffer resource path |
EXAMPLES
Create a buffer object and bind it to a buffer resourcefunction init(self)
local size = 1
local positions = {
-- triangle 1
size, size, 0,
-size, -size, 0,
size, -size, 0,
-- triangle 2
size, size, 0,
-size, size, 0,
-size, -size, 0,
}
local buffer_handle = buffer.create(#positions, {
{
name = hash("position"),
type = buffer.VALUE_TYPE_FLOAT32,
count = 3
}
})
local stream = buffer.get_stream(buffer_handle, hash("position"))
-- transfer vertex data to buffer
for k=1,#positions do
stream[k] = positions[k]
end
local my_buffer = resource.create_buffer("/my_buffer.bufferc", { buffer = buffer_handle })
go.set("/go#mesh", "vertices", my_buffer)
end
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.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 bufferfunction init(self)
local res_path = go.get("#mesh", "vertices")
local buf = resource.get_buffer(res_path)
local stream_positions = buffer.get_stream(self.buffer, "position")
for i=1,#stream_positions do
print(i, stream_positions[i])
end
end
resource.set_buffer(path,buffer)
sets the buffer of a resource
PARAMETERS
path |
hash, string |
The path to the resource |
buffer |
buffer |
The resource buffer |
EXAMPLES
How to set the data from a bufferlocal 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.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:
|
RETURNS
metrics |
table | a table with the following fields:
|
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_current_manifest()
Return a reference to the Manifest that is currently loaded.
PARAMETERS
None
RETURNS
manifest_reference |
number | reference to the Manifest that is currently loaded |
resource.store_resource(manifest_reference,data,hexdigest,callback)
add a resource to the data archive and runtime index. The resource will be verified internally before being added to the data archive.
PARAMETERS
manifest_reference |
number |
The manifest to check against. |
data |
string |
The resource data that should be stored. |
hexdigest |
string |
The expected hash for the resource, retrieved through collectionproxy.missing_resources. |
callback |
function(self, hexdigest, status) |
The callback
function that is executed once the engine has been attempted to store
the resource.
|
EXAMPLES
function init(self)
self.manifest = resource.get_current_manifest()
end
local function callback_store_resource(self, hexdigest, status)
if status == true then
print("Successfully stored resource: " .. hexdigest)
else
print("Failed to store resource: " .. hexdigest)
end
end
local function load_resources(self, target)
local resources = collectionproxy.missing_resources(target)
for _, resource_hash in ipairs(resources) do
local baseurl = "http://example.defold.com:8000/"
http.request(baseurl .. resource_hash, "GET", function(self, id, response)
if response.status == 200 then
resource.store_resource(self.manifest, response.response, resource_hash, callback_store_resource)
else
print("Failed to download resource: " .. resource_hash)
end
end)
end
end
resource.store_manifest(manifest_buffer,callback)
Create a new manifest from a buffer. The created manifest is verified by ensuring that the manifest was signed using the bundled public/private key-pair during the bundle process and that the manifest supports the current running engine version. Once the manifest is verified it is stored on device. The next time the engine starts (or is rebooted) it will look for the stored manifest before loading resources. Storing a new manifest allows the developer to update the game, modify existing resources, or add new resources to the game through LiveUpdate.
PARAMETERS
manifest_buffer |
string |
the binary data that represents the manifest |
callback |
function(self, status) |
the callback function
executed once the engine has attempted to store the manifest.
|
EXAMPLES
How to download a manifest with HTTP and store it on device.local function store_manifest_cb(self, status)
if status == resource.LIVEUPATE_OK then
pprint("Successfully stored manifest. This manifest will be loaded instead of the bundled manifest the next time the engine starts.")
else
pprint("Failed to store manifest")
end
end
local function download_and_store_manifest(self)
http.request(MANIFEST_URL, "GET", function(self, id, response)
if response.status == 200 then
resource.store_manifest(response.response, store_manifest_cb)
end
end)
end
resource.store_archive(path,callback,[options])
Stores a zip file and uses it for live update content. The contents of the zip file will be verified against the manifest to ensure file integrity. It is possible to opt out of the resource verification using an option passed to this function. The path is stored in the (internal) live update location.
PARAMETERS
path |
string |
the path to the original file on disc |
callback |
function(self, status) |
the callback function
executed after the storage has completed
|
[options] |
table |
optional table with extra parameters. Supported entries:
|
EXAMPLES
How to download an archive with HTTP and store it on device.local LIVEUPDATE_URL = <a file server url>
-- This can be anything, but you should keep the platform bundles apart
local ZIP_FILENAME = 'defold.resourcepack.zip'
local APP_SAVE_DIR = "LiveUpdateDemo"
function init(self)
self.proxy = "levels#level1"
print("INIT: is_using_liveupdate_data:", resource.is_using_liveupdate_data())
-- let's download the archive
msg.post("#", "attempt_download_archive")
end
-- helper function to store headers from the http request (e.g. the ETag)
local function store_http_response_headers(name, data)
local path = sys.get_save_file(APP_SAVE_DIR, name)
sys.save(path, data)
end
local function load_http_response_headers(name)
local path = sys.get_save_file(APP_SAVE_DIR, name)
return sys.load(path)
end
-- returns headers that can potentially generate a 304
-- without redownloading the file again
local function get_http_request_headers(name)
local data = load_http_response_headers(name)
local headers = {}
for k, v in pairs(data) do
if string.lower(k) == 'etag' then
headers['If-None-Match'] = v
elseif string.lower(k) == 'last-modified' then
headers['If-Modified-Since'] = v
end
end
return headers
end
local function store_archive_cb(self, path, status)
if status == true then
print("Successfully stored live update archive!", path)
sys.reboot()
else
print("Failed to store live update archive, ", path)
-- remove the path
end
end
function on_message(self, message_id, message, sender)
if message_id == hash("attempt_download_archive") then
-- by supplying the ETag, we don't have to redownload the file again
-- if we already have downloaded it.
local headers = get_http_request_headers(ZIP_FILENAME .. '.json')
if not resource.is_using_liveupdate_data() then
headers = {} -- live update data has been purged, and we need do a fresh download
end
local path = sys.get_save_file(APP_SAVE_DIR, ZIP_FILENAME)
local options = {
path = path, -- a temporary file on disc. will be removed upon successful liveupdate storage
ignore_cache = true -- we don't want to store a (potentially large) duplicate in our http cache
}
local url = LIVEUPDATE_URL .. ZIP_FILENAME
print("Downloading", url)
http.request(url, "GET", function(self, id, response)
if response.status == 304 then
print(string.format("%d: Archive zip file up-to-date", response.status))
elseif response.status == 200 and response.error == nil then
-- register the path to the live update system
resource.store_archive(response.path, store_archive_cb)
-- at this point, the "path" has been moved internally to a different location
-- save the ETag for the next run
store_http_response_headers(ZIP_FILENAME .. '.json', response.headers)
else
print("Error when downloading", url, "to", path, ":", response.status, response.error)
end
-- If we got a 200, we would call store_archive_cb() then reboot
-- Second time, if we get here, it should be after a 304, and then
-- we can load the missing resources from the liveupdate archive
if resource.is_using_liveupdate_data() then
msg.post(self.proxy, "load")
end
end,
headers, nil, options)
resource.is_using_liveupdate_data()
Is any liveupdate data mounted and currently in use? This can be used to determine if a new manifest or zip file should be downloaded.
PARAMETERS
None
RETURNS
bool |
bool | true if a liveupdate archive (any format) has been loaded |
2D texture type
Cube map 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
COMPRESSION_TYPE_DEFAULT compression type
BASIS_UASTC compression type
LIVEUPDATE_OK
The handled resource is invalid.
Mismatch between manifest expected version and actual version.
Mismatch between running engine version and engine versions supported by manifest.
Mismatch between manifest expected signature and actual signature.
Mismatch between scheme used to load resources. Resources are loaded with a different scheme than from manifest, for example over HTTP or directly from file. This is typically the case when running the game directly from the editor instead of from a bundle.
Mismatch between between expected bundled resources and actual bundled resources. The manifest expects a resource to be in the bundle, but it was not found in the bundle. This is typically the case when a non-excluded resource was modified between publishing the bundle and publishing the manifest.
Failed to parse manifest data buffer. The manifest was probably produced by a different engine version.