SDK p2game

Đăng nhập, bảng xếp hạng, lưu tiến trình đám mây và phòng chơi mạng — mà game không bao giờ chạm vào thông tin đăng nhập của người chơi.

Mô hình bảo mật

Game chạy trong iframe trên một tên miền riêng và không giữ token của người chơi. SDK gửi yêu cầu qua postMessage tới khung nền tảng; khung đó mới là nơi cầm phiên đăng nhập và gọi API. Ba hệ quả đáng chú ý:

  • · Một game bị chèn mã độc vẫn không lấy được danh tính người chơi.
  • · Điểm số không bịa được bằng cách gọi thẳng API: mỗi ván có một phiên do nền tảng cấp, có hạn dùng.
  • · Game không cần và không được tự dựng biểu mẫu đăng nhập.

Cài đặt

Cách đơn giản nhất là nhúng bản UMD, phục vụ ngay từ cùng origin với game nên không vướng chính sách bảo mật:

<!-- Nhúng trực tiếp, không cần bundler -->
<script src="https://games.p2game.io/sdk/p2game-sdk.v1.js"></script>
<script src="game.js"></script>

Nếu bạn dùng bundler:

npm install @p2game.io/sdk

import { p2 } from "@p2game.io/sdk";

Gói còn hai lối vào phụ. Làm game bình thường thì không cần tới chúng.

import { p2 } from "@p2game.io/sdk";

// Định nghĩa giao thức postMessage — hằng số và kiểu dữ liệu.
// Chỉ cần khi bạn tự dựng công cụ quanh giao thức.
import { SDK_PROTOCOL_VERSION } from "@p2game.io/sdk/protocol";

// Nửa còn lại của giao thức, dành cho khung nhúng game.
// Nền tảng dùng lối vào này; game của bạn thì không.
import { HostBridge } from "@p2game.io/sdk/host";

// Luật phòng chơi mạng dạng hàm thuần — máy chủ phòng và chế độ giả lập
// cùng dùng. Chỉ cần khi bạn muốn tự kiểm thử logic quanh phòng.
import { joinRoom, setRoomState } from "@p2game.io/sdk/room-core";

Khởi động

// Gọi sớm nhất có thể, trước khi nạp tài nguyên nặng.
const ctx = await p2.init();

console.log(ctx.player);       // null nếu người chơi chưa đăng nhập
console.log(ctx.leaderboards); // các bảng đã khai trong p2game.json

// Khi khung hình đầu tiên đã vẽ xong — nền tảng gỡ màn hình chờ.
p2.ready();

init() nhận ba tuỳ chọn, cả ba đều có mặc định hợp lý:

await p2.init({
  // Thời gian chờ bắt tay với khung nền tảng. Mặc định 10 giây.
  timeoutMs: 10_000,

  // Cho phép chạy ngoài khung nền tảng. Mặc định BẬT, nên khi mở thẳng
  // index.html lúc phát triển, SDK tự giả lập và lưu vào localStorage.
  // Đặt false nếu muốn game báo lỗi thay vì chạy ở chế độ giả lập.
  allowStandalone: true,

  // In log giao thức ra console khi gỡ lỗi tích hợp.
  debug: false,
});
Quên gọi p2.ready() thì nền tảng phải hiển thị màn hình chờ cho tới khi hết thời gian, và bước chạy thử sẽ ghi cảnh báo SD-004.

Bảng xếp hạng

Bảng phải được khai trong p2game.json trước. Máy chủ kiểm bốn lớp trước khi nhận điểm: phiên chơi hợp lệ, điểm không vượt maxScore, ván đủ dài theo minSessionSeconds, và không vượt hạn mức tần suất.

// Gửi điểm khi kết thúc ván
const result = await p2.leaderboard.submit("high-score", score, {
  level: currentLevel,       // siêu dữ liệu tuỳ ý, tối đa 1 KB
});

