klyo SDK для ігор HTML5

Як додати SDK до гри

Один рядок в index.html перед твоїм власним скриптом. Це працює й тоді, коли хтось відкриває гру поза каталогом: виклики не ламаються, а одразу відповідають. Польські назви з попередніх версій (klyo.gotowa, klyo.wynik, klyo.postep, klyo.tablica, klyo.zapis, klyo.przerwa, klyo.nagroda, klyo.pelnyEkran, klyo.obraz) і далі працюють, бо це ті самі функції.

<script src="https://games.klyo.pl/sdk/klyo-gry-sdk.js"></script>

Як повідомити, що гра готова

Виклич це, коли гра завантажилася і в неї можна грати. Сторінка тоді прибере заставку й зупинить індикатор завантаження.

klyo.ready();

Як надіслати результат до таблиці рекордів

Після кожної завершеної партії. Результат іде до таблиці рекордів на сервері й до рекордів гравця, також на другому пристрої, якщо в нього є акаунт. У відповіді є все для фінального екрана: місце за сьогодні разом зі стрибком, за тиждень, за весь час і гравець, що стоїть одразу вище.

klyo.score(1200, (o) => {
  // o.todayRank, o.previousTodayRank (jump),
  // o.weekRank, o.allTimeRank,
  // o.above = { name, score }  → "320 to OpenGamers"
  showEndScreen(o);
});

Як дати гравцеві мету під час партії

Викликай її при кожній зміні рахунку; набір сам обмежує частоту (до 4 разів на секунду). Під грою сторінка показує позначку «#14 · 320 до OpenGamers», а коли когось обганяєш, «↑ #13, ти обганяєш…». Без цього виклику позначки немає; у мережу нічого не йде, це розмова зі сторінкою.

klyo.progress(points);

Як показати двадцять найкращих результатів

Три періоди: день, тиждень, увесь час. Відповідь містить імена гравців, ті самі, що показує спільнота.

klyo.leaderboard.get("day", (t) => {
  showBoard(t.entries);
});

Команди, мапи й запрошення одним посиланням

Ти передаєш у лобі команди й карти, а кімната на сервері їх зберігає: лобі порталу показує колонки команд із вільними місцями (обирає гравець, до повної команди не пустить) і плитки карт (обирає господар кімнати). Посилання-запрошення веде друга просто в кімнату й у команду того, хто його надіслав, тож ви граєте разом. На комп'ютері досить відкрити посилання, на телефоні одного дотику до картки запрошення. Швидка гра підбирає суперників за картою й командою, а з dropIn одразу додає гравців у партію, що вже триває. Сторони й карту бери тільки з room().players[i].team і room().map, ніколи з локального вибору в меню твоєї гри: так двоє гравців, які обидва обрали атаку, точно опиняться в одній команді.

klyo.online.onInvite(() => playOnline()); // player from a link
function playOnline() {
  klyo.online.lobby({ players: 10, mode: "realtime", dropIn: true,
    teams: [{ id: "attack", name: "Attack" }, { id: "defense", name: "Defense" }],
    maps: [{ id: "port", name: "Port", image: "maps/port.webp" }] }, (o) => {
    if (!o.ok) return;
    const me = o.room.players.find((p) => p.who === o.room.me);
    startMatch(o.room.map, me.team, o.room.players);
  });
}

Як сервер стежить за правилами матчу

Правила партії ти записуєш у файл klyo-rules.json у своєму пакеті: скільки разів на секунду гравець може стріляти, скільки набоїв у магазині, що його поповнює і скільки триває перезаряджання, як швидко рухається персонаж і яка найбільша шкода. Ми читаємо файл під час випуску, тож гравець не змінить його в браузері. Сервер партії перевіряє кожну дію, перш ніж її побачать інші гравці, і на резервному з'єднанні теж. Дія, що порушує правила, нікуди не дійде, а твоя гра отримає onReject із причиною. Влучання й очки бери тільки з повідомлень, які несуть дію.

