@antha/input 0.17.0 → 0.19.0

package/dist/bindings/antha-menu-state.mod.d.ts

@@ -0,0 +1,62 @@
+import { type AnthaReadRawInputModState } from '../raw-inputs/antha-read-raw-input.mod.js';
+import { type MenuNavModState } from './antha-menu-nav.mod.js';
+/**
+ * Menu navigation state whose return path lists parent menus from the outermost to the nearest.
+ *
+ * @category Internal
+ */
+export type AnthaMenuState<MenuKey extends string = string> = {
+    activeMenu: MenuKey | undefined;
+    returnTo: MenuKey[];
+};
+/**
+ * State consumed or updated by {@link createAnthaMenuStateMod}.
+ *
+ * @category Internal
+ */
+export type AnthaMenuStateModState<MenuKey extends string = string> = MenuNavModState & AnthaReadRawInputModState & {
+    menuState: AnthaMenuState<MenuKey> | undefined;
+};
+/**
+ * Returns to the nearest parent menu and removes it from the path, or closes menu mode when the
+ * path is empty.
+ *
+ * @category Internal
+ */
+export declare function getAnthaMenuReturnState<MenuKey extends string>(currentState: Readonly<AnthaMenuState<MenuKey>> | undefined): AnthaMenuState<MenuKey>;
+/**
+ * Resolves pause and back inputs into a menu-state transition.
+ *
+ * @category Internal
+ */
+export declare function getAnthaMenuStateForNavigation<MenuKey extends string>({ menuExitWasTriggered, menuState, openPauseMenuWasTriggered, pauseMenu, }: Readonly<{
+    menuExitWasTriggered: boolean;
+    menuState: Readonly<AnthaMenuState<MenuKey>> | undefined;
+    openPauseMenuWasTriggered: boolean;
+    pauseMenu: MenuKey;
+}>): AnthaMenuState<MenuKey> | undefined;
+/**
+ * Switches the raw-input consumer and menu-navigation state on pause/back inputs. Add this before
+ * `createAnthaMenuNavMod` so navigation sees the updated `isInMenu` value.
+ *
+ * @category Pre-Built Mods
+ */
+export declare function createAnthaMenuStateMod<MenuKey extends string = string, InputConsumer extends string = string>({ gameInputConsumerName, menuInputConsumerName, pauseMenuKey, }: Readonly<{
+    /**
+     * The name assigned to inputs consumed by the game so that they don't get consumed by menus at
+     * the same time.
+     */
+    gameInputConsumerName: NoInfer<InputConsumer>;
+    /**
+     * The name assigned to inputs consumed by menus so that they don't get consumed by the game at
+     * the same time.
+     */
+    menuInputConsumerName: NoInfer<InputConsumer>;
+    pauseMenuKey: NoInfer<MenuKey>;
+}>): import("@antha/engine").AnthaMod<NoInfer<AnthaMenuStateModState<NoInfer<MenuKey>>>>;
+/**
+ * The mod created by {@link createAnthaMenuStateMod}.
+ *
+ * @category Internal
+ */
+export type AnthaMenuStateMod = ReturnType<typeof createAnthaMenuStateMod>;

package/dist/bindings/antha-menu-state.mod.js

