@datamoc/mw_games 0.14.0 → 0.16.0

package/dist/two-d/ui/Meter.d.ts

@@ -0,0 +1,76 @@
+import { Container } from 'pixi.js';
+import type { Texture2D } from '../render/Types2D.ts';
+export interface MeterOptions {
+    /** total icons; fractional counts floor, below 1 becomes 1 */
+    count: number;
+    /** filled icons, fractions allowed (a half heart is 0.5); defaults to full */
+    value?: number;
+    /** icon diameter in pixels */
+    size?: number;
+    /** gap between icons in pixels */
+    gap?: number;
+    /** the filled icon's art; `emptyTexture` must come with it, or neither */
+    filledTexture?: Texture2D;
+    /** the empty icon's art; `filledTexture` must come with it, or neither */
+    emptyTexture?: Texture2D;
+    /** filled colour in flat mode; tints `filledTexture` too, when both are given */
+    color?: number;
+    /** empty colour in flat mode; the theme's panel fill when omitted */
+    emptyColor?: number;
+}
+/**
+ * A discrete meter: N icons with a value filled, the Zelda heart row or star rating to
+ * `Bar`'s continuous fill. Fractions clip mid-icon through a mask, so halves (or any
+ * fraction) work identically for flat shapes and game-supplied textures, with no extra
+ * half-state art to author.
+ *
+ * Flat icons are theme-drawn pips; game art arrives as a `filledTexture`/`emptyTexture`
+ * pair, which must come together - one without the other throws, since a half-drawn
+ * meter would only guess. Colour follows the theme the way `Bar` does unless the game
+ * passes its own, and a passed colour survives later theme changes.
+ *
+ * @example
+ * ```ts
+ * import { Meter } from '@datamoc/mw_games/two-d/ui';
+ *
+ * const hearts = new Meter({ count: 5, value: 3 });
+ *
+ * hearts.setValue(2.5); // down to two and a half hearts
+ * console.log(hearts.value); // 2.5
+ * ```
+ */
+export declare class Meter extends Container {
+    private emptyLayer;
+    private filledLayer;
+    private maskShape;
+    private count_;
+    private size_;
+    private gap_;
+    private value_;
+    private explicitColor;
+    private fillColor;
+    private emptyColor_?;
+    private readonly filledTexture?;
+    private readonly emptyTexture?;
+    private readonly themeListener;
+    constructor(options: MeterOptions);
+    /** filled icons, fractions included */
+    get value(): number;
+    /** total icons */
+    get count(): number;
+    /** the resolved filled colour: the explicit one, or the theme's highlight */
+    get color(): number;
+    setValue(value: number, count?: number): void;
+    /**
+     * Recolours the fill at runtime, counting as explicit exactly as passing `color` does,
+     * so a later theme change cannot throw the game's own colour away.
+     */
+    setColor(color: number): void;
+    resize(size: number, gap?: number): void;
+    private get totalWidth();
+    private iconX;
+    private draw;
+    private icon;
+    destroy(options?: Parameters<Container['destroy']>[0]): void;
+}
+//# sourceMappingURL=Meter.d.ts.map

package/dist/two-d/ui/Meter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Meter.d.ts","sourceRoot":"","sources":["../../../src/two-d/ui/Meter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAoB,MAAM,SAAS,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,MAAM,WAAW,YAAY;IAC5B,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,0EAA0E;IAC1E,aAAa,CAAC,EAAE,SAAS,CAAC;IAC1B,0EAA0E;IAC1E,YAAY,CAAC,EAAE,SAAS,CAAC;IAEzB,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,KAAM,SAAQ,SAAS;IACnC,OAAO,CAAC,UAAU,CAAmB;IACrC,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,SAAS,CAAkB;IAEnC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAU;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAC,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAY;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAY;IAE1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IAEnD,YAAY,OAAO,EAAE,YAAY,EAuBhC;IAED,uCAAuC;IACvC,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,kBAAkB;IAClB,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,6EAA6E;IAC7E,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAoB,GAAG,IAAI,CAIzD;IAED;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAI5B;IAED,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAkB,GAAG,IAAI,CAIlD;IAED,OAAO,KAAK,UAAU,GAErB;IAED,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,IAAI;IAkBZ,OAAO,CAAC,IAAI;IAeH,OAAO,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAGpE;CACD"}

package/dist/two-d/ui/Meter.js

