klyo games: publish HTML5 browser games

The developer's profile card on games.klyo.pl: “about me” and the tagline under the name. YOU WRITE: the owner's assistant, on the owner's own AI plan; klyo runs no model. Without `o_mnie` and `haslo` we return the current card, the released games (the only material you may write from) and the rules. With them, we save through the same check as the studio; an omitted field stays unchanged. Saving changes the developer's public page immediately and replaces the previous text, so FIRST show the text to the owner and save only with their consent. Do not invent facts about the person. Examples: • Write my developer profile card on klyo • Improve the tagline under my name on my developer page • What is in my profile card on games.klyo.pl now?

Take this account's game (`slug`) off the portal. The first call removes it from the catalogue and takes its page down; the address stays yours and you can upload the game there again. A second call on a game that is already taken down removes it from your list for good. Scores and reviews stay attached to the address and are never handed to another game. Use it to clean up after a failed attempt, for example when two entries of the same game ended up in the waiting room. A package that never became a game (only `upload_id` in the waiting room, from klyo_upload_package or klyo_my_games) is deleted with `upload_id` instead of `slug`: its file and preview are removed for good. Examples: • Delete my game neon-coil-arena • Remove the failed entry from the waiting room • Delete the older copy of the same game

Change the CONTENT of a game that is already in the catalogue: name, tagline, description, how to play on a phone and on a computer, round length, genre, shelves, mood, game languages, screen layout, score limit, stage, store links, content questionnaire and age. It does NOT touch the package: replacing files is `klyo_update_game`, which runs the game through the safety check again. A typo in the description should not cost that, which is why these are two tools. LANGUAGES (since 2026-09-18): the description has TWO versions in tags: <en>…</en> in English (REQUIRED, at least 25 words) and <pl>…</pl> in Polish (the owner gets +40 XP for it). Put versions in other languages here only if the developer wrote them personally; what YOU translate goes through klyo_game_translate as a proposal the owner approves in the studio. klyo does not translate on its own account. `jezyk_tekstu` says which language the name, tagline and controls are in. Pass ONLY the fields you change: everything else stays as it is, and the fields you pass replace the current text. Examples: • Add to my game how to play it on a phone • Fix the description of lantern-thief and add an English version • Set the round length to 2 to 5 minutes in slice-rush

Edits a game's text files (html, htm, js, mjs, css, json, svg, txt, xml, webmanifest) without a ZIP. Target: a game's `slug` or a waiting-room package's `upload_id`. The first edit opens a WORKSHOP: a copy of the game next to the version players have, with its own preview address. Players keep playing the previous version until you release the new one (klyo_release_version for a game, klyo_publish_game for a package); the owner sees it in the studio as “New version waiting”. Each item of `edits` has a `path` and one of three: `old_string` with `new_string` (an exact fragment that must occur once, or add `replace_all`), `content` (the whole file or a new file), or `delete: true`. For a file that exists, pass `expected_hash` from klyo_game_files: if someone changed the file in the meantime you get a conflict and nothing is saved. The changes of one call are applied all or none. Every changed file goes through the klyo check (malicious code, third-party ads, nothing from outside klyo), and the whole game once more before release. Send an image, sound, font or large file (up to 20 MB) with the ticket from klyo_upload_package and reference it in the edit with `from_upload` (no base64). GAME FROM SCRATCH: `nowa` (plansza, zrecznosciowa, logiczna) instead of a target creates a package from the Klyo Kit skeleton and applies `edits` right away; the response carries `upload_id`. UNDO: before every edit a checkpoint `auto-N` is created (it is in the response); `revert` goes back to it or to a named `checkpoint`, `discard` abandons the whole workshop for good; players see none of this. Limits: a file from content up to 1 MB, a call up to 256 KB and 20 edits, 3 open workshops per account; a workshop with no changes for 7 days expires, and the version players have stays untouched. Examples: • Change the board colour in style.css of my game czworki • In js/gra.js of slice-rush change the speed from 4 to 6 • Add a levels.json file with three levels to the package in the waiting room

