---
title: Custom Settings
description: Add custom settings to various parts of ORK Framework with your own classes. Custom settings are an easy way to add your own settings to the editor and functionality to the game. There are globally available settings (see global custom…
url: "https://orkframework.com/guide/ork3/ork3-documentation/scripting/custom-settings/"
updated: "2026-07-08"
category: ORK 3 Documentation / Scripting
tags:
  - Scripting
---

# Custom Settings

Add custom settings to various parts of ORK Framework with your own classes.

Custom settings are an easy way to add your own settings to the editor and functionality to the game. There are globally available settings (see global custom settings below) and as settings bound to separate instances of content (e.g. combatants or items, see custom settings below).

# Global Custom Settings

Global custom settings are available, as the name suggests, globally - i.e. from everywhere and at all times. They are set up in **Base/Control > Global Custom Settings**.

Each global custom setting will create it's own in-game instance and will be saved with save games. When enabling *Clear New Game*, starting a new game will automatically create a new, clean instance when starting a new game (e.g. to remove any changes made to the instance by a previous game.

## Using

You can call custom functionality via the *Use* function of it's implementation (see details in the scripting information below). The *Use* function can start different functionality based on the passed on parameters, e.g. via the *info* string parameter.

The function can be used without scripting by built-in functionality in schematics (*Use Global Custom Settings* node), menu screens *(Use Global Custom Settings* button type in *Button List* menu parts), abilities, items, status effects, battle menus, research items and body parts (*Use Global Custom Settings* status change type).

Beside using this, you can also implement custom nodes to call functionality (other than the *Use* function) of your global custom settings classes.

## Scripting

To add your own global custom settings, you need to write a custom class extending from *BaseGlobalCustomSettingsType* class.

The class has to implement the *CreateInstance* function, which returns in instance class implementing the *IGlobalCustomSettingsInstance* interface. Additionally, the class has to add the *EditorSettingsInfo* attribute to add editor information for the type selection dropdown of the global custom settings.

The instance class is used for keeping track of any in-game changes as well as saving and loading the data of the instance with save games.

### Accessing

Global custom settings can be accessed via *ORK.GlobalCustomSettings*, either getting a setting by it's index in the editor or by using it's GUID.

Via index:

```
int index = 0;
GlobalCustomSettings settings = ORK.GlobalCustomSettings.Get(index);
```

Via GUID:

```
string guid = "YOUR_GUID";
GlobalCustomSettings settings = ORK.GlobalCustomSettings.Get(guid);
```

You can access the in-game instance via the *GlobalCustomSettings* class by using the *Instance* property.

E.g. to cast it to a specific setting's instance instead of the *IGlobalCustomSettingsInstance* interface:

```
DebugGlobalCustomSettingsType.Instance instance = ORK.GlobalCustomSettings.Get(index).Instance as DebugGlobalCustomSettingsType.Instance;
if(instance != null)
{
    // your code
}
```

Casting it to your specific class instance allows you to access other functionality beside the functions provided by the interface.

### Initialization and Unloading

Global custom settings instances don't require a specific function for initializing it's content - if you need to handle some custom setup, call this in the constructor of your instance class.

However, the instance requires the *Unload* function, which will be called when an old instance is replaced by a new instance (e.g. when loading a save game or starting a new game with creating a new instance). This function can be used to handle things to clean up an old instance, e.g. to remove event hooks.

### Debug Class Example

Below you can see the an example implementation of the *Debug* global custom settings type.

This class outputs a text to the console and increases a counter by 1 each time it's used. The counter is saved with save games.

```
using UnityEngine;
using GamingIsLove.Makinom;
using System.Collections.Generic;

namespace GamingIsLove.ORKFramework
{
    [EditorSettingInfo("Debug", "Test implementation, outputs information on user and target to the console.n" +
        "Each call to the 'Use' function will increase a counter, which can also be output to the console.")]
    public class DebugGlobalCustomSettingsType : BaseGlobalCustomSettingsType
    {
        [EditorHelp("Debug Type", "Select the debug type will be used:n" +
            "- Log: Printed to 'Debug.Log'.n" +
            "- Warning: Printed to 'Debug.LogWarning'.n" +
            "- Error: Printed to 'Debug.LogError'.", "")]
        [EditorFoldout("Debug Settings", "")]
        public DebugType type = DebugType.Log;

        [EditorSeparator]
        public VariableOrigin<GameObjectSelection> variable = new VariableOrigin<GameObjectSelection>();

        [EditorHelp("Text", "The text that will be printed to the Unity console.", "")]
        [EditorEndFoldout]
        [EditorSeparator]
        [EditorTitleLabel("Console Output")]
        [EditorLabel("<user> = user information, <target> = target informationn" +
            "<count> = use counter, <info> = info text")]
        public TextContent text = new TextContent("<user>:<target>:<count>:<info>");

        public DebugGlobalCustomSettingsType()
        {

        }

        public override IGlobalCustomSettingsInstance CreateInstance()
        {
            return new Instance(this);
        }


        /*
        ============================================================================
        Instance class
        ============================================================================
        */
        public class Instance : IGlobalCustomSettingsInstance
        {
            protected DebugGlobalCustomSettingsType settings;

            protected int count = 0;

            public Instance(DebugGlobalCustomSettingsType settings)
            {
                this.settings = settings;
            }

            public virtual void Unload()
            {

            }

            public virtual void Use(object user, object target, string info, VariableHandler variables, SelectedDataHandler selectedData)
            {
                this.count++;

                UIText content = new UIText(this.settings.text, null, null,
                    this.settings.variable.GetFirstHandler(new DataCall(user, target, variables, selectedData)));
                content.Replace("<count>", ORK.TextDisplaySettings.numberFormatting.intNumberFormat.FormatInt(this.count));
                content.Replace("<user>", user is IContent ? ((IContent)user).GetName() : "" + user);
                content.Replace("<target>", target is IContent ? ((IContent)target).GetName() : "" + target);
                content.Replace("<info>", info);

                if(DebugType.Log == this.settings.type)
                {
                    Debug.Log(content.Text);
                }
                else if(DebugType.Warning == this.settings.type)
                {
                    Debug.LogWarning(content.Text);
                }
                else if(DebugType.Error == this.settings.type)
                {
                    Debug.LogError(content.Text);
                }
            }

            public virtual DataObject SaveGame()
            {
                DataObject data = new DataObject();
                data.Set("count", this.count);
                return data;
            }

            public virtual void LoadGame(DataObject data)
            {
                if(data != null)
                {
                    data.Get("count", ref this.count);
                }
            }
        }
    }
}
```

# Custom Settings

Custom settings can be added to combatants, classes, items, equipment, abilities and status effects.

Each instance of those contents will have their own instances of the added custom settings, e.g. each combatant has it's own custom settings instances, each status effect added to a combatant has it's own instances of it's added custom settings.

The data of those instances are saved with the save data of the content they belong to, e.g. with a combatant, an item or equipment.

## Using

Using the correct custom settings of a content can depend on a *settings key* set up to identify it. Otherwise, the use is similar to global custom settings, i.e. you call the instance's *Use* function.

The function can be used in schematics via the *Use Custom Settings* node and call it call it for content stored in selected data. Abilities, items and status effects can use the *Use Custom Settings* status change type to call their own instance's *Use* function.

Beside using this, you can also implement custom nodes to call functionality (other than the *Use* function) of your custom settings classes.

## Scripting

To add your own custom settings, you need to write a custom class extending from *BaseCustomSettingsType* class.

The class has to implement the *CreateInstance* function, which returns in instance class implementing the *ICustomSettingsInstance* interface. Additionally, the class has to add the *EditorSettingsInfo* attribute to add editor information for the type selection dropdown of the custom settings.

The instance class is used for keeping track of any in-game changes as well as saving and loading the data of the instance with save games.

### Accessing

Since custom settings are bound to instances of content like combatants or items, they're also accessed via those instances. Basically, everything implementing the *ICustomSettings* interface can give access to the instance of a custom setting added to it.

This is currently available in the following classes representing an instance of a content:

- abilities via the *AbilityShortcut* class
- classes via the *ClassShortcut* class
- combatants via the *Combatant* class
- equipment via the *EquipShortcut* class
- items via the *ItemShortcut* class
- status effects via the *StatusEffect* class

The *ICustomSettings* interface provides 2 functions to interact with the custom settings instance.

The *UseCustomSettings* function calls the *Use* function of the instance for a provided settings key, e.g. on an item (*ItemShortcut* class):

```
item.UseCustomSettings("key", user, target, "info", variables, selectedData);
```

The *user* and *target* parameters can be anything, e.g. a combatant, while the *info* string provides the context for the call. You can use it to call different functionality in your custom settings instance. Passing on variables or selected data is optional, e.g. pass on *null* if you don't need them.

The *GetCustomSettingsInstance* function returns the instance of custom settings for a provided key, e.g. on a combatant (*Combatant* class):

```
DebugCustomSettingsType.Instance instance = combatant.GetCustomSettingsInstance("debug") as DebugCustomSettingsType.Instance;
```

The above example also casts the instance to a specific class implementation. If the returned instance doesn't match the cast class type, the *instance* will be *null*.

### Initialization

Custom settings provide two initialization functions, the *Init* function for initialization of a new instance and the *InitLoad* function when initializing an instance before loading data from a save game. Both pass on the source they belong to, e.g. the instance of the combatant or item they're bound to.

### Debug Class Example

Below you can see the an example implementation of the *Debug* custom settings type.

This class outputs a text to the console and increases a counter by 1 each time it's used. The counter is saved with save games.

```
using UnityEngine;
using GamingIsLove.Makinom;
using System.Collections.Generic;

namespace GamingIsLove.ORKFramework
{
    [EditorSettingInfo("Debug", "Test implementation, outputs information on the instance, user and target to the console.n" +
        "Each call to the 'Use' function will increase a counter, which can also be output to the console.")]
    public class DebugCustomSettingsType : BaseCustomSettingsType
    {
        [EditorHelp("Debug Type", "Select the debug type will be used:n" +
            "- Log: Printed to 'Debug.Log'.n" +
            "- Warning: Printed to 'Debug.LogWarning'.n" +
            "- Error: Printed to 'Debug.LogError'.", "")]
        public DebugType type = DebugType.Log;

        [EditorSeparator]
        public VariableOrigin<GameObjectSelection> variable = new VariableOrigin<GameObjectSelection>();

        [EditorHelp("Text", "The text that will be printed to the Unity console.", "")]
        [EditorSeparator]
        [EditorTitleLabel("Console Output")]
        [EditorLabel("<count> = use counter, <content> = content information (e.g. item)n" +
            "<user> = user information, <target> = target informationn" +
            "<info> = info text")]
        public TextContent text = new TextContent("<content>:<user>:<target>:<count>:<info>");

        public DebugCustomSettingsType()
        {

        }

        public override string ToString()
        {
            return "Debug";
        }

        public override ICustomSettingsInstance CreateInstance()
        {
            return new Instance(this);
        }


        /*
        ============================================================================
        Instance class
        ============================================================================
        */
        public class Instance : ICustomSettingsInstance
        {
            protected DebugCustomSettingsType settings;

            protected int count = 0;

            public Instance(DebugCustomSettingsType settings)
            {
                this.settings = settings;
            }

            public virtual void Init(object source)
            {

            }

            public virtual void InitLoad(object source)
            {

            }

            public virtual void Use(object source, object user, object target, string info, VariableHandler variables, SelectedDataHandler selectedData)
            {
                this.count++;

                UIText content = new UIText(this.settings.text, null, null, 
                    this.settings.variable.GetFirstHandler(new DataCall(user, target, variables, selectedData)));
                content.Replace("<count>", ORK.TextDisplaySettings.numberFormatting.intNumberFormat.FormatInt(this.count));
                content.Replace("<content>", source is IContent ? ((IContent)source).GetName() : "" + source);
                content.Replace("<user>", user is IContent ? ((IContent)user).GetName() : "" + user);
                content.Replace("<target>", target is IContent ? ((IContent)target).GetName() : "" + target);
                content.Replace("<info>", info);

                if(DebugType.Log == this.settings.type)
                {
                    Debug.Log(content.Text);
                }
                else if(DebugType.Warning == this.settings.type)
                {
                    Debug.LogWarning(content.Text);
                }
                else if(DebugType.Error == this.settings.type)
                {
                    Debug.LogError(content.Text);
                }
            }

            public virtual DataObject SaveGame()
            {
                DataObject data = new DataObject();
                data.Set("count", this.count);
                return data;
            }

            public virtual void LoadGame(DataObject data)
            {
                if(data != null)
                {
                    data.Get("count", ref this.count);
                }
            }
        }
    }
}
```

 