@@ -0,0 +1,134 @@
+import { Container, Graphics, Sprite } from 'pixi.js';
+import { theme, themeChanged } from './theme.js';
+/**
+ * A discrete meter: N icons with a value filled, the Zelda heart row or star rating to
+ * `Bar`'s continuous fill. Fractions clip mid-icon through a mask, so halves (or any
+ * fraction) work identically for flat shapes and game-supplied textures, with no extra
+ * half-state art to author.
+ *
+ * Flat icons are theme-drawn pips; game art arrives as a `filledTexture`/`emptyTexture`
+ * pair, which must come together - one without the other throws, since a half-drawn
+ * meter would only guess. Colour follows the theme the way `Bar` does unless the game
+ * passes its own, and a passed colour survives later theme changes.
+ *
+ * @example
+ * ```ts
+ * import { Meter } from '@datamoc/mw_games/two-d/ui';
+ *
+ * const hearts = new Meter({ count: 5, value: 3 });
+ *
+ * hearts.setValue(2.5); // down to two and a half hearts
+ * console.log(hearts.value); // 2.5
+ * ```
+ */
+export class Meter extends Container {
+    constructor(options) {
+        super();
+        this.emptyLayer = new Container();
+        this.filledLayer = new Container();
+        this.maskShape = new Graphics();
+        this.themeListener = () => this.draw();
+        if ((options.filledTexture === undefined) !== (options.emptyTexture === undefined)) {
+            throw new Error('a Meter takes filledTexture and emptyTexture together, or neither');
+        }
+        this.count_ = normalizeCount(options.count);
+        this.size_ = options.size ?? 16;
+        this.gap_ = options.gap ?? 4;
+        this.value_ = clampValue(options.value ?? this.count_, this.count_);
+        this.explicitColor = options.color !== undefined;
+        this.fillColor = options.color ?? theme().color.textHighlight;
+        this.emptyColor_ = options.emptyColor;
+        this.filledTexture = options.filledTexture;
+        this.emptyTexture = options.emptyTexture;
+        this.addChild(this.emptyLayer);
+        this.addChild(this.filledLayer);
+        this.addChild(this.maskShape);
+        this.filledLayer.mask = this.maskShape;
+        this.draw();
+        themeChanged.add(this.themeListener);
+    }
+    /** filled icons, fractions included */
+    get value() {
+        return this.value_;
+    }
+    /** total icons */
+    get count() {
+        return this.count_;
+    }
+    /** the resolved filled colour: the explicit one, or the theme's highlight */
+    get color() {
+        return this.fillColor;
+    }
+    setValue(value, count = this.count_) {
+        this.count_ = normalizeCount(count);
+        this.value_ = clampValue(value, this.count_);
+        this.draw();
+    }
+    /**
+     * Recolours the fill at runtime, counting as explicit exactly as passing `color` does,
+     * so a later theme change cannot throw the game's own colour away.
+     */
+    setColor(color) {
+        this.explicitColor = true;
+        this.fillColor = color;
+        this.draw();
+    }
+    resize(size, gap = this.gap_) {
+        this.size_ = size;
+        this.gap_ = gap;
+        this.draw();
+    }
+    get totalWidth() {
+        return this.count_ * this.size_ + (this.count_ - 1) * this.gap_;
+    }
+    iconX(index) {
+        const x = index * (this.size_ + this.gap_);
+        return theme().direction === 'rtl' ? this.totalWidth - x - this.size_ : x;
+    }
+    draw() {
+        const t = theme();
+        if (!this.explicitColor)
+            this.fillColor = t.color.textHighlight;
+        const empty = this.emptyColor_ ?? t.color.panelFill;
+        this.emptyLayer.removeChildren();
+        this.filledLayer.removeChildren();
+        for (let i = 0; i < this.count_; i++) {
+            const x = this.iconX(i);
+            this.emptyLayer.addChild(this.icon(x, empty, this.emptyTexture, false));
+            this.filledLayer.addChild(this.icon(x, this.fillColor, this.filledTexture, true));
+        }
+        const filledWidth = this.totalWidth * (this.count_ > 0 ? this.value_ / this.count_ : 0);
+        const maskX = t.direction === 'rtl' ? this.totalWidth - filledWidth : 0;
+        this.maskShape.clear().rect(maskX, 0, filledWidth, this.size_).fill({ color: 0xffffff });
+    }
+    icon(x, color, texture, tint) {
+        if (texture) {
+            const sprite = new Sprite(texture);
+            sprite.x = x;
+            sprite.width = this.size_;
+            sprite.height = this.size_;
+            if (tint && this.explicitColor)
+                sprite.tint = color;
+            return sprite;
+        }
+        const shape = new Graphics();
+        const radius = this.size_ / 2;
+        shape.circle(x + radius, radius, radius).fill({ color });
+        return shape;
+    }
+    destroy(options) {
+        themeChanged.remove(this.themeListener);
+        super.destroy(options);
+    }
+}
+function clampValue(value, count) {
+    if (!Number.isFinite(value))
+        return count;
+    return Math.max(0, Math.min(count, value));
+}
+function normalizeCount(count) {
+    if (!Number.isFinite(count))
+        return 1;
+    return Math.max(1, Math.floor(count));
+}
+//# sourceMappingURL=Meter.js.map

