playablelabs-zero-black-first-load
PlayableLabs: Zero Black Time on First Load
Section titled “PlayableLabs: Zero Black Time on First Load”Applies to every playable (web / three.js, Cocos, none) before delivery. The page shows its loading screen at first paint and keeps it, with a moving bar, until the game is visible. Reference: TimelineUpThreePLA PR #54 (web host).
- The loading screen is page HTML/CSS, not scene content. Put it at the top of
<body>, before the game DOM and script, with its art inlined as data URIs (a separate request is a black frame). - The game bundle starts after that paint. Run the entry chunk from a timer queued inside
requestAnimationFrame, with a timer fallback for tabs that never fire rAF. A synchronous 1.4 MB parse in<body>blocks first paint. - Nothing heavy runs before first paint, and nothing runs in one block. Each pool or prefab step is a yield point (
onLoadStaged); the thread returns to the browser once a step has held it past ~12 ms. Activation order stays the same. - The bar is real progress. Stages own fixed shares (bridge, runtime, asset preload by real count, scene, staged pools, shader warm-up); the value is monotonic. No timed tween stands in for work.
- The splash leaves only when nothing black can show behind it: first frame drawn, shaders warm, every scene cover (parameter-flicker overlay) gone. The scene’s loading view never shows (item 6), so no second bar replays 0 to 100.
- One loading screen: the page splash. The scene’s own loading view never shows while a splash exists; a second screen fading in after the splash is a defect. Dashboard Loading* art, tint, layout and active flags apply to the splash itself, and a replaced image stays hidden until loaded. The splash starts with a
holdclass (stock art hidden) until the params apply; the game releases it right afteradaptSplashToParams, with a ~2.5 s safety release. Mechanism:references/splash-hold.mdin the web-perf skill, when the web module is installed. - Prove it by capture, not by reading code. Screenshot the packed
index.htmlevery few hundred ms from navigation start at 4x CPU throttle: no blank, dark, barless, or stock-art frame before the customer’s art. Also run the packer smoke; a passing unit test is not this proof. Procedure, negative control and hold cost:references/splash-hold.md.
Cocos (3.8 playables): the same five outcomes apply: splash in the build’s HTML template painted before the engine bundle runs, bundle started after paint, bar fed by real assetManager/director.loadScene progress, the scene’s loading node never shown (it only gates the game flow), and customer art applied to the splash itself. The splash starts with the same hold class and is released after the params apply, with the same 2.5 s safety release. Verified on the web host only; port and measure the Cocos path before claiming it.