Cherry.lua

Cherry is a starter for Solar2D apps to help building your game.

• Introduction
• Usage
• Libraries
• Starters
• Components
• Music and Sounds
• License
• Third Parties
• Games using Cherry

Introduction to Cherry

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

Installation

• 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 'src.app'

• add a src/app.lua
• then call App.start() with your options

-- src/app.lua
App.start({
  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

Layers

from back to front:

• Background: global to the app, not reset by Router
• App.transversalBackLayer: global to the app, not reset by Router
• self.view: local to current composer view
• App.transversalFrontLayer: global to the app, not reset by Router
• App.hud: local to each view, reset by Router Game.elements use App.hud as parent, and allow cross callbacks.

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

Components

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.

Libraries

See documentation for the complete components list and options.

Tools

• 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 :

https://soundcloud.com/velvetcoffee

Local development

dependencies

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/luazen.so;' .. package.cpath
local luazen  = require('luazen')

Tests

UT with busted: http://olivinelabs.com/busted/

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

To display your _G.log() use:

> make test verbose=true

To add tests to your game, use the mocks provided by Cherry:

mkdir test
cd test
ln -s ../../../Cherry/test/mocks mocks

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

• Cherry uses the awesome particle effects provided by CBEffects.
• There are some adapted functions from Underscore.Lua
• Mobile GUI assets from GraphicBurger
• Avatars from Tiny Speck
• Profile icon designed by Miguel C Balandrano

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

core

• 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