Nộp và phát hành | Tài liệu nhà phát triển WebSuperGames

Quy trình

Bạn chuẩn bị gói nộp và kiểm thử ở chế độ standalone theo trang Kiểm thử.
Bạn gửi gói nộp cho đội vận hành.
Đội vận hành chạy wsg validate và wsg build để kiểm tra tự động, rồi wsg publish để đưa bundle lên Cloudflare R2 và đăng ký phiên bản với portal. Phiên bản mới có thể được đưa lên ở dạng nháp: đã nằm trên origin game nhưng chưa mở cho người chơi.
Đội vận hành duyệt bản chạy thật, rồi đặt nó làm phiên bản hiện tại. Game xuất hiện trên trang chủ, trang thể loại, tìm kiếm, và người chơi bấm Chơi là chạy phiên bản mới.

Cập nhật game đi đúng quy trình trên với một version mới.

Gói nộp

tap-rush/                 tên thư mục trùng slug
├─ game.json
├─ thumbnail.png          512×512, dưới 150 KB
├─ cover.png              tuỳ chọn, 1200×630
└─ dist/                  thư mục build, trùng build.outDir
   ├─ index.html          ở gốc thư mục build
   ├─ game.js
   └─ assets/...

Tên thư mục gốc phải trùng slug trong game.json.
game.json theo tham chiếu, với version chưa từng phát hành. Vì đội vận hành không build lại game của bạn, đặt "build": { "command": "echo prebuilt", "outDir": "dist" }.
thumbnail.png là ảnh hiển thị trong danh sách game: 512×512, tối đa 150 KB, nhìn rõ ở cỡ nhỏ.
Thư mục build đáp ứng Yêu cầu với game: index.html ở gốc, đường dẫn tương đối, SDK nhúng bằng /sdk/v1/wsg-sdk.js, không gọi origin ngoài.
Nén cả thư mục thành một file .zip khi gửi, kèm vài dòng ghi chú phát hành (thay đổi gì, cách chơi, phím điều khiển).

Kiểm tra tự động

wsg validate kiểm tra game.json và ảnh: xem Kiểm tra game.json.
wsg build chạy build.command, rồi kiểm tra: có index.html ở gốc outDir; tối đa 300 file và 20 MB (vượt 3 MB thì cảnh báo); index.html tối đa 200 KB; URL tuyệt đối tới origin lạ trong index.html và file .js (cảnh báo, --strict thì lỗi); cảnh báo nếu index.html không nhúng wsg-sdk.js.
wsg publish làm lại hai bước trên, từ chối nếu version đã có trên origin game, rồi tải bundle và ảnh lên, đăng ký game và phiên bản với portal, và (trừ khi dùng --draft) đặt phiên bản đó làm phiên bản hiện tại.

wsg build với gói ví dụ

$ pnpm wsg build tap-rush
> chạy "echo prebuilt" trong tap-rush
prebuilt
  OK    dist/index.html 1.0 KB
  OK    2 file, 6.7 KB

build: OK (0 lỗi, 0 cảnh báo)

Lưu trữ và đường dẫn

Game được lưu trên Cloudflare R2 và phục vụ từ origin game https://games.leonogames.com:

Đường dẫn	Nội dung	`Cache-Control`
`/<slug>/<version>/…`	Bundle của từng phiên bản, không bao giờ thay đổi	`public, max-age=31536000, immutable`
`/<slug>/media/thumbnail.png`	Ảnh đại diện (và `cover.png` nếu có), bị ghi đè mỗi lần phát hành	`public, max-age=3600`
`/sdk/v1/wsg-sdk.js`	File SDK v1, portal cập nhật bản vá	`public, max-age=3600`

Ảnh trong /<slug>/media/ giữ đuôi của file bạn nộp (thumbnail.png, thumbnail.webp…). Vì cache một giờ, ảnh mới có thể mất tới một giờ mới hiện ở mọi nơi.
Mọi response của origin game có Content-Security-Policy: frame-ancestors <origin portal>: chỉ portal được nhúng game vào iframe. Mở thẳng URL trên trình duyệt vẫn được (game chạy standalone), nhưng trang web khác không nhúng được.
Các header khác: Content-Type theo đuôi file, X-Content-Type-Options: nosniff, Cross-Origin-Resource-Policy: cross-origin.
Bundle tham chiếu SDK bằng đường dẫn gốc /sdk/v1/wsg-sdk.js nên dùng được ở mọi môi trường. Khi chạy thử ngoài portal, lấy SDK từ https://games.leonogames.com/sdk/v1/wsg-sdk.js (xem Kiểm thử).

Phiên bản

Mỗi lần phát hành phải tăng version. Phiên bản đã có sẽ bị từ chối (lỗi 409) và phải tăng version rồi nộp lại.
Phiên bản đã phát hành là bất biến; URL của phiên bản cũ vẫn chạy. Người chơi đang mở trang game tiếp tục với phiên bản đã tải cho tới khi tải lại trang.
Đổi limits, mô tả, tag hay ảnh cũng là phát hành một phiên bản mới, vì chúng nằm trong game.json của từng phiên bản. Phiên chơi tạo sau khi phát hành mới dùng limits mới.
Khi có sự cố, đội vận hành có thể đặt lại một phiên bản cũ làm phiên bản hiện tại, hoặc tạm ẩn game.
Trang game trên portal có thể mất một đến hai phút để chuyển sang phiên bản mới do bộ nhớ đệm.

Duyệt game

Trước khi mở cho người chơi, đội vận hành:

Chạy kiểm tra tự động ở trên và đọc các cảnh báo (đặc biệt là URL tới origin lạ).
Chơi thử trên portal thử nghiệm, trên điện thoại và máy tính: tải nhanh, overlay tải biến mất, điểm được nhận và lên bảng xếp hạng, quảng cáo tạm dừng và tắt tiếng đúng, chuyển tab thì game dừng.
Đối chiếu checklist và xem qua nội dung game.

Các lệnh chạy từ gốc repo, đọc cấu hình từ .env ở gốc (WSG_API_ORIGIN, WSG_ADMIN_TOKEN, WSG_WEB_ORIGIN, WSG_GAMES_ORIGIN, WSG_SDK_URL, WSG_STORAGE_DRIVER và các biến S3_* khi lưu lên R2). Thông tin đăng nhập storage và token admin do đội vận hành cấp, không commit vào repo.

Bash

pnpm wsg validate games/my-game                     # kiểm tra game.json, slug, taxonomy, thumbnail
pnpm wsg build games/my-game --strict               # build và kiểm tra ràng buộc bundle; URL lạ là lỗi
WSG_SDK_URL=/sdk/v1/wsg-sdk.js pnpm wsg publish games/my-game          # validate → build → upload → API
WSG_SDK_URL=/sdk/v1/wsg-sdk.js pnpm wsg publish games/my-game --draft  # tạo phiên bản, chưa mở cho người chơi
pnpm wsg publish games/my-game --no-build           # dùng outDir có sẵn, không chạy build.command
pnpm wsg list                                       # danh sách game và trạng thái
pnpm wsg publish-sdk                                # đưa SDK vừa build lên /sdk/v1/

--mock (với publish và list) dùng một API giả trong bộ nhớ, để thử lệnh mà không đụng tới portal.
wsg publish --draft in ra id của phiên bản để đội vận hành đặt nó làm phiên bản hiện tại sau khi duyệt.
Đặt WSG_SDK_URL=/sdk/v1/wsg-sdk.js khi build game từ template Phaser để bundle tham chiếu SDK bằng đường dẫn gốc.