@@ -0,0 +1,86 @@
+import { defineAnthaMod } from '@antha/engine';
+import { check } from '@augment-vir/assert';
+import { getObjectTypedEntries } from '@augment-vir/common';
+import { isPlayerMenuNavigationAllowed, MenuNavBinding, } from './antha-menu-nav.mod.js';
+/**
+ * Returns to the nearest parent menu and removes it from the path, or closes menu mode when the
+ * path is empty.
+ *
+ * @category Internal
+ */
+export function getAnthaMenuReturnState(currentState) {
+    return {
+        activeMenu: currentState?.returnTo.at(-1),
+        returnTo: currentState?.returnTo.slice(0, -1) || [],
+    };
+}
+/**
+ * Resolves pause and back inputs into a menu-state transition.
+ *
+ * @category Internal
+ */
+export function getAnthaMenuStateForNavigation({ menuExitWasTriggered, menuState, openPauseMenuWasTriggered, pauseMenu, }) {
+    const activeMenu = menuState?.activeMenu;
+    if (!check.isDefined(activeMenu)) {
+        return openPauseMenuWasTriggered
+            ? {
+                activeMenu: pauseMenu,
+                returnTo: [],
+            }
+            : undefined;
+    }
+    return openPauseMenuWasTriggered || menuExitWasTriggered
+        ? getAnthaMenuReturnState(menuState)
+        : undefined;
+}
+/**
+ * Switches the raw-input consumer and menu-navigation state on pause/back inputs. Add this before
+ * `createAnthaMenuNavMod` so navigation sees the updated `isInMenu` value.
+ *
+ * @category Pre-Built Mods
+ */
+export function createAnthaMenuStateMod({ gameInputConsumerName, menuInputConsumerName, pauseMenuKey, }) {
+    return defineAnthaMod({
+        modName: 'antha-menu-state',
+        execute({ state }) {
+            const nextMenuState = state.activeBindings
+                ? getObjectTypedEntries(state.activeBindings)
+                    .map(([playerPosition, playerActiveBindings,]) => {
+                    if (!isPlayerMenuNavigationAllowed({
+                        allowedPlayerMenuNavigation: state.allowedPlayerMenuNavigation,
+                        playerPosition,
+                    })) {
+                        return undefined;
+                    }
+                    const openPauseMenuBinding = playerActiveBindings[MenuNavBinding.OpenPauseMenu];
+                    const menuExitBinding = playerActiveBindings[MenuNavBinding.MenuExit];
+                    const nextMenuState = getAnthaMenuStateForNavigation({
+                        menuExitWasTriggered: !!menuExitBinding && !menuExitBinding.actCount,
+                        menuState: state.menuState,
+                        openPauseMenuWasTriggered: !!openPauseMenuBinding && !openPauseMenuBinding.actCount,
+                        pauseMenu: pauseMenuKey,
+                    });
+                    if (!nextMenuState) {
+                        return undefined;
+                    }
+                    [
+                        openPauseMenuBinding,
+                        menuExitBinding,
+                    ].forEach((menuBinding) => {
+                        if (menuBinding && !menuBinding.actCount) {
+                            menuBinding.actCount = 1;
+                            menuBinding.lastActDuration = menuBinding.holdDuration;
+                        }
+                    });
+                    return nextMenuState;
+                })
+                    .find(check.isDefined)
+                : undefined;
+            if (nextMenuState) {
+                state.menuState = nextMenuState;
+            }
+            state.isInMenu = check.isDefined(state.menuState?.activeMenu);
+            state.rawInputConsumer = state.isInMenu ? menuInputConsumerName : gameInputConsumerName;
+        },
+    });
+}

package/dist/bindings/directional-input.d.ts

@@ -0,0 +1,40 @@
+import { type ActiveBindings } from './player-bindings.js';
+/**
+ * Names the bindings that control a two-dimensional direction.
+ *
+ * @category Internal
+ */
+export type DirectionalBindingNames<BindingName extends string> = {
+    down: BindingName;
+    left: BindingName;
+    right: BindingName;
+    up: BindingName;
+};
+/** @category Internal */
+export type DirectionalInput = {
+    durationMs: number;
+    value: number;
+};
+/** @category Internal */
+export declare function getDirectionalInput<BindingName extends string>({ activeBindings, bindingName, }: Readonly<{
+    activeBindings: ActiveBindings<BindingName> | undefined;
+    bindingName: BindingName;
+}>): DirectionalInput;
+/** @category Internal */
+export declare function getAxisValue({ negative, positive, }: Readonly<{
+    negative: DirectionalInput;
+    positive: DirectionalInput;
+}>): number;
+/**
+ * Converts directional bindings into a normalized vector and favors the newest opposing input.
+ * Useful for determining player input from binding assignments.
+ *
+ * @category Util
+ */
+export declare function getDirectionalInputVector<BindingName extends string>({ activeBindings, bindingNames, }: Readonly<{
+    activeBindings: ActiveBindings<BindingName> | undefined;
+    bindingNames: Readonly<DirectionalBindingNames<BindingName>>;
+}>): {
+    x: number;
+    y: number;
+} | undefined;

package/dist/bindings/directional-input.js

