FingerTips Personalizer Framework, Application Programming Interface

This manual is a work in progress.

Treat Personalizer exactly the way you have always treated homegrown configuration components. It may behave differently under the hood, and the information your game provides to it will have an unusual impact on subsequent games of the same genre, but in the end Personalizer API simply stores and retrieves configuration settings for you.

Personalizer is not intended for use in real time. This means that you should not read and write preferences with gameplay underway; unless the gamer explicitly requests a reconfiguration, such as through bringing up the Options menu. Although in-memory operations that Personalizer performs may be adequately fast for your game, the safe solution is to call Personalizer methods outside the actual gameplay.

Personalizer Visual Tuner, the visual tool used to prepare configuration metadata for your game, will generate the so called code snippets when you save the project. These snippets set a good example of how you should work with Personalizer API and can serve as the starting point for the Personalizer-related code in your game. This manual contains a more extensive explanation of Personalizer C++ API's features.

If you are the person responsible for packaging the game or creating the game's installer, please refer to other documentation for information on redistributables and relevant system requirements.

The only linking option for FingerTips Personalizer C++ API is run-time dynamic linking. The API code is included in the Personalizer Redistributable Core as a DLL which loads and unloads at run-time on your request. This conserves memory and simplifies updates of the API code. If a bug is found and fixed in the API, the Personalizer Redistributable Core needs to be updated, but not your game.

Personalizer API's namespace literal is personalizer. You can either save typing by using the using directive or qualify names of the API classes (personalizer::Profile, personalizer::Tuner, and so on). You can also shorten the literal through namespace aliasing (consult your C++ handbook or the Internet.)

For accessing countable structures such as profiles, options, bindings, sequences, sequence elements, and controls, use 1-based indices. For example, to retrieve the first option by its index, request option number 1, not number 0.

These are the system requirements for developing applications with FingerTips Personalizer C++ API:

There are two general kinds of classes in the Personalizer API: singleton classes and reflections classes.

Singleton classes (Tuner, PreferencesManager, LibraryManager) are limited to a single instance each, as the name suggests. They exist at all times and serve to interface between the game and the preferences memory. You can access these instances, but you cannot create them.

Since you don't create singleton classes directly, you must first obtain a pointer to such class in order to call its methods. Personalizer DLL exports function GetSingletonPointer that returns pointers to Personalizer singleton classes.

Reflection classes are regular classes. You can create objects of these classes by numbers whenever you need them. Reflection classes are used to transfer preferences and library information across the boundary of the interface created with singleton classes. Personalizer DLL exports function CreateClass that creates reflection objects.

The following snippets demonstrate the approach to creating instances of Personalizer classes. Function types pCreateClass and pGetSingletonPointer are declared in header DLLExports.hpp.

	// function fCreateClass will create instances of regular Personalizer classes
	static pCreateClass fCreateClass = 0;
	
	// function fGetSingletonPtr will obtain pointers to singleton Personalizer classes
	static pGetSingletonPointer fGetSingletonPtr = 0;
	
	HINSTANCE personalizer_dll = 0;
	
	// ... call LoadLibrary here to load the Personalizer DLL
	
	// obtain pointers to exported DLL functions
	fCreateClass = reinterpret_cast<pCreateClass>(GetProcAddress(personalizer_dll, "CreateClass"));
	
	fGetSingletonPtr = reinterpret_cast<pGetSingletonPointer>(GetProcAddress(personalizer_dll, "GetSingletonPointer"));
	// 
	

	try
	{
	  // obtain a pointer to the Tuner singleton
	  personalizer::ITunerPtr pITuner
	    = static_cast<personalizer::ITunerPtr>((*fGetSingletonPointer())(CLS_Singleton_Tuner));
	
	  // call Tuner::bootstrap
	  pITuner -> bootstrap(...);
	}
	catch (...)
	{
	}
	

	try
	{
	  // create an Option object
	  personalizer::IOptionPtr pIOption 
	    = static_cast<personalizer::IOptionPtr>((*fCreateClass())(CLS_Option));

	  // call Option::set
	  pIOption -> set(...);
	}
	catch (...)
	{
	}
	

As you see, creation of Personalizer objects follows a simple pattern. Here is the generic syntax for creating an object:

	  I[class name]Ptr [object name] = static_cast<I[class name]>(fCreateClass([class identifier]));
	

	  I[class name]Ptr [pointer name] = static_cast<I[class name]>(fGetSingletonPtr([class identifier]));
	

The following table lists class identifiers (CLS_[class name]) and corresponding class interface pointers (I[classname]Ptr) that you should use when creating Personalizer objects. Also note that Personalizer objects' constructors may throw exceptions; do wrap creation statements in try/catch blocks.