if (result.improved) {
  p2.ui.toast(`Kỷ lục mới: ${result.personalBest}`, "success");
}

// Đọc bảng xếp hạng
const top = await p2.leaderboard.top("high-score", { limit: 10, window: "WEEKLY" });
const near = await p2.leaderboard.aroundMe("high-score", { range: 3 });

Đăng nhập

const player = await p2.auth.getUser();

if (!player) {
  // KHÔNG tự dựng form đăng nhập. Nền tảng sẽ mở hộp thoại của nó.
  const loggedIn = await p2.auth.requestLogin();
}

p2.auth.onChange((player) => {
  updateHud(player?.displayName ?? "Khách");
});

Lưu tiến trình đám mây

Tối đa 32 khoá cho mỗi người chơi mỗi game, 64 KB một khoá, tổng 512 KB. Cần khai quyền persistent-storage và bật sdk.cloudSave.

// Lưu tiến trình, đồng bộ giữa mọi thiết bị của người chơi
await p2.storage.set("progress", { level: 7, coins: 1280 });

const saved = await p2.storage.get("progress");
const keys = await p2.storage.keys();
await p2.storage.remove("progress");

Vòng đời

p2.onPause(() => engine.pause());     // người chơi chuyển tab
p2.onResume(() => engine.resume());
p2.onBeforeUnload(() => saveNow());   // cơ hội cuối để lưu

p2.gameOver({ score, level });        // kết thúc một ván

Phòng chơi mạng

Từ SDK 1.1, game tạo được phòng thời gian thực cho nhiều người chơi mà không cần máy chủ riêng hay quyền external-network. Nền tảng chỉ chuyển tiếp: giữ danh sách người trong phòng, hai vùng trạng thái dùng chung và chuyển thông điệp. Logic game vẫn chạy ở máy người chơi — thường chủ phòng làm trọng tài, vì chỉ chủ phòng ghi được trạng thái phòng.

// p2game.json
"sdk": { "version": "1.1" },
"multiplayer": {
  "maxPlayers": 4,       // 2–16 người mỗi phòng
  "requiresAuth": false  // bật nếu game có chat giữa người chơi
}
// Ghép vào một phòng công khai còn chỗ, không có thì tạo mới
const room = await p2.rooms.quickMatch({ filter: { mode: "2v2" } });

// …hoặc tạo phòng riêng rồi đưa mã cho bạn bè
const mine = await p2.rooms.create({ maxPlayers: 2, visibility: "private" });
showInviteCode(mine.code);                 // ví dụ "K7QM2X"
const joined = await p2.rooms.join("k7qm2x"); // không phân biệt hoa thường

// Thông điệp: nhanh, không lưu lại — dùng cho di chuyển, bắn, chat
room.send("move", { x, y });
room.send("whisper", { text: "gg" }, { to: otherPlayerId });
room.on("move", (msg) => moveGhost(msg.from, msg.data));

// Trạng thái phòng: chỉ chủ phòng ghi, ai vào sau cũng thấy ngay
if (room.isHost) await room.setState({ phase: "playing", seed: 42 });
room.onStateChange(({ state }) => applyPhase(state.phase));

// Trạng thái riêng của từng người (tối đa 4 KB)
await room.setPlayerState({ ready: true, team: "red" });

room.onPlayerJoin((p) => addAvatar(p));
room.onPlayerLeave(({ player, reason }) => removeAvatar(player.id));
room.onHostChange(({ isHost }) => isHost && becomeReferee());
room.onConnection((s) => showBanner(s === "reconnecting"));

if (room.isHost) await room.lock();   // ván bắt đầu, không nhận thêm người
await room.leave();

