t1k:playablelabs:web:hole-ui
| Field | Value |
|---|---|
| Module | web |
| Version | 1.18.2 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/t1k:playablelabs:web:hole-ui[standard | sources | dump <assetsDir> <prefab> | check --url <url> | --dir <dist>]Hole-genre web UI standard
Section titled “Hole-genre web UI standard”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.
The standard
Section titled “The standard”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).
| State | Element | Where | Size |
|---|---|---|---|
| play | timer | top 36, centred | 448x173 |
| play | kills (kill modes only) | left 115, top 84 (level with the timer) | skull 78x112 + 64px count |
| play | goals | a centred row, top 239 | cards 180x234, 216 apart, count 45px |
| play | progress (instead of goals) | top 248, centred | 965x71 |
| play | tutorial | centre (0, -555); “Swipe to move” 55px at (0, -355) | 431x232 figure-eight + 150x164 hand |
| play | logo | left 36, bottom 40 | fits 260x140 (wide logo) or 150x150 (square app icon) |
| play | CTA “Play Now” (references/art/CTA_Playnow.png) | right 36, bottom 45 | 356x130 |
| win / lose | veil | the whole screen, black, alpha 0.87 (min 0.8), the game visible under it | |
| win / lose | title | (0, 600) | 900 wide; win “Excellent!”, lose “TIME’S UP!” (a non-timeout loss: the line’s loss art) |
| win / lose | game logo | (0, 0) | fits 1004x646 (wide) or 600x600 (square) |
| win / lose | button | (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.
Use the real UI
Section titled “Use the real UI”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:
bun scripts/cocos-ui-dump.cjs <project>/assets <project>/assets/resources/prefab/UI/GameView.prefabbun scripts/cocos-ui-dump.cjs <project>/assets <project>/assets/scene/MainScene.scene --root UICanvasIt 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.
DOM contract (what the check reads)
Section titled “DOM contract (what the check reads)”- Each piece carries
data-hole-ui:timer,kills,goals,goal-card(one per card),progress,tutorial,tutorial-text,logo,cta, and on the end cardsend(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, exposewindow.__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.
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 winAt 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.
Executed by
Section titled “Executed by”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”.
| Step | Agent |
|---|---|
Run scripts/hole-ui-check.cjs, list the findings per viewport and state | t1k-tester, or the calling agent itself |
Run scripts/cocos-ui-dump.cjs on a line’s prefab or scene | t1k-tester, or the calling agent itself |
Pick sprites, fix the layout, review report.html | the calling agent |
Hard rules
Section titled “Hard rules”- 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.
goalsis the row container; its width depends on the card count, so only its top and centre are checked. Eachgoal-cardis 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.jsonsets the in-game logo to 256x164 at x -376, while the prefab says 450x289: readParameterToolBuild/playable-config.jsonbeside 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.