RCPrefs Docs (version 1.0.0)

Requirements

RCPrefs requires a web server with root FTP access.

Installation

The RCPrefs package will create the following three folders when imported into your project.

    1. RCPrefs – Contains the RCPrefs demo scene as well as the editor scripts.
    2. Plugins/RCPrefs – Contains RCPrefsFetcher script, and resources needed for the editor and publishing.
    3. Editor Default Resources/RCPrefs – Contains resources for the editor.
    4. Learn more about the RCPrefs Playmaker Actions here.

Editor Window

Open the Editor window from the menu Window->RCPrefs->RCPrefs Editor

The editor is the main RCPrefs window where you will spend your time creating and modifying RCPrefs and pref sets.   This window also contains your FTP server settings as well as few other tools.

RCPrefsDocs_1_0_EditorWindow

RCPref Editing

An RCPref is similar to Unity’s PlayerPrefs.  They are comprised of Key, Type and Value.  RCPrefs also contain an Action that determines what will happen when it is downloaded.

RCPref Key

Key names are robust and follow the same guidelines as PlayerPrefs.  If for some reason you have two prefs with the same key name, the second will most likely end up overriding the first.

RCPref Types

RCPrefs types are Integer, Float and String.  If you are looking for Booleans use integers with values of 1 and 0.

RCPref Value

Values must correspond to the type.  If you have an integer field, you will not be able to set it as a string or float.

RCPref Action

When a pref set is downloaded each individual RCPref will be processed based upon its defined Action.  Click on the RCPref’s triangle to access the Action options.  There are four possible actions that can be selected from the Action pop up menu.  These actions are covered in greater detail in the Action section below.

RCPrefsDocs_02_0_EditorWindow

    1. Save as PlayerPref
    2. Save as Encrypted PlayerPref
    3. Send Message to GameObject (Requires name of target GameObject)
    4. Trigger C# Event

Options 1 & 2 use Unity’s PlayerPrefs class to store the pref data and handled automatically by RCPrefs.  Options 3 & 4 provide the developer with flexibility to store the data however they choose, but will require some additional planning and coding.

Pref Organization Tools

RCPrefsDocs_03_0_EditorWindow

Delete (a)

Removes the RCPref from the current set.

Inactive/Active Toggle (b)

Moves an active RCPref to the inactive list or an inactive RCPref to the active list.  Making an RCPref inactive allows you keep it with the Pref Set in the editor, but it will not be uploaded to the server or processed by the client.

Reorder RCPrefs Arrows (c)

Arrange the RCPrefs in any order you choose using the up and down arrows.

Pref Set Editing

RCPrefs are organized into Pref Sets that are used for posting and fetching the prefs from the server. The advantage of using Pref Sets is that they allow you to have different values for your RCPrefs depending on version or platform. For example…You could have a set of RCPrefs on iOS that is different than Android. Pref Sets can be easily duplicated and renamed.

Pref Set Options Menu

RCPrefsDocs_04_0_SetOptions

Edit Name

Set names are fairly robust, but try to use names without spaces or unusual characters to be safe.

New

Creates new empty Pref Set.

Duplicate

Makes a copy of the current Pref Set and appends “(Copy)” to its name.  This is good for making new sets for new versions or different platforms (ie. Android, iOS, Windows)

Delete

Deletes the current set.

Append Demo Sets

Adds in two demo Pref Sets to facilitate testing of the demo scene.  The demo sets have a randomly generated number at the end to lessen conflicts with sets on the RCPrefs playground server.

FTP & Server Settings

The FTP settings of RCPrefs should be familiar to anyone that has used an FTP client.  In fact, it is recommended that you confirm that your FTP settings are correct using an FTP client before entering them into RCPrefs.  If you don’t have an FTP client we recommend Cyberduck as it is free.

You can also reference the FTP settings found in the RCPrefs Demo project if you need guidance.

RCPrefsDocs_06_0_FTPSettings

Use Pref Set Name for Posted File

This will automatically name the file on your server the same as your current Pref Set.  This is the recommended option, but you are welcome to use your own custom file name if you choose.

Use Default Server Settings

The first Pref Set in your list will be used for your “Default Server Settings“.  Once you set up the server settings for this Default Set, it can be applied to all newly created sets by simply checking the option.

If the “Use Default Server Settings” is not selected, the set will need to have all FTP fields filled in.  This option allows you to use multiple servers if that suits your needs.

Server Address

Should look something like “rcprefsplayground.com” or possibly “192.241.31.11”

Port

Default for most FTP clients is 21.  Modify if necessary.

Directory

Enter the directory path where the files will be stored and accessed.  Leaving blank “/” will store the files in the root of your server.