The following sections contains short references for Personalizer classes and methods. It is intended to serve as a simple overview of Personalizer's capabilities. If you need more detailed information on the methods listed here, please use the Doxygen-generated reference included in the Personalizer Development Kit.

Since regular Personalizer classes, such as Option and Binding, are instantiated as pointers to interfaces, you should use a suitable casting syntax when passing objects to Personalizer methods. All Personalizer methods receive instances of Personalizer objects by reference. The syntax to use is easier to understand from this example:

	  // create an Option object
	  IOptionPtr setting = static_cast<IOptionPtr>(fCreateClass(CLS_Option));

	  // profileIt is an iterator pointing to a profile
	  // getOption expects a reference to Option
	  profileIt -> getOption((Option&)(*setting), L"MusicVolume");
	

As you can see, the idea is to dereference the pointer to the interface and cast the interface as class reference.

	Note
	If you have an idea of a nicer way to do this, and the solution does not involve macros, just send us a message saying so.

Almost every game written for PCs follows certain configuration patterns. The implementations of the configuration process may differ (within limits), but the patterns persist.

In particular, the very first thing to do after basic initialization is to load the configuration profile and read in all settings. After that, it may be required to change some of the settings in response to explicit user requests. Finally, the settings must persist across runs of the game, that is, must be saved on disk for subsequent loading.

Depending on the complexity of the game and requirements imposed on those game screens where manual configuration happens, other tasks may be added, such as creating multiple profiles for different users of the game.

Personalizer relieves game developer of the chores related to internals of configuration components, but it still requires some programming to implement the common configuration patterns. Here is the basic procedure that you should follow.

The following chapters present Personalizer classes and contain many examples of actual use.

When you perform system diagnostics by calling the API bootstrap method, API hopes to find the preferences memory files under a predefined location, which is fixed for every operating system. If the preferences memory is broken, the API will try to restore files from a snapshot. If snapshot restoration fails or the preferences memory is simply absent, the API falls back to the so called Unaware Mode.

In Unaware Mode, there is only one virtual profile filled with your game's default settings. You can retrieve the settings and change them, and the virtual profile will be incorporated back into preferences memory as soon as Personalizer redistributeable core is reinstalled. Because Unaware Mode defies the very principles of Personalizer, the game is advised to execute the redistributable core installer as soon as possible; ideally, the very moment the API reports being in Unaware Mode. After the preferences memory is in place, you can reinitialize the API.

This API tries to be conscious about dumping problems into client code's lap. We throw exceptions only for cases of serious errors that do or may prevent the Framework from operating properly. Most of these exceptions will be raised early on, if ever, on the stage where you initialize the API and obtain basic pointers. During normal workflow there is little need to try/catch things, although it is a recommended approach for any code. However, there is need to track system's reactions to your calls.

This API uses Unicode internally for everything except the file and path names. This means you must also use wide strings for all strings that you pass to API methods or receive from API methods.

We called the Unicode strings typedef ClassicString. If this surprises you, think of Classic as Traditional. Before computers, strings could contain any characters at all. Thus, ClassicString.

	Note
	Currently, Personalizer API defines a Unicode string as std::basic_string<wchar_t>.

Class Tuner is responsible for initializing and unitializing the framework. It also incapsulates the game configuration metadata that Personalizer relies upon in its operation.

Before you can do anything useful with Personalizer, you must bootstrap the framework by calling Tuner::bootstrap. After you are done working with preferences, bring the framework down by calling Tuner::release. For more elaborate information about bootstrapping, refer to Chapter 2, Bootstrapping.

By calling Tuner methods such as supportedOptions() and supportedActions(), you can access configuration metadata created in Personalizer Visual Tuner and loaded through a call to Tuner::bootstrap.

