Koin dan toko di dalam game

Koin adalah mata uang arcade. Satu saldo mengikuti pemain lintas game, jadi yang dia kumpulkan di game balapan bisa dibelanjakan di game puzzle. Gamemu tidak mencetak atau menyimpan koin; dia minta arcade yang memindahkannya.

Dari mana koin pemain datang

Tidak ada satu pun tindakan gamemu yang memberi koin, dan bermain pun tidak dibayar: dari sebuah game, koin sampai ke pemain hanya lewat papan peringkatnya. Skor tinggi tidak membayar langsung; dia membayar saat masuk peringkat.

Menjual sesuatu dengan koin

Dua langkah: daftarkan daftar harganya, lalu panggil buy().

1. Daftarkan katalognya

Harga tinggal di server, tidak pernah di bundle-mu. Deklarasikan seluruh daftarnya lewat server MCP:

update_game(game: 'rosok-garage', shop: [
  { sku: 'engine_lv2', title: 'Mesin Lv2', coin_price: 800 },
  { sku: 'paint_gold',  title: 'Cat emas',  coin_price: 400 },
  { sku: 'fuel',        title: 'Bensin',    coin_price: 150, type: 'consumable' },
])

atau lewat Harness API kalau kamu menulis skripnya sendiri.

shop mengganti daftarnya sekaligus. Sku yang kamu tinggalkan dinonaktifkan, bukan dihapus, jadi pemain yang sudah membelinya tetap punya nama untuk ditampilkan. Kolomnya:

2. Beli dari dalam game

const { items } = await taploka.shop();
// [{ sku: 'engine_lv2', title: 'Mesin Lv2', coin_price: 800, type, owned: false, qty: 0 }]

try {
    const { item, balance } = await taploka.buy('engine_lv2');
    unlockEngine(item.sku);
    showBalance(balance);
} catch (error) {
    if (error.code === 'INSUFFICIENT_BALANCE') {
        showTopUpHint();
    }
}

Kamu mengirim sebuah sku dan tidak ada yang lain. Arcade membaca harganya dari katalog, memotong dompet, dan mencatat itemnya, semua dalam satu transaksi: pemotongan yang gagal tidak memberi apa pun, dan item yang diberikan sudah pasti dibayar.

3. Baca kepemilikan saat start-up

const { items } = await taploka.inventory();   // [{ sku, qty, granted_at }]

Lakukan ini, jangan percaya cloud save-mu. Save ditulis klien dan bisa diedit; inventori tidak. Pakai save untuk progres, inventori untuk kepemilikan.

Error yang perlu ditangani

Percobaan ulang dan dobel tap

Setiap pembelian bersifat idempoten. Host melampirkan kunci untukmu, jadi permintaan yang timeout lalu diulang tetap dipotong sekali. Kalau kodemu sendiri bisa menembakkan pembelian yang sama dua kali, kirim kunci stabil buatanmu:

await taploka.buy('fuel', { key: `fuel-${runId}` });

Dua pembelian dengan kunci yang sama dihitung satu pemotongan. Item non-consumable ditolak dengan ITEM_OWNED apa pun kuncinya, jadi dobel tap karena tidak sabar tidak akan pernah membayar dua kali.

Memotong tanpa item katalog

Untuk pemotongan yang bukan item terdaftar, potong langsung:

const { balance } = await taploka.spend(50, 'continue', { key: `continue-${runId}` });

reason adalah slug pendek yang ditampilkan di riwayat dompet. Pakai ini untuk konsumsi yang tidak bisa diwakili entri toko, misalnya membayar untuk melanjutkan ronde. Dia tidak memberi apa pun, jadi apa yang dibeli pemain jadi urusanmu untuk diingat. Utamakan buy() kalau cocok: hanya buy() yang mendapat harga sisi server dan catatan kepemilikan yang tidak bisa diutak-atik.

Membaca saldo

const { balance, earned, spent } = await taploka.wallet();

Tampilkan kalau tokomu punya layar. Jangan cache lintas sesi: misi dan hadiah bisa mengkredit pemain saat dia masih bermain.

Apa yang kamu dapat, dan cara mencairkannya

Setiap koin yang dibelanjakan pemain di gamemu memberimu bagi hasil, 70% secara default, dikreditkan ke dompetmu sebagai berlian dalam transaksi yang sama dengan penjualannya, jadi sudah ada di sana sebelum animasi di layar pemain selesai. Membeli dari gamemu sendiri tidak membayar apa-apa: bagi hasilnya akan langsung kembali dan itemnya jadi gratis.

Panel developer-mu menampilkannya di Pendapatan: berapa yang sudah dibayarkan tiap game, berapa yang siap dicairkan, dan kursnya.

1.000 koin item  →  700 berlian buat kamu  →  Rp1.400 dengan kurs Rp2 per berlian

Pencairan adalah permintaan yang diproses administrator secara manual. Tidak ada transfer otomatis:

1. Kamu mengajukan sejumlah nominal, minimal batas bawahnya (50.000 berlian secara default), dengan rekening bank atau e-wallet.
2. Berliannya langsung keluar dari dompetmu. Penahanan itulah yang mencegah saldo yang sama diajukan dua kali.
3. Admin melakukan transfernya dan menandai lunas, atau menolaknya. Penolakan mengembalikan berliannya langsung.

Dua aturan yang perlu kamu tahu sebelum merencanakan sesuatu di atasnya:

• Hanya berlian yang bisa dicairkan. Koin yang kamu beli, menangkan dari misi, atau kumpulkan dari main boleh kamu belanjakan, tapi tidak bisa dijual balik. Arcade membeli kembali apa yang dia bayarkan ke kamu, tidak lebih.
• Berlian bukan koin. Saldonya terpisah dari koinmu dan tidak bisa dibelanjakan di game mana pun: hanya bisa dicairkan atau dipakai mendanai kampanye klip. Gaji moderator dan bayaran klip TikTok juga masuk sebagai berlian.

Kursnya ditentukan arcade dan disalin ke tiap permintaan saat kamu mengajukannya, jadi perubahan kurs tidak pernah menghargai ulang pencairan yang sudah menunggu.

Tamu

Pemain yang belum masuk tetap mengumpulkan dan membelanjakan seperti biasa, dan semua yang dia beli pindah ke akunnya begitu dia mendaftar. Jangan kunci toko di balik login. Yang tidak bisa dilakukan tamu adalah masuk papan peringkat dan membeli paket koin dengan uang.