useDesktopGameShell

Configures the desktop and derives game geometry.

import { useDesktopGameShell } from 'filedom';

const { metrics, geometry, ready } = useDesktopGameShell({
  deriveGeometry: (m) => ({
    center: { x: m.width / 2, y: m.height / 2 },
    iconSize: 96,
  }),
  view: (g) => ({ iconSize: g.iconSize }),
});

if (!ready || !geometry || !metrics) return null;

Call it in your game component and mount stages from the returned geometry. Applying an icon size restarts Finder, and the hook withholds metrics and geometry until that restart has finished, so stages never mount against a desktop that is about to be rearranged.

Options

PropType

deriveGeometry(metrics: SystemMetrics) => G | null

Derives geometry from calibrated metrics. Return null when not ready.

Type(metrics: SystemMetrics) => G | null

view?((geometry: G) => DesktopViewConfig)

Returns desktop view settings for the derived geometry. Settings are applied only when they include iconSize.

Type((geometry: G) => DesktopViewConfig)

showDesktop?boolean

Reveal the desktop once configured. Default false.

Typeboolean

initial?SystemMetrics

Seed for metricsRef until the desktop is configured.

TypeSystemMetrics

transform?((metrics: SystemMetrics) => SystemMetrics)

Transforms incoming metrics before they are stored.

Type((metrics: SystemMetrics) => SystemMetrics)

onMetrics?((metrics: SystemMetrics) => void)

Called with the latest metrics when configuration finishes, then on each later update.

Type((metrics: SystemMetrics) => void)

host?DesktopHost

Optional host adapter for tests.

TypeDesktopHost

view returns a DesktopViewConfig: iconSize (rounded, minimum 1), textSize in points (default 10), labelPosition ('bottom' or 'right', default 'bottom'), and gridArrangement (default NotArranged). Grid spacing is not configurable here; use useViewOptions if you need it.

Returns

metrics and geometry are null until the desktop is configured. metricsRef gives callbacks the current metrics and holds initial until then. ready is true once metrics are calibrated and any view change has been applied. geometry can still be null after that if deriveGeometry returns null.