package/dist/two-d/ui/Meter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Meter.js","sourceRoot":"","sources":["../../../src/two-d/ui/Meter.ts"],"names":[],"mappings":"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"}

package/dist/two-d/ui/SettingsScreen.d.ts

@@ -0,0 +1,112 @@
+import { Container } from 'pixi.js';
+import type { Action } from '../../core/Input.ts';
+import { Settings } from '../../core/Settings.ts';
+/** one game-defined row over the `Settings` custom bag (`hints`, `violence`, ...) */
+export type SettingsCustomRow = {
+    kind: 'boolean';
+    key: string;
+    label: string;
+} | {
+    kind: 'number';
+    key: string;
+    label: string;
+    min: number;
+    max: number;
+    step?: number;
+} | {
+    kind: 'choice';
+    key: string;
+    label: string;
+    options: readonly [string, ...string[]];
+};
+export interface SettingsScreenOptions {
+    settings: Settings;
+    width?: number;
+    rowHeight?: number;
+    /** English defaults; a game mapping these to translated strings overrides them */
+    labels?: {
+        music?: string;
+        sfx?: string;
+        muted?: string;
+        zoom?: string;
+        controls?: string;
+        reset?: string;
+        rebindHint?: string;
+    };
+    zoomMin?: number;
+    zoomMax?: number;
+    zoomStep?: number;
+    /** game-defined rows appended after zoom, in order */
+    custom?: readonly SettingsCustomRow[];
+    /** which actions the controls page lists; the stored binding keys when omitted */
+    actions?: readonly Action[];
+    /** passed through to the controls page's `RebindScreen` */
+    onConflict?: (key: string, action: Action, previousOwners: readonly Action[]) => boolean;
+}
+/**
+ * A ready-made settings screen over `core.Settings`: music and sound-effect sliders,
+ * a mute checkbox, a zoom slider, one row per game-defined `custom` descriptor, a
+ * controls page (`RebindScreen`), and a reset-to-defaults row. Every change writes
+ * straight through to the `Settings` it was given, so there is no apply step and no
+ * second persistence mechanism.
+ *
+ * Bindings captured on the controls page reach `Input` directly, bypassing `Settings`;
+ * leaving the page writes them back into it, so a rebind survives a restart. `cancel` on
+ * the main page is left to the caller (a `Window` closes, typically), reported as `false`.
+ *
+ * @example
+ * ```ts
+ * import { Settings } from '@datamoc/mw_games/core';
+ * import { SettingsScreen } from '@datamoc/mw_games/two-d/ui';
+ *
+ * const settings = new Settings({ namespace: 'my-game' });
+ * const screen = new SettingsScreen({
+ * 	settings,
+ * 	custom: [{ kind: 'boolean', key: 'hints', label: 'Hints' }],
+ * });
+ *
+ * screen.handleAction('down');
+ * console.log(screen.selectedRow); // 'sfx'
+ * ```
+ */
+export declare class SettingsScreen extends Container {
+    private readonly settings;
+    private readonly width_;
+    private readonly rowHeight;
+    private readonly labels;
+    private readonly zoomMin;
+    private readonly zoomMax;
+    private readonly zoomStep;
+    private readonly customRows;
+    private readonly actionsOption;
+    private readonly onConflict;
+    private readonly highlight;
+    private readonly main;
+    private readonly rebindLayer;
+    private rows;
+    private selected;
+    private rebind;
+    private readonly themeListener;
+    constructor(options: SettingsScreenOptions);
+    /** the selected main-page row: 'music', 'sfx', 'muted', 'zoom', `custom:${key}`, 'controls' or 'reset' */
+    get selectedRow(): string;
+    /** true while the controls (rebind) page is open */
+    get isRebinding(): boolean;
+    /** @returns true when the action was used; `cancel` on the main page returns false */
+    handleAction(action: Action): boolean;
+    /** re-reads every row from `Settings`, for a screen kept alive while settings change elsewhere */
+    refresh(): void;
+    private select;
+    private drawHighlight;
+    private buildMain;
+    private addSliderRow;
+    private readSlider;
+    private addToggleRow;
+    private readToggle;
+    private addCustomRow;
+    private addActionRow;
+    private openRebind;
+    private closeRebind;
+    destroy(options?: Parameters<Container['destroy']>[0]): void;
+}
+//# sourceMappingURL=SettingsScreen.d.ts.map