@@ -0,0 +1,52 @@
+/** @category Internal */
+export function getDirectionalInput({ activeBindings, bindingName, }) {
+    const activeBinding = activeBindings?.[bindingName];
+    return {
+        durationMs: activeBinding?.holdDuration.milliseconds ?? Infinity,
+        value: activeBinding?.value || 0,
+    };
+}
+/** @category Internal */
+export function getAxisValue({ negative, positive, }) {
+    return negative.value && negative.durationMs < positive.durationMs
+        ? -negative.value
+        : positive.value && positive.durationMs < negative.durationMs
+            ? positive.value
+            : 0;
+}
+/**
+ * Converts directional bindings into a normalized vector and favors the newest opposing input.
+ * Useful for determining player input from binding assignments.
+ *
+ * @category Util
+ */
+export function getDirectionalInputVector({ activeBindings, bindingNames, }) {
+    const movementX = getAxisValue({
+        negative: getDirectionalInput({
+            activeBindings,
+            bindingName: bindingNames.left,
+        }),
+        positive: getDirectionalInput({
+            activeBindings,
+            bindingName: bindingNames.right,
+        }),
+    });
+    const movementY = getAxisValue({
+        negative: getDirectionalInput({
+            activeBindings,
+            bindingName: bindingNames.up,
+        }),
+        positive: getDirectionalInput({
+            activeBindings,
+            bindingName: bindingNames.down,
+        }),
+    });
+    const magnitude = Math.hypot(movementX, movementY);
+    if (!magnitude) {
+        return undefined;
+    }
+    return {
+        x: (movementX / magnitude) * Math.min(magnitude, 1),
+        y: (movementY / magnitude) * Math.min(magnitude, 1),
+    };
+}

package/dist/bindings/local-player-bindings.d.ts

@@ -0,0 +1,18 @@
+import { type GamepadInputDeviceKey } from 'input-device-handler';
+import { type MenuNavBinding } from './antha-menu-nav.mod.js';
+import { type DirectionalBindingNames } from './directional-input.js';
+import { type PlayerPosition, type PlayersBindingAssignments } from './player-bindings.js';
+/**
+ * Builds per-slot gamepad movement and menu bindings. Keyboard controls default to slot `'1'`; set
+ * `keyboardPlayerPosition` to `undefined` to disable them.
+ *
+ * @category Util
+ */
+export declare function createDefaultLocalPlayerBindings<BindingName extends string>({ directionalBindingNames, playerGamepads, ...keyboardOptions }: Readonly<{
+    directionalBindingNames: Readonly<DirectionalBindingNames<BindingName>>;
+    keyboardPlayerPosition?: PlayerPosition | undefined;
+    playerGamepads: ReadonlyArray<Readonly<{
+        playerPosition: PlayerPosition;
+        gamepadDeviceKey: GamepadInputDeviceKey;
+    }>>;
+}>): PlayersBindingAssignments<MenuNavBinding | BindingName>;

package/dist/bindings/local-player-bindings.js

