Starters Core

This page is both a reference to the 'starters core' package as well as a reference for individual libraries from the package that are also included in other starters.

This package includes these elements:

Starters Core - Button Maker

globals.lua

All starter kits/packages come with the module file easy/globals.lua.

Contrary to some folks' beliefs, global variables are not evil. In fact, they would not be possible if they were not useful and sometimes needed.

This module sets some useful globals that help save you time typing common values and figuring out commonly needed things:

persist.lua

The starter core includes a special module that makes it easy and efficient to maintain persistent data in your games. This module can be found in the file easy/persist.lua

This is directly adopted from SSK2, but the 'secure' save/load feature has been removed.

Setting Default Values

The persist library lets you set 'default' values for any named field. This way, if you call get() for a named field before you set() it, you will get a valid value.

To set a defaut value for a field in a persistent data set, use this function:

persist.setDefault( fileName, fieldName, value [ , params ] )

Setting and Getting Values

Use these functions set and get values respectively:

persist.set( fileName, fieldName, value [ , params ] )

persist.get( fileName, fieldName [ , params ] )

Multiple Sets Allowed?

As you may have determined already, this module supports multiple separate data sets. Simply use different names for the fileName setting and your data will be separated into independent sets. (See Complete Example below.)

Data Caching

This library utilizes caching to speed up data accesses.

Whenever a persistent data set is mofified the following checks occur:

  1. Is data cached?
    • If not, load it from file or create blank record.
    • Cache data in persist module.
  2. Is there a value for the field user is accessing?
    • If not, and if there is a default set,
      • Set field in cached copy to default
      • Return default value.
  3. Did user set save parameter to false?
    • If not, save cached data immediately

I will be modifying this slightly in the future to handle back to back set/setDefault calls with save set to true. This modification will prevent these saves from blocking and affecting frame rate.

Complete Persist Example

The following example shows a example usage with automatic secure mode enabling when on device.


-- Set up two data sets with defaults
--
persist.setDefault( "store.json", "disabled_ads", false , { save = false } )
persist.setDefault( "store.json", "bought_extra_content", false )

persist.setDefault( "settings.json", "sound_enabled", true, { save = false } )
persist.setDefault( "settings.json", "last_score", 0 )

-- Check persistent data fields
print( "Ads disabled? ", persist.get( "store.json", "disabled_ads") )

print( "Last Score: ", persist.get( "settings.json", "last_score" ) )

-- Set 'last score' to a random value
persist.set( "settings.json", "last_score", math.random(100, 10000) )

-- Check persistent data fields again
print( "Ads disabled? ", persist.get( "store.json", "disabled_ads") )

print( "Last Score: ", persist.get( "settings.json", "last_score" ) )

soundMgr.lua

All starter kits/packages come with the module file easy/soundMgr.lua.

This is a very basic sound library that takes the drudgery (and likelihood of error) out of playing sounds in your game.

While it works fine as is, this module is meant to give you a starting point from which to expand and improve.

Sound Categories

Basic Usage

local soundMgr = require "easy.soundMgr"

Adding Sounds

addEffect( name, src )

soundMgr.addEffect( "click", "sounds/sfx/click.wav" )

addMusic( name, src )

soundMgr.addMusic( "soundTrack", "sounds/music/Blipotron.mp3" )

Playing Sounds

playEffect( name, options )

soundMgr.playEffect( "click" )

playMusic( name, options )

soundMgr.playMusic( "soundTrack", { fadein = 5000 } )

Stopping Sounds

This module will find and stop all instances of a named sound.

stopEffect( name )

soundMgr.stopEffect( "click" )

stopMusic( name )

soundMgr.stopMusic( "soundTrack" )

Removing Sounds

These featuers automatically stop and remove and then unload all instances of a named sound.

removeEffect( name )

soundMgr.removeEffect( "click" )

removeMusic( name )

soundMgr.removeMusic( "soundTrack" )

utils.lua

All starter kits/packages come with the module file easy/utils.lua.

This is a terse and alphabetical quick reference to the functions found in easy.utils.lua and easy.files.*

Remember: You've got the source so if there is any confusion about using these, you can dig into the code. :)

RoamingGamer Copyright © Roaming Gamer, LLC. 2008-2018; All Rights Reserved