Skip to content

t1k:playablelabs:web:hole-ui

FieldValue
Moduleweb
Version1.18.2
Effortmedium
Tools—

Keywords: data-hole-ui, goods hunt web ui, hole em all web ui, hole endcard layout, hole game ui standard, hole hud layout, hole playable end card, hole ui check, holecraft web ui, tiles in hole web ui

/t1k:playablelabs:web:hole-ui
[standard | sources | dump <assetsDir> <prefab> | check --url <url> | --dir <dist>]

Scope: the HUD and the win / lose end cards of a hole-genre playable built for the web engine host (three.js, DOM UI): every new game of the GH (Goods Hunt), TIH (Tiles in Hole), HEA (Hole Em All) and HC (HoleCraft) lines, and any end card being fixed. One layout for all four lines; each line keeps its own sprites.

Out of scope: Cocos builds (their UI is canvas, nothing to measure in the DOM; read them with the dump tool below), and a port whose brief is pixel parity with its Cocos version (that brief wins; a GH port matches its own Cocos build). Boot globals and the CTA call itself: t1k-playablelabs-web-host-contract.

references/hole-ui-spec.json is the single source: positions, sizes, tolerance and viewports, each number with the prefab it was read from. Units are design units of a 1080x1920 portrait UI. Widget offsets are distances from the design-box edges; center is an offset from the box centre with y UP (Cocos).

StateElementWhereSize
playtimertop 36, centred448x173
playkills (kill modes only)left 115, top 84 (level with the timer)skull 78x112 + 64px count
playgoalsa centred row, top 239cards 180x234, 216 apart, count 45px
playprogress (instead of goals)top 248, centred965x71
playtutorialcentre (0, -555); “Swipe to move” 55px at (0, -355)431x232 figure-eight + 150x164 hand
playlogoleft 36, bottom 40fits 260x140 (wide logo) or 150x150 (square app icon)
playCTA “Play Now” (references/art/CTA_Playnow.png)right 36, bottom 45356x130
win / loseveilthe whole screen, black, alpha 0.87 (min 0.8), the game visible under it
win / losetitle(0, 600)900 wide; win “Excellent!”, lose “TIME’S UP!” (a non-timeout loss: the line’s loss art)
win / losegame logo(0, 0)fits 1004x646 (wide) or 600x600 (square)
win / losebutton(0, -600)602x219; win references/art/CTA_Playnow.png, lose references/art/CTA_TryAgain.png (green, lavender-border buttons only, see below)

End cards: title, logo and button pop in one after another, each scale 0 to 1 over 0.5 s (back-out), 0.15 s apart. Win: a tap anywhere on the card opens the store, with confetti. Lose: only the button opens the store.

The design box is laid out the way Cocos lays out the line’s own build: one scale = min(screenW/1080, screenH/1920), and the canvas grows on the longer side instead of letterboxing (1080 wide and about 2340 tall on a 390x844 phone). Widgets align to the safe area (env(safe-area-inset-*)): top / bottom / left / right are distances from its edges and center is relative to its centre. Place the UI layer like that: size it safeW/scale x safeH/scale design px at the safe-area origin, transform: scale(scale), and anchor each piece to its own edge. Checked against the approved thread screenshots on a 390x844 iPhone: GH’s CTA centre lands at 0.908 of the screen height, the screenshot has 0.909. A 1080x1920 box fitted and centred in the safe area puts the bottom row 29 pt too high and squeezes everything towards the middle.

Copy each sprite from the line’s Cocos project at native resolution, cropped to its .meta frame and with its node tint applied (both in references/ui-sources.md), and draw it at the spec size. references/ui-sources.md lists every slot per line: repo, branch, path, native pixels and the size the line shows it at. Never redraw a button, a timer pill, a goal card or a title as CSS shapes or text when the line has the art, and never take a size from a screenshot. A slot the line lacks (the HC win title) takes the art of the closest line in that table. The table names, per line, the versions the studio approved in the “Update UI các game” thread: art comes from those, not from whatever branch is checked out.

Buttons drawn in the standard pair’s style (green body, lavender border) are replaced with the studio’s pair in references/art/, at the spec size. CTA_Playnow.png replaces the gameplay CTA and the win button, CTA_TryAgain.png replaces the lose button. A button in another style keeps the line’s own art and size: in the approved versions that is GH’s win button (“PLAY NOW”) and lose button (“TRY AGAIN!”), both grey-bordered. references/ui-sources.md lists which slot is which. Judge the border on the art file itself, not from memory.