@@ -0,0 +1,185 @@
+import { KnownInput } from '@antha/gamepad-type';
+import { arrayToObject, mapObjectValues } from '@augment-vir/common';
+import { InputDirection } from '../raw-inputs/raw-input.js';
+import { defaultMenuNavBindings } from './antha-menu-nav.mod.js';
+import { AnyGamepad, } from './player-bindings.js';
+const keyboardDirectionalBindings = {
+    down: [
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyS',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-ArrowDown',
+        },
+    ],
+    left: [
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyA',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-ArrowLeft',
+        },
+    ],
+    right: [
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyD',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-ArrowRight',
+        },
+    ],
+    up: [
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyW',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-ArrowUp',
+        },
+    ],
+};
+function createDirectionalBindings({ directionalBindingNames, gamepadDeviceKey, includeKeyboard, }) {
+    return arrayToObject([
+        {
+            bindingName: directionalBindingNames.down,
+            gamepadBindings: [
+                {
+                    direction: InputDirection.Positive,
+                    inputName: KnownInput.DPadDown,
+                },
+                {
+                    direction: InputDirection.Positive,
+                    inputName: KnownInput.LeftStickY,
+                },
+                {
+                    direction: InputDirection.Positive,
+                    inputName: KnownInput.RightStickY,
+                },
+            ],
+            keyboardBindings: keyboardDirectionalBindings.down,
+        },
+        {
+            bindingName: directionalBindingNames.left,
+            gamepadBindings: [
+                {
+                    direction: InputDirection.Positive,
+                    inputName: KnownInput.DPadLeft,
+                },
+                {
+                    direction: InputDirection.Negative,
+                    inputName: KnownInput.LeftStickX,
+                },
+                {
+                    direction: InputDirection.Negative,
+                    inputName: KnownInput.RightStickX,
+                },
+            ],
+            keyboardBindings: keyboardDirectionalBindings.left,
+        },
+        {
+            bindingName: directionalBindingNames.right,
+            gamepadBindings: [
+                {
+                    direction: InputDirection.Positive,
+                    inputName: KnownInput.DPadRight,
+                },
+                {
+                    direction: InputDirection.Positive,
+                    inputName: KnownInput.LeftStickX,
+                },
+                {
+                    direction: InputDirection.Positive,
+                    inputName: KnownInput.RightStickX,
+                },
+            ],
+            keyboardBindings: keyboardDirectionalBindings.right,
+        },
+        {
+            bindingName: directionalBindingNames.up,
+            gamepadBindings: [
+                {
+                    direction: InputDirection.Positive,
+                    inputName: KnownInput.DPadUp,
+                },
+                {
+                    direction: InputDirection.Negative,
+                    inputName: KnownInput.LeftStickY,
+                },
+                {
+                    direction: InputDirection.Negative,
+                    inputName: KnownInput.RightStickY,
+                },
+            ],
+            keyboardBindings: keyboardDirectionalBindings.up,
+        },
+    ], ({ bindingName, gamepadBindings, keyboardBindings }) => {
+        return {
+            key: bindingName,
+            value: [
+                ...gamepadBindings.map((gamepadBinding) => {
+                    return {
+                        ...gamepadBinding,
+                        deviceKey: gamepadDeviceKey,
+                    };
+                }),
+                ...(includeKeyboard ? keyboardBindings : []),
+            ],
+        };
+    });
+}
+function createMenuNavBindings({ gamepadDeviceKey, includeKeyboard, }) {
+    return mapObjectValues(defaultMenuNavBindings, (_bindingName, assignments) => {
+        return assignments.flatMap((assignment) => {
+            if (assignment.deviceKey === AnyGamepad) {
+                return [
+                    {
+                        ...assignment,
+                        deviceKey: gamepadDeviceKey,
+                    },
+                ];
+            }
+            return includeKeyboard ? [assignment] : [];
+        });
+    });
+}
+/**
+ * Builds per-slot gamepad movement and menu bindings. Keyboard controls default to slot `'1'`; set
+ * `keyboardPlayerPosition` to `undefined` to disable them.
+ *
+ * @category Util
+ */
+export function createDefaultLocalPlayerBindings({ directionalBindingNames, playerGamepads, ...keyboardOptions }) {
+    const keyboardPlayerPosition = 'keyboardPlayerPosition' in keyboardOptions ? keyboardOptions.keyboardPlayerPosition : '1';
+    return playerGamepads.reduce((playerBindingAssignments, { gamepadDeviceKey, playerPosition }) => {
+        const includeKeyboard = playerPosition === keyboardPlayerPosition;
+        return {
+            ...playerBindingAssignments,
+            [playerPosition]: {
+                ...createDirectionalBindings({
+                    directionalBindingNames,
+                    gamepadDeviceKey,
+                    includeKeyboard,
+                }),
+                ...createMenuNavBindings({
+                    gamepadDeviceKey,
+                    includeKeyboard,
+                }),
+            },
+        };
+    }, {});
+}

package/dist/bindings/player-bindings.d.ts

@@ -55,7 +55,7 @@ export type PlayerPosition = `${number}`;
  * @category Internal
  */
 export declare const bindingAssignmentShape: import("object-shape-tester").Shape<{
-    deviceKey: import("object-shape-tester").Shape<import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TLiteral<"0"> | import("@sinclair/typebox").TLiteral<"1"> | import("@sinclair/typebox").TLiteral<"2"> | import("@sinclair/typebox").TLiteral<"3"> | import("@sinclair/typebox").TLiteral<"mouse"> | import("@sinclair/typebox").TLiteral<"keyboard"> | import("@sinclair/typebox").TLiteral<"any-gamepad">)[]>>;
+    deviceKey: import("object-shape-tester").Shape<import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TLiteral<"0"> | import("@sinclair/typebox").TLiteral<"1"> | import("@sinclair/typebox").TLiteral<"2"> | import("@sinclair/typebox").TLiteral<"3"> | import("@sinclair/typebox").TLiteral<"keyboard"> | import("@sinclair/typebox").TLiteral<"mouse"> | import("@sinclair/typebox").TLiteral<"any-gamepad">)[]>>;
     direction: import("object-shape-tester").Shape<import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TLiteral<InputDirection.Flat> | import("@sinclair/typebox").TLiteral<InputDirection.Negative> | import("@sinclair/typebox").TLiteral<InputDirection.Positive>)[]>>;
     gamepadBrand: import("object-shape-tester").Shape<import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<string>>>;
     inputName: import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<string>>;
