Skip to content
πŸ’ Corona starter and Components
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status codecov License GitHub release

Cherry is a starter for CoronaSDK App to help building your game.


Introduction to Cherry

You may extend Cherry framework, or just pick few components, in order to start your own game.


  • clone Cherry next to your project
  • symlink the lib to your project root:
> ln -s ../Cherry/cherry cherry
  • add a main.lua with
-- main.lua
require 'cherry.main'
require ''
  • add a src/app.lua
  • then call App.start() with your options
-- src/app.lua
  name    = 'YourGame',
  version = '1.0',
  • add a env/development.json
  "silent": true,
  "invincible": true,
  "view-testing": "playground"

see env settings for more options.

A typical tree should be :

β”œβ”€β”€ Cherry
β”‚Β Β  β”œβ”€β”€ cherry
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ assets
β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ images
β”‚Β Β  β”‚Β Β  β”‚Β Β  └── sounds
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ core
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ components
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ engine
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ libs
β”‚Β Β  β”‚Β Β  └── screens
β”‚Β Β  └── test
β”œβ”€β”€ YourGame
β”‚Β Β  β”œβ”€β”€ cherry -> ../Cherry/cherry
β”‚Β Β  β”œβ”€β”€ assets
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ images
β”‚Β Β  β”‚Β Β  └── sounds
β”‚Β Β  β”‚
β”‚Β Β  β”œβ”€β”€ build.settings
β”‚Β Β  β”œβ”€β”€ config.lua
β”‚Β Β  β”œβ”€β”€ env
β”‚Β Β  β”œβ”€β”€ src
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ components
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ extensions
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ models
β”‚Β Β  β”‚Β Β  └── screens
β”‚Β Β  β”œβ”€β”€ test
β”‚Β Β  └── main.lua

Using Cherry

Adding a new Screen

A Screen implements the Composer library.

  • Start by creating a new screen, for instance duplicate the simplest one src/screens/Playground.lua
  • Register your new screen in the Router : YOUR_NEW_SCREEN = 'YourNewScreen'
  • Now you can open your screen from anywhere calling : Router:open(Router.YOUR_NEW_SCREEN)

Adding a new Model

  • Each model should implement new and show functions, for instance read how Item is built.
  • Register your model in main.lua : YourModel = require 'game.models.YourModel'
  • Use YourModel:new() during the LevelDrawer parsing
  • Use YourModel:show() during the Game rendering


Either use these components within the full workflow or pick them one by one to use it in your own game.

See documentation for the complete components list and options.


See documentation for the complete components list and options.


  • screen routing
  • game Camera
  • touch controller
  • sound library (music + effects)
  • an API to register effects from CBEffects.
  • user profile and game status
  • google analytics events (a lot are already plugged in the workflow)

Music and Sounds

Courtesy of VelvetCoffee, you may use the samples from /assets/sounds for your own game, providing you credit VelvetCoffee for the work and link to :

Local development


Luacheck, busted and luacov are used for the tests and coverage. install the luarocks using the Makefile, they will be created locally within .rocks/

Corona SDK embed Lua 5.1 with the apps. To use native libs from luarocks, you must install and build them for lua 5.1, the move the .so to an embed folder as well. Cherry uses hererocks to locally use this version.

> pip install hererocks
> make install
> make test

external dependencies

now you can move your external lib to a path in your app, and use it, after having modified your cpath.

package.cpath = 'cherry/rocks/lib/lua/5.1/;' .. package.cpath
local luazen  = require('luazen')


UT with busted:

> make test
50 successes / 0 failures / 0 errors / 0 pending : 0.014314 seconds

To display your _G.log() use:

> make test verbose=true

BSD License

You may use Cherry or a part of it in a free or commercial game or app, providing you follow the BSD crediting requirements, provided in the project LICENSE

Third Parties

Games using Cherry

  • Phantoms released on November 2015 as the actual source for

[todo] Doc to provide

  • screens : HOME required
  • App.hud: empty between screens | on front
  • App.display: common between screens | on back
waiting for the doc, read the code
  • Look in app.App to see what you may override with App:start(options)
  • Look in engine.Game to see what you may override with Game:YourStuff()
  • env files simple example: development.json
  "silent": true,
  "view-testing": "Playground"
  • adding custom screens

  • extending/overriding engine.Game

  • users from savedData:

version 3.12.6 --> 31206
less important misc
  • setting custom bg
  • setting custom gravity
  • defining colors
  • defining analytics ids
  • defining facebook ids
  • defining ios id
You can’t perform that action at this time.