Upload a NEW VERSION of a game that is already on the account (`slug`): from a file (`upload_id` from klyo_upload_package) or from a public `zip_url`. The game keeps its address, name, description, scores and hearts; only the files change. Do not create a second game to ship a fix: that splits players and records between two addresses. A published game does NOT change right away: the new version goes to a waiting room with its own preview address and replaces any version that was already waiting there, including an open workshop from klyo_game_patch; the response carries a measurement of the files (`zmiana`: how much code, visuals and sound changed, new files and texts, and a suggested kind: `poprawka` fix | `funkcja` feature | `interfejs` interface). A game that is not in the catalogue yet gets the new files at once. Then two ways: the owner plays the preview and clicks “Release” in the studio, OR you call klyo_release_version. A clip for the new version is recorded by a person in the studio; the assistant does not record. Examples: • Upload the fixed version of lantern-thief from this address • Replace my game's package with the new one, I fixed a bug • Update the game without changing its address or name

Prepare a browser game for release on games.klyo.pl: the package (`upload_id` from klyo_upload_package, or a public `zip_url`), name, tagline, player description (at least 25 words, about 220 to be indexed by Google), genre from the list, text language and all ten answers of the content questionnaire, exactly what a person fills in in the studio wizard; limits are in the schema (name up to 30 characters, tagline up to 80, lists of genres and moods). Write the description in English (required) and in Polish (earns XP); you translate other languages later with klyo_game_translate and the owner approves them in the studio. We download and check the package (size, files, third-party ads, malicious code, profanity, other companies' brands). IT DOES NOT PUBLISH: the game goes live at its own address `g-<slug>.klyo.pl` in the `oczekuje` (waiting) state until the account owner plays it and clicks “Release to the catalogue”. Do not tell the user the game is published; it is ready to be looked at. We check the package, not the gameplay. If the game shows a white screen, call `klyo_game_diagnostics` with the same `slug`. REQUIRES that the account owner has accepted the developer terms in a browser at https://dev.klyo.pl/ beforehand; the assistant does not sign agreements. PREMIUM REVIEW: for stage `gotowa` (finished) or no stage, pass `przeglad`: seven points (graphics, animation, sound, feedback to player actions, light and dark theme, languages, online), each with evidence; the owner sees it before “Release”, together with the traces found in the code. Examples: • Prepare my game from this ZIP address for release on klyo games • Publish the game “Lantern Thief”, the package is at this link • Upload this package as a game for everyone, with no violence

Write a post in the klyo games community: a question, a request for playtesters, a launch or a game showcase. The post is visible immediately, with no moderation queue, and can be linked to a game from the catalogue (`gra_slug`); then readers get a “play” button. Examples: • Write a post on klyo about my game's launch • Ask for playtesters for my game on klyo games • Add a showcase of lantern-thief to the community

Types fields into the OPEN “New game” form in the developer's studio (dev.klyo.pl); the owner watches them fill in, corrects them and submits the form THEMSELVES. You write, on the owner's own AI plan; klyo runs no model and saves nothing: it is a draft in their browser. Without `pola` you get the list of fields, the allowed genres and moods, the rules and `formularz_otwarty` (whether the form is open). With `pola` we send them live; invalid ones (too long, a genre outside the list, no English description, profanity) come back in `odrzucone` with the reason. You do NOT fill in the content questionnaire, statements or consents: those are the owner's declarations. Send corrections with the same tool. Examples: • Fill in the new game form on klyo • Add the English and Polish descriptions in my game's form • Change the tagline in the form to a shorter one

Game analytics for the developer, read `_najpierw` first: one verdict (`wyrok`, `en.verdict`) and the top tasks with a reason and a fix (`dlaczego`/`jak`, `en.why`/`en.how`). Then: `lejek` = the session funnel the klyo kit records with NO code in the game (wejscie = opened the game page, start = pressed Play, gotowa = klyo.ready() with average load ms for phone and computer, ruch = first real move, gra30 = 30 s of visible play, koniec = round finished (with or without a score), dalej = went on to the next game from the end screen, wynik = reached a score), each step with `sesji`, `telefon`, `komputer` and `odpada` (sessions lost at this step, the answer to WHERE players leave); `poziomy` from klyo.level(n, "start"|"complete"|"fail") with start, koniec (completed) and porazka (fail) per level; `zdarzenia` from klyo.event(name, value) with count and sum; `mapa` = click map on a 24 × 16 grid of the game screen (`komorki` = [cell index, clicks], index = row × 24 + column, separate portrait and landscape) collected by the kit with no code; `sesje` = the latest sessions WITHOUT any person (country, phone or computer, time, play seconds, rounds, score, returning; the player tag is stable only within this game); `kraje` and `rozklad` (how long sessions lasted). Fix what `_najpierw` says (klyo_fix_game, klyo_game_patch, a new version) and ask again after the next players. Read-only. Examples: • Why do players leave my game? • On which level do people quit lantern-thief? • Where do players click in my game, and how long does it load on phones?

Set the tile players recognise the game by in the catalogue. Frames are screenshots FROM YOUR RUNNING GAME: we take them ourselves once the game is live at its own address, so they appear only AFTER release (`klyo_publish_game`), not during it. Call without `klatka` to get the list of available frames with their addresses; show them to the account owner, or look at them yourself and pick one that shows gameplay rather than the title screen. Then call again with its number. We deliberately do not accept a custom image: the cover must show what the player will really see after clicking. Retouched art that does not match the game is a reason for taking the game down. Examples: • Show frames to choose from for the cover of lantern-thief • Set the second frame as my game's cover • My game has no image in the catalogue, fix it

Your game's files to read, without a ZIP from the owner. Target: a game's `slug` or a waiting-room package's `upload_id`. Without `path` you get the list (path, size, whether it is text, `hash`); with `path`, the content of one text file, up to 200 KB at a time (read further with `from_line`, narrow with `lines`); with `changes: true`, what changed in the waiting version compared with the version players have: how much code, visuals and sound (the same numbers the studio shows at “Release”) and the line differences. When the game has a waiting version (a workshop from klyo_game_patch or a new package) you read that one; otherwise the version players are playing. Pass the `hash` field as `expected_hash` to klyo_game_patch. Images and sounds are not returned as content, only their size. Read-only. Examples: • Show the files of my game czworki • Read js/gra.js from lantern-thief starting at line 200 • What changed in the waiting version of slice-rush?

Really play your game and see it: you send input steps, you get screenshots (image content) and the game state. It runs on the OWNER'S device, never on the klyo server: the owner opens the klyo studio (https://dev.klyo.pl/) on a computer or phone and clicks "Allow" under "Your assistant wants to play …" (your call puts that request on the studio, also on one opened within 10 minutes); they see every move and can stop it. Real graphics card, real screen, so 3D games work. Target: `slug` or `upload_id`; you play the same version klyo_game_files reads (the waiting version or package under its preview, otherwise the version players have). The first call opens the game, next calls continue it, `restart` reloads it, `close` ends the session. `steps` run on one timeline of at most 3000 ms: each step starts when the previous one ends, or at `at_ms` to run in parallel (run + turn the camera + jump). Types: key (`key` like KeyW, ArrowUp, Space, Enter, `hold_ms`), click (`x`, `y`, `button`, `count`), tap (`x`, `y`), drag (`x`, `y`, `to_x`, `to_y`, `ms`, `pointer`), move (relative mouse `dx`, `dy`, `ms`, for a mouse-look camera), wheel (`dy`), wait (`ms`), screenshot. Coordinates are fractions 0 to 1 of the game view. Up to 40 steps and 4 screenshots per call (`screenshots` adds them at the end, default 1). Input is synthetic (not trusted events): pointer lock is simulated for mouse-look games. `request_id` makes a retry return the same result without playing twice. `stan`: ok | brak_urzadzenia (ask the owner to open the studio and click "Allow", then call again) | karta_w_tle (the studio tab is hidden and the browser pauses the game) | urzadzenie_nie_odpowiada | zatrzymane (the owner stopped it) | w_toku. Errors from this session: klyo_game_diagnostics with `sesja` = `sesja.znacznik`. Evidence: a play of a waiting version or package in which the game drew at least 10 frames on a hardware graphics card is saved for those exact files (`dowod_urzadzenia` in the answer); klyo_game_diagnostics then lists it under `bramka.sprawdzono_na_urzadzeniu` instead of NIESPRAWDZONA, until the files change. Examples: • Play klyo-blocks: walk forward for a second, look right and take a screenshot • Tap the start button in the middle of my game and show me the first level • Open the waiting version of slice-rush on my phone and swipe left twice

GAME PRODUCTION CONTRACT: CALL THIS FIRST, before you design or write a single line of a game for klyo. Returns the “studio quality” standard: screens (phone, tablet, desktop, portrait and landscape, resize), input (touch, mouse and keyboard), game loop, minimum content, sound, graphics, a catalogue of FREE game assets by genre (CC0 3D models, textures, sounds, fonts with direct download links and a credit line for each; propose a premium version of the game to the user with them), social layer (leaderboard, saves, clips; multiplayer only when it makes sense), brands and law, the LOCAL test `klyo-test` (the same one the server runs on publishing) with a fix-and-test loop, the quality gate and the release stages (preview, demo, finished, new version). The text of the standard is in Polish. Read-only, no parameters. When the user writes “make a battleship game”, do not ask them about phones, leaderboards or sound: it is all here. Do not say “done” until `klyo-test` passes without critical errors. Examples: • Make me a battleship game • What are the requirements for a game on klyo? • Build a puzzle game for phone and desktop • Where can I get free 3D models and sounds for my game?

GAME SKELETON ON KLYO KIT: call after klyo_game_requirements, before you write code. Returns two starter files (index.html, gra.js) to copy and the full kit API: game loop (menu, play and pause, game over, play again), touch, mouse, keyboard and gamepad input as one event, a canvas for any screen with safe areas, synthesized sound with no files (resumed after the app comes back from the background), juice (tweens, shake, particles, flash), light and dark theme, saves across devices, a score to the leaderboard with rank, modes solo, on one device or online by link, PL and EN, accessibility. You write ONLY the gameplay. Read-only. Optional `rodzaj`: `plansza` (board game with turns), `zrecznosciowa` (arcade) or `logiczna` (puzzle, the default). Reference game: Battleships. Examples: • Start a game on Klyo Kit • Give me a game skeleton with a menu, pause and a leaderboard • How do I make an online game that friends join by link on klyo?

Full description of the `klyo-gry-sdk.js` kit: how a game embedded in the catalogue sends a score to the leaderboard, saves progress on the server, asks for full screen, inserts an ad break, offers a REWARDED ad and lets the player record a clip. Read-only, needs no input. CALL THIS RIGHT AFTER klyo_game_requirements, BEFORE YOU WRITE A GAME FOR klyo. Without it you will build a game with no leaderboard, no saves across devices and without the only allowed way to show ads, and the package will bounce off the check if you put another ad network in it. Examples: • How do I add a rewarded ad to a game on klyo? • What can a game embedded in klyo games call? • How do I save player progress across devices?

Visits to the game page and plays, day by day, for the given game (`slug`). Read-only. The developer's share of ad revenue is calculated from this. Examples: • How many people played my game this week? • Stats for lantern-thief • Show plays day by day

Translations of a game's texts into the klyo languages (pl, en, de, fr, es, pt, it, ru, uk, tr). YOU TRANSLATE: the owner's assistant, on the owner's own AI plan; klyo runs no model and does not pay for translation. Two steps in one tool: (1) call with only `slug` to get the original field by field (`oryginal`), the original language, the languages still to do (`do_tlumaczenia`, with their state) and the check rules; (2) call with `slug` and `tlumaczenia` = { language code: { field: text } } with ALL the fields from `oryginal`. Each language goes through the same check as the developer's own text: long dashes and the ellipsis character are replaced with plain ones, no markup, no longer than twice the original, name and tagline on one line up to 80 characters, the text must be in that language, no disallowed words. A language that fails comes back in `odrzucone` with the reason: fix it and send it again; good languages are saved. What is saved are PROPOSALS: the owner approves them in the studio (dev.klyo.pl, the game, Translations) and only approved ones count for Google. Do not tell the user the translations are already on the page. This tool does not change the developer's own texts (English required, Polish for XP); that is klyo_fix_game. PAGE ADDRESS PER LANGUAGE: every language page of the game has its own address in that language (/de/spider-solitaer/, /uk/pasians-pavuk/), never the Polish one. Send `adres` with the language, or we derive it from the translated name; it is approved together with the texts and then stays stable (a later name change does not move it). ORDER: translate BEFORE the release, while the game waits (klyo_publish_game status `oczekuje`) and ask the owner to approve them; then the very first catalogue build has every language ready and indexable. Translations sent after the release leave those language pages for a few minutes as an unchecked machine translation, kept out of Google until approved. Examples: • Translate my game into all klyo languages • What is missing in the translations of lantern-thief? • Add German and French versions of my game's description

Roll a game (`slug`) back to the previous version, the one before the last klyo_release_version. Same move as “Restore” in the studio: the previous version's files are kept next to the current ones and come back with one switch, without uploading; the version we take down stays next to it (rolling back again swaps them). The game's address, scores and stats do not change. Refused with `brak_poprzedniej` when the game has only one version. Use it when the owner reports that a new version breaks the game; then fix locally, run klyo-test, klyo_update_game, klyo_release_version. Examples: • Roll lantern-thief back to the previous version • The new version breaks the game, restore the previous one

Release to players the version waiting after klyo_update_game (`slug`). Same step as the “Release” button in the studio: players get the new version at once (anyone in the middle of a round sees a bar “update or finish the round”), the previous version stays with us, the game page is rebuilt and the developer's followers are notified. You may omit the kind of change (`zmiana`); then we use the one measured from the files. Effect on the clip: `poprawka` (fix): the clip stays; `funkcja` (feature): the clip stays and `nowosc` (one sentence) goes to the feed as “New”; `interfejs` (interface): the old clip leaves the tile and the feed until a person records a new one in the studio (the assistant does not record clips). Release only when the owner has confirmed that they played the new version, or deliberately wants to release it without playing. PREMIUM REVIEW: for any change other than `poprawka`, pass `przeglad` (seven points with evidence, listed in the schema and in klyo_game_requirements); before the swap the whole game goes through the check again. Examples: • Release the new version of lantern-thief, it is a fix • I played it and it works: release the version with the new feature, a daily mode • Release the waiting version of my game

The way to release a game from a file on disk, with no tunnel and without exposing an unreleased game publicly. Returns three things at once: (1) `paczki_w_poczekalni`: packages already on the account that have not become a game yet, each with its `upload_id`; (2) `bilet`: a token valid for one hour ONLY for sending files, which you put in the `Authorization: Bearer` header (it opens no tool; you do not have it in your configuration, which is why you get it here); (3) a recipe: if you have a shell (curl), send the file with the ticket in two HTTP requests; if you do not, ask the owner to upload the ZIP in the studio at https://dev.klyo.pl/ (it lands in the waiting room, nothing is published) and call this tool again: the package will appear in `paczki_w_poczekalni`. Pass the returned `upload_id` to klyo_publish_game or klyo_update_game instead of `zip_url`. Do not save the ticket in project files. Examples: • How do I send a ZIP from my disk to klyo? • Publish this game, the file is on my computer • The owner uploaded a package in the studio, which one should I publish? • I don't want to expose the game publicly, how do I upload the package?

Read `_najpierw` first: one object with what blocks the release (`co`), the parsed error (`komunikat`, `miejsce` file:line, `biblioteka` crate and version, `urzadzenie` device and browser), why (`dlaczego`, `en.why`) and how to fix it (`jak_naprawic`, `en.how_to_fix`). Each raw trace appears once, in `bledy_przegladarki`; `bledy_rozbior[].linia` points into it. Eyes inside the game: for a package in the waiting room (`upload_id`) or a game in the catalogue (`slug`) it returns the files the game asked for that are missing from the package, and the JavaScript errors from the preview in the browser, in the order they happened. Also: the package check result (size, third-party ads, malicious code, missing klyo kit), ready conclusions in `wnioski`, and `dopasowanie`: the fit measurement from publishing on four screens (phone portrait and landscape with touch, tablet, desktop): `uwagi[]` with the codes `przewija` (page scrolls) | `maly_ekran` (screen too small) | `maly_tekst` (text too small) | `ciezka` (too heavy) | `dlugie_wczytanie` (long load) | `niski_fps` (low frame rate) | `male_cele_dotyku` (small touch targets) | `przycisk_bez_nazwy` (button without a name), `dotyk_nasluch` and `zrzut` thumbnails; `null` = the game has not been measured yet (a measurement starts with every version release). VERDICT `bramka.wynik`: POPRAW (fix `krytyczne`), GOTOWA, GOTOWA_BEZ_POMIARU_EKRANOW, NIESPRAWDZONA (the game asked for 3D graphics, WebGL or WebGPU, and the measurement browser has none: the klyo server renders no 3D, so the gameplay was NOT seen; `nie_sprawdzono`, test it on a device with a graphics card) and POMIAR_NIEAKTUALNY (the measurement describes older files, `dopasowanie.aktualny: false`: order `zmierz`). Never report NIESPRAWDZONA or POMIAR_NIEAKTUALNY as ready. GOOGLE: `widocznosc` (game in the catalogue) says whether the game page is in Google search: `w_google: false` with `problemy[]` (`kod` podobny_opis: the page text repeats `z` by `procent` % above `prog` %, so the last catalogue build took the page out of Google with noindex), each with `dlaczego`/`jak_naprawic` and `en.why`/`en.how_to_fix`; with a passing gate the same shows in `_najpierw.google`. A green gate does not mean the page is in Google: rewrite the description in that language (klyo_fix_game) and it returns with the next build. `fps` is the GAME's frame rate, null when the game drew no frame (the page rhythm is in `fps_strony`); `grafika_gry` says what the game asked for, `maszyna.grafika` what the measurement browser can render. A thumbnail overwritten by a later measurement loses `zrzut_adres` (`zrzut_z_innego_pomiaru: true`). Read-only. YOUR BROWSER IS THE EYE HERE: we do not keep a browser farm and do not need one. Open the preview address on YOUR side (Playwright, Chrome, a phone), really play (click, swipe, wait for the second level) and our sensor on that page reports everything that crashed. Then ask with this tool. Order: open, play, ask; the other way round gives an empty answer, because errors are collected only once the game runs. Add `?s=<your marker>` to the address and pass `sesja` with the same value to get only the errors from your own run. NO BROWSER (a conversation in claude.ai or ChatGPT)? Pass `zmierz: true` for a package or a waiting version: we open the preview for you, collect errors and thumbnails of four screens (`zrzut_adres`); one measurement runs at a time per account and one more waits in the queue and starts by itself; 6 per hour, a full measurement counts as two. Add `pelny: true` for the production profile (a slow phone and every declared language). A game with a waiting version (workshop) shows its files, errors and premium review (`przeglad`). Examples: • Why does my game show a white screen? • Check the errors in the package preview • What is missing from the lantern-thief package?

List this account's games in the klyo games catalogue: name, address (slug), state (published, or rejected with the reason), size, visits and plays. Read-only. Call this FIRST to learn the `slug` the other tools need. Examples: • Which games do I have on klyo? • Is my game published yet? • Show the state of my games

State of this connection to klyo: server version, key scope, account role, how many tools you see and whether you may write, plus the state of integrations (Google Search Console, Google Ads, AdMob, and for the owner also Cloudflare), each as `ok`, `not_connected`, `auth_error` or `no_data`, with what to do. Call it at the start of work and before you base a decision on a report whose section may not have loaded. Read-only. Examples: • Is my connection to klyo working and what can I do? • Which integrations are connected? • Which version is the klyo server?