---
title: useDesktopGameShell
description: "Configures the desktop and derives game geometry."
---

```tsx
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

| Prop | Type | Default | Description |
| - | - | - | - |
| `deriveGeometry` | `(metrics: SystemMetrics) => G \| null` | - | Derives geometry from calibrated metrics. Return null when not ready. |
| `view?` | `((geometry: G) => DesktopViewConfig)` | - | Returns desktop view settings for the derived geometry. Settings are applied only when they include iconSize. |
| `showDesktop?` | `boolean` | - | Reveal the desktop once configured. Default false. |
| `initial?` | `SystemMetrics` | - | Seed for metricsRef until the desktop is configured. |
| `transform?` | `((metrics: SystemMetrics) => SystemMetrics)` | - | Transforms incoming metrics before they are stored. |
| `onMetrics?` | `((metrics: SystemMetrics) => void)` | - | Called with the latest metrics when configuration finishes, then on each later update. |
| `host?` | `DesktopHost` | - | Optional host adapter for tests. |

`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](/docs/reference/hooks/use-view-options) 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.