@@ -67,7 +67,7 @@ export declare const bindingAssignmentShape: import("object-shape-tester").Shape
  */
 export declare const playersBindingAssignmentsShape: import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<Partial<Record<`${number}`, Partial<Record<string, {
     gamepadBrand?: string;
-    deviceKey: "0" | "1" | "2" | "3" | "mouse" | "keyboard" | "any-gamepad";
+    deviceKey: "0" | "1" | "2" | "3" | "keyboard" | "mouse" | "any-gamepad";
     inputName: string;
     direction: InputDirection;
 }[]>>>>>>;

package/dist/index.d.ts

@@ -1,11 +1,14 @@
+export * from '@antha/gamepad-type';
+export * from 'input-device-handler';
 export * from './bindings/antha-active-bindings-debug.element.js';
 export * from './bindings/antha-binding-assignments-debug.element.js';
 export * from './bindings/antha-input-bindings.mod.js';
 export * from './bindings/antha-menu-nav.mod.js';
+export * from './bindings/antha-menu-state.mod.js';
+export * from './bindings/directional-input.js';
+export * from './bindings/local-player-bindings.js';
 export * from './bindings/player-bindings.js';
 export * from './elements/antha-keyboard.element.js';
 export * from './raw-inputs/antha-raw-input-debug.element.js';
 export * from './raw-inputs/antha-read-raw-input.mod.js';
 export * from './raw-inputs/raw-input.js';
-export * from '@antha/gamepad-type';
-export * from 'input-device-handler';

package/dist/index.js

@@ -1,11 +1,14 @@
+export * from '@antha/gamepad-type';
+export * from 'input-device-handler';
 export * from './bindings/antha-active-bindings-debug.element.js';
 export * from './bindings/antha-binding-assignments-debug.element.js';
 export * from './bindings/antha-input-bindings.mod.js';
 export * from './bindings/antha-menu-nav.mod.js';
+export * from './bindings/antha-menu-state.mod.js';
+export * from './bindings/directional-input.js';
+export * from './bindings/local-player-bindings.js';
 export * from './bindings/player-bindings.js';
 export * from './elements/antha-keyboard.element.js';
 export * from './raw-inputs/antha-raw-input-debug.element.js';
 export * from './raw-inputs/antha-read-raw-input.mod.js';
 export * from './raw-inputs/raw-input.js';
-export * from '@antha/gamepad-type';
-export * from 'input-device-handler';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@antha/input",
-    "version": "0.17.0",
+    "version": "0.19.0",
     "description": "An Antha mod for handling inputs.",
     "keywords": [
         "vir",
@@ -33,7 +33,6 @@
         "test:docs": "virmator docs check"
     },
     "dependencies": {
-        "@antha/gamepad-type": "^0.17.0",
         "@augment-vir/assert": "^32.3.0",
         "@augment-vir/common": "^32.3.0",
         "date-vir": "^9.1.1",
@@ -43,6 +42,8 @@
         "vira": "^32.0.0"
     },
     "devDependencies": {
+        "@antha/engine": "^0.19.0",
+        "@antha/gamepad-type": "^0.19.0",
         "@augment-vir/test": "^32.3.0",
         "@web/dev-server-esbuild": "^2.0.0",
         "@web/test-runner": "^1.0.0",
@@ -53,7 +54,8 @@
         "typedoc": "^0.28.20"
     },
     "peerDependencies": {
-        "@antha/engine": "^0.17.0",
+        "@antha/engine": "^0.19.0",
+        "@antha/gamepad-type": "^0.19.0",
         "element-vir": "^27"
     },
     "engines": {