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 thecloud
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", }, }, ... }