klyo.online.act("shoot", { damage: 36, hit: target });
klyo.online.pos(x, y, z);
klyo.online.onReject((r) => {
  // r.reason: "burst-empty", "locked", "too-fast", "too-far"
  fixAmmo(r);
});
// klyo-rules.json:
// { "online": { "actions": { "shoot": { "perSecond": 10, "burst": 30, "refill": "reload" },
//   "reload": { "lockMs": 2500 } }, "position": { "maxSpeed": 7.5 } } }

Як показати щотижневий турнір

Кожна гра з SDK сама отримує турнір: з понеділка до неділі, без грошових призів, п'єдестал отримує XP (100, 60 і 30), якщо взяли участь щонайменше троє гравців. До таблиці потрапляють лише результати, що пройшли перевірку на чесність. У відповіді є кінець випуску, топ 50, твоє місце й переможці останніх тижнів.

klyo.tournament.get((t) => {
  // t.endsAt, t.entries, t.me = { rank, score },
  // t.winners = [{ edition, name, score }]
  showTournament(t);
});

Як зберігати прогрес між пристроями

До 64 КБ на гравця й гру, зберігається на сервері. Завантажуй на старті, зберігай після важливих змін, а не щокадру.

klyo.save.set({ level: 4, gold: 120 });
klyo.save.get((z) => {
  if (z.ok && z.data) loadState(z.data);
});

Як поставити рекламну паузу в доречному місці

Момент обираєш ти, а не ми. Добре місце: кінець рівня або екран після програшу; погане: посеред бою. Гра чекає на callback, перш ніж іти далі.

klyo.adBreak("between-levels", () => {
  resumeGame();
});

Як додати рекламу з винагородою

Гравець вмикає її кнопкою: подивись і забери бонус. Давай нагороду ТІЛЬКИ тоді, коли у відповіді ok має значення true; false означає, що реклами не було, вона не додивилась до кінця або гравець її закрив.

bonusButton.onclick = () => {
  klyo.rewardedAd((o) => {
    if (o.ok) giveBonus(500);
    else say("Bonus next time.");
  });
};

Як увімкнути повноекранний режим

Браузери дозволяють повний екран лише у відповідь на клік гравця, тож викликай це з обробника кліку, а не після завантаження гри.

klyo.fullscreen();

Як дати гравцям записати кліп із твоєї гри

Один рядок, і гравець отримує на сторінці робочу кнопку запису. Кадри ніколи не перетинають межу вікна: гра сама їх кодує й передає готові байти, тому це працює й на телефонах, де браузери не вміють записувати екран.

klyo.canvas(myCanvas);

Як реагувати, коли сторінка просить тиші

Гравець запускає гру в маленькому вікні за робочим столом і вимикає звук порталу. Сторінка не може заглушити твою гру ззовні (браузер це забороняє), тож вона повідомляє тобі, а ти вирішуєш: вимкнути мікшер, зупинити музику. Без цього виклику нічого не відбувається й нічого не ламається.

klyo.onSound((on) => {
  mixer.mute = !on;
});

Як підлаштувати керування під пристрій

Дотик чи клавіатура, скільки пікселів, без здогадок за шириною екрана. Відповідь: { touch, width, height }.

const d = klyo.device();
if (d.touch) showOnScreenButtons();

Як грати онлайн із кількома людьми

Кімната з кодом із 6 символів, який можна надіслати друзям, або швидкий підбір суперника в межах гри. Сервер стежить за чергою ходів і зберігає ходи, а гра перевіряє правила. Хід або повідомлення займає до 1 КБ, покрокова кімната вміщує до 64 людей, жива до 16. Партія закінчується викликом move з result.winner, що потрапляє в рейтинг перемог (klyo.online.ranking), а швидка гра зводить гравців зі схожим рекордом. У живій кімнаті (mode: 'realtime') send і onMessage ідуть каналом UDP до сервера партій klyo, до 120 повідомлень на секунду; send надсилає байти (Uint8Array), рядок або об'єкт приблизно до 1 КБ, і отримувач дістає той самий тип. Повідомлення send може загубитися дорогою, як будь-який пакет UDP, тож використовуй його для стану, який і так оновлюється. Для події, що мусить дійти (постріл, влучання, підбирання предмета), використовуй klyo.online.act, і в грі без правил теж: SDK надсилає її тричі, а отримувач дістає один раз. klyo.online.net() показує транспорт і пінг. Якщо UDP не проходить, ті самі виклики йдуть резервним з'єднанням (20 на секунду). Ключі відповіді: room.code, room.me, room.host, room.turn, room.players.