Read a line’s UI yourself when the version you port is newer than the table:

Terminal window
bun scripts/cocos-ui-dump.cjs <project>/assets <project>/assets/resources/prefab/UI/GameView.prefab
bun scripts/cocos-ui-dump.cjs <project>/assets <project>/assets/scene/MainScene.scene --root UICanvas

It prints each node’s design-space centre, content size, Widget anchors, sprite file with its native size and label text, nested prefabs expanded with their overrides; x marks an inactive node. A scene’s UI canvas sits at (540, 960): subtract it for centre offsets.

  • Each piece carries data-hole-ui: timer, kills, goals, goal-card (one per card), progress, tutorial, tutorial-text, logo, cta, and on the end cards end (the full-screen veil, its own background colour carries the alpha), end-title, end-visual, end-button.
  • When window.__PLA_QA__ is true before the game boots, expose window.__holeUi = { end(result) } that shows the 'win' or 'lose' card at once, as the game would at its end. Never expose it otherwise.
  • Hidden elements (display none, visibility hidden, opacity under 0.05) count as absent.

scripts/fixtures/hole-ui-ok.html is a complete page laid out to the spec with plain boxes: copy its layer math and attributes.

Terminal window
bun scripts/hole-ui-check.cjs --dir <dist or index.html> [--out hole-ui-report]
bun scripts/hole-ui-check.cjs --url http://127.0.0.1:5173/ --viewports 390x844 --states win

At each spec viewport (390x844, 360x800, 430x932, 405x720, 1280x720) it boots the game muted with __PLA_QA__ set, waits for __PLA_SCENE_UP__, measures the play state, then calls __holeUi.end for each end card, and checks position and size (tolerance 24 design units), goal-card spacing, overlap, on-screen and the veil. It writes report.json and report.html: every screenshot with the spec’s boxes dashed green and the measured ones red. Exit 0 all pass, 1 a check failed, 2 usage, 3 environment (puppeteer-core or Chrome missing: it uses t1k-playablelabs-base-playthrough’s launcher, so set PLAYTHROUGH_PUPPETEER to a puppeteer-core dir if none is found).

Done means exit 0 at every spec viewport, and a person has looked at report.html: the check proves where the boxes are, not that the right art is in them.

Running scripts/hole-ui-check.cjs or scripts/cocos-ui-dump.cjs and tabulating their findings is mechanical: t1k-tester (read-only build-verification lane) or the calling agent. Choosing which line’s art fills a slot, and judging the report screenshots, stays with the calling agent. Routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”.

StepAgent
Run scripts/hole-ui-check.cjs, list the findings per viewport and statet1k-tester, or the calling agent itself
Run scripts/cocos-ui-dump.cjs on a line’s prefab or scenet1k-tester, or the calling agent itself
Pick sprites, fix the layout, review report.htmlthe calling agent
  • End cards animate in. --end-settle (default 1300 ms) must outlast the pop-in (0.5 s + 2 x 0.15 s); a half-scaled title fails its size.
  • The tutorial hides on the first input. The check never sends input, so it measures the tutorial at rest.
  • goals is the row container; its width depends on the card count, so only its top and centre are checked. Each goal-card is checked for size and the 216 step.
  • HC9 (the HoleCraft series reference) points its kill counter at a skull sprite uuid with no file. The approved HC gameplay version, HCDesignPA4, has the file (skullIcon.png).
  • Runtime parameters override the prefab. HC’s playable-config.json sets the in-game logo to 256x164 at x -376, while the prefab says 450x289: read ParameterToolBuild/playable-config.json beside the prefab before taking a size.
  • A web label sits on the Cocos baseline, not in a CSS line box. Cocos TTF labels draw with textBaseline: 'alphabetic' and put a single line’s baseline 0.37 x fontSize below the label box centre (first baseline at 0.87 x fontSize, minus half the free height). A CSS box centred on the font’s ascent and descent lifts Baloo or Lilita text by about 15 design units at fontSize 100: the GH timer then hugs the top of its pill. Draw the text at that baseline (SVG <text y>, or a measured offset) and look at the report screenshot, because the box check cannot see this.