Configuring Settings

Controllers have a series of settings that can have various effects on them.

→ Settings List

Getting Current Settings

You can see a list of these settings and their current values with the .list() method of any controller's settings property.

var controller = Controller.getController(0);
controller.settings.list();

>> GC_Settings {
>>     analogStickDpadThreshold: 0.7,
>>     buttonThreshold: 0.95,
>>     joystickDeadzone: Object {…},
>>     mapAnalogToShape: "none",
>>     useAnalogAsDpad: "none",
>> }

Checking an Individual Setting

Settings are accessed directly from the settings property.

var controller = Controller.getController(0);

console.log(controller.settings.useAnalogAsDpad);
>> "none"

Updating Settings

Any setting can be updated either directly, or with the update() method.

var controller = Controller.getController(0);

controller.settings.useAnalogAsDpad = "left";
controller.settings.update("analogStickDpadThreshold", 0.3);

update() can be used to change multiple settings at once by passing it a list of setting/value pairs.

var controller = Controller.getController(0);

controller.settings.update({
    useAnalogAsDpad: "left",
    analogStickDpadThreshold: 0.3
});

Resetting or Clearing Values

Directly Setting a Value

A setting can be reset to it's default value by setting it to "default". It can be cleared by setting it to undefined. For global settings, these are functionally the same. For individual settings the difference is that undefined makes it fall back to the global setting and "default" makes sure it is set to it's defaul value, even when the global setting is not.

var controller = Controller.getController(0);

console.log(controller.settings.useAnalogAsDpad);
>> "none"

controller.settings.useAnalogAsDpad = "left";
console.log(controller.settings.useAnalogAsDpad);
>> "left"

controller.settings.useAnalogAsDpad = "default";
console.log(controller.settings.useAnalogAsDpad);
>> "none"

Using the clear() Method

The clear() method will clear all controller settings. In practice, this means that each controller setting will fall back to the global version of that setting. This method works slightly different on global settings.

var controller = Controller.getController(0);

console.log(controller.settings.useAnalogAsDpad);
>> "none"

controller.settings.useAnalogAsDpad = "left";
console.log(controller.settings.useAnalogAsDpad);
>> "left"

controller.settings.clear();
console.log(controller.settings.useAnalogAsDpad);
>> "none"

Single-Controller Settings vs Global Settings

Each setting can be either set globally or on a specific controller instance. Controller settings cascade from global to controller instance: If a controller has a setting explicitly set, it will use that value. Otherwise it will use the global setting.

Behavior Differences

Global settings are accessed from the globalSettings attribute of the Controller object. Global settings can be interacted with using the same methods as individual controller settings, although clear() behaves slightly differently.

// list()
Controller.globalSettings.list();

>> GC_Settings {
>>     analogStickDpadThreshold: 0.7,
>>     buttonThreshold: 0.95,
>>     joystickDeadzone: Object {…},
>>     mapAnalogToSquare: true,
>>     useAnalogAsDpad: "none",
>> }

// update()
Controller.globalSettings.update("analogStickDpadThreshold", 0.3);

On the globalSettings list, clear() will reset all settings to their default values, rather than clearing them (essentially, all settings must have some value, so the global list has to reset to something valid).

// clear()
console.log(Controller.globalSettings.useAnalogAsDpad);
>> "none"

Controller.globalSettings.useAnalogAsDpad = "left";
console.log(Controller.globalSettings.useAnalogAsDpad);
>> "left"

Controller.globalSettings.clear();
console.log(Controller.globalSettings.useAnalogAsDpad);
>> "none"

Settings Cascading

var playerOne = Controller.getController(0);

// Default values
console.log(Controller.globalSettings.useAnalogAsDpad);
console.log(playerOne.settings.useAnalogAsDpad);
>> "none"      // Global
>> "none"      // Indivudual

// Only the global setting for 'useAnalogAsDpad' is updated
Controller.globalSettings.useAnalogAsDpad = "left";

console.log(Controller.globalSettings.useAnalogAsDpad);
console.log(playerOne.settings.useAnalogAsDpad);
>> "left"      // Global
>> "left"      // Indivudual

// Now the controller's individual copy is updated
playerOne.settings.useAnalogAsDpad = "right";

console.log(Controller.globalSettings.useAnalogAsDpad);
console.log(playerOne.settings.useAnalogAsDpad);
>> "left"      // Global
>> "right"     // Indivudual

// Changing the global setting will not overwrite
// the indivudual copy
Controller.globalSettings.useAnalogAsDpad = "both";

console.log(Controller.globalSettings.useAnalogAsDpad);
console.log(playerOne.settings.useAnalogAsDpad);
>> "both"      // Global
>> "right"      // Indivudual

// Clearing the local copy of 'useAnalogAsDpad' will make
// it fall back to the global copy
playerOne.settings.useAnalogAsDpad = undefined;

console.log(Controller.globalSettings.useAnalogAsDpad);
console.log(playerOne.settings.useAnalogAsDpad);
>> "both"      // Global
>> "both"      // Indivudual

// Clearing the global copy of 'useAnalogAsDpad' will reset
// it to it's default value
Controller.globalSettings.useAnalogAsDpad = "default";

console.log(Controller.globalSettings.useAnalogAsDpad);
console.log(playerOne.settings.useAnalogAsDpad);
>> "none"      // Global
>> "none"      // Indivudual