FTP URL­­­

This is a preview of the FTP login. (Read only)

User Name

Your FTP account user name.

Password

This is encrypted and kept with the RCPrefs data.  Choosing “Ask” will ensure your password is not saved and will require you to reenter it any time you post to the server.

Test FTP Connection

After you set up your FTP settings use this to make sure that you can connect to the server.  Make sure you have write privileges for your account on your FTP server.

Advanced URL Overrides

There is little reason to use these, but are here in case it helps your particular situation.

Use Default URL

RCPrefs performs a WWW call to fetch the corresponding server file.  If the defaults are used, the URL of this file is automatically generated based on where the file was uploaded.

If for some reason you need to manually post the file at a different server location, you can enter in the URL where the file resides and RCPrefs will know how to fetch it.

Encrypt Server Files

By default the files posted to the server are encrypted so only RCPrefs can read them.  It’s not advised, but you can post the files as unencrypted if you choose.  This might be done for testing purposes or to manually change the values of the XML file if you don’t have access to Unity.  You can switch back and forth between encrypted and unencrypted after the app is deployed with no adverse effects.

Local Test Mode

Enable this mode if your game is live and you want to test new values before posting them to the server. When enabled RCPrefs will not fetch Pref Sets from the server, but instead will use the same data used the RCPrefs Editor.  All fetches from the RCPrefs Fetcher or static fetch calls such as “RCPrefs.RequestRCPrefsFromServer(“MyPrefSet”)” will be affected. This mode only works in the Unity Editor.

Editor Default Settings

Default Pref Settings

Customize the initial settings for creating new RCPrefs.  You can set default key names, types, actions and recipient game object names if you are using “Send Message” action type..

User Verbose Logging in Editor

Enables detailed logging when fetching RCPrefs from the server.

Send Message Code Generator (Copy/Paste)

RCPrefsDocs_07_0_CodeGenerator

If you are using the action type “Send Message to Game Object” this will generate template code you can copy and paste into your own script.  When using the Send Message action a method matching the key of each RCPref will be need to be generated in your choice of Java or C#.

By default the code does a type check to make sure there isn’t a type conflict.  You can disable this, but be careful not to change your RCPrefs types after they have been deployed as this may cause crashing.

Using RCPref Actions

When a Pref Set is fetched from the server each RCPref is processed depending on its defined action type.  There are four different action types, but you will most likely end up using just one or two depending on how you save your prefs data.

RCPrefsDocs_02_0_EditorWindow

Save as PlayerPref Action

Relies on Unity’s PlayerPrefs class to store the pref data.  RCPrefs and PlayerPrefs have similar structures so it is pretty straightforward. If you have an RCPref that is defined as:

Key: MyPref
Type: Integer
Value: 4
Action: Save as PlayerPref

Method called when processed:

PlayerPrefs.SetInt(“MyPref”,4);

Access the data by calling:

PlayerPrefs.GetInt(“MyPref);

Save As Encrypted PlayerPref Action

Uses Unity’s PlayerPrefs to store data, but encrypts and decrypts the key and value before saving to protect sensitive data from tampering.

Without encryption your “BossHitPoints_Lvl_1” would appear like this in your PlayerPrefs…
RCPrefsDocs_08_0_EncryptedPref

And with encryption it looks like this in your PlayerPrefs…
RCPrefsDocs_08_1_EncryptedPref

If you have an RCPref that is defined as:

Key: MyPref
Type: Integer
Value: 4
Action: Save as Encrypted Pref

The method called when processed:

RCPrefs.SetEncryptedInt(“MyPref”,4);

Access the data by calling:

RCPrefs.GetEncryptedInt(“MyPref);

You can use Encrypted Prefs in your app even if you are not using any server based fetches. Learn more about using Encrypted Prefs here…

Send Message to GameObject Action

Send Message can be helpful if you wish to store the downloaded RCPrefs using your own custom data solution.  This could involve updating a record on an SQLite database or saving to a binary file.

This type of RCPref also needs to have the name of a target GameObject defined in the RCPref action section of the editor.  (This field does not support drag and dropping of game objects into the field)

When an RCPref is downloaded and processed, RCPrefs will try to find the specified target GameObject and then will try to send a message to the game object. If no GameObject is found, then no message will be sent.

Example processing for the following RCPref:

Key: MyPref
Type: Integer
Value: 4
Action: Send Message To GameObject
GameObject Name: “RCPrefsTarget”

GameObject go = GameObject.Find(“RCPrefsTarget”);
If (go!=null){
go.SendMessage(“MyPref”,4,SendMessageOption.DontRequireReceiver);
}