package/dist/two-d/ui/SettingsScreen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SettingsScreen.d.ts","sourceRoot":"","sources":["../../../src/two-d/ui/SettingsScreen.ts"],"names":[],"mappings":"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"}

package/dist/two-d/ui/SettingsScreen.js

@@ -0,0 +1,338 @@
+import { Container, Graphics } from 'pixi.js';
+import * as Input from '../../core/Input.js';
+import { Settings } from '../../core/Settings.js';
+import { Button } from './Button.js';
+import { Checkbox } from './Checkbox.js';
+import { Label } from './Label.js';
+import { RebindScreen } from './RebindScreen.js';
+import { Slider } from './Slider.js';
+import { Spinner } from './Spinner.js';
+import { theme, themeChanged } from './theme.js';
+/**
+ * A ready-made settings screen over `core.Settings`: music and sound-effect sliders,
+ * a mute checkbox, a zoom slider, one row per game-defined `custom` descriptor, a
+ * controls page (`RebindScreen`), and a reset-to-defaults row. Every change writes
+ * straight through to the `Settings` it was given, so there is no apply step and no
+ * second persistence mechanism.
+ *
+ * Bindings captured on the controls page reach `Input` directly, bypassing `Settings`;
+ * leaving the page writes them back into it, so a rebind survives a restart. `cancel` on
+ * the main page is left to the caller (a `Window` closes, typically), reported as `false`.
+ *
+ * @example
+ * ```ts
+ * import { Settings } from '@datamoc/mw_games/core';
+ * import { SettingsScreen } from '@datamoc/mw_games/two-d/ui';
+ *
+ * const settings = new Settings({ namespace: 'my-game' });
+ * const screen = new SettingsScreen({
+ * 	settings,
+ * 	custom: [{ kind: 'boolean', key: 'hints', label: 'Hints' }],
+ * });
+ *
+ * screen.handleAction('down');
+ * console.log(screen.selectedRow); // 'sfx'
+ * ```
+ */
+export class SettingsScreen extends Container {
+    constructor(options) {
+        super();
+        this.highlight = new Graphics();
+        this.main = new Container();
+        this.rebindLayer = new Container();
+        this.rows = [];
+        this.selected = 0;
+        this.rebind = null;
+        this.themeListener = () => this.drawHighlight();
+        this.settings = options.settings;
+        this.width_ = options.width ?? 320;
+        this.rowHeight = options.rowHeight ?? 36;
+        this.labels = {
+            music: 'Music',
+            sfx: 'Sound effects',
+            muted: 'Mute',
+            zoom: 'Zoom',
+            controls: 'Controls...',
+            reset: 'Reset to defaults',
+            rebindHint: 'Keys (cancel: back)',
+            ...options.labels,
+        };
+        this.zoomMin = options.zoomMin ?? 0.5;
+        this.zoomMax = options.zoomMax ?? 4;
+        this.zoomStep = options.zoomStep ?? 0.25;
+        this.customRows = options.custom ?? [];
+        this.actionsOption = options.actions;
+        this.onConflict = options.onConflict;
+        this.addChild(this.highlight);
+        this.addChild(this.main);
+        this.addChild(this.rebindLayer);
+        this.rebindLayer.visible = false;
+        this.buildMain();
+        this.refresh();
+        this.drawHighlight();
+        themeChanged.add(this.themeListener);
+    }
+    /** the selected main-page row: 'music', 'sfx', 'muted', 'zoom', `custom:${key}`, 'controls' or 'reset' */
+    get selectedRow() {
+        return this.rows[this.selected]?.id ?? '';
+    }
+    /** true while the controls (rebind) page is open */
+    get isRebinding() {
+        return this.rebind !== null;
+    }
+    /** @returns true when the action was used; `cancel` on the main page returns false */
+    handleAction(action) {
+        if (this.rebind) {
+            if (action === 'cancel' && !this.rebind.isCapturing) {
+                this.closeRebind();
+                return true;
+            }
+            return this.rebind.handleAction(action);
+        }
+        const row = this.rows[this.selected];
+        if (!row)
+            return false;
+        switch (action) {
+            case 'up':
+                this.select((this.selected + this.rows.length - 1) % this.rows.length);
+                return true;
+            case 'down':
+                this.select((this.selected + 1) % this.rows.length);
+                return true;
+            case 'left':
+                row.adjust(-1);
+                return true;
+            case 'right':
+                row.adjust(1);
+                return true;
+            case 'confirm':
+                row.activate();
+                return true;
+            default:
+                return false;
+        }
+    }
+    /** re-reads every row from `Settings`, for a screen kept alive while settings change elsewhere */
+    refresh() {
+        for (const row of this.rows)
+            row.refresh();
+    }
+    select(index) {
+        this.selected = index;
+        this.drawHighlight();
+    }
+    drawHighlight() {
+        if (this.rows.length === 0) {
+            this.highlight.clear();
+            return;
+        }
+        this.highlight
+            .clear()
+            .rect(0, this.selected * this.rowHeight, this.width_, this.rowHeight)
+            .fill({ color: theme().color.selection });
+    }
+    buildMain() {
+        const current = this.settings.current;
+        this.addSliderRow('music', this.labels.music, 0, 100, 1, 10, Math.round(current.musicVolume * 100), (v) => this.settings.setMusicVolume(v / 100));
+        this.addSliderRow('sfx', this.labels.sfx, 0, 100, 1, 10, Math.round(current.sfxVolume * 100), (v) => this.settings.setSfxVolume(v / 100));
+        this.addToggleRow('muted', this.labels.muted, current.muted, (v) => this.settings.setMuted(v));
+        this.addSliderRow('zoom', this.labels.zoom, this.zoomMin, this.zoomMax, this.zoomStep, this.zoomStep, current.zoom, (v) => this.settings.setZoom(v));
+        for (const descriptor of this.customRows)
+            this.addCustomRow(descriptor);
+        this.addActionRow('controls', this.labels.controls, () => this.openRebind());
+        this.addActionRow('reset', this.labels.reset, () => {
+            this.settings.reset();
+            this.refresh();
+        });
+        this.main.children.forEach((child, index) => {
+            child.y = index * this.rowHeight;
+        });
+    }
+    addSliderRow(id, label, min, max, step, keyStep, initial, write) {
+        const root = new Container();
+        const caption = new Label({ text: label });
+        caption.y = 10;
+        const control = new Slider({ width: 140, min, max, step, value: initial });
+        control.x = this.width_ - 148;
+        control.y = 10;
+        root.addChild(caption, control);
+        this.main.addChild(root);
+        const show = () => {
+            caption.setText(`${label}: ${control.value}`);
+        };
+        show();
+        control.onChange.add((value) => {
+            write(value);
+            show();
+        });
+        this.rows.push({
+            id,
+            root,
+            adjust: (delta) => control.setValue(control.value + delta * keyStep),
+            activate: () => { },
+            refresh: () => {
+                control.setValue(this.readSlider(id));
+                show();
+            },
+        });
+    }
+    readSlider(id) {
+        const current = this.settings.current;
+        switch (id) {
+            case 'music':
+                return Math.round(current.musicVolume * 100);
+            case 'sfx':
+                return Math.round(current.sfxVolume * 100);
+            case 'zoom':
+                return current.zoom;
+            default:
+                return 0;
+        }
+    }
+    addToggleRow(id, label, initial, write) {
+        const root = new Container();
+        const caption = new Label({ text: label });
+        caption.y = 10;
+        const control = new Checkbox({ checked: initial });
+        control.x = this.width_ - 28;
+        control.y = 8;
+        root.addChild(caption, control);
+        this.main.addChild(root);
+        control.onChange.add(write);
+        this.rows.push({
+            id,
+            root,
+            adjust: () => control.toggle(),
+            activate: () => control.toggle(),
+            refresh: () => control.setChecked(this.readToggle(id)),
+        });
+    }
+    readToggle(id) {
+        if (id === 'muted')
+            return this.settings.current.muted;
+        return this.settings.getCustom(id.slice('custom:'.length), false) === true;
+    }
+    addCustomRow(descriptor) {
+        const id = `custom:${descriptor.key}`;
+        if (descriptor.kind === 'boolean') {
+            const stored = this.settings.getCustom(descriptor.key, false);
+            this.addToggleRow(id, descriptor.label, stored === true, (v) => this.settings.setCustom(descriptor.key, v));
+        }
+        else if (descriptor.kind === 'number') {
+            const stored = this.settings.getCustom(descriptor.key, descriptor.min);
+            const initial = typeof stored === 'number' ? stored : descriptor.min;
+            const grid = descriptor.step ?? 0;
+            const keyStep = grid > 0 ? grid : (descriptor.max - descriptor.min) / 20;
+            const root = new Container();
+            const caption = new Label({ text: descriptor.label });
+            caption.y = 10;
+            const control = new Slider({
+                width: 140,
+                min: descriptor.min,
+                max: descriptor.max,
+                step: descriptor.step ?? 0,
+                value: initial,
+            });
+            control.x = this.width_ - 148;
+            control.y = 10;
+            root.addChild(caption, control);
+            this.main.addChild(root);
+            const show = () => {
+                caption.setText(`${descriptor.label}: ${control.value}`);
+            };
+            show();
+            control.onChange.add((value) => {
+                this.settings.setCustom(descriptor.key, value);
+                show();
+            });
+            this.rows.push({
+                id,
+                root,
+                adjust: (delta) => control.setValue(control.value + delta * keyStep),
+                activate: () => { },
+                refresh: () => {
+                    const value = this.settings.getCustom(descriptor.key, descriptor.min);
+                    control.setValue(typeof value === 'number' ? value : descriptor.min);
+                    show();
+                },
+            });
+        }
+        else {
+            const options = descriptor.options;
+            const root = new Container();
+            const caption = new Label({ text: descriptor.label });
+            caption.y = 10;
+            const control = new Spinner({ min: 0, max: options.length - 1, step: 1, value: 0, wrap: true });
+            control.x = this.width_ - 32;
+            control.y = 2;
+            root.addChild(caption, control);
+            this.main.addChild(root);
+            const indexOf = (value) => {
+                const index = typeof value === 'string' ? options.indexOf(value) : -1;
+                return index >= 0 ? index : 0;
+            };
+            const show = () => {
+                caption.setText(`${descriptor.label}: ${options[control.value]}`);
+            };
+            control.setValue(indexOf(this.settings.getCustom(descriptor.key, options[0])));
+            show();
+            control.onChange.add((index) => {
+                this.settings.setCustom(descriptor.key, options[index]);
+                show();
+            });
+            this.rows.push({
+                id,
+                root,
+                adjust: (delta) => (delta > 0 ? control.increment() : control.decrement()),
+                activate: () => control.increment(),
+                refresh: () => {
+                    control.setValue(indexOf(this.settings.getCustom(descriptor.key, options[0])));
+                    show();
+                },
+            });
+        }
+    }
+    addActionRow(id, label, run) {
+        const root = new Container();
+        const control = new Button({ width: this.width_ - 16, height: 28, text: label, onClick: run });
+        control.x = 8;
+        control.y = 4;
+        root.addChild(control);
+        this.main.addChild(root);
+        this.rows.push({ id, root, adjust: () => { }, activate: run, refresh: () => { } });
+    }
+    openRebind() {
+        const actions = this.actionsOption ?? Object.keys(this.settings.current.bindings);
+        const hint = new Label({ text: this.labels.rebindHint });
+        const list = new RebindScreen({
+            width: this.width_,
+            height: Math.max(1, actions.length) * this.rowHeight,
+            actions,
+            onConflict: this.onConflict,
+        });
+        hint.y = 0;
+        list.y = this.rowHeight;
+        this.rebindLayer.addChild(hint, list);
+        this.rebindLayer.visible = true;
+        this.main.visible = false;
+        this.highlight.visible = false;
+        this.rebind = list;
+    }
+    closeRebind() {
+        //captures bypass Settings straight into Input, so sync them back on exit
+        this.settings.setBindings(Input.exportBindings());
+        this.rebindLayer.removeChildren();
+        this.rebind?.destroy();
+        this.rebind = null;
+        this.rebindLayer.visible = false;
+        this.main.visible = true;
+        this.highlight.visible = true;
+    }
+    destroy(options) {
+        themeChanged.remove(this.themeListener);
+        this.rebind?.destroy();
+        this.rebind = null;
+        super.destroy(options);
+    }
+}
+//# sourceMappingURL=SettingsScreen.js.map