klyo.online.quick((o) => {
  if (o.ok) showCode(o.room.code);
});
klyo.online.onStart((r) => begin(r.players, r.turn));
klyo.online.onMove((m) => apply(m.who, m.move));
// when klyo.online.room().turn === klyo.online.room().me:
klyo.online.move({ from: 12, to: 16 });

Як дати гравцям лобі, не пишучи його

Вікно «Грати онлайн» (швидка гра з гравцем зі схожим рекордом, своя кімната з кодом, посилання для друга, список кімнат, що чекають на гравців, найкращі гравці й твій рекорд) малює портал, а не гра. Гра робить один виклик і отримує відповідь, коли починається партія. Посилання з кодом (?pokoj=CODE) відкриває сторінку гри й саме приєднує до кімнати; після оновлення сторінки resume повертає в партію зі списком ходів.

klyo.online.lobby({ players: 2 }, (o) => {
  if (o.ok) begin(o.room);
});

Як мати спільний пул гравців із власним сайтом чи іншим порталом

Ті самі кімнати працюють і поза klyo. На твоїй власній сторінці або на іншому порталі браузерних ігор завантаж наш міст кімнат перед SDK: тоді гра приєднується до кімнат klyo як гість, і її гравці зустрічаються з гравцями klyo в тих самих кімнатах наживо. Міст охоплює кімнати наживо (швидкий матч, приєднання, старт, повідомлення, канал матчу, команди й мапи); покрокові кімнати лишаються на сторінках klyo. Гість не має доступу до акаунта klyo, платежів чи панелі. Результати, збереження й запис працюють лише на сторінках klyo. Спершу твій домен має бути в нашому списку: надішли нам адресу своєї сторінки, і ми її дозволимо.

<script src="https://games.klyo.pl/sdk/klw-mini.js"></script>
<script src="https://games.klyo.pl/sdk/pokoj-most.js"></script>
<script>
  window.klyoMostPokoi = klyoPokojMost({ slug: "your-game", nick: () => playerName });
</script>
<script src="https://games.klyo.pl/sdk/klyo-gry-sdk.js"></script>

Мультиплеєрна гра з власним матч-сервером

Вже маєш сервер (Photon, Colyseus, власний WebSocket) і гру на своєму сайті? Нічого не переносиш: версія на klyo підключається до того самого сервера, тож гравці з klyo і з твого сайту грають у тих самих партіях. Так само працює CrazyGames: зберігає файли гри, а сервер партій тримає розробник. У студії, на останньому кроці майстра «Вміст», вкажи адресу сервера й політику конфіденційності гри; людина з klyo схвалює їх, зазвичай протягом доби. Доти пакет, що підключається до цього сервера, не потрапляє в каталог. Ми дозволяємо лише цю одну адресу і лише в твоїй грі. Умови: гравець на klyo грає як гість (без входу у твої акаунти й без платежів у грі), а гра містить наш SDK (klyo.ready і результати). Сторінка гри повідомляє гравцям, що партії йдуть на твоєму сервері, і посилається на твою політику конфіденційності. Гра з власним сервером працює в браузері; до телефонного застосунку klyo вона поки що не потрапляє.

// no change in the game code: the same address as on your site
const ws = new WebSocket("wss://eu1.your-game.com/ws");
klyo.ready();
// after a match:
klyo.score(points);

Повний приклад: хрестики-нулики онлайн (увесь файл)

Встав в index.html, додай SDK і публікуй. Господар грає за X, сервер пам'ятає, чий хід, а дошка повертається після оновлення сторінки.

