{"id":50269545,"url":"https://github.com/chemodun/x4-optionshelper","last_synced_at":"2026-05-27T16:04:31.593Z","repository":{"id":354158742,"uuid":"1222385967","full_name":"chemodun/X4-OptionsHelper","owner":"chemodun","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-27T11:17:38.000Z","size":8436,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T12:27:55.338Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chemodun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-27T10:09:51.000Z","updated_at":"2026-04-27T11:17:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chemodun/X4-OptionsHelper","commit_stats":null,"previous_names":["chemodun/x4-optionshelper"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/chemodun/X4-OptionsHelper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chemodun%2FX4-OptionsHelper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chemodun%2FX4-OptionsHelper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chemodun%2FX4-OptionsHelper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chemodun%2FX4-OptionsHelper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chemodun","download_url":"https://codeload.github.com/chemodun/X4-OptionsHelper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chemodun%2FX4-OptionsHelper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33573276,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-27T16:04:08.572Z","updated_at":"2026-05-27T16:04:31.584Z","avatar_url":"https://github.com/chemodun.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Options Helper\n\nA library mod for **X4: Foundations** that provides reusable MD (Mission Director) script libraries for building `SirNukes Mod Support APIs` options menus.\n\nInstead 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.\n\n## Requirements\n\n- **X4: Foundations** version 8.00 or newer\n- **SirNukes Mod Support APIs** version 1.95 or higher\n\n## Installation\n\nPlace the `options_helper/` folder in your X4 extensions directory alongside your other mods.\n\n---\n\n## API Reference\n\nAll libraries live in the `md.Options_Helper` namespace. Widget-building libraries use `purpose=\"run_actions\"` (called with `\u003crun_actions ref=\"...\"\u003e`) while layout and event-processing libraries use `purpose=\"include_actions\"` (called with `\u003cinclude_actions ref=\"...\"\u003e`).\n\n### Layout libraries\n\n#### `Add_Empty_Row` — `include_actions`\n\nAdds a thin visual separator row (border height) to the current options menu.\n\n```xml\n\u003cinclude_actions ref=\"md.Options_Helper.Add_Empty_Row\" /\u003e\n```\n\n---\n\n#### `Add_Title_Row` — `run_actions`\n\nAdds a centred section title row followed by an empty separator row.\n\n- `title` *(required)* - Text string or text DB reference `{page, id}`\n- `columns` *(default: `12`)* - Number of columns in the menu\n\n```xml\n\u003crun_actions ref=\"md.Options_Helper.Add_Title_Row\"\u003e\n  \u003cparam name=\"title\" value=\"{1972092401, 100}\" /\u003e\n  \u003cparam name=\"columns\" value=\"12\" /\u003e\n\u003c/run_actions\u003e\n```\n\n---\n\n### Widget libraries\n\n#### `Add_Checkbox` — `run_actions`\n\nAdds a checkbox widget with a text label to its right. Automatically starts a new row when `col == 1`.\n\n- `id` *(required)* - String identifier - used to build the widget id and the echo key `$\u003cid\u003e`\n- `col` *(default: `1`)* - Column for the checkbox widget\n- `textColSpan` *(default: `1`)* - Column span for the label text cell\n- `text` *(default: `''`)* - Label text or text DB reference\n- `data` *(required)* - Table holding the current value at key `$\u003cid\u003e`\n- `active` *(default: `true`)* - Whether the widget is interactive\n- `handle` *(default: `null`)* - Cue to signal on click\n\n**Handler echo fields:**\n\n- `event.param.$echo.$valueId` - table key string, e.g. `'$mySetting'`\n- `event.param.$checked` - int `0` or `1` after the click\n\n```xml\n\u003crun_actions ref=\"md.Options_Helper.Add_Checkbox\"\u003e\n  \u003cparam name=\"id\" value=\"'mySetting'\" /\u003e\n  \u003cparam name=\"col\" value=\"1\" /\u003e\n  \u003cparam name=\"textColSpan\" value=\"11\" /\u003e\n  \u003cparam name=\"text\" value=\"{1972092401, 110}\" /\u003e\n  \u003cparam name=\"data\" value=\"@$mySettings\" /\u003e\n  \u003cparam name=\"handle\" value=\"Handle_Checkbox\" /\u003e\n\u003c/run_actions\u003e\n```\n\n---\n\n#### `Add_Dropdown` — `run_actions`\n\nAdds a label text cell followed by a dropdown widget on the same row. Automatically starts a new row when `col == 1`.\n\n- `id` *(required)* - String identifier - used to build the widget id and the echo key `$\u003cid\u003e`\n- `options` *(required)* - List of `[$text = ..., $value = ...]` option entries\n- `currentIndex` *(default: `1`)* - 1-based index of the initially selected option\n- `col` *(default: `1`)* - Column for the label text cell\n- `textColSpan` *(default: `1`)* - Column span for the label\n- `text` *(default: `''`)* - Label text or text DB reference\n- `dropdownColSpan` *(default: `1`)* - Column span for the dropdown widget\n- `active` *(default: `true`)* - Whether the widget is interactive\n- `handle` *(default: `null`)* - Cue to signal on option confirm\n\n**Handler echo fields:**\n\n- `event.param.$echo.$valueId` - table key string, e.g. `'$myOption'`\n- `event.param.$option.$value` - value of the selected option\n\n```xml\n\u003crun_actions ref=\"md.Options_Helper.Add_Dropdown\"\u003e\n  \u003cparam name=\"id\" value=\"'myOption'\" /\u003e\n  \u003cparam name=\"options\" value=\"$myOptions\" /\u003e\n  \u003cparam name=\"currentIndex\" value=\"$currentIndex\" /\u003e\n  \u003cparam name=\"col\" value=\"1\" /\u003e\n  \u003cparam name=\"textColSpan\" value=\"7\" /\u003e\n  \u003cparam name=\"text\" value=\"{1972092401, 120}\" /\u003e\n  \u003cparam name=\"dropdownColSpan\" value=\"5\" /\u003e\n  \u003cparam name=\"handle\" value=\"Handle_Dropdown\" /\u003e\n\u003c/run_actions\u003e\n```\n\n---\n\n#### `Add_Slider` — `run_actions`\n\nAdds a non-selectable label row followed by a slider widget row. Always creates a two-row pair.\n\n- `id` *(required)* - String identifier - used to build the widget id and the echo key `$\u003cid\u003e`\n- `text` *(default: `''`)* - Label text or text DB reference shown above the slider\n- `min` *(default: `0`)* - Minimum slider value\n- `max` *(default: `100`)* - Maximum slider value\n- `step` *(default: `1`)* - Step increment between slider positions\n- `suffix` *(default: `''`)* - String appended to the displayed current value\n- `colSpan` *(default: `1`)* - Column span for both the label and slider cells\n- `data` *(required)* - Table holding the current value at key `$\u003cid\u003e`\n- `readOnly` *(default: `false`)* - Whether the slider is display-only\n- `handle` *(default: `null`)* - Cue to signal on slider confirm\n\n**Handler echo fields:**\n\n- `event.param.$echo.$valueId` - table key string, e.g. `'$mySlider'`\n- `event.param.$value` - confirmed longfloat value\n\n```xml\n\u003crun_actions ref=\"md.Options_Helper.Add_Slider\"\u003e\n  \u003cparam name=\"id\" value=\"'myThreshold'\" /\u003e\n  \u003cparam name=\"min\" value=\"0\" /\u003e\n  \u003cparam name=\"max\" value=\"1000000\" /\u003e\n  \u003cparam name=\"step\" value=\"1000\" /\u003e\n  \u003cparam name=\"text\" value=\"{1972092401, 130}\" /\u003e\n  \u003cparam name=\"suffix\" value=\"' Cr'\" /\u003e\n  \u003cparam name=\"colSpan\" value=\"12\" /\u003e\n  \u003cparam name=\"data\" value=\"@$mySettings\" /\u003e\n  \u003cparam name=\"handle\" value=\"Handle_Slider\" /\u003e\n\u003c/run_actions\u003e\n```\n\n---\n\n### Event-processing libraries\n\nThese 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.\n\n#### `Process_Dropdown_Changed` — `include_actions`\n\nReads `event.param.$echo.$valueId` and `event.param.$option.$value`, writes the selected value into `$resultTable`.\n\n```xml\n\u003ccue name=\"Handle_Dropdown\" instantiate=\"true\"\u003e\n  \u003cconditions\u003e\u003cevent_cue_signalled /\u003e\u003c/conditions\u003e\n  \u003cactions\u003e\n    \u003cset_value name=\"$resultTable\" exact=\"@$mySettings\" /\u003e\n    \u003cinclude_actions ref=\"md.Options_Helper.Process_Dropdown_Changed\" /\u003e\n    \u003cremove_value name=\"$resultTable\" /\u003e\n  \u003c/actions\u003e\n\u003c/cue\u003e\n```\n\n---\n\n#### `Process_Slider_Changed` — `include_actions`\n\nReads `event.param.$echo.$valueId` and `event.param.$value`, writes the confirmed slider value into `$resultTable`.\n\n```xml\n\u003ccue name=\"Handle_Slider\" instantiate=\"true\"\u003e\n  \u003cconditions\u003e\u003cevent_cue_signalled /\u003e\u003c/conditions\u003e\n  \u003cactions\u003e\n    \u003cset_value name=\"$resultTable\" exact=\"@$mySettings\" /\u003e\n    \u003cinclude_actions ref=\"md.Options_Helper.Process_Slider_Changed\" /\u003e\n    \u003cremove_value name=\"$resultTable\" /\u003e\n  \u003c/actions\u003e\n\u003c/cue\u003e\n```\n\n---\n\n#### `Process_Checkbox_Changed` — `include_actions`\n\nReads `event.param.$echo.$valueId` and `event.param.$checked` (int `0`/`1`), writes the checked state into `$resultTable`.\n\n```xml\n\u003ccue name=\"Handle_Checkbox\" instantiate=\"true\"\u003e\n  \u003cconditions\u003e\u003cevent_cue_signalled /\u003e\u003c/conditions\u003e\n  \u003cactions\u003e\n    \u003cset_value name=\"$resultTable\" exact=\"@$mySettings\" /\u003e\n    \u003cinclude_actions ref=\"md.Options_Helper.Process_Checkbox_Changed\" /\u003e\n    \u003cremove_value name=\"$resultTable\" /\u003e\n  \u003c/actions\u003e\n\u003c/cue\u003e\n```\n\n---\n\n## Complete Usage Example\n\n```xml\n\u003c!-- Register your menu on API reload --\u003e\n\u003ccue name=\"Register_Menu\" instantiate=\"true\"\u003e\n  \u003cconditions\u003e\n    \u003cevent_cue_signalled cue=\"md.Simple_Menu_API.Reloaded\" /\u003e\n  \u003c/conditions\u003e\n  \u003cactions\u003e\n    \u003csignal_cue_instantly cue=\"md.Simple_Menu_API.Register_Options_Menu\"\n      param=\"table[\n        $id      = 'my_mod_options',\n        $columns = 12,\n        $title   = 'My Mod Options',\n        $onOpen  = My_Menu_Open,\n      ]\" /\u003e\n  \u003c/actions\u003e\n\u003c/cue\u003e\n\n\u003c!-- Build menu content on open --\u003e\n\u003ccue name=\"My_Menu_Open\" instantiate=\"true\"\u003e\n  \u003cconditions\u003e\u003cevent_cue_signalled /\u003e\u003c/conditions\u003e\n  \u003cactions\u003e\n    \u003c!-- load your settings table into $mySettings here --\u003e\n\n    \u003cinclude_actions ref=\"md.Options_Helper.Add_Empty_Row\" /\u003e\n    \u003crun_actions ref=\"md.Options_Helper.Add_Title_Row\"\u003e\n      \u003cparam name=\"title\" value=\"'General Settings'\" /\u003e\n    \u003c/run_actions\u003e\n\n    \u003crun_actions ref=\"md.Options_Helper.Add_Checkbox\"\u003e\n      \u003cparam name=\"id\" value=\"'enabled'\" /\u003e\n      \u003cparam name=\"col\" value=\"1\" /\u003e\n      \u003cparam name=\"textColSpan\" value=\"11\" /\u003e\n      \u003cparam name=\"text\" value=\"'Enable feature'\" /\u003e\n      \u003cparam name=\"data\" value=\"@$mySettings\" /\u003e\n      \u003cparam name=\"handle\" value=\"Handle_Checkbox\" /\u003e\n    \u003c/run_actions\u003e\n\n    \u003crun_actions ref=\"md.Options_Helper.Add_Slider\"\u003e\n      \u003cparam name=\"id\" value=\"'threshold'\" /\u003e\n      \u003cparam name=\"min\" value=\"0\" /\u003e\n      \u003cparam name=\"max\" value=\"100000\" /\u003e\n      \u003cparam name=\"step\" value=\"1000\" /\u003e\n      \u003cparam name=\"text\" value=\"'Minimum threshold'\" /\u003e\n      \u003cparam name=\"suffix\" value=\"' Cr'\" /\u003e\n      \u003cparam name=\"colSpan\" value=\"12\" /\u003e\n      \u003cparam name=\"data\" value=\"@$mySettings\" /\u003e\n      \u003cparam name=\"handle\" value=\"Handle_Slider\" /\u003e\n    \u003c/run_actions\u003e\n  \u003c/actions\u003e\n\u003c/cue\u003e\n\n\u003c!-- Handlers --\u003e\n\u003ccue name=\"Handle_Checkbox\" instantiate=\"true\"\u003e\n  \u003cconditions\u003e\u003cevent_cue_signalled /\u003e\u003c/conditions\u003e\n  \u003cactions\u003e\n    \u003cset_value name=\"$resultTable\" exact=\"@$mySettings\" /\u003e\n    \u003cinclude_actions ref=\"md.Options_Helper.Process_Checkbox_Changed\" /\u003e\n    \u003cremove_value name=\"$resultTable\" /\u003e\n    \u003c!-- persist $mySettings here --\u003e\n  \u003c/actions\u003e\n\u003c/cue\u003e\n\n\u003ccue name=\"Handle_Slider\" instantiate=\"true\"\u003e\n  \u003cconditions\u003e\u003cevent_cue_signalled /\u003e\u003c/conditions\u003e\n  \u003cactions\u003e\n    \u003cset_value name=\"$resultTable\" exact=\"@$mySettings\" /\u003e\n    \u003cinclude_actions ref=\"md.Options_Helper.Process_Slider_Changed\" /\u003e\n    \u003cremove_value name=\"$resultTable\" /\u003e\n    \u003c!-- persist $mySettings here --\u003e\n  \u003c/actions\u003e\n\u003c/cue\u003e\n```\n\n---\n\n## Credits\n\n- **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)\n- *\"X4: Foundations\"* is a trademark of [Egosoft](https://www.egosoft.com).\n\n## Acknowledgements\n\n- [EGOSOFT](https://www.egosoft.com) - for the X series.\n- [SirNukes](https://next.nexusmods.com/profile/sirnukes?gameId=2659) - for the `Mod Support APIs` that power the UI hooks.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchemodun%2Fx4-optionshelper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchemodun%2Fx4-optionshelper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchemodun%2Fx4-optionshelper/lists"}