The following code snippet demonstrates what you can do with Tuner's methods. The code prints out complete configuration metadata for your game. The possibility to extract configuration metadata is interesting, because, if you feel like, you can write subroutines for your game that would automatically generate setup screens from metadata created in Personalizer Visual Tuner.

	  // ... bootstraping skipped ...
	  std::wcout << L"Game title: " << pITuner -> getGameTitle() << std::endl;
	  std::wcout << L"Game origin: " << pITuner -> getOrigin() << std::endl;
	  
	  // obtain references to metadata maps
	  SupportedActions &mySupportedActions = pITuner -> supportedActions();
	  SupportedOptions &mySupportedOptions = pITuner -> supportedOptions();
	  CustomActions &myCustomActions = pITuner -> customActions();
	  CustomOptions &myCustomOptions = pITuner -> customOptions();

	  std::wcout << L"The game has " << myCustomActions.size() << L" custom actions" << std::endl;
	  std::wcout << L"The game has " << myCustomOptions.size() << L" custom options" <<std::endl;
	  std::wcout << L"Total supported game actions: " << mySupportedActions.size() << std::endl;
	  std::wcout << L"Total supported game options: " << mySupportedOptions.size() << std::endl;

	  // dump info about supported options
	  /** At this point, all the supported options must already be in the library, so we are safe in 
	  ** assuming that retrieval of definitions by name will work and work as expected.
	  **/

	  // create an instance of OptionDefinition
	  personalizer::IOptionDefinitionPtr optionDef 
	      = static_cast<IOptionDefinitionPtr>((*fCreateClass())(CLS_OptionDefinition));

	  // for every option the game supports
	  for (SupportedOptions::iterator soIt = mySupportedOptions.begin();
	       soIt != mySupportedOptions.end();
	       ++soIt)
	  {
	    ClassicString optionName = (soIt -> second).getName();

	    pILibraryManager -> getOptionDefinition((OptionDefinition&)(*optionDef), optionName);

	    // print out option name and its custom caption
	    // custom captions are identical to names if undefined
	    std::wcout << std::endl << L"Option " << optionDef -> getName()
	               << " (" << optionDef -> getCustomName() << std::endl;

	    std::wcout <<                L"       is of value type " << optionDef -> getOptionType() << std::endl;

	    if ((soIt -> second).hasDefault())
	      {
	        std::wcout <<            L"       Its default value is: " << (soIt -> second).getDefault() << std::endl;
	      }
	  
	    if ((soIt -> second).getGrade() > 0)
	      {
	        std::wcout <<            L"       Graded as: " << (soIt -> second).getGrade() << std::endl;
	      }
          }
	  // you can do the same for actions
	  // you can also explore custom option types
	  // and even interpret the classes of actions and options

	

After a succussful call to Tuner::bootstrap you can work with preferences memory and libraries. Class PreferencesManager provides high-level methods for managing preferences memory.

You can obtain iterators pointing to configuration profiles, create and remove profiles, save changes in the preferences memory and revert to the on-disk version of the preferences memory.

PreferencesManager also exposes a utility method, unmanglePersonalizerName, that the game must use on names of actions and options before displaying them to the gamer. Personalizer names cannot contain spaces, hence the necessity to preprocess them before display.

Class LibraryManager is a wrapper around libraries; many of its methods are of interest mainly to other API methods.

However, you can use LibraryManager to access library definitions of actions, options, and option types, as well as perform validation of option values.

Class Profile is a container for options, bindings, and sequences, plus some extra service information. Profile has more methods than any other Personalizer class; however, its methods are divided into related groups that follow roughly the same usage pattern.

In short, to retrieve and modify settings related to your game, you will use Profile's methods.

Note that you never need to create instances of Profile directly using the procedures outlined earlier in this document; instead, call PreferencesManager::createProfile.

Class Option contains information related to a single option setting. You will need Option objects to retrieve options defined in profiles, to define new options, and also to modify existing option definitions.

One option definition may contain several values in the order of decreasing preference. You can obtain an option's value as a whole or you can retrieve distinct preference values and optionally perform on-the-fly conversion to a more convenient data type.

Class Binding contains information related to a single binding. You will need Binding objects to retrieve bindings defined in profiles, to define new bindings, and also to modify existing binding definitions.

Class Control reflects a single control as defined in FingerTips Personalizer, Framework Design. Control is used with Binding and Sequence.

Class Sequence stores a single sequence: associated controls, sequence elements, and preferences metadata.

SequenceElement is a hybrid class. Instances of SequenceElement act as either action calls or option settings, depending on context. Sequence elements are used to construct sequences and to retrieve sequences data.

Class SupportedOption incapsulates configuration metadata for a single option that your game supports. You can access the map of supported options by calling Tuner::supportedOptions() (see Example 3.1.)

Class SupportedAction incapsulates configuration metadata for a single action that your game supports. You can access the map of supported actions by calling Tuner::supportedActions() (see Example 3.1.)

Class ActionDefinition incapsulates definition of a library action. Instances of ActionDefinition are used with LibraryManager to retrieve action definitions from the library of actions.

Class OptionDefinition incapsulates definition of a library option. Instances of OptionDefinition are used with LibraryManager to retrieve option definitions from the library of option types.

Class OptionTypeDefinition incapsulates definition of a library option type. Instances of OptionTypeDefinition are used with LibraryManager to retrieve option type definitions from the library of option types.