Resource API documentation

Version: beta

Functions and constants to access resources.

FUNCTION
resource.atlas()	reference to atlas resource
resource.font()	reference to font resource
resource.get_current_manifest()	return a reference to the Manifest that is currently loaded
resource.load()	load a resource
resource.material()	reference to material resource
resource.set()	Set a resource
resource.set_texture()	set a texture
resource.store_manifest()	create, verify, and store a manifest to device
resource.store_resource()	add a resource to the data archive and runtime index
resource.texture()	reference to texture resource
resource.tile_source()	reference to tile source resource

CONSTANT
resource.LIVEUPDATE_BUNDLED_RESOURCE_MISMATCH	LIVEUPDATE_BUNDLED_RESOURCE_MISMATCH
resource.LIVEUPDATE_ENGINE_VERSION_MISMATCH	LIVEUPDATE_ENGINE_VERSION_MISMATCH
resource.LIVEUPDATE_FORMAT_ERROR	LIVEUPDATE_FORMAT_ERROR
resource.LIVEUPDATE_INVALID_RESOURCE	LIVEUPDATE_INVALID_RESOURCE
resource.LIVEUPDATE_OK	LIVEUPDATE_OK
resource.LIVEUPDATE_SCHEME_MISMATCH	LIVEUPDATE_SCHEME_MISMATCH
resource.LIVEUPDATE_SIGNATURE_MISMATCH	LIVEUPDATE_SIGNATURE_MISMATCH
resource.LIVEUPDATE_VERSION_MISMATCH	LIVEUPDATE_VERSION_MISMATCH
resource.TEXTURE_FORMAT_LUMINANCE	luminance type texture format
resource.TEXTURE_FORMAT_RGB	RGB type texture format
resource.TEXTURE_FORMAT_RGBA	RGBA type texture format
resource.TEXTURE_TYPE_2D	2D texture type

Functions

resource.atlas()

resource.atlas()

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

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

resource.font()

resource.font()

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

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

resource.get_current_manifest()

resource.get_current_manifest()

Return a reference to the Manifest that is currently loaded.

PARAMETERS

RETURNS

manifest_reference

number reference to the Manifest that is currently loaded

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()

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

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.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_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:

resource.TEXTURE_TYPE_2D

width: number The width of the texture (in pixels)
height: number The width of the texture (in pixels)
format: number The texture format. Supported values:

resource.TEXTURE_FORMAT_LUMINANCE
resource.TEXTURE_FORMAT_RGB
resource.TEXTURE_FORMAT_RGBA

buffer

buffer The buffer of precreated pixel data

Currently, only 1 mipmap is generated.

EXAMPLES

How to set all pixels of an atlas

function init(self)
  self.height = 128
  self.width = 128
  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("#sprite", "texture0")
  local header = { width=self.width, height=self.height, type=resource.TEXTURE_TYPE_2D, format=resource.TEXTURE_FORMAT_RGB, num_mip_maps=1 }
  resource.set_texture( resource_path, header, self.buffer )
end

resource.store_manifest()

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.

self: object The current object.
status: constant the status of the store operation:

resource.LIVEUPATE_OK
resource.LIVEUPATE_INVALID_RESOURCE
resource.LIVEUPATE_VERSION_MISMATCH
resource.LIVEUPATE_ENGINE_VERSION_MISMATCH
resource.LIVEUPATE_SIGNATURE_MISMATCH
resource.LIVEUPDATE_BUNDLED_RESOURCE_MISMATCH
resource.LIVEUPDATE_FORMAT_ERROR

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_resource()

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. `self` object The current object. `hexdigest` string The hexdigest of the resource. `status` boolean Whether or not the resource was successfully stored.

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.texture()

resource.texture()

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

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()

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

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

Constants

resource.LIVEUPDATE_BUNDLED_RESOURCE_MISMATCH

LIVEUPDATE_BUNDLED_RESOURCE_MISMATCH

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.

resource.LIVEUPDATE_ENGINE_VERSION_MISMATCH

LIVEUPDATE_ENGINE_VERSION_MISMATCH

Mismatch between running engine version and engine versions supported by manifest.

resource.LIVEUPDATE_FORMAT_ERROR

LIVEUPDATE_FORMAT_ERROR

Failed to parse manifest data buffer. The manifest was probably produced by a different engine version.

resource.LIVEUPDATE_INVALID_RESOURCE

LIVEUPDATE_INVALID_RESOURCE

The handled resource is invalid.

resource.LIVEUPDATE_OK

LIVEUPDATE_OK

resource.LIVEUPDATE_SCHEME_MISMATCH

LIVEUPDATE_SCHEME_MISMATCH

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.