@ksteinstudio/game-controller 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ksteinstudio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,348 @@
+# Universal Game Controller Engine
+
+[![npm version](https://img.shields.io/npm/v/@ksteinstudio/game-controller)](https://www.npmjs.com/package/@ksteinstudio/game-controller)
+[![license](https://img.shields.io/npm/l/@ksteinstudio/game-controller)](LICENSE)
+
+A lightweight, zero-dependency engine for rendering interactive virtual game controllers via JSON configuration. Renders inside an `<iframe>` and communicates with the parent window through `postMessage`. Perfect for mobile web games, browser-based emulators, and remote control interfaces.
+
+**Key features:**
+- Percentage-based positioning (0–100) for resolution independence
+- Multi-touch support via PointerEvents API
+- JSON-driven layout — define controllers as data
+- Iframe-sandboxed renderer — secure and isolated
+- GPU-accelerated CSS transforms for low-latency input
+- Zero runtime dependencies
+- TypeScript-first with full type exports
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @ksteinstudio/game-controller
+
+# yarn
+yarn add @ksteinstudio/game-controller
+
+# pnpm
+pnpm add @ksteinstudio/game-controller
+```
+
+- Works with any framework: React, Vue, Svelte, Angular, or vanilla JS/TS
+- Supports ESM and CommonJS
+- TypeScript types included out of the box
+- Browser-only (requires DOM APIs)
+
+---
+
+## Quick Start
+
+### 1. Define a Controller Layout (JSON)
+
+```json
+{
+  "version": "1.0.0",
+  "name": "My-Layout",
+  "canvas": {
+    "aspectRatio": "16:9",
+    "backgroundColor": "rgba(0,0,0,0.5)"
+  },
+  "elements": [
+    {
+      "id": "left-stick",
+      "type": "joystick",
+      "position": { "x": 15, "y": 60 },
+      "zIndex": 1,
+      "radius": 12,
+      "innerStickSize": 5,
+      "deadzone": 0.1,
+      "mode": "static",
+      "style": { "color": "rgba(85, 85, 85, 0.6)" }
+    },
+    {
+      "id": "btn-a",
+      "type": "button",
+      "position": { "x": 85, "y": 65 },
+      "zIndex": 1,
+      "shape": "circle",
+      "size": 8,
+      "label": "A",
+      "actionKey": "JOY_A",
+      "style": { "color": "#4CAF50" }
+    }
+  ]
+}
+```
+
+### 2. Embed with the SDK
+
+```typescript
+import { createControllerSDK } from '@ksteinstudio/game-controller';
+import layout from './controller.json';
+
+const controller = createControllerSDK({
+  config: layout,
+  container: document.getElementById('controller-container'),
+  onInput: (event) => {
+    console.log('Input:', event.type, event.payload);
+  },
+  onReady: () => {
+    console.log('Controller is ready');
+  },
+});
+
+// Update the layout dynamically
+controller.updateConfig(newLayout);
+
+// Clean up
+controller.destroy();
+```
+
+---
+
+## API Reference
+
+### `createControllerSDK(options)`
+
+Creates and embeds a controller inside a container element.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `config` | `ControllerConfig` | ✅ | The JSON layout configuration |
+| `container` | `HTMLElement` | ✅ | DOM element to mount the iframe into |
+| `iframeSrc` | `string` | ❌ | Custom URL for the renderer (uses embedded renderer by default) |
+| `onInput` | `(event: InputEvent) => void` | ❌ | Callback for all input events |
+| `onReady` | `() => void` | ❌ | Called when the renderer is initialized |
+| `width` | `string` | ❌ | CSS width for the iframe (default: `100%`) |
+| `height` | `string` | ❌ | CSS height for the iframe (default: `100%`) |
+
+**Returns** `ControllerSDKInstance`:
+
+| Method | Description |
+|--------|-------------|
+| `updateConfig(config)` | Send a new layout to the renderer |
+| `destroy()` | Remove the iframe and clean up listeners |
+| `getIframe()` | Access the underlying HTMLIFrameElement |
+
+---
+
+## Type Definitions
+
+### Position
+
+All positions use a **percentage-based coordinate system** (0–100) for resolution independence.
+
+```typescript
+interface Position {
+  x: number; // 0 to 100 (% of canvas width)
+  y: number; // 0 to 100 (% of canvas height)
+}
+```
+
+### Element Types
+
+| Type | Description | Key Properties |
+|------|-------------|----------------|
+| `button` | Pressable button (circle or square) | `shape`, `size`, `label`, `actionKey` |
+| `joystick` | Analog stick with normalized output | `radius`, `innerStickSize`, `deadzone`, `mode` |
+| `dpad` | 4-directional pad | `size`, `actionKeys` |
+| `slider` | Linear input control | `length`, `orientation`, `actionKey` |
+
+### Events Emitted
+
+| Event | Payload | When |
+|-------|---------|------|
+| `INPUT_START` | `{ elementId, actionKey, timestamp }` | Button pressed |
+| `INPUT_END` | `{ elementId, actionKey, timestamp }` | Button released |
+| `JOYSTICK_MOVE` | `{ elementId, vector: {x,y}, angle, magnitude, timestamp }` | Joystick moves (vector normalized -1 to 1) |
+| `DPAD_PRESS` | `{ elementId, direction, actionKey, timestamp }` | DPad direction pressed |
+| `DPAD_RELEASE` | `{ elementId, direction, actionKey, timestamp }` | DPad direction released |
+
+---
+
+## Math Utilities
+
+Exported utilities for building custom layout editors or tools.
+
+### Snap-to-Grid
+
+```typescript
+import { snapToGrid, snapPositionToGrid } from '@ksteinstudio/game-controller';
+
+const snapped = snapToGrid(37, 20); // → 35
+const pos = snapPositionToGrid({ x: 37.2, y: 62.8 }, 20); // → { x: 35, y: 65 }
+```
+
+### Coordinate Conversion
+
+```typescript
+import { pixelToPercentage, percentageToPixel } from '@ksteinstudio/game-controller';
+
+const pct = pixelToPercentage(320, 1920); // → 16.67
+const px = percentageToPixel(50, 1080);   // → 540
+```
+
+### Alignment Guides
+
+```typescript
+import { findAlignmentGuides } from '@ksteinstudio/game-controller';
+
+const result = findAlignmentGuides(draggedElement, cursorPosition, otherElements);
+// result.position → snapped position
+// result.guides   → array of active alignment lines
+```
+
+---
+
+## Framework Examples
+
+### React
+
+```tsx
+import { useEffect, useRef } from 'react';
+import { createControllerSDK, ControllerConfig, InputEvent } from '@ksteinstudio/game-controller';
+
+const layout: ControllerConfig = {
+  version: '1.0.0',
+  name: 'react-controller',
+  canvas: { aspectRatio: '16:9', backgroundColor: 'rgba(0,0,0,0.4)' },
+  elements: [
+    {
+      id: 'stick', type: 'joystick', position: { x: 20, y: 65 },
+      zIndex: 1, radius: 12, innerStickSize: 5, deadzone: 0.1, mode: 'static',
+      style: { color: 'rgba(80,80,80,0.6)' },
+    },
+    {
+      id: 'btn-a', type: 'button', position: { x: 85, y: 60 },
+      zIndex: 1, shape: 'circle', size: 10, label: 'A', actionKey: 'JUMP',
+      style: { color: '#4CAF50' },
+    },
+  ],
+};
+
+function GameController() {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const sdk = createControllerSDK({
+      config: layout,
+      container: containerRef.current,
+      onInput: (event: InputEvent) => {
+        console.log(event.type, event.payload);
+      },
+    });
+
+    return () => sdk.destroy();
+  }, []);
+
+  return <div ref={containerRef} style={{ width: '100%', height: '300px' }} />;
+}
+```
+
+### Vue 3
+
+```vue
+<template>
+  <div ref="controllerRef" style="width: 100%; height: 300px" />
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from 'vue';
+import { createControllerSDK, type ControllerSDKInstance } from '@ksteinstudio/game-controller';
+
+const controllerRef = ref<HTMLDivElement>();
+let sdk: ControllerSDKInstance;
+
+onMounted(() => {
+  if (!controllerRef.value) return;
+
+  sdk = createControllerSDK({
+    config: {
+      version: '1.0.0',
+      name: 'vue-controller',
+      canvas: { aspectRatio: '16:9' },
+      elements: [
+        {
+          id: 'joy', type: 'joystick', position: { x: 20, y: 65 },
+          zIndex: 1, radius: 12, innerStickSize: 5, deadzone: 0.1, mode: 'static',
+        },
+      ],
+    },
+    container: controllerRef.value,
+    onInput: (event) => console.log(event),
+  });
+});
+
+onUnmounted(() => sdk?.destroy());
+</script>
+```
+
+### Vanilla JavaScript (No Bundler)
+
+```html
+<div id="controller" style="width: 100%; height: 400px;"></div>
+
+<script type="module">
+  import { createControllerSDK } from 'https://esm.sh/@ksteinstudio/game-controller';
+
+  createControllerSDK({
+    config: {
+      version: '1.0.0',
+      name: 'vanilla-layout',
+      canvas: { aspectRatio: '16:9', backgroundColor: 'rgba(0,0,0,0.3)' },
+      elements: [
+        {
+          id: 'dpad', type: 'dpad', position: { x: 15, y: 50 },
+          zIndex: 1, size: 15, style: { color: '#333' },
+        },
+        {
+          id: 'btn-a', type: 'button', position: { x: 85, y: 55 },
+          zIndex: 1, shape: 'circle', size: 10, label: 'A', actionKey: 'A',
+          style: { color: '#4CAF50' },
+        },
+      ],
+    },
+    container: document.getElementById('controller'),
+    onInput: (e) => console.log(e.type, e.payload),
+  });
+</script>
+```
+
+---
+
+## All Exports
+
+```typescript
+import { createControllerSDK } from '@ksteinstudio/game-controller';
+
+import type {
+  ControllerConfig,
+  ButtonElement,
+  JoystickElement,
+  DpadElement,
+  InputEvent,
+  Position,
+} from '@ksteinstudio/game-controller';
+
+import {
+  snapToGrid,
+  snapPositionToGrid,
+  pixelToPercentage,
+  percentageToPixel,
+  findAlignmentGuides,
+  calculateCanvasDimensions,
+} from '@ksteinstudio/game-controller';
+
+import { createParentBridge, createIframeBridge } from '@ksteinstudio/game-controller';
+
+import { renderControllerFromConfig, destroyRenderer } from '@ksteinstudio/game-controller';
+```
+
+---
+
+## License
+
+[MIT](LICENSE) © Ksteinstudio

package/dist/index.d.mts

@@ -0,0 +1,272 @@
+interface Position {
+    x: number;
+    y: number;
+}
+interface ElementStyle {
+    color?: string;
+    opacity?: number;
+    scale?: number;
+    borderColor?: string;
+    borderWidth?: number;
+    fontSize?: number;
+    fontFamily?: string;
+}
+interface BaseElement {
+    id: string;
+    type: 'button' | 'joystick' | 'dpad' | 'slider';
+    position: Position;
+    zIndex: number;
+    style?: ElementStyle;
+}
+interface ButtonElement extends BaseElement {
+    type: 'button';
+    label?: string;
+    shape: 'circle' | 'square';
+    size: number;
+    actionKey: string;
+}
+interface JoystickElement extends BaseElement {
+    type: 'joystick';
+    radius: number;
+    innerStickSize: number;
+    deadzone: number;
+    mode: 'static' | 'floating';
+}
+interface DpadElement extends BaseElement {
+    type: 'dpad';
+    size: number;
+    actionKeys?: {
+        up: string;
+        down: string;
+        left: string;
+        right: string;
+    };
+}
+interface SliderElement extends BaseElement {
+    type: 'slider';
+    length: number;
+    orientation: 'horizontal' | 'vertical';
+    actionKey: string;
+}
+type ControllerElement = ButtonElement | JoystickElement | DpadElement | SliderElement;
+interface CanvasSettings {
+    aspectRatio: string;
+    backgroundColor?: string;
+    gridDensity?: number;
+}
+interface ControllerConfig {
+    version: string;
+    name: string;
+    canvas: CanvasSettings;
+    elements: ControllerElement[];
+}
+
+declare const enum MessageType {
+    CONFIG_LOAD = "CONFIG_LOAD",
+    INPUT_START = "INPUT_START",
+    INPUT_END = "INPUT_END",
+    JOYSTICK_MOVE = "JOYSTICK_MOVE",
+    DPAD_PRESS = "DPAD_PRESS",
+    DPAD_RELEASE = "DPAD_RELEASE",
+    SLIDER_CHANGE = "SLIDER_CHANGE",
+    RENDERER_READY = "RENDERER_READY",
+    CONFIG_UPDATE = "CONFIG_UPDATE"
+}
+interface Vector2D {
+    x: number;
+    y: number;
+}
+interface ConfigLoadMessage {
+    type: MessageType.CONFIG_LOAD;
+    payload: ControllerConfig;
+}
+interface InputStartMessage {
+    type: MessageType.INPUT_START;
+    payload: {
+        elementId: string;
+        actionKey: string;
+        timestamp: number;
+    };
+}
+interface InputEndMessage {
+    type: MessageType.INPUT_END;
+    payload: {
+        elementId: string;
+        actionKey: string;
+        timestamp: number;
+    };
+}
+interface JoystickMoveMessage {
+    type: MessageType.JOYSTICK_MOVE;
+    payload: {
+        elementId: string;
+        vector: Vector2D;
+        angle: number;
+        magnitude: number;
+        timestamp: number;
+    };
+}
+interface DpadPressMessage {
+    type: MessageType.DPAD_PRESS;
+    payload: {
+        elementId: string;
+        direction: 'up' | 'down' | 'left' | 'right';
+        actionKey: string;
+        timestamp: number;
+    };
+}
+interface DpadReleaseMessage {
+    type: MessageType.DPAD_RELEASE;
+    payload: {
+        elementId: string;
+        direction: 'up' | 'down' | 'left' | 'right';
+        actionKey: string;
+        timestamp: number;
+    };
+}
+interface SliderChangeMessage {
+    type: MessageType.SLIDER_CHANGE;
+    payload: {
+        elementId: string;
+        actionKey: string;
+        value: number;
+        timestamp: number;
+    };
+}
+interface RendererReadyMessage {
+    type: MessageType.RENDERER_READY;
+}
+interface ConfigUpdateMessage {
+    type: MessageType.CONFIG_UPDATE;
+    payload: ControllerConfig;
+}
+type ControllerMessage = ConfigLoadMessage | InputStartMessage | InputEndMessage | JoystickMoveMessage | DpadPressMessage | DpadReleaseMessage | SliderChangeMessage | RendererReadyMessage | ConfigUpdateMessage;
+type InputEvent = InputStartMessage | InputEndMessage | JoystickMoveMessage | DpadPressMessage | DpadReleaseMessage | SliderChangeMessage;
+
+type MessageHandler = (message: ControllerMessage) => void;
+declare function createParentBridge(iframe: HTMLIFrameElement): {
+    sendConfig(config: ControllerConfig): void;
+    updateConfig(config: ControllerConfig): void;
+    onMessage(handler: MessageHandler): () => boolean;
+    onInput(handler: (event: InputEvent) => void): () => boolean;
+    destroy(): void;
+};
+declare function createIframeBridge(): {
+    emitControllerEvent(message: ControllerMessage): void;
+    emitInputStart(elementId: string, actionKey: string): void;
+    emitInputEnd(elementId: string, actionKey: string): void;
+    emitJoystickMove(elementId: string, x: number, y: number, angle: number, magnitude: number): void;
+    emitDpadPress(elementId: string, direction: "up" | "down" | "left" | "right", actionKey: string): void;
+    emitDpadRelease(elementId: string, direction: "up" | "down" | "left" | "right", actionKey: string): void;
+    emitSliderChange(elementId: string, actionKey: string, value: number): void;
+    signalReady(): void;
+    onMessage(handler: MessageHandler): () => boolean;
+    destroy(): void;
+};
+type ParentBridge = ReturnType<typeof createParentBridge>;
+type IframeBridge = ReturnType<typeof createIframeBridge>;
+
+declare function snapToGrid(value: number, gridDensity: number): number;
+declare function snapPositionToGrid(position: Position, gridDensity: number): Position;
+declare function pixelToPercentage(pixelValue: number, containerSize: number): number;
+declare function percentageToPixel(percentageValue: number, containerSize: number): number;
+declare function convertPixelPositionToPercentage(pixelX: number, pixelY: number, containerWidth: number, containerHeight: number): Position;
+declare function convertPercentagePositionToPixel(position: Position, containerWidth: number, containerHeight: number): {
+    x: number;
+    y: number;
+};
+declare function clampPercentage(value: number): number;
+declare function clamp(value: number, min: number, max: number): number;
+declare function distance(a: Position, b: Position): number;
+declare function normalizeVector(x: number, y: number): {
+    x: number;
+    y: number;
+    magnitude: number;
+};
+declare function angleFromVector(x: number, y: number): number;
+declare function applyDeadzone(value: number, deadzone: number): number;
+declare function applyDeadzoneToVector(x: number, y: number, deadzone: number): {
+    x: number;
+    y: number;
+};
+declare function parseAspectRatio(aspectRatio: string): {
+    width: number;
+    height: number;
+};
+declare function calculateCanvasDimensions(containerWidth: number, containerHeight: number, aspectRatio: string): {
+    width: number;
+    height: number;
+    offsetX: number;
+    offsetY: number;
+};
+
+interface AlignmentGuide {
+    axis: 'horizontal' | 'vertical';
+    position: number;
+    sourceElementId: string;
+    targetElementId: string;
+}
+interface SnapResult {
+    position: Position;
+    guides: AlignmentGuide[];
+}
+declare function findAlignmentGuides(draggedElement: ControllerElement, dragPosition: Position, otherElements: ControllerElement[], threshold?: number): SnapResult;
+declare function generateGridLines(gridDensity: number): number[];
+
+interface ButtonRenderContext {
+    element: ButtonElement;
+    canvasWidth: number;
+    canvasHeight: number;
+    onInputStart: (elementId: string, actionKey: string) => void;
+    onInputEnd: (elementId: string, actionKey: string) => void;
+}
+declare function createButtonElement(context: ButtonRenderContext): HTMLElement;
+declare function updateButtonElement(container: HTMLElement, element: ButtonElement, canvasWidth: number, canvasHeight: number): void;
+
+interface JoystickRenderContext {
+    element: JoystickElement;
+    canvasWidth: number;
+    canvasHeight: number;
+    onJoystickMove: (elementId: string, vector: Vector2D, angle: number, magnitude: number) => void;
+}
+declare function createJoystickElement(context: JoystickRenderContext): HTMLElement;
+declare function updateJoystickElement(container: HTMLElement, element: JoystickElement, canvasWidth: number, canvasHeight: number): void;
+
+interface DpadRenderContext {
+    element: DpadElement;
+    canvasWidth: number;
+    canvasHeight: number;
+    onDpadPress: (elementId: string, direction: 'up' | 'down' | 'left' | 'right', actionKey: string) => void;
+    onDpadRelease: (elementId: string, direction: 'up' | 'down' | 'left' | 'right', actionKey: string) => void;
+}
+declare function createDpadElement(context: DpadRenderContext): HTMLElement;
+declare function updateDpadElement(container: HTMLElement, element: DpadElement, canvasWidth: number, canvasHeight: number): void;
+
+interface RendererState {
+    config: ControllerConfig | null;
+    canvas: HTMLElement | null;
+    elementMap: Map<string, HTMLElement>;
+    bridge: IframeBridge;
+    resizeObserver: ResizeObserver | null;
+}
+declare function initializeRenderer(rootElement: HTMLElement): RendererState;
+declare function renderControllerFromConfig(rootElement: HTMLElement, config: ControllerConfig): RendererState;
+declare function destroyRenderer(state: RendererState): void;
+
+interface ControllerSDKOptions {
+    config: ControllerConfig;
+    container: HTMLElement;
+    iframeSrc?: string;
+    onInput?: (event: InputEvent) => void;
+    onReady?: () => void;
+    width?: string;
+    height?: string;
+}
+interface ControllerSDKInstance {
+    updateConfig: (config: ControllerConfig) => void;
+    destroy: () => void;
+    getIframe: () => HTMLIFrameElement;
+}
+declare function createControllerSDK(options: ControllerSDKOptions): ControllerSDKInstance;
+
+export { type AlignmentGuide, type BaseElement, type ButtonElement, type ButtonRenderContext, type CanvasSettings, type ConfigLoadMessage, type ConfigUpdateMessage, type ControllerConfig, type ControllerElement, type ControllerMessage, type ControllerSDKInstance, type ControllerSDKOptions, type DpadElement, type DpadPressMessage, type DpadReleaseMessage, type DpadRenderContext, type ElementStyle, type IframeBridge, type InputEndMessage, type InputEvent, type InputStartMessage, type JoystickElement, type JoystickMoveMessage, type JoystickRenderContext, MessageType, type ParentBridge, type Position, type RendererReadyMessage, type SliderChangeMessage, type SliderElement, type SnapResult, type Vector2D, angleFromVector, applyDeadzone, applyDeadzoneToVector, calculateCanvasDimensions, clamp, clampPercentage, convertPercentagePositionToPixel, convertPixelPositionToPercentage, createButtonElement, createControllerSDK, createDpadElement, createIframeBridge, createJoystickElement, createParentBridge, destroyRenderer, distance, findAlignmentGuides, generateGridLines, initializeRenderer, normalizeVector, parseAspectRatio, percentageToPixel, pixelToPercentage, renderControllerFromConfig, snapPositionToGrid, snapToGrid, updateButtonElement, updateDpadElement, updateJoystickElement };