<!doctype html>
<meta charset="utf-8">
<script src="https://games.klyo.pl/sdk/klyo-gry-sdk.js"></script>
<div id="board"></div><p id="status"></p>
<script>
var B = document.getElementById("board"), S = document.getElementById("status");
var cells = ["", "", "", "", "", "", "", "", ""], mark = "";
function me() { var r = klyo.online.room(); return r ? r.me : ""; }
function draw() { var h = ""; for (var i = 0; i < 9; i++) h += '<button data-i="' + i + '">' + (cells[i] || "\u00b7") + "</button>"; B.innerHTML = h; }
function won() { var L = [[0,1,2],[3,4,5],[6,7,8],[0,3,6],[1,4,7],[2,5,8],[0,4,8],[2,4,6]];
  return L.some(function (l) { return cells[l[0]] && cells[l[0]] === cells[l[1]] && cells[l[0]] === cells[l[2]]; }); }
B.addEventListener("click", function (e) {
  var i = e.target.getAttribute("data-i"), r = klyo.online.room();
  if (i === null || cells[i] || !r || r.turn !== r.me) return;      // the server keeps whose turn it is; the game checks the rules
  cells[i] = mark; draw();
  klyo.online.move({ i: +i }, won() ? { end: true, result: { winner: r.me } } : null);
});
klyo.online.onStart(function (r) { mark = r.host === me() ? "X" : "O"; cells = ["", "", "", "", "", "", "", "", ""]; draw(); S.textContent = "Playing! You: " + mark; });
klyo.online.onMove(function (m) { if (m.who !== me()) { cells[m.move.i] = mark === "X" ? "O" : "X"; draw(); } S.textContent = m.turn === me() ? "Your move" : "Opponent's move"; });
klyo.online.onEnd(function (z) { S.textContent = z.result && z.result.winner === me() ? "You win!" : "Match over"; });
klyo.ready();
klyo.online.resume(function (r) {                                   // return after a refresh or from a ?pokoj=CODE link
  if (r.ok) { r.moves.forEach(function (m) { cells[m.move.i] = m.who === r.room.host ? "X" : "O"; }); draw(); return; }
  klyo.online.lobby({ players: 2 }, function (o) { if (!o.ok) S.textContent = "Play when you are ready."; });
});
</script>

Як побачити, чому гравці йдуть

Без жодного рядка коду набір klyo записує шість кроків кожної сесії: відвідини сторінки гри, «Грати», завантаження (klyo.ready), перший хід, 30 секунд гри та результат, окремо для телефона й комп'ютера, а ще карту кліків. У студії, у розділі «Результати й оцінки», ти бачиш, на якому кроці люди йдуть і як довго вантажиться гра. Два рядки дають більше: klyo.level(3, "complete") показує, на якому рівні гравці кидають гру, а klyo.event("coins", 50) рахує твої власні події. Твій помічник ШІ отримує те саме через інструмент MCP klyo_game_analytics, разом із завданнями: що виправити й чому. На сервер потрапляють лише числа, жодних персональних даних.

klyo.level(3, "start");     // level 3 started
klyo.level(3, "complete");  // cleared
klyo.level(3, "fail");      // lost
klyo.event("shop_open");
klyo.event("coins", 50);

Як позначити момент, вартий кліпу

Гра найкраще знає, коли стається щось варте показу: комбо, вибух, пройдений рівень, поразка на волосинку. Один виклик ставить позначку на шкалі запису. Редактор кліпів сам виділяє відрізок навколо останньої позначки, тож гравцеві не треба шукати момент посекундно. Рекорд із klyo.wynik має перевагу. Тип: коротке слово без пробілів, дані: невеликий об'єкт для підпису до кліпу. У мережу нічого не йде; без запису позначка просто зникає.

klyo.moment("combo", { streak: 12 });

klyo.league.standings({scope: 'week'}, showBoard);
klyo.league.start(crypto.randomUUID(), resumeRun);
// Keep run and base; retry identical moves after a lost acknowledgement.
klyo.league.moves(run, base, [column], acceptServerState);
klyo.league.finish(run, moveCount, showConfirmedScore);

Як зробити гру для центру рекордів