The target GameObject needs to have a method name that is the same as the key of the pref.  (Unlike saving as PlayerPrefs of Encrypted Player Prefs, this needs to be planned and done ahead of time.) You can use the Send Message Copy/Paste Code Generator to create quick templates for your receiver code.

To see an example of the “Send Message Action” refer to the RCPrefsDemo Scene.  The “RCPrefsDemoGUI.cs” file has two methods (“ContestURL()” and “AllowAdSkipping()” ) that handle the Send Message to GameObject action.

Trigger C# Event

If you would like to handle your own data storage and are familiar with C# delegates and events, this is an flexible approach.  Overall it has the same objective as Send Message to Game Object, but may require less code depending on what you are doing.

To learn more about delegates and C# events check out this video from Prime31.  You can also reference the “RCPrefsDemoGUI.cs” file for an example of using C# events with RCPrefs.

If Trigger C# Event is selected one of three RCPrefs Events will fire depending on the type. To subscribe and unsubscribe to RCPrefs events you would incorporate something similar to this in a script on one of your game objects.

void OnEnable (){

   RCPrefs.StringValueUpdated += HandleStringValueUpdated;
   RCPrefs.IntValueUpdated += HandleIntValueUpdated;
   RCPrefs.FloatValueUpdated += HandleFloatValueUpdated;
}
    
void OnDisable () {
   RCPrefs.StringValueUpdated -= HandleStringValueUpdated;
   RCPrefs.IntValueUpdated -= HandleIntValueUpdated;
   RCPrefs.FloatValueUpdated -= HandleFloatValueUpdated;
}

A sample of one of the above event handlers might look like:

void HandleIntValueUpdated (string prefNameint value){
   switch (prefName){
   case "XPBonus_Lvl1":
        //Your code to save to a DB or other solution
        break;
    default:
        break;
    }
}

 

Fetching RCPrefs

Fetching prefs is designed to occur once per launch and is definitely not something that should be done in Unity’s Update function.  Fetching is done in a co-routine and will not lock up your game, but the speed in which the prefs are downloaded and processed is largely based on your internet speed.

Fetching RCPrefs can be downloaded using the a supplied component called an RCPref Fetcher, or manually via code.  Both are explained below.

RCPrefs Fetcher

Creating an RCPrefs Fetcher is the simplest way download Pref Sets. You can add an RCPrefsFetcher GameObject to your scene from the GameObject by using the GameObject menu.

GameObject->Create Other->RCPrefs Fetcher.

Select the “RCPrefsFetcher” GameObject to view the RCPrefs Fetcher component.

RCPrefsDocs_09_0_Fetcher

Pref Set to Fetch

Provides a list of all available Pref Sets from the RCPrefs Editor.  If you are unable to find your pref set in the pop up menu, make sure the editor has been saved.

Call On

Choose whether the fetch will occur on either the Awake or Start functions.

Delay

If you need to delay the fetch you can add any float value here.  (1, .2, 3.5)

Use Verbose Logging

This provides detailed logging when the prefs are downloaded, but only in the editor.

Destroy after Fetch

If selected the “RCPrefsFetcher” game object will be destroyed 1 second after the fetch whether the fetch was successful or not.

Fetch Now

Use this to force a fetch from within the editor for testing purposes.  This only works when the in editor is in the play mode.

Manual Fetch via Code

If you would like to fetch your prefs manually from code you can use the static function:

RCPrefs.RequestRCPrefsFromServer(string prefSetName);

This will create a game object called “RCPrefsFetcher” and will destroy it after the fetch is complete.

Using the RCPrefs Debug Tools

The debug tools are designed to make your life easier when working with not only RCPrefs but also PlayerPrefs.  There are three main tools that allow you to inspect and in some cases modify preferences.

To bring up the RCPrefs Debug Tools, select from Window->RCPrefs->RCPrefs Debug Tools.

Server Prefs View

The Server Prefs option allows you to verify and review Prefs Sets that are being hosted on the server and used by your game.

RCPrefsDocs_10_0_DebugServer

You can fetch sets without the game running.

Fetching a set from the Debug Tools will NOT execute the associated RCPrefs Action. Actions are only called when the game is running.

Player Prefs View

The Player Prefs view allows you to view all the Player Prefs that the editor version of the game is using.

RCPrefsDocs_11_0_PlayerPrefs

You can modify values of PlayerPrefs or delete them all together.   Just make sure you hit “Save” if you make any changes.

You can reload the prefs if you have not committed with a save.

The view does show all Player Prefs including those that are encrypted.

 

Encrypted Player Prefs Views

This shows you only the Encrypted Prefs that are saved in the editor’ss local PlayerPrefs.  You can toggle between their encrypted and decrypted views.