Mỗi thay đổi — kể cả do chính bạn gây ra — chỉ áp vào room.state và room.players khi máy chủ phát lại, nên mọi máy thấy các thay đổi theo đúng một thứ tự. Rớt mạng dưới 15 giây thì ghế được giữ và phòng tự đồng bộ lại khi nối lại; chủ phòng rời đi thì quyền chủ chuyển cho người vào sớm nhất còn kết nối. Mỗi người chơi chỉ ngồi một phòng trong một game — vào từ tab khác thì tab cũ nhận onClose với lý do replaced.

Vào phòng

p2.rooms.quickMatch({ filter?, maxPlayers? })Vào một phòng công khai, chưa khoá, còn chỗ, có metadata khớp đúng mọi khoá của filter. Không có thì tạo phòng công khai mới với metadata = filter.
p2.rooms.create({ maxPlayers?, visibility?, metadata?, state? })Tạo phòng và làm chủ phòng. maxPlayers mặc định bằng giá trị trong manifest; visibility "public" (mặc định) hoặc "private" — phòng riêng chỉ vào được bằng mã.
p2.rooms.join(code)Vào phòng bằng mã mời 6 ký tự, không phân biệt hoa thường.
p2.rooms.list({ filter? })Tối đa 50 phòng công khai còn chỗ, mới nhất trước. Mỗi dòng: id, code, playerCount, maxPlayers, metadata, createdAt.
p2.rooms.current()Phòng đang ở, hoặc null. Vào phòng khác khi đang ở một phòng thì lỗi CONFLICT.

Thuộc tính của room

id, codeĐịnh danh phòng và mã mời để chia sẻ.
selfId, selfId và thông tin của chính mình trong phòng. Khách chưa đăng nhập có id dạng guest-…
hostId, isHostChủ phòng hiện tại — người duy nhất ghi trạng thái phòng, khoá phòng, mời người khác ra.
players, player(id)Danh sách người theo thứ tự vào phòng. Mỗi người: id, displayName, avatarUrl, anonymous, joinedAt, connected, state.
stateTrạng thái phòng dùng chung (chỉ đọc; đổi bằng setState).
metadata, maxPlayers, visibility, lockedThông tin phòng. metadata đặt lúc tạo, dùng để lọc khi ghép.
closedtrue sau khi rời phòng, bị mời ra hoặc mất ghế.

Thao tác trên room

send(type, data?, { to? })Gửi thông điệp cho cả phòng trừ mình, hoặc chỉ cho id / danh sách id trong to. type 1–32 ký tự; data tối đa 8 KB. Không lưu lại — người vào sau không nhận.
setState(patch)Chỉ chủ phòng. Gộp các khoá vào state; khoá mang null bị xoá. Tổng tối đa 32 KB.
setPlayerState(state)Thay toàn bộ trạng thái riêng của mình, tối đa 4 KB.
lock(locked = true)Chỉ chủ phòng. Phòng khoá không nhận thêm người và biến khỏi danh sách ghép.
kick(playerId)Chỉ chủ phòng. Người bị mời nhận onClose với lý do kicked.
leave()Rời phòng. Mình là chủ thì quyền chủ chuyển cho người vào sớm nhất còn kết nối; mình là người cuối thì phòng bị xoá.

Sự kiện của room

on(type, fn) · on("*", fn)Thông điệp { type, data, from, at }. at là giờ máy chủ nhận (ms), dùng để sắp thứ tự, không dùng làm đồng hồ game.
onPlayerJoin(fn)Người mới vào — nhận thông tin người chơi. Không bắn cho chính người vừa vào.
onPlayerLeave(fn){ player, reason } với reason: left (tự rời), kicked (bị mời ra), timeout (rớt mạng quá 15 giây).
onPlayerUpdate(fn)Một người đổi trạng thái riêng, hoặc rớt mạng / nối lại (trường connected).
onStateChange(fn){ state, changes, by } — state là toàn bộ trạng thái mới, changes là phần vừa đổi (null = đã xoá), by là id người ghi.
onHostChange(fn){ hostId, isHost } khi quyền chủ phòng chuyển sang người khác.
onUpdate(fn)Phòng được khoá/mở, hoặc vừa đồng bộ lại toàn bộ sau khi nối lại mạng.
onConnection(fn)Đường truyền của chính mình: connecting, open, reconnecting, closed. Nên hiện thông báo khi reconnecting.
onClose(fn){ reason }: left, kicked, expired (rớt mạng quá lâu), replaced (vào lại từ tab/thiết bị khác).