Що гра отримує безкоштовно. Плитку в центрі рекордів (games.klyo.pl/records/) з рекордом за весь час і п'єдесталом, місце в медальному заліку дня (золото, срібло, бронза за місця 1–3 у кожній грі), запис на живій стрічці «останні рекорди», значок «Лідер дня: X» на плитці в каталозі й сповіщення «X тебе обігнав» для гравців з акаунтом. Одна умова: гра викликає klyo.wynik.

Три виклики, і готово. На старті klyo.ready(), під час партії klyo.progress(points) (позначка «#14 · 320 до X» під грою), наприкінці klyo.score(points, cb), і у відповіді є все для фінального екрана: місце за сьогодні разом зі стрибком, за тиждень, за весь час і гравець одразу вище. Один найкращий результат на пристрій за день: десять партій поспіль не займуть десяти місць.

Межа результату. У студії, у рядку гри, вкажи найвищий результат, який гра може дати. Плитка отримує позначку «межа ✓», а будь-який результат понад межу одразу відхиляється. Без межі таблиця працює, але на плитці написано «без межі», а результат, більший за наступний понад удесятеро (за щонайменше десяти записів), іде «на перевірку». Запис можна видалити в картці гри.

З помічником ШІ (MCP). Підключи klyo до свого помічника й скажи: «додай таблицю рекордів klyo до цієї гри». Інструмент klyo_game_sdk дає йому той самий опис, що й на цій сторінці: виклики, схему старт → прогрес → результат, межу. klyo_update_game завантажує новий пакет.

Покрокова інструкція: як додати таблицю рекордів до гри на HTML5

Чого SDK не робить і чого не можна завантажувати

Твоя гра не може мати власної реклами. Жодної сторонньої мережі: AdMob, AdSense, Unity Ads, AppLovin, ironSource, Poki, CrazyGames чи подібних. Перевірка під час завантаження відхиляє такий пакет і називає знайдену мережу.

Чому. Рекламу показує наша сторінка навколо рамки гри. Так лишається один акаунт видавця, один розрахунок і частка, яку можна перевірити. Два видавці на одній сторінці для Google є недійсним трафіком, за який закривають акаунт: наш, а опосередковано й твій.

Гра не дістає ні до сторінки, ні до сервера. Жодних файлів cookie, жодного акаунта гравця, жодних даних з інших ігор: вона працює на власній адресі й спілкується зі сторінкою лише через ці виклики. Тому ми можемо приймати чужі ігри, не читаючи їхній код рядок за рядком.

Можна перевірити ще до першої реклами. Рекламні паузи й реклама з нагородою працюють у попередньому перегляді й на порталі навіть тоді, коли для гравця немає жодної реклами: замість справжньої сторінка показує короткий екран-заступник, а потім відповідає точно так, як відповість зі справжньою. Тож усю механіку бонусів можна зібрати й перевірити ще до першої копійки.

Що буде, якщо хтось відкриє гру поза klyo

Нічого не ламається. Рекламна пауза повертається одразу, результати й збереження лишаються в браузері, а кліпу просто нікуди піти. Можеш тримати одну збірку для всього; окремий пакет для нас не потрібен.

Klyo Kit: каркас гри студійного рівня

Два теги script і один виклик. Набір дає те, що потрібно кожній студії: меню, паузу, фінальний екран із найкращим результатом і місцем у таблиці рекордів, налаштування (звук, світла чи темна тема, мова), дотик, мишу, клавіатуру й геймпад як одну подію, полотно під будь-який екран із безпечними зонами iPhone, синтезований звук без файлів (відновлюється після повернення з фону), «соковитість» (плавні переходи, тремтіння, частинки, спалахи), збереження між пристроями, режими: сам, на одному пристрої (передай телефон), онлайн за посиланням. Ти пишеш лише ігровий процес.

<script src="https://games.klyo.pl/sdk/klyo-gry-sdk.js"></script>
<script src="https://games.klyo.pl/sdk/klyo-kit.js"></script>
<script>
var gra = klyoKit.start({ nazwa: "My game", tryby: ["solo", "hotseat", "online"], uklad: "oba",
  naStart: function (tryb) { newRound(); } });
var c = gra.plotno(), g = c.getContext("2d");           // full screen, DPR, resize
gra.on("tap", function (d) { /* touch and mouse together */ gra.dzwiek.graj("zbior"); gra.juice.czastki(d.x, d.y); });
gra.koniec({ wygrana: true, wynik: 120 });              // end screen + leaderboard + best
</script>

• Зразкова гра на наборі: Морський бій (сам, на одному пристрої, онлайн за посиланням, ~200 рядків). gra.ai.minimax дає покроковим іграм суперника, а gra.wskazniki обробляє кілька пальців на одному екрані. Решту робить набір.
• Через помічника: klyo_game_scaffold повертає стартові файли й повний API; помічник ніколи не пише меню, паузу чи звук удруге.
• Жодних зовнішніх таблиць стилів і шрифтів: хости ігор мають style-src 'self', тому набір вбудовує свій CSS, використовує системний шрифт, а кольори бере з gra.motyw.paleta.

Гра на будь-якому екрані: що ми вимагаємо і що вимірюємо

Твоя гра отримує весь прямокутник сцени, а в повноекранному режимі весь екран пристрою: на телефоні «Грати» відкриває повний екран тим самим жестом, горизонтальна гра на вертикальному телефоні отримує рамку, повернуту на 90°, і жоден жест не йде до браузера. Тож гра мусить сама підлаштовуватися під будь-які пропорції, від 390×844 до 2400×1560.

• Розкладка під будь-які пропорції. Слухай resize, масштабуй полотно до innerWidth × innerHeight; жодних фіксованих 1280×720 зі смугами.
• Дотик. pointerdown/pointermove або touchstart/touchmove з { passive: false } і preventDefault() на canvas, а також touch-action: none. Сенсорне керування: торкнись і тягни. На телефоні немає наведення курсора, тож прицілювання «рухом без кнопки» там просто не існує. Гра без обробників дотику отримує в студії завдання «лише для комп’ютера».
• Читабельність. Найменший текст ≥ 10 px CSS при ширині 390 px і devicePixelRatio 1.
• Орієнтація під час релізу. Вкажи горизонтальну, вертикальну або обидві, і портал сам попросить повернути пристрій та поверне рамку. Не блокуй орієнтацію в самій грі.
• Звук. Вмикай його після першого жесту гравця; після повернення з фону (iPhone) відновлюй AudioContext у жесті.
• Розмір і час. Перше завантаження на телефонах ≤ 20 МБ, перший кадр гри ≤ 20 с, відносні шляхи.
• Перевір на своєму комп’ютері, перш ніж надсилати. node klyo-test.mjs http://localhost:8080/ my-game ./klyo-test --uklad=pion. Файл /sdk/klyo-test.mjs вимірює рівно те саме, що й ми під час випуску, з тими самими порогами (Node.js 22 + Chrome/Chromium); --uklad це розкладка, яку ти вкажеш під час випуску (pion | poziom | oba). Перед випуском додай --slaby-telefon --jezyki: дешевий телефон (процесор учетверо повільніший, слабка мережа) і та сама гра польською та англійською, з мініатюрою для кожної мови.

Під час випуску ми відкриваємо гру на чотирьох екранах (телефон вертикально й горизонтально з дотиком, планшет, комп’ютер) і вимірюємо: прокручування всередині рамки, частку екрана, яку займає гра, найдрібніший текст, обробники дотику, розмір першого завантаження й час завантаження. Результат із мініатюрами ти бачиш у картці гри в студії, а твій асистент бачить його в klyo_game_diagnostics. Ми не вгадуємо: це те, що бачить гравець.

Що потрібно в пакеті

• Файл index.html у корені ZIP. З нього стартує гра.
• Гра має працювати без завантаження і без реєстрації, у браузері, зокрема на телефонах.
• До 350 МБ. Перевірка дивиться на розмір, відсутні файли, сторонні рекламні мережі та сліди шкідливого коду, приблизно за десяток секунд.
• Анкета про вік, яку ти заповнюєш під час завантаження, дає позначку, від якої залежать видимість гри та її потрапляння в застосунки магазинів.