# three.js minimap and game HUD, a second camera in a corner and a health bar that updates
https://paprika3d.com/docs/guides/threejs-minimap-game-hud
How to put a minimap from a second, top-down camera in a corner of a three.js game, and a health bar and score in HTML over the canvas that follow the game's state, with the paprika3d plugin's look and feel showing the HUD on a desktop and a phone, a HUD that does not update when health changes, and a minimap that covers the health bar on a narrow screen.
## Two layers over the game
A game HUD is usually two layers drawn over the 3D view.
- **Text and bars in HTML.** Health, score, ammo and timers are `div`s positioned over the canvas. They stay sharp at any pixel ratio, take CSS, and cost the GPU nothing. Keep one function that writes every HUD element from the game's state, and call it wherever the state changes; a HUD that drifts from the state comes from a change that skipped it.
- **The minimap from a second camera.** An `OrthographicCamera` above the player, looking straight down, follows the player's position each frame. A `marker` on a layer that the minimap camera renders and the main camera does not (`marker.layers.set(1)`, `map.layers.enable(1)`) shows where the player is and which way the map is turned.
There are two common ways to put the second camera's picture on screen. One renders it after the main view into a corner with `renderer.setViewport` and `renderer.setScissor`, as the answer in "How to controll minimap like games?" describes. The other renders it into a `WebGLRenderTarget` and shows that texture on a plane in a HUD scene, drawn over the frame with an orthographic camera measured in pixels, as "Position a Plane mesh on the upper right corner" asks. The page below takes the second way, for a reason in the next paragraph. Three details make it work:
```js
renderer.setRenderTarget(mapTarget); // the top-down view into the texture
renderer.render(scene, map);
renderer.setRenderTarget(null); // back to the screen, or the game draws into the texture too
renderer.render(scene, camera);
renderer.autoClear = false; // the HUD scene draws over the frame
renderer.clearDepth(); // and is not hidden by the 3D scene's depth
renderer.render(hudScene, hudCamera);
renderer.autoClear = true;
```
paprika3d is a Claude Code plugin and MCP server that opens a three.js page in its own headless Chrome. `look` returns the page's picture with the HUD in it, and its `HTML over the canvas` line lists the HTML over the picture: each element's box in page pixels, and how many overlap, are off-screen or are cut off by the screen edge. `feel` plays the input that changes the state and says whether the HUD's text changed, on which frame, beside the state that changed. `open` takes a phone's size and pixel ratio. A minimap drawn with `setViewport` and `setScissor` comes out wrong in `look` today: it redraws the frame's render calls without the viewport and scissor changes between them, and takes the minimap's camera for the game's, so its picture shows the minimap and not the game. A minimap drawn into a render target, as here, is redrawn as the page drew it.
## Install
paprika3d needs Google Chrome and Node 20.11 or later, and the Claude Code plugin needs Claude Code 2.1.118 or later.
```bash
claude plugin marketplace add paprika3d/paprika3d
claude plugin install paprika3d@paprika3d
npm install three
```
## A meadow with a HUD and a minimap
A player walks a meadow with the arrow keys. A coin to the right adds a point, and a patch of lava to the left takes 25 health. The health bar and score are HTML at the top left, and the minimap sits at the top right on a wide screen and at the bottom right, smaller, on a narrow one. `observe()` returns health, score and the player's place, and `setState` sets them.
```html
Meadow
Score 0
```
The calls below were made on 2026-10-28. Run folder paths are shortened to ``, and replies are cut to the lines this guide discusses, with nothing reworded. The machine had no GPU (Chrome drew with SwiftShader); nothing here depends on frame times.
## What look reads
```text
open {"url": "index.html", "cwd": ""}
Opened http://127.0.0.1:33849/index.html in 0.1 s, paused at frame 0.
{"name":"meadow","keys":{"ArrowLeft":"left","ArrowRight":"right","ArrowUp":"forward","ArrowDown":"back"}}
look {}
Picture: /paprika3d/runs/2026-10-28T10-28-08-658Z/look-1.png
Canvas: 1280x800 buffer for 1280x800 CSS at DPR 1 (renderer pixel ratio 1); resize handler ran.
Known, intentional (window.__game.intentional): 1 line left out ("marker" 1).
HTML over the canvas: 2 (.panel via page), 0 overlap, 0 off-screen, 0 cut off: div#health "HP 100" [16, 16, 255, 58], div#score "Score 0" [16, 72, 87, 100].
On screen (9):
ground 86% [0, 79, 1279, 799] 60 × 60 units
trees ×5 3.1% [270, 119, 1188, 386]
lava 0.67% [432, 399, 555, 461] 1.5 × 1.5 units
player 0.46% [613, 356, 666, 444]
coin 0.19% [760, 370, 812, 416]
Never visible: none
```
The picture has the game, the two panels and the minimap in its top right corner, with the eight trees, the lava and the marker seen from above. The `HTML over the canvas` line lists the two panels with their boxes, and none overlaps another or runs off the screen. `On screen` is the main camera's view: five of the eight trees are in it, and the minimap, a plane in another scene, is not an object of the game's scene. The marker is drawn on the minimap and nowhere else, so the main camera never shows it, and `look` would list it under `Never visible`; the page sets `window.__game.intentional` to `'marker'` to tell `look` that is on purpose, and the `Known, intentional` line counts what it left out.
## What feel reads: the HUD answers each change
```text
feel {"steps": [{"key": "ArrowRight", "frames": 30}]}
Watched the steps' 30 frames and 45 frames after them, counted from the first step.
Moved during the steps: player 2 units, marker 2 units.
Removed: 1 objects there before the steps are gone.
HUD text: changed in one frame.
State: score 0 → 1, player.x 0 → 2.
feel {"steps": [{"key": "ArrowLeft", "frames": 30}]}
Watched the steps' 30 frames and 45 frames after them, counted from the first step.
Moved during the steps: player 2 units, marker 2 units.
HUD text: changed in one frame.
State: hp 100 → 75, player.x 0 → -2.
```
Walking right picks up the coin (the object removed) and the score goes from 0 to 1; walking left crosses the lava and health goes from 100 to 75. Each time the HUD's text changed with it, and the marker moved with the player, so the minimap follows.
## Bug 1: health changes and the HUD does not
The same page with the lava's damage written without the call to `hud()`:
```js
if (onLava && !game.onLava) game.hp = Math.max(0, game.hp - 25);
```
```text
feel {"steps": [{"key": "ArrowLeft", "frames": 30}]}
Watched the steps' 30 frames and 45 frames after them, counted from the first step.
Moved during the steps: player 2 units, marker 2 units.
HUD text: unchanged.
State: hp 100 → 75, player.x 0 → -2.
```
The state says the player lost 25 health, and the HUD text did not change: the bar still reads full until some other change, such as the next coin, rewrites it. A HUD written from the state in one function, called from every place the state changes (or once per frame, when the values differ from the last written ones), cannot fall behind. `feel` reads the HUD's text, so give a bar its number, as `HP 100` here, or a width change alone goes unseen by it.
## Bug 2: on a phone, the minimap covers the health bar
The same page with the minimap always 200 pixels wide at the top right, opened at a phone's size:
```text
open {"url": "index.html", "cwd": "", "size": [390, 844], "dpr": 3}
Opened http://127.0.0.1:44599/index.html at 390 × 844, DPR 3 in 0.1 s, paused at frame 0.
look {}
Canvas: 390x844 buffer for 390x844 CSS at DPR 3 (renderer pixel ratio 1, capped below DPR 3); resize handler ran.
HTML over the canvas: 2 (.panel via page), 0 overlap, 0 off-screen, 0 cut off: div#health "HP 100" [16, 16, 255, 58], div#score "Score 0" [16, 72, 87, 100].
```
In the picture, the minimap's frame starts at x 172, inside the health panel, which runs to 255: the right third of the health bar is under the map. The line cannot say so, since it lists HTML and the minimap is drawn in the canvas; its box comes from the page's own numbers: a frame 204 pixels wide, centred at the screen's width less 116. The page's `layout()` moves the minimap to the bottom right at 140 pixels when the screen is narrower than 600, and the same `open` and `look` on it show the minimap in the bottom corner, clear of both panels. `layout()` also runs on resize, so turning a phone does not strand the minimap where the old width put it.
## What to read in the replies
- `look`, the picture: the HUD and the minimap as a player sees them. The minimap is in the picture and in no text line.
- `look`, `HTML over the canvas`: each HTML HUD element's box, and the counts that overlap, are off-screen or are cut off by the screen edge.
- `look`, `Known, intentional`: what `window.__game.intentional` left out, such as a minimap-only marker.
- `feel`, `HUD text` with `State`: a state change with `HUD text: unchanged` is a HUD that missed it.
- `open` with `size` and `dpr`: the same page at a phone's size, for the same `look`.
## What paprika3d does not do
It pictures a minimap drawn with `setViewport` and `setScissor` wrongly today, as said above; the page itself is fine, and the render-target way avoids the fault. Its text lines list HTML over the canvas and the main camera's objects, not what a second camera or a HUD scene draws, so a minimap's content and place are read from the picture. `feel` reads the HUD's text and the overlays' opacity, not a bar's width. A health bar that floats over a character is a label pinned to a point in the scene: [three.js HTML labels](https://paprika3d.com/docs/guides/threejs-html-labels-css2drenderer) covers placing one, with `CSS2DRenderer` or a sprite as the "Sphere + Health Bar" answers suggest. It does not design or write the HUD; the agent writes it and looks again.
## Without paprika3d
Log the state and the HUD's text together in each place the state changes, and compare. Open the page in the browser's device toolbar at a phone's size and in both orientations, and look at every corner. To check the minimap camera, render it full screen for a moment (`renderer.render(scene, map)` alone) and see what it covers.
Written by the paprika3d agent on 2026-10-28, reviewed weekly. Every code sample on this page ran in the harness before publishing.
Updated 2026-10-28.