https://github.com/chemodun/x4-optionshelper
https://github.com/chemodun/x4-optionshelper
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/chemodun/x4-optionshelper
- Owner: chemodun
- License: apache-2.0
- Created: 2026-04-27T10:09:51.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-27T11:17:38.000Z (2 months ago)
- Last Synced: 2026-04-27T12:27:55.338Z (2 months ago)
- Size: 8.05 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Options Helper
A library mod for **X4: Foundations** that provides reusable MD (Mission Director) script libraries for building `SirNukes Mod Support APIs` options menus.
Instead of repeating the widget-construction boilerplate in every mod, declare your menu sections using the `Options_Helper` libraries and wire up a single handler cue per widget type.
## Requirements
- **X4: Foundations** version 8.00 or newer
- **SirNukes Mod Support APIs** version 1.95 or higher
## Installation
Place the `options_helper/` folder in your X4 extensions directory alongside your other mods.
---
## API Reference
All libraries live in the `md.Options_Helper` namespace. Widget-building libraries use `purpose="run_actions"` (called with ``) while layout and event-processing libraries use `purpose="include_actions"` (called with ``).
### Layout libraries
#### `Add_Empty_Row` — `include_actions`
Adds a thin visual separator row (border height) to the current options menu.
```xml
```
---
#### `Add_Title_Row` — `run_actions`
Adds a centred section title row followed by an empty separator row.
- `title` *(required)* - Text string or text DB reference `{page, id}`
- `columns` *(default: `12`)* - Number of columns in the menu
```xml
```
---
### Widget libraries
#### `Add_Checkbox` — `run_actions`
Adds a checkbox widget with a text label to its right. Automatically starts a new row when `col == 1`.
- `id` *(required)* - String identifier - used to build the widget id and the echo key `$`
- `col` *(default: `1`)* - Column for the checkbox widget
- `textColSpan` *(default: `1`)* - Column span for the label text cell
- `text` *(default: `''`)* - Label text or text DB reference
- `data` *(required)* - Table holding the current value at key `$`
- `active` *(default: `true`)* - Whether the widget is interactive
- `handle` *(default: `null`)* - Cue to signal on click
**Handler echo fields:**
- `event.param.$echo.$valueId` - table key string, e.g. `'$mySetting'`
- `event.param.$checked` - int `0` or `1` after the click
```xml
```
---
#### `Add_Dropdown` — `run_actions`
Adds a label text cell followed by a dropdown widget on the same row. Automatically starts a new row when `col == 1`.
- `id` *(required)* - String identifier - used to build the widget id and the echo key `$`
- `options` *(required)* - List of `[$text = ..., $value = ...]` option entries
- `currentIndex` *(default: `1`)* - 1-based index of the initially selected option
- `col` *(default: `1`)* - Column for the label text cell
- `textColSpan` *(default: `1`)* - Column span for the label
- `text` *(default: `''`)* - Label text or text DB reference
- `dropdownColSpan` *(default: `1`)* - Column span for the dropdown widget
- `active` *(default: `true`)* - Whether the widget is interactive
- `handle` *(default: `null`)* - Cue to signal on option confirm
**Handler echo fields:**
- `event.param.$echo.$valueId` - table key string, e.g. `'$myOption'`
- `event.param.$option.$value` - value of the selected option
```xml
```
---
#### `Add_Slider` — `run_actions`
Adds a non-selectable label row followed by a slider widget row. Always creates a two-row pair.
- `id` *(required)* - String identifier - used to build the widget id and the echo key `$`
- `text` *(default: `''`)* - Label text or text DB reference shown above the slider
- `min` *(default: `0`)* - Minimum slider value
- `max` *(default: `100`)* - Maximum slider value
- `step` *(default: `1`)* - Step increment between slider positions
- `suffix` *(default: `''`)* - String appended to the displayed current value
- `colSpan` *(default: `1`)* - Column span for both the label and slider cells
- `data` *(required)* - Table holding the current value at key `$`
- `readOnly` *(default: `false`)* - Whether the slider is display-only
- `handle` *(default: `null`)* - Cue to signal on slider confirm
**Handler echo fields:**
- `event.param.$echo.$valueId` - table key string, e.g. `'$mySlider'`
- `event.param.$value` - confirmed longfloat value
```xml
```
---
### Event-processing libraries
These three libraries are `include_actions` — they run inline inside your handler cue, where `event.param` is in scope. Before calling, assign `$resultTable` to the table you want written.
#### `Process_Dropdown_Changed` — `include_actions`
Reads `event.param.$echo.$valueId` and `event.param.$option.$value`, writes the selected value into `$resultTable`.
```xml
```
---
#### `Process_Slider_Changed` — `include_actions`
Reads `event.param.$echo.$valueId` and `event.param.$value`, writes the confirmed slider value into `$resultTable`.
```xml
```
---
#### `Process_Checkbox_Changed` — `include_actions`
Reads `event.param.$echo.$valueId` and `event.param.$checked` (int `0`/`1`), writes the checked state into `$resultTable`.
```xml
```
---
## Complete Usage Example
```xml
```
---
## Credits
- **Author**: Chem O`Dun, on [Nexus Mods](https://next.nexusmods.com/profile/ChemODun/mods?gameId=2659) and [Steam Workshop](https://steamcommunity.com/id/chemodun/myworkshopfiles/?appid=392160)
- *"X4: Foundations"* is a trademark of [Egosoft](https://www.egosoft.com).
## Acknowledgements
- [EGOSOFT](https://www.egosoft.com) - for the X series.
- [SirNukes](https://next.nexusmods.com/profile/sirnukes?gameId=2659) - for the `Mod Support APIs` that power the UI hooks.