Scrappy Settings

Scrappy Settings is a simple settings management library for Solar2D that simplifies customisable settings.

All settings are stored in plain text in a settings.ini file in the project’s root directory, and modified ones are stored in the app’s documents directory.

As with all my plugins it is free to use however if you find it useful, and are able to, I’d appreciate a coffee.

Image Credit: Settings by ProSymbols from the Noun Project.

Getting Started

There are multiple ways to include the library in your project, the simplest is probably via the plugin, as outlined below, however if you wish you can also access the source code.

Plugin

build.settings


settings =
{
    plugins =
    {
        ["plugin.scrappySettings"] =
        {
            publisherId = "com.scrappyferret",
            supportedPlatforms =
            {
                iphone = { url="https://plugins.scrappyferret.com/scrappySettings/iphone.tgz" },
                android = { url="https://plugins.scrappyferret.com/scrappySettings/android.tgz" },
                macos = false,
                win32 = false
            },
        },
    },
}

main.lua


require( "plugin.scrappySettings" )

Scrappy.Settings:init()

Source Code

If you wish you to access the source code directly it is available on GitLab here.

You can then clone or fork it if you wish, or add the library as a submodule to your project with this command:

git submodule add https://gitlab.com/scrappyferret-libs/scrappy-settings.git settings

However you get the source code into your project, you will then need to include it and initiate it.

main.lua


require( "settings.core" )

Scrappy.Settings:init()

API

Scrappy.Settings:init()

Initiates the library.


Scrappy.Settings:get( name )

Gets the value of a setting.

name ( string ) – The name of the setting to retrieve.

returns – The value, or nil if not found.


Scrappy.Settings:set( name, value, [ dontSave ] )

Sets the value of a setting.

name ( string ) – The name of the setting to set.

value ( string, number, boolean, table ) – The value to set.

dontSave ( boolean ) – Should the auto-save be disabled for this set. Optional, defaults to false so it will save.


Scrappy.Settings:is( name, value )

Checks if the value of a setting matches another value.

name ( string ) – The name of the setting to check.

value ( string, number, boolean, table ) – The value to compare.

returns – True if the setting matches the value, false if not.


Scrappy.Settings:reset( name, dontSave )

Resets a setting.

name ( string, table of strings ) – The name of the setting to reset. Optional, if not included then the whole settings database will be reset to defaults.

dontSave ( boolean ) – Should the auto-save be disabled for this reset. Optional, defaults to false so it will save.


Examples

A basic settings.ini file to include in your project’s root directory.

language:en
volume:0.7
debugMode:false

Accessing some settings, changing them, and resetting back to defaults.

-- Get the current language
local language = Scrappy.Settings:get( "language" )

-- Is it English? If so, say hello!
if language == "en" then
    print( "Hello, world!" )
end

-- Now change it to German
Scrappy.Settings:set( "language", "de" )

-- Check that we are in fact in German, and if so say hallo!
if Scrappy.Settings:is( "language", "de" ) then
    print( "Hallo Welt!" )
end

-- Now reset back to default
Scrappy.Settings:reset( "language" )

-- And finally print out the language again to confirm the reset
print( Scrappy.Settings:get( "language" ) )