npm package: @kp-mods/mods-settings
Description: [![pipeline status](https://gitgud.io/karryn-prison-mods/mods-settings/badges/master/pipeline.svg?ignore_skipped=true)](https://gitgud.io/karryn-prison-mods/mods-settings/-/commits/master) [![Latest Release](https://gitgud.io/karryn-prison-mods/mods-setti
Author: madtisa
Latest version: 3.2.0

# Mods Settings

[![pipeline status](https://gitgud.io/karryn-prison-mods/mods-settings/badges/master/pipeline.svg?ignore_skipped=true)](https://gitgud.io/karryn-prison-mods/mods-settings/-/commits/master)
[![Latest Release](https://gitgud.io/karryn-prison-mods/mods-settings/-/badges/release.svg)](https://gitgud.io/karryn-prison-mods/mods-settings/-/releases)
[![Discord server](https://img.shields.io/discord/454295440305946644?color=%235865F2&amp;label=Discord&amp;logo=Discord)](https://discord.gg/remtairy)

[TOC]

## Description

Adds menu with settings to configure mods.

## Download

Download [the latest version of the mod][latest].

## Installation

Use [this installation guide](https://gitgud.io/karryn-prison-mods/modding-wiki/-/wikis/Installation).

## Preview

<img alt="settings" src="./preview/settings.png" height="300">
<img alt="mods-menu" src="./preview/mods-menu.png" height="500">

## For mod creators

### How to add settings to your mod

Let's take mod `MyMod.js` as an example:

```js
// #MODS TXT LINES:
// {"name":"MyMod","status":true,"description":"","parameters":{}}
// #MODS TXT LINES END
console.log('Very useful mod here!');
```

There are two ways to register settings:
- <details>
  <summary>By using global library (click me!)</summary>

  #### Register settings using global library

  To add settings to the mod perform following steps:

  1. Add dependency to your mod's declarations (at the beginning).
     It will ensure that `ModsSettings` loaded before `MyMod`.
     Changes in `MyMod.js`:
      ```diff
       // #MODS TXT LINES:
      +// {"name":"ModsSettings","status":true,"parameters":{}}
       // {"name":"MyMod","status":true,"description":"","parameters":{}}
       // #MODS TXT LINES END
      ```
  2. _Optional._ Install and use types if you want to operate with strongly
     typed settings.
      1. Install types:
         ```bash
         npm install -D @kp-mods/mods-settings
         ```
      2. Add types to your mod:
         Changes in `MyMod.js`:
         ```diff
          // #MODS TXT LINES:
          // {"name":"ModsSettings","status":true,"parameters":{}}
          // {"name":"MyMod","status":true,"description":"","parameters":{}}
          // #MODS TXT LINES END
         +/// <reference types="@kp-mods/mods-settings" />
          console.log('Very useful mod here!');
         ```
      3. Register settings. Intelli-sense will help you if you didn't skip step 2.
         After this step specified settings will be available in mods menu.
         ```ts
         // Name of the mod must be the same as js filename.
         const settings = ModsSettings.forMod('MyMod')
             .addSettings({
                 // Adds ON/OFF setting with description
                 isEnabled: {
                     type: 'bool',
                     defaultValue: true,
                     description: {
                         title: 'Is Enabled',
                         help: 'Enables mod'
                     }
                 },
                 // Adds value gauge with range from 0 to 1 and step of 0.1 (without description)
                 someValueYouWillUse: {
                     type: 'volume',
                     defaultValue: 1,
                     step: 0.1,
                     minValue: 0,
                     maxValue: 1
                 }
             })
             .register();
         ```
      4. Use settings:
         ```ts
         if (settings.get('isEnabled')) {
             const usefulValue = settings.get('someValueYouWillUse') * 100;
             console.log('Very useful mod here! Useful value is: ' + usefulValue);
         }
         ```

      Resulted `MyMod.js`:

      ```ts
      // #MODS TXT LINES:
      // {"name":"ModsSettings","status":true,"parameters":{}}
      // {"name":"MyMod","status":true,"description":"","parameters":{}}
      // #MODS TXT LINES END
      /// <reference types="@kp-mods/mods-settings" />

      // Register settings.
      const settings = ModsSettings.forMod('MyMod')
          .addSettings({
              isEnabled: {
                  type: 'bool',
                  defaultValue: true,
                  description: {
                      title: 'Is Enabled',
                      help: 'Enables mod'
                  }
              },
              someValueYouWillUse: {
                  type: 'volume',
                  defaultValue: 1,
                  step: 0.1,
                  minValue: 0,
                  maxValue: 1
              }
          })
          .register();

      // Use settings
      if (settings.get('isEnabled')) {
          const usefulValue = settings.get('someValueYouWillUse') * 100;
          console.log('Very useful mod here! Useful value is: ' + usefulValue);
      }
      ```
  </details>

- <details>
  <summary>By bundling with a module (click me!)</summary>

  #### Register settings using a module

  Alternatively, you can import the library as module, if you use bundler (e.g. webpack):

  1. Add dependency to your mod's declarations (at the beginning).
     It will ensure that `ModsSettings` loaded before `MyMod`.
     Changes in `MyMod.js`:
      ```diff
       // #MODS TXT LINES:
      +// {"name":"ModsSettings","status":true,"parameters":{}}
       // {"name":"MyMod","status":true,"description":"","parameters":{}}
       // #MODS TXT LINES END
      ```
  2. Install library `@kp-mods/mods-settings`
      ```bash
      npm install @kp-mods/mods-settings
      ```
  3. Register settings. After this step specified settings will be available in mods menu.
     ```ts
     import {registerMod} from '@kp-mods/mods-settings';
     // or if you use don't use typescript:
     // const {registerMod} = require('@kp-mods/mods-settings');

     // Name of the mod must be the same as js filename.
     const settings = ModsSettings.forMod('MyMod')
         .addSettings({
             // Adds ON/OFF setting with description
             isEnabled: {
                 type: 'bool',
                 defaultValue: true,
                 description: {
                     title: 'Is Enabled',
                     help: 'Enables mod'
                 }
             },
             // Adds value gauge with range from 0 to 1 and step of 0.1 (without description)
             someValueYouWillUse: {
                 type: 'volume',
                 defaultValue: 1,
                 step: 0.1,
                 minValue: 0,
                 maxValue: 1
             }
         })
         .register();
     ```
  4. Use settings:
     ```ts
     if (settings.get('isEnabled')) {
         const usefulValue = settings.get('someValueYouWillUse') * 100;
         console.log('Very useful mod here! Useful value is: ' + usefulValue);
     }
     ```

  Resulted `MyMod.js`:

  ```js
  // #MODS TXT LINES:
  // {"name":"ModsSettings","status":true,"parameters":{}}
  // {"name":"MyMod","status":true,"description":"","parameters":{}}
  // #MODS TXT LINES END
  import {registerMod} from '@kp-mods/mods-settings';
  // or if you use don't use typescript:
  // const {registerMod} = require('@kp-mods/mods-settings');

  // Register settings.
     const settings = ModsSettings.forMod('MyMod')
         .addSettings({
             isEnabled: {
                 type: 'bool',
                 defaultValue: true,
                 description: {
                     title: 'Is Enabled',
                     help: 'Enables mod'
                 }
             },
             someValueYouWillUse: {
                 type: 'volume',
                 defaultValue: 1,
                 step: 0.1,
                 minValue: 0,
                 maxValue: 1
             }
         })
         .register();

  // Use settings
  if (settings.get('isEnabled')) {
      const usefulValue = settings.get('someValueYouWillUse') * 100;
      console.log('Very useful mod here! Useful value is: ' + usefulValue);
  }
  ```
  </details>

## Links

[![Discord server](https://img.shields.io/discord/454295440305946644?color=%235865F2&amp;label=Discord&amp;logo=Discord)](https://discord.gg/remtairy)

[latest]: https://gitgud.io/karryn-prison-mods/mods-settings/-/releases/permalink/latest "The latest release"