RCPrefsDocs_12_0_EP_DecryRCPrefsDocs_13_0_EP_Encry

You can also delete or modify the Encrypted Prefs values for testing, but only when “Show Decrypted” is selected.  Make sure you hit “Save” if you make changes.

You can reload the prefs if you have not committed with a save.

Using Encrypted Prefs

You can use Encrypted Prefs in your app even if you are not using any server based fetches. To use Encrypted Prefs simply replace any applicable PlayerPrefs class methods with similar RCPrefs class methods.  For example…

PlayerPrefs.SetString(“MyStringPref”, “Hello World”);

PlayerPrefs.GetString(“MyStringPref”);

Becomes..

RCPrefs.SetEncryptedString(“MyStringPref”, “Hello World”);

RCPrefs.GetEncryptedString(“MyStringPref”);

If you use the RCPrefs class to encrypt PlayerPrefs, you will not be able to access them using standard PlayerPref commands.

RCPrefs & PlayMaker

RCPrefs integrates all its Encrypted PlayerPrefs functionality with PlayMaker.  Setting and Getting Encrypted PlayerPrefs is as simple as adding an action to a FSM.

RCPrefsDocs_15_0_Playmaker

RCPref Playmaker Installation

Download the RCPrefs PlayMaker actions here… Then click on the package to install.

Password Editor and Encryption

To bring up the Password Editor window, select from Window->RCPrefs->RCPrefs Password.

RCPrefsDocs_14_0_EP_Password

RCPrefs uses encryption in two different areas.  The files that are posted to your server are encrypted so that they cannot be read or easily modified.  When the files are fetched, they are decrypted then processed. The other place where encryption occurs is if you are using Encrypted Prefs. ie. RCPrefs.SetEncryptedInt(“MyPref”,4); The same password is used for both cases of encryption.

Setting a password is optional and if you do not set a password a default password will be used.  Your prefs will be more secure if you enter your own.

32 character passwords are recommended and you can use an online generator such as https://identitysafe.norton.com/password-generator.

However, if you enter your own password, DO NOT CHANGE YOUR PASSWORD after the game is deployed.  If you do change the password after the game is live, some clients will not be able to decrypt the RCPrefs they download from the server.  There also could be difficulties decrypting Encrypted Prefs between versions of your game.

Store your password in a safe place!

I could go on and on, but just don’t change it!  OK?

RCPrefs Exposed Methods and Events

These methods and events are available for you to use and subscribe to.

RCPrefs.cs exposes the following methods:

//Use to manually request a pref set from the server
public static void RequestRCPrefsFromServer(string prefSetName);
    
//Encrypts key and integer value then saves as a PlayerPref
public static void SetEncryptedInt(string keyint value);
    
//Decrypts PlayerPref and returns int value
//Returns 0 if key doesn't exist or can't be decrypted.
public static int GetEncryptedInt(string key)

//Decrypts PlayerPref and returns int value;
//Returns defaultValue if key doesn't exist or can't be decrypted.
public static int GetEncryptedInt(string keyint defaultValue)

//Encrypts key and float value then saves as a PlayerPref
public static void SetEncryptedFloat(string keyfloat value)
    
//Decrypts PlayerPref and returns float value
//Returns 0 if key doesn't exist or can't be decrypted.
public static float GetEncryptedFloat(string key)

//Decrypts PlayerPref and returns float value
//Returns defaultValue if key doesn't exist or can't be decrypted.
public static float GetEncryptedFloat(string keyfloat defaultValue)
        
//Encrypts key and string value then saves as a PlayerPref
public static void SetEncryptedString(string keystring value)
    
//Decrypts PlayerPref and returns string value
//Returns "" if key doesn't exist or can't be decrypted.
public static string GetEncryptedString(string key)


//Decrypts PlayerPref and returns string value
//Returns defaultValue if key doesn't exist or can't be decrypted.
public static string GetEncryptedString(string keystring defaultValue)
    
//Deletes PlayerPref from unencrypted key
public static void DeleteEncryptedKey(string key)

RCPrefs.cs fires the following events:

//Subscribe to this to find out when a RCPrefetcher completes it's downloading of prefs
public static event PrefSetFetchComplete PrefSetFetchCompleted;
    
//Subscribe to this to find out when an RCPref Integer with an Action of "C#-Eventhas been updated
public static event UpdatedInt IntValueUpdated;

//Subscribe to this to find out when an RCPref Float with an Action of "C#-Eventhas been updated
public static event UpdatedFloat FloatValueUpdated;

//Subscribe to this to find out when an RCPref String with an Action of "C#-Eventhas been updated
public static event UpdatedString StringValueUpdated;

DamianDocs