Portebla

An input system for games and interactive projects allowing the use of UI elements, gamepads, touch events, keyboard, and mouse. Portebla focuses on providing a highly responsive, out-of-the-box virtual controller overlay for mobile HTML5 games.

Installation

npm install portebla --save-dev

Basic Usage

Import and instantiate Portebla by passing a configuration object. The library will automatically mount the virtual controller interface into the container you specify.

import { Portebla } from 'portebla';

// Initialize the controller
const portebla = new Portebla({
    container: document.getElementById('portebla-container'),
    layout: 'auto', // 'auto', 'portrait', or 'landscape'
    leftControl: 'joystick', // 'joystick' or 'dpad'
    rightControl: 'buttons', // 'buttons' (ABXY)
    centerControl: 'menu' // 'menu' (START/SELECT)
});

// Inside your main game loop, query the inputs
function gameLoop() {
    // 1. MUST CALL UPDATE to reset the 'justPressed' flags every frame
    portebla.input.update();

    // 2. Query Joysticks (Values range from -1.0 to 1.0)
    const joyX = portebla.input.joystick.x;
    const joyY = portebla.input.joystick.y;

    // 3. Query Buttons
    if (portebla.input.buttons.A.pressed) {
        console.log("A is currently held down!");
    }
    
    if (portebla.input.buttons.START.justPressed) {
        console.log("Start was pressed this exact frame!");
    }

    requestAnimationFrame(gameLoop);
}

gameLoop();

Configuration Options

When instantiating new Portebla(options), you can customize the layout and controls:

| Option | Type | Default | Description | |--------|------|---------|-------------| | container | HTMLElement | document.body | The DOM element where Portebla will mount its UI. | | layout | string | 'auto' | The layout style. Use 'auto' for responsive design, or strictly enforce 'portrait' or 'landscape'. | | leftControl | string | 'joystick' | The directional control type: 'joystick' or 'dpad'. | | rightControl| string | 'buttons' | The action controls: 'buttons' (A, B, X, Y). | | centerControl| string | 'menu' | The menu controls: 'menu' (Start, Select). | | fullControl | string | 'none' | Set to 'touchcanvas' to enable Dual-Screen mode (see below). | | vibration | boolean | true | Enables or disables native haptic feedback (navigator.vibrate) when buttons are pressed. |

Input Manager Reference

You can access the global input state at any time via portebla.input.

portebla.input.buttons

A dictionary of all available buttons. Available keys: 'A', 'B', 'X', 'Y', 'START', 'SELECT', 'UP', 'DOWN', 'LEFT', 'RIGHT'. Each button contains:

• .pressed (boolean): true while the button is held down.
• .justPressed (boolean): true only during the exact frame the button was pressed.
• .justReleased (boolean): true only during the exact frame the button was released.

portebla.input.joystick

Tracks the left directional pad/joystick.

• .x (number): Ranges from -1.0 (left) to 1.0 (right).
• .y (number): Ranges from -1.0 (up) to 1.0 (down).
• .active (boolean): true while the user is touching the joystick.

Advanced Features

Touch Canvas (Dual-Screen Mode)

Portebla supports a "Nintendo DS" style layout where the standard controls are replaced by a massive secondary touch screen. This is perfect for inventory screens, mini-maps, or drawing mini-games.

To enable it, set fullControl: 'touchcanvas':

const portebla = new Portebla({
    container: document.getElementById('portebla-container'),
    layout: 'portrait',
    fullControl: 'touchcanvas'
});

// Retrieve the DOM element to mount your secondary WebGL/Canvas renderer!
const secondaryScreen = portebla.getTouchContainer();
secondaryScreen.appendChild(myPixiJsCanvas);

You can then track precise multi-touch coordinates on this secondary screen via the input manager:

const tc = portebla.input.touchCanvas;
console.log(tc.x, tc.y); // Ranges from -1.0 to 1.0 (0,0 is the dead center of the canvas)
console.log(tc.active);  // true if currently being touched

Automatic Orientation Enforcement

If your game strictly requires a specific orientation, simply pass layout: 'portrait' or layout: 'landscape'.

Portebla uses pure CSS Media Queries to detect the physical screen aspect ratio. If the user holds their device horizontally while your game is in 'portrait' mode, Portebla will automatically hide the UI and display a full-screen "Please rotate your device" warning overlay, completely out-of-the-box.

Native Haptic Feedback (Vibration)

Every virtual button across the entire interface (D-Pad, ABXY, Start/Select) natively hooks into the browser's navigator.vibrate API. When a player taps a button on a supported mobile device, they will feel a crisp 30ms tactile vibration burst, simulating the feel of a real physical controller. This is enabled by default and requires zero setup!

Changelog

v1.0.7

• Tweak: Reverted haptic feedback duration to 30ms for better compatibility with slower vibration motors while maintaining responsiveness.

v1.0.6

• Tweak: Finalized haptic feedback duration at a crisp 20ms.

v1.0.5

• Tweak: Tuned haptic feedback duration to 35ms for the perfect balance of responsiveness and tactile feel.

v1.0.4

• Fix: Improved navigator.vibrate cross-device compatibility by scoping to window.navigator and utilizing the Array signature.

v1.0.2

• Feature: Added universal Haptic Feedback support (navigator.vibrate).
• Feature: Added vibration toggle to PorteblaOptions to disable haptics.
• Docs: Extensive documentation updates and interactive demo overhaul.
• Fix: CSS Grid spacing logic for dual-screen mode overlapping on tall devices.