Mọi hàm on… trả về một hàm huỷ đăng ký. Trình nghe tự bị gỡ khi phòng đóng.

Mã lỗi thường gặp

NOT_FOUNDKhông có phòng mang mã này, hoặc phòng vừa tan.
ROOM_FULLPhòng đã đủ người.
FORBIDDENPhòng đã khoá; không phải chủ phòng; chưa ở trong phòng; hoặc game chưa khai multiplayer.
UNAUTHENTICATEDManifest bật multiplayer.requiresAuth mà người chơi chưa đăng nhập.
CONFLICTĐang ở một phòng khác — gọi leave() trước.
INVALID_ARGUMENTTham số sai: maxPlayers ngoài khoảng, metadata không phải chuỗi/số/boolean, type thông điệp quá dài…
QUOTA_EXCEEDEDThông điệp hoặc trạng thái vượt hạn mức kích thước.
RATE_LIMITEDGửi quá nhanh (khoảng 30 thao tác mỗi giây, dồn tối đa 60). Có retryAfterMs.
UNAVAILABLEMất kết nối tới máy chủ phòng. SDK tự nối lại; thao tác thì nên thử lại sau.
Hạn mức: thông điệp tối đa 8 KB, khoảng 30 thông điệp mỗi giây (dồn tối đa 60), trạng thái phòng 32 KB, trạng thái mỗi người 4 KB. Dùng send() cho những gì thay đổi liên tục như vị trí; để setState() cho những gì người vào sau cần biết.

Xử lý lỗi

Mọi lỗi từ SDK là P2GameError với trường code ổn định.

try {
  await p2.leaderboard.submit("high-score", score);
} catch (err) {
  switch (err.code) {
    case "UNAUTHENTICATED": promptLogin(); break;
    case "SCORE_REJECTED":  console.warn(err.message); break;
    case "RATE_LIMITED":    retryAfter(err.retryAfterMs); break;
    default:                console.error(err.message);
  }
}

// Mã riêng của phòng chơi mạng
try {
  await p2.rooms.join(code);
} catch (err) {
  switch (err.code) {
    case "NOT_FOUND":   showError("Không có phòng mang mã này."); break;
    case "ROOM_FULL":   showError("Phòng đã đủ người."); break;
    case "FORBIDDEN":   showError("Phòng đã khoá."); break;
    case "CONFLICT":    await p2.rooms.current()?.leave(); break; // đang ở phòng khác
    case "UNAVAILABLE": retryLater(); break;                     // mất kết nối máy chủ phòng
  }
}

Chạy thử khi chưa lên nền tảng

Khi mở game ngoài khung nền tảng (ví dụ chạy dev server ở máy bạn), SDK tự chuyển sang chế độ giả lập: điểm số và cloud save lưu vào localStorage, mọi lời gọi vẫn trả về đúng hình dạng dữ liệu. Bạn không phải viết nhánh mã riêng cho lúc phát triển.

Phòng chơi mạng cũng được giả lập: mở game ở hai tab cùng trình duyệt là có hai người chơi thử trong cùng một phòng, nói chuyện qua BroadcastChannel và áp đúng luật của máy chủ thật. Đóng tab tạo phòng thì phòng đóng theo.

Tắt bằng p2.init({ allowStandalone: false }) — khi đó mở ngoài khung nền tảng sẽ ném lỗi thay vì chạy giả lập. Hữu ích nếu bạn muốn chắc chắn không vô tình phát hành một bản build chỉ chạy được ở chế độ giả lập.