🤖 Merge PR DefinitelyTyped#74033 [Gimloader] Document settings api by @TheLazySquid

Author: TheLazySquid

types/gimloader/gimloader-tests.ts

@@ -76,3 +76,124 @@ device.state; // $ExpectType Record<string, any>
 worldManager.physics.bodies.staticBodies; // $ExpectType Set<string>
 worldManager.devices.interactives.findClosestInteractiveDevice([], 0, 0); // $ExpectType Device | undefined
 worldManager.inGameTerrainBuilder.clearPreviewLayer();
+
+api.settings.something;
+api.settings.somethingElse;
+api.settings.something = 123;
+api.settings.something = "abc";
+api.settings.something = {};
+api.settings.listen("someSetting", (val: any) => {});
+api.settings.create([
+    {
+        type: "group",
+        title: "Group",
+        settings: [
+            {
+                type: "toggle",
+                id: "toggle1",
+                title: "A Toggle",
+                description: "Some Toggle",
+            },
+        ],
+    },
+    {
+        type: "color",
+        id: "color1",
+        title: "A Color",
+        rgba: true,
+        default: "rgba(255, 0, 0, 1)",
+        onChange: (val: string) => {},
+    },
+    {
+        type: "dropdown",
+        id: "dropdown1",
+        options: [
+            { label: "Option 1", value: "option1" },
+            { label: "Option 2", value: "option2" },
+        ],
+        title: "A Dropdown",
+        default: "option1",
+        onChange: (value: string) => {},
+    },
+    {
+        type: "multiselect",
+        id: "multiselect1",
+        options: [
+            { label: "Option A", value: "optionA" },
+            { label: "Option B", value: "optionB" },
+            { label: "Option C", value: "optionC" },
+        ],
+        title: "A Multiselect",
+        default: ["optionA", "optionC"],
+        onChange: (value: string[]) => {},
+    },
+    {
+        type: "number",
+        id: "number1",
+        title: "A Number",
+        min: 5,
+        max: 10,
+        step: 2,
+        onChange: (value: number) => {},
+    },
+    {
+        type: "radio",
+        id: "radio1",
+        options: [
+            { label: "Option A", value: "optionA" },
+            { label: "Option B", value: "optionB" },
+            { label: "Option C", value: "optionC" },
+        ],
+        title: "A Radio",
+        default: "optionB",
+        description: "Pick one",
+        onChange: (value: string) => {},
+    },
+    {
+        type: "slider",
+        id: "slider1",
+        title: "A Slider",
+        min: 5,
+        max: 500,
+        step: 2,
+        formatter: (v: number) => v + "s",
+        ticks: [5, 100, 300, 400, 500],
+        onChange: (value: number) => {},
+    },
+    {
+        type: "text",
+        id: "text1",
+        title: "A Text",
+        placeholder: "Type",
+        maxLength: 50,
+        onChange: (value: string) => {},
+    },
+    {
+        type: "toggle",
+        id: "toggle2",
+        title: "Another Toggle",
+        default: true,
+        onChange: (value: boolean) => {},
+    },
+    {
+        type: "custom",
+        id: "custom1",
+        title: "Custom Setting",
+        default: 50,
+        render: (container: HTMLElement, value: any, update: (value: any) => void) => {
+            container.innerText = `Value is ${value}`;
+            container.onclick = () => update(value + 1);
+        },
+        onChange: (value: any) => {},
+    },
+    {
+        type: "customsection",
+        id: "customsection1",
+        default: 50,
+        render: (container: HTMLElement, value: any, update: (value: any) => void) => {
+            container.innerText = `Value is ${value}`;
+            container.onclick = () => update(value + 1);
+        },
+        onChange: (value: any) => {},
+    },
+]);

types/gimloader/index.d.ts

