gameface-driving

Driving a Gameface UI

This skill records the procedure for the game_* tools: the facts the tool schemas cannot tell you. Facts that may be game-specific are labeled; the reference target is Cities: Skylines II (CS2, Cohtml 1.64.0.7). For what the engine itself supports (layout, events, missing platform APIs), load the gameface skill; this one stays operational.

Session start and triage

Screenshot first and orient before acting: menus, dialogs, or a loading screen change what is safe to click. A capture holds the UI view alone: the application's own rendering never reaches it, and every transparent region comes back flat white, so an expanse of white is the normal backdrop of a HUD rather than a blank or broken UI. Read the application's state from what its UI displays, never from the scene behind it. When any tool fails, run game_status before retrying; it settles whether the endpoint is reachable and which engine and page answered. Read the page identity from target.url (for example assetdb://gameui/index.html). A dead endpoint mid-session usually means the game crashed or was closed. Report it and wait for the developer to relaunch the game; retry-looping cannot help, and testing that was interrupted mid-action may have left the UI in a state worth re-checking with a screenshot once the game is back. No reconnect ritual exists or is needed: the server re-resolves the page target on the next call after the game returns.

Finding elements

game_query is the built-in element search; the schema covers its parameters, so what follows is how to read and use it. Text is the durable anchor where the UI shows it and an attribute selector is the one where it does not; attributes: true on a match reveals which attribute the next query should anchor on. Its three counts cascade: unprunedTotal (what the selector and text filter produced), total (after deepest pruning), and returned (after limit); total above returned means the limit truncated, so narrow the query, while unprunedTotal above total just shows how many ancestors deepest pruned. deepest exists because an element's textContent includes its descendants': a panel and its title button both match the title, and deepest prunes the panel; pass deepest: false when you want the enclosing container (finding a panel by its title), and note a query no text drives — a selector alone, or text: '' — has no such bleed to correct. tag: true handles die on the next tagging call and on any view reload; re-tag rather than reusing a stale handle. When a selector is non-unique but the match order is known, the input tools' index parameter is a lighter alternative to tagging; each tool reports Matches: N so you can tell whether the selector was ambiguous, and an out-of-range index reports the match count so you can correct it. Narrow with game_query, then read the one element you settled on with game_dom. For a predicate no selector can express here (computed state, or picking a parent by what its children are, since :has() throws), scan manually from game_eval: [...document.querySelectorAll('button')].find(el => ...), then tag the node with el.setAttribute('data-probe', '1') and target [data-probe] when you need a unique selector, removing it after. There is no XPath, no TreeWalker, and no innerText to lean on (engine gaps; details in the gameface skill). The JS query APIs answer a short set of pseudo-classes and throw "Invalid CSS selector" on the rest: combinators, [attr*=], :first-child, :last-child, :only-child, :nth-child(), :root, :hover, :focus, :active, ::before and ::after are what is verified to work on CS2, and :not(), :has(), :is(), :where(), the of-type family, :nth-last-child(), :empty, :checked and :disabled are verified to throw; treat anything in neither list as untested rather than as supported. :nth-child() itself takes an integer, even, odd, or a bare an step; an an+b offset (n+2, -n+3) throws like an unsupported pseudo-class. Every selector-taking tool names the construct it suspects and a rewrite when it hits the rejection, game_eval and game_debug_evaluate included, falling back to the supported set when it can pin no construct: act on what it names rather than retrying the selector. game_console is the exception, streaming page exceptions as the engine wrote them, so a rejection surfacing there arrives bare.