API Functions and Examples - Starexify/JsonConfig GitHub Wiki

The JSON Config API offers a set of helper functions for managing your configs.

After setting up the module and creating your first config, you can use these functions to interact with your configuration values.

Terms

Term	Meaning
`config`	The complete configuration object with all settings
`key`/`*Key`	A field name in the config (e.g., "playerName")
`value`	The actual data stored in a config field (e.g., "Funkin")

Function References

Basic Config Operations

Function	Description	Example
`getConfig()`	Returns the entire configuration object	`var config = getConfig()`
`saveConfig(config)`	Saves the given config values to disk and updates the default config	`saveConfig({playerName: "Boyfriend"})`
`clearConfig()`	Completely clears the configuration by deleting the config file	`if(clearConfig()) trace("Config cleared successfully")`
`resetConfig()`	Resets the current configuration to its default values	`var defaultConfig = resetConfig()`

Simple Values

Function	Description	Example
`getConfigValue(key)`	Gets a value from your config by key	`var name = getConfigValue("playerName")`
`setConfigValue(key, value)`	Updates or adds a value in your config	`setConfigValue("playerName", "Boyfriend")`

Array Operations

Function	Description	Example
`getArrayConfigValue(parentKey, index)`	Gets a value from an array in your config	`var secondSong = getArrayConfigValue("songList", 1)`
`setArrayConfigValue(parentKey, index, value)`	Updates or adds a value in an array	`setArrayConfigValue("songList", 2, "Philly")`

Nested Object Operations

Function	Description	Example
`getNestedConfigValue(parentKey, childKey)`	Gets a value from a nested object	`var volume = getNestedConfigValue("audio", "volume")`
`setNestedConfigValue(parentKey, childKey, value)`	Updates or adds a value in a nested object	`setNestedConfigValue("audio", "volume", 0.8)`

Deep Nested Operations

Function	Description	Example
`getDeepConfigValue(keyPath)`	Gets a value from deeply nested objects using a path	`var sfxVolume = getDeepConfigValue(["audio", "sfx", "volume"])`
`setDeepConfigValue(keyPath, value)`	Updates or adds a value in deeply nested objects	`setDeepConfigValue(["audio", "sfx", "volume"], 0.5)`

Path and Configuration Management

Function	Description	Example
`getPath()`	Gets the config path.	`var configDir = getPath()`
`getFilePath()`	Gets the full file path of the config	`var fullPath = getFilePath()`
`setFilePath()`	Sets the file path and saves the config (automatically adds ".json")	`setFilePath("config/myMod/settings")`
`getConfigID()`	Gets the ID of the config	`var id = getConfigID()`
`setConfigID(path)`	Sets the ID of the config	`setConfigID("gameSettings")`
`getDefaultConfig()`	Gets the default configuration object	`var defaults = getDefaultConfig()`
`setDefaultConfig(config)`	Sets the default configuration object	`setDefaultConfig({playerName: "Boyfriend"})`

Complete Usage Example

Building on the example from the Getting Started page, here's how to use the various config functions:

class Testing extends ScriptedModule {
    var config:JsonConfig;
    var configValues:Dynamic = {
        playerName: "Boyfriend",
        difficulty: "Normal",
        audio: {
            music: 0.8,
            sfx: 0.9
        },
        unlockedSongs: ["Tutorial", "Bopeebo"]
    };
    
    function new() {
        super("Testing");
    }
    
    override function onCreate(event:ScriptEvent) {
        // Create a new config with default values
        config = new JsonConfig("myModConfig", configValues);
        
        // Basic usage examples
        trace("Current player name: " + config.getConfigValue("playerName"));
        
        // Change a simple value
        config.setConfigValue("difficulty", "Hard");
        
        // Working with nested values
        var musicVolume = config.getNestedConfigValue("audio", "music");
        trace("Music volume: " + musicVolume);
        
        // Update a nested value
        config.setNestedConfigValue("audio", "sfx", 0.7);
        
        // Working with arrays
        var firstSong = config.getArrayConfigValue("unlockedSongs", 0);
        trace("First unlocked song: " + firstSong);
        
        // Add a new song to the array
        var songs = config.getConfigValue("unlockedSongs");
        config.setArrayConfigValue("unlockedSongs", songs.length, "Fresh");
        
        // Working with deep paths
        config.setDeepConfigValue(["gameplay", "controls", "keyboard", "up"], "W");
        var upKey = config.getDeepConfigValue(["gameplay", "controls", "keyboard", "up"]);
        trace("Up key: " + upKey);
    }
}