# Kingdom Cards™ — Facebook Instant Games Edition

**File:** `kingdom-cards-fb-instant-games.zip` — upload this exact ZIP to Meta.
**Measured from the actual ZIP (Oct 27, 2026):**

| | Facebook edition | Website edition | Meta Instant Games limit |
|---|---|---|---|
| Files in bundle | **108** | ~1,035 | max 500 |
| Size (uncompressed) | **11.29 MB** (11,842,107 bytes) | ~84 MB | max 200 MB |
| ZIP size | 10.89 MB (11,415,865 bytes) | — | — |

The website edition at kingdom-cards.pages.dev is **unchanged** — it keeps the
trailer, all 807 recorded narration clips, the Living Scripture videos, and the
QR card images. Everything below applies to the Facebook bundle only.

## What's inside the ZIP (index.html is at the ZIP root)

- `index.html` — the full game (same code as the website) with the Facebook
  edition flag on and the guarded FBInstant bootstrap (SDK v7.0).
- `fbapp-config.json` — Instant Games config (RICH_GAMEPLAY, portrait).
- `icon.webp` — game icon.
- `assets/art/` — all 103 card-art files (kept in full).
- `assets/music/final-stand.mp3` — the Final Stand soundtrack (kept).
- `assets/js/peerjs.min.js` — friends camera/peer library (kept).

## What was cut from the Facebook bundle — and what happens instead

1. **Recorded narration MP3s (807 files, ~32 MB) — NOT shipped.**
   **Narration route taken: device speechSynthesis.** Packing 807 clips into
   audio sprites could not be robustly verified in this build, so the FB
   edition speaks with the device voice — the game's original narration path.
   Screen-guidance lines (welcome, friends, study, rules, versus, results)
   are spoken from a built-in line map; all dynamic narration the game builds
   as text (battle results, teachings, player names, totals) is spoken exactly
   as on the website. Clip-only card audio lines with no mapped line skip
   quietly — the same way a missing clip behaves on the website. No MP3 is
   ever requested in FB mode, so there are no broken audio calls.
2. **Trailer (`trailer.mp4`, 9.8 MB + poster) — dropped.** Marketing, not
   gameplay. The trailer card is hidden in FB mode; poster fallbacks point at
   the kept Armor of God soldier art.
3. **Living Scripture video clips (9 MP4s, ~30 MB) — dropped.** In FB mode
   every "Watch the Moment" slot opens a **still card with its KJV verse**
   ("read the verse together") — never a broken video player. Terrell's own
   YouTube/TikTok links on cards are untouched. The same applies to the
   **Sin Landing** panels (added Oct 27, 2026): in FB mode a landed sin
   card's panel keeps the saying, what it does, its counter and Scripture,
   and the **Watch on TikTok link** — the in-game TikTok embed player is
   website-edition only.
4. **QR PNGs (102 files) — dropped.** QR codes are pointless inside Facebook
   (players are already in the app); the card panel simply omits the QR image
   in FB mode and keeps the card link, collection, and practice actions.

## How Facebook play works

- The game loads the Instant Games SDK **only** when Facebook is plausibly
  the host, and only acts if `FBInstant` really answers: `initializeAsync` →
  `setLoadingProgress` → `startGameAsync`. Outside Facebook (including this
  bundle opened in a plain browser) the game runs exactly like the website,
  with zero errors.
- **Invites:** if the entry-point data carries a room code
  (`data: { room: "XXXX" }`), the player lands in the same Friends invite
  flow the website's `?room=` links use.
- **Sharing:** Share buttons use `FBInstant.shareAsync` (with the room code
  attached) when a live Instant Games session exists, and fall back to the
  normal share sheet with the public link
  (https://kingdom-cards.pages.dev/) everywhere else.

## Upload steps (Meta)

1. Go to **developers.facebook.com** → your app **Kingdom Cards** (the app
   being created for this game) → add the **Instant Games** product if it
   isn't already there.
2. Open **Instant Games → Web Hosting** → **Upload Version** and upload
   `kingdom-cards-fb-instant-games.zip` (do not unzip it first; index.html
   must sit at the ZIP root — it does).
3. When the upload finishes processing, click the **star** on that version
   to push it to production.
4. **Test before anything public:** open the game from the app dashboard's
   test link / in Messenger, play a full solo round and a Friends round with
   a room code, and confirm narration speaks with the device voice.
5. Meta review is required before the game is public — submit for review
   only after the test in step 4 passes. Nothing here has been uploaded or
   submitted yet; that step is Terrell's (or done on his explicit go-ahead).

## Rebuilding this bundle

The bundle is generated from the website `index.html` by a packaging script:
set the edition flag, remove the narration preload + trailer video, drop the
website-only download anchors, swap trailer-poster fallbacks to kept art,
then copy only `assets/art`, `assets/music/final-stand.mp3`,
`assets/js/peerjs.min.js`, `icon.webp`, and `fbapp-config.json`. Re-run it
after any website game update and re-check the file count stays under 500.