@@ -452,6 +452,8 @@ declare global {
                 setCanInteractThroughColliders(canInteract: boolean): void;
                 setForceDisabled(forceDisabled: boolean): void;
                 setInfo(info: any): void;
+                remove(zone: CircleShort | Rect): void;
+                onInteraction?(): void;
             }
 
             interface DeviceInput {
@@ -515,6 +517,11 @@ declare global {
                 update(): void;
             }
 
+            interface SkinSetupOptions extends SkinOptions {
+                x?: number;
+                y?: number;
+            }
+
             interface SkinOptions {
                 id: string;
                 editStyles?: Record<string, string>;
@@ -527,7 +534,7 @@ declare global {
                 scene: Scene;
                 skinId: string;
                 applyEditStyles(options: SkinOptions): void;
-                setupSkin(position: Vector): void;
+                setupSkin(position: SkinSetupOptions): void;
                 updateSkin(options: SkinOptions): void;
             }
 
@@ -1077,6 +1084,8 @@ declare global {
                 device: Device;
                 scene: Scene;
                 angle: number;
+                x: number;
+                y: number;
             } & Partial<RectShort & CircleShort & Ellipse>;
 
             interface ColliderEntry {
@@ -2110,6 +2119,118 @@ declare global {
             }
         }
 
+        type SettingsChangeCallback = (value: any, remote: boolean) => void;
+
+        interface CustomSection {
+            type: "customsection";
+            id: string;
+            default?: any;
+            onChange?: (value: any, remote: boolean) => void;
+            render: (
+                container: HTMLElement,
+                currentValue: any,
+                onChange: (newValue: any) => void,
+                // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
+            ) => (() => void) | void;
+        }
+
+        interface CustomSetting extends BaseSetting<any> {
+            type: "custom";
+            // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
+            render: (container: HTMLElement, currentValue: any, update: (newValue: any) => void) => (() => void) | void;
+        }
+
+        interface ColorSetting extends BaseSetting<string> {
+            type: "color";
+            rgba?: boolean;
+        }
+
+        interface RadioSetting extends BaseSetting<string> {
+            type: "radio";
+            options: {
+                label: string;
+                value: string;
+            }[];
+        }
+
+        interface SliderSetting extends BaseSetting<number> {
+            type: "slider";
+            min: number;
+            max: number;
+            step?: number;
+            ticks?: number[];
+            formatter?: (value: number) => string;
+        }
+
+        interface TextSetting extends BaseSetting<string> {
+            type: "text";
+            placeholder?: string;
+            maxLength?: number;
+        }
+
+        interface ToggleSetting extends BaseSetting<boolean> {
+            type: "toggle";
+        }
+
+        interface NumberSetting extends BaseSetting<number> {
+            type: "number";
+            min?: number;
+            max?: number;
+            step?: number;
+        }
+
+        interface MultiselectSetting extends BaseSetting<string[]> {
+            type: "multiselect";
+            options: {
+                label: string;
+                value: string;
+            }[];
+        }
+
+        interface BaseSetting<T> {
+            id: string;
+            default?: T;
+            title: string;
+            description?: string;
+            onChange?: (value: T, remote: boolean) => void;
+        }
+
+        interface DropdownSetting extends BaseSetting<string> {
+            type: "dropdown";
+            options: {
+                label: string;
+                value: string;
+            }[];
+            allowNone?: boolean;
+        }
+
+        type PluginSetting =
+            | DropdownSetting
+            | MultiselectSetting
+            | NumberSetting
+            | ToggleSetting
+            | TextSetting
+            | SliderSetting
+            | RadioSetting
+            | ColorSetting
+            | CustomSetting
+            | CustomSection;
+
+        interface SettingGroup {
+            type: "group";
+            title: string;
+            settings: PluginSetting[];
+        }
+
+        type PluginSettingsDescription = (PluginSetting | SettingGroup)[];
+
+        interface SettingsMethods {
+            create: (description: PluginSettingsDescription) => void;
+            listen: (key: string, callback: SettingsChangeCallback) => () => void;
+        }
+
+        type PluginSettings = SettingsMethods & Record<string, any>;
+
         class PluginsApi {
             /** A list of all the plugins installed */
             get list(): string[];
@@ -2128,6 +2249,7 @@ declare global {
                 needsLib: string[];
                 optionalLib: string[];
                 syncEval: string;
+                deprecated: string | null;
                 gamemode: string[];
                 hasSettings: string;
             };
@@ -2160,6 +2282,7 @@ declare global {
                 needsLib: string[];
                 optionalLib: string[];
                 syncEval: string;
+                deprecated: string | null;
                 gamemode: string[];
                 hasSettings: string;
             };
@@ -2653,6 +2776,8 @@ declare global {
             storage: Readonly<ScopedStorageApi>;
             /** Functions for intercepting the arguments and return values of functions */
             patcher: Readonly<ScopedPatcherApi>;
+            /** A utility for creating persistent settings menus, only available to plugins */
+            settings: PluginSettings;
             /** Methods for getting info on libraries */
             libs: Readonly<LibsApi>;
             /** Gets the exported values of a library */

types/gimloader/package.json

@@ -1,7 +1,7 @@
 {
     "private": true,
     "name": "@types/gimloader",
-    "version": "1.8.9999",
+    "version": "1.9.9999",
     "nonNpm": "conflict",
     "nonNpmDescription": "Types for the Gimloader global variables",
     "projects": [