@vibegameengine/ui-scaler

A React component for building responsive Game UIs that scale intelligently.

The Problem

Game UIs are often designed for a specific resolution (e.g., 1024x768). On smaller screens (mobile), you want the UI to shrink to fit. On larger screens (desktop), you often want the UI to stay the same "physical" size or just anchor to corners, rather than blowing up to fill the whole 4K screen.

The Solution

ScalableContainer provides a "safe zone" that:

1. Scales Down on small screens (Mobile behavior) to ensure your design fits.
2. Stays 1:1 on large screens (Desktop behavior) to preserve crisp text and convenient clickable areas.

Installation

npm install @vibegameengine/ui-scaler

Usage

Wrap your entire UI layer (HTML overlays on top of Canvas) with this component.

import { ScalableContainer } from '@vibegameengine/ui-scaler';

const GameUI = () => {
  return (
    // targetWidth: The width your UI was designed for (e.g., 1024px or 1920px).
    // If screen < targetWidth, it scales down.
    // If screen > targetWidth, it stays at scale 1.0.
    <ScalableContainer targetWidth={1024} zIndex={10}>
      
      {/* Absolute positioning works relative to the scaled container */}
      <div style={{ position: 'absolute', top: 20, left: 20 }}>
          Score: 1000
      </div>

      <div style={{ position: 'absolute', bottom: 20, right: 20 }}>
          <button>Fire</button>
      </div>

    </ScalableContainer>
  );
};

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | ReactNode | Required | The UI elements to scale. | | targetWidth | number | 1024 | The reference logic width. Below this screen width, content scales down. | | zIndex | number | 10 | Z-Index of the container (useful for overlays). |

Tips

• Designed to work with HTML/CSS overlays on top of a canvas.
• Passes pointer events through to the canvas by default (pointer-events: none).
• Enable interaction on buttons with pointer-events: auto.