Corona SDK : Client Usage

Supercharge your Corona SDK apps and games with the Coronium client module for Corona SDK.

Download Coronium Module

Corona SDK Module Download

The latest Coronium Corona SDK module can be found by clicking here.

Corona SDK Project Layout

CoronaProject
  /coronium <- Coronium module folder
    cloud.lua <- Coronium class files
    ...
  build.settings <- Corona SDK
  config.lua <- Corona SDK
  main.lua <- Corona SDK

main.lua

-- CoronaProject/main.lua
local Cloud = require('coronium.cloud')

local cloud = Cloud:new({
  host = "192.168.71.73",
  project_key = "00000000-0000-0000-000000000",
  https = false --required for local dev
})

Globalization

The cloud module is globalized into the Corona SDK environment by default. This makes it much simpiler to use the cloud features in your project. Though generally a frowned-upon practice, the benefits outweight the negatives for this use case, especially when using a framework like Composer. This could be considered a "responsible" global.

You can shorten the initalization a little bit due to globalization:

-- CoronaProject/main.lua
require('coronium.cloud'):new({
  host = '192.168.71.73',
  ...
})

You can then access the cloud module from anywhere in your project:

-- request callback
local function listener(event)
  if event.phase == 'ended' then
    print(#event.response.users)
    --6 users in a table array
  end
end

-- send request
local req = cloud:request('/users/list', { count = 6 }, listener)

Global Me Not

If you would rather not have the cloud module as a global, set globalize to false in the Cloud config init (see below). You will need to handle your intializations at a local level for each call.

Configuration

When initializing the coronium module, the following configuration parameters are available:

Config Options

Name	Description	Type	Default	Required
`host`	The address to the Coronium 2 system.	`string`	`nil`	Y
`project_key`	The generated project key.*	`string`	`nil`	Y
`https`	If you're running without certs (or localhost), set to `false`.	`boolean`	`true`	N
`show_response`	Output the `response` data table.	`boolean`	`nil`	N
`show_progress`	Output progress updates.	`boolean`	`nil`	N
`show_verbose`	Output request and response meta.	`boolean`	`nil`	N
`runtime_event`	Broadcast cloud events to the Runtime listener.	`boolean`	`nil`	N
`runtime_event_id`	Runtime event identifier.	`string`	CloudEvent	N
`globalize`	Whether to "globalize" the `cloud` module (recommended).	`boolean`	`true`	N

You can find your project_key using the cloud tool on the server.

Example

--Config table is passed to `Cloud:new`
Cloud:new({
  host = '192.168.71.73',
  project_key = '00000000-0000-0000-000000',
  show_response = true
})

Making a Request

A very basic example of making a client request to the cloud server:

Things to know...

This example shows only the client side of the code. A Routing Method would need to be setup at /leaderboard/scores for this code to actually work (more on that later).

--CoronaProject/some.lua

--Initial setup, done once.
require('coroium.cloud'):new({
  host = '192.168.71.73',
  project_key = '00000000-0000-0000-000000',
  https = false
})

--Set up cloud request listener
local function listener(event)
  if event.phase == 'ended' then
    -- response.scores is a table array
    local scores = event.response.scores
    for _, score in ipairs(scores) do
      print(score.player..': '..score.score)
    end
  end
end

--Send a cloud request, with no arguments
local req = cloud:request('/leaderboard/scores', {}, listener)

Behind The Scenes

The cloud:request is a simplified wrapper over Corona SDK's network.request. The event you receive in your listener is practically the same as Corona's networkRequest event, except for a few differences:

The event.isError flag is usually set on network connectivity issues in normal Corona usage. In the case of cloud:request it can be set for failed JSON decoding as well. Check the error key for clues.

The event.response is always a table holding the result(s) from the cloud request. It's good practice to check for an error key (or the absence of one), in case of trouble:

if not event.response.error then
  --all good
else
  --boom! print error
  print(event.response.error)
end

Corona SDK Requests

All cloud based requests from the Corona SDK Module use the HTTP POST method automatically. Overriding this option is highly discouraged.

Android Permissons

Include the following in your Corona SDK project build.settings file:

settings =
{
  ...

  android =
  {
    usesPermissions =
    {
       "android.permission.INTERNET",
    },
  },

  ...
}