UserPreferences

Date: April 24, 2009

Introduction

User Preferences are a relatively new thing in the world of StepMania. They were born in spinal shark's (the themer) e-series theme, emit. The intent was to duplicate the functionality of PARTICLE from k//eternal's PROJEKTXIII+ SECOND STRIKERS within StepMania itself, allowing for cross-platform compatibility.

The first theme that was released with this technology was NAKET Coder Evolution, which allowed for a customizable Toasty. The prior theme in the NAKET series, NAKET Coder Revolution: Bleeding Heart Liberal, also had this functionality, but required users to edit files manually. NCEvo's implementation differed by using the methods first experimented with in emit, and added a screen to the theme that allowed the user to easily change the toasty.

dubaiOne expanded on this with more options, also using the same technique as emit, but with a much nicer back-end.

After dubaiOne's release, the initial version of UserPreferences was created, comprising the internal functions of version 1.0. The only thing added were some wrappers and documentation on how to use it.

(todo: talk about expansion into sm-ssc land)

Installation

  1. Make sure that UserPreferences.lua is in your theme's Scripts directory.
  2. Create a file called 01 ThemePrefs.lua in your theme's Scripts directory, paste this into it, and edit it for your theme: 
    BasePrefPath = "Themes/yourtheme/Other/";

UserPrefs = {
	Toasty = "toasty",
	SelMusic_DifficultyDisplay = "SelectMusicDiffDisplay",
	-- and so on...
}
    The path variable must be called BasePrefPath, or you will have to edit UserPreferences.lua as well.

Usage

When both files are in place, you can then use GetUserPref and SetUserPref: >p?The first argument in each is the filename, accessed using the friendly name in the UserPrefs above. The second argument is the name of the env to be written, since UserPreferences links up with EnvUtils2. For SetUserPref, the third argument is the value to be written. This is what gets returned by GetUserPref.

Full Example

This is meant to be placed in a BGAnimation folder. In particular, this example goes in BGAnimations/ScreenGameplay toasty/default.lua.

-- let's say it returns "forden":
local Toasty = GetUserPref(UserPrefs['Toasty'], "Toasty");

local t = Def.ActorFrame{
	-- assuming you have a file called "forden"
	LoadActor(Toasty)..{
		-- some commands, etc.
	};
};

return t;

Download

(I'll have it up soon)