Settings

Define user-configurable settings that appear in GemShell's UI.

Setting Types

Checkbox

{
  id: 'enabled',
  type: 'checkbox',
  label: 'Enable feature',
  description: 'Tooltip text shown on hover',
  default: true
}

Text

{
  id: 'message',
  type: 'text',
  label: 'Message',
  placeholder: 'Enter text...',
  description: 'The message to display',
  default: ''
}

Textarea

{
  id: 'customCss',
  type: 'textarea',
  label: 'Custom CSS',
  placeholder: '/* Your CSS here */',
  rows: 5,
  default: ''
}

Number

{
  id: 'port',
  type: 'number',
  label: 'Port',
  min: 1,
  max: 65535,
  step: 1,
  placeholder: '8080',
  default: 8080
}

Slider / Range

{
  id: 'opacity',
  type: 'slider',  // or 'range'
  label: 'Opacity',
  min: 0,
  max: 100,
  step: 5,
  default: 80
}

Select (Dropdown)

{
  id: 'position',
  type: 'select',
  label: 'Position',
  options: ['top-left', 'top-right', 'bottom-left', 'bottom-right'],
  default: 'bottom-right'
}

Color

{
  id: 'color',
  type: 'color',
  label: 'Text color',
  default: '#ffffff'
}

Setting Properties

Property	Type	Required	Description
id	string	Yes	Unique identifier
type	string	Yes	Setting type
label	string	Yes	Display label
default	any	No	Default value
description	string	No	Tooltip text
placeholder	string	No	Placeholder text (text, textarea, number)
min	number	No	Minimum value (number, slider)
max	number	No	Maximum value (number, slider)
step	number	No	Step increment (number, slider)
rows	number	No	Number of rows (textarea)
options	string[]	No	Options list (select)

Accessing Settings

In script.js (Runtime)

// GEMSHELL_SETTINGS is auto-injected
const { enabled, message, opacity, position, color } = GEMSHELL_SETTINGS;

if (!enabled) return;

const el = document.getElementById('my-element');
el.style.opacity = opacity / 100;
el.style.color = color;

In template.html

{{#if enabled}}
<div style="opacity: {{opacity}}%; color: {{color}}">
  {{message}}
</div>
{{/if}}

In Hooks (Build-time)

onModifyAssets: async (context, settings) => {
  // settings object contains all setting values
  if (settings.enabled) {
    gemshell.log(`Message: ${settings.message}`);
  }
}

Settings Priority

Settings are merged in this order (later overrides earlier):

1. Plugin defaults - from plugin.js
2. Global saved settings - user changed in Manage Plugins
3. Per-game overrides - user changed in Game Settings

Complete Example

module.exports = {
  name: 'FPS Counter',
  version: '1.0.0',
  inject: ['style.css', 'template.html', 'script.js'],
  
  settings: [
    {
      id: 'enabled',
      type: 'checkbox',
      label: 'Show FPS Counter',
      description: 'Display frames per second in-game',
      default: true
    },
    {
      id: 'position',
      type: 'select',
      label: 'Position',
      description: 'Where to show the counter',
      options: ['top-left', 'top-right', 'bottom-left', 'bottom-right'],
      default: 'top-left'
    },
    {
      id: 'opacity',
      type: 'slider',
      label: 'Opacity',
      min: 20,
      max: 100,
      step: 10,
      default: 80
    },
    {
      id: 'color',
      type: 'color',
      label: 'Text Color',
      default: '#4ade80'
    }
  ]
};