@littlepartytime/sdk 2.2.1 → 2.2.3

package/GAME_DEV_GUIDE.md

@@ -23,10 +23,10 @@ my-game/
 ├── vitest.config.ts       # Test configuration
 ├── tsconfig.json
 ├── assets/                # Game images and custom assets
-│   ├── icon.png           # 1:1 (256x256+) - game list icon
-│   ├── banner.png         # 16:9 (640x360+) - lobby banner
-│   ├── cover.png          # 21:9 (840x360+) - store/featured cover
-│   ├── splash.png         # 9:21 (360x840+) - loading screen
+│   ├── icon.png           # 1:1 (512x512+) - game list icon
+│   ├── banner.webp        # 16:9 (1280x720+) - lobby banner
+│   ├── cover.webp         # 21:9 (1260x540+) - store/featured cover
+│   ├── splash.webp        # 9:21 (1080x2520+) - loading screen
 │   ├── cards/             # Custom game assets (optional)
 │   │   ├── king.png
 │   │   └── queen.png
@@ -76,10 +76,10 @@ const config: GameConfig = {
   name: "My Game",           // Display name (Chinese preferred for CN users)
   description: "...",        // Brief description
   assets: {
-    icon: "assets/icon.png",       // 1:1 game list icon
-    banner: "assets/banner.png",   // 16:9 lobby banner
-    cover: "assets/cover.png",     // 21:9 store/featured cover
-    splash: "assets/splash.png",   // 9:21 loading screen
+    icon: "assets/icon.png",        // 1:1 (512x512+), PNG recommended
+    banner: "assets/banner.webp",   // 16:9 (1280x720+), WebP recommended
+    cover: "assets/cover.webp",     // 21:9 (1260x540+), WebP recommended
+    splash: "assets/splash.webp",   // 9:21 (1080x2520+), WebP recommended
   },
   minPlayers: 2,
   maxPlayers: 6,
@@ -253,12 +253,12 @@ export default function GameRenderer({ platform, state }: GameRendererProps) {
     [platform]
   );
 
-  // Render game UI
+  // Render game UI — use inline styles + CSS variables for consistent styling
   return (
-    <div>
+    <div style={{ color: "var(--text-primary)" }}>
       {/* Your game UI here */}
-      {/* Use Tailwind CSS classes - the platform provides Tailwind */}
-      {/* Use the design tokens from the platform: bg-bg-primary, text-accent, etc. */}
+      {/* Use inline styles with CSS variables from the platform design tokens */}
+      {/* See "Renderer Styling Guide" section below for details */}
     </div>
   );
 }
@@ -594,10 +594,10 @@ The `.zip` upload package contains:
 ├── rules.md       # Game rules
 ├── bundle.js      # Client-side bundle
 ├── engine.cjs     # Server-side engine
-├── icon.png       # 1:1 game icon
-├── banner.png     # 16:9 banner
-├── cover.png      # 21:9 cover
-├── splash.png     # 9:21 splash screen
+├── icon.png|.webp    # 1:1 game icon
+├── banner.png|.webp  # 16:9 banner
+├── cover.png|.webp   # 21:9 cover
+├── splash.png|.webp  # 9:21 splash screen
 └── assets/        # Custom game assets (if any)
     ├── cards/
     │   └── king.png
@@ -657,21 +657,21 @@ export default defineConfig({
 
 Every game must include 4 images in the `assets/` directory. These are validated and packaged by the `pack` command.
 
-| Image | Aspect Ratio | Min Size | Purpose |
-|-------|-------------|----------|---------|
-| `icon.png` | 1:1 | 256x256 | Game list icon |
-| `banner.png` | 16:9 | 640x360 | Lobby banner |
-| `cover.png` | 21:9 | 840x360 | Store/featured cover |
-| `splash.png` | 9:21 | 360x840 | Loading/splash screen |
+| Image | Aspect Ratio | Recommended Size | Purpose |
+|-------|-------------|-----------------|---------|
+| `icon.png` | 1:1 | 512x512 | Game list icon |
+| `banner.png` or `.webp` | 16:9 | 1280x720 | Lobby banner |
+| `cover.png` or `.webp` | 21:9 | 1260x540 | Store/featured cover |
+| `splash.png` or `.webp` | 9:21 | 1080x2520 | Loading/splash screen |
 
 **Rules:**
-- **Formats**: PNG or WebP only
+- **Formats**: PNG or WebP only. Recommendation: use PNG for icon (small, sharp edges), WebP for banner/cover/splash (photo-like content, 60-80% smaller than PNG)
 - **Aspect ratio**: Must match exactly (1% tolerance)
-- **Minimum dimensions**: Must meet or exceed the minimum size
-- **File size**: Warning if any image exceeds 2MB
-- **Paths**: Referenced in `GameConfig.assets` as relative paths from the project root
+- **Dimensions**: Must meet or exceed the recommended size. Exact match preferred; larger with correct ratio also accepted
+- **File size**: Warning if any image exceeds 2MB (WebP typically avoids this even at splash resolution)
+- **Paths**: Referenced in `GameConfig.assets` as relative paths from the project root (e.g., `"assets/banner.webp"`)
 
-The `pack` command reads these images, validates them, and includes them in the zip with canonical names (`icon.png`, `banner.png`, etc.).
+The `pack` command reads these images, validates them, and includes them in the zip with canonical names (`icon`, `banner`, `cover`, `splash`) preserving the original file extension (`.png` or `.webp`).
 
 ### Custom Game Assets
 
@@ -679,10 +679,10 @@ For assets used inside your game UI (card images, sound effects, fonts, etc.), p
 
 ```
 assets/
-├── icon.png          # Platform display images (root level, required)
-├── banner.png
-├── cover.png
-├── splash.png
+├── icon.png          # Platform display images (root level, required, .png or .webp)
+├── banner.webp
+├── cover.webp
+├── splash.webp
 ├── cards/            # Custom game assets (subdirectories)
 │   ├── king.png
 │   └── queen.png
@@ -724,7 +724,7 @@ export default function GameRenderer({ platform, state }: GameRendererProps) {
 | Approach | When to Use | How |
 |----------|-------------|-----|
 | **Inline in bundle** | Tiny assets (< 4KB) | Vite automatically inlines as data URLs |
-| **CSS/SVG** | UI elements, icons | Tailwind CSS utilities or inline SVG components |
+| **CSS/SVG** | UI elements, icons | Inline styles, `<style>` injection, or inline SVG components |
 | **Emoji/Unicode** | Simple visual indicators | Unicode characters directly in JSX |
 
 > **Tip:** Use `platform.getAssetUrl()` for assets 100KB+ instead of inlining them into the bundle.
@@ -822,30 +822,114 @@ interface PlayerState {
 
 ### Renderer Rules
 1. **React functional component**: Use hooks, not class components.
-2. **Tailwind CSS only**: Use the platform's design tokens for consistent styling.
+2. **Inline styles + `<style>` injection**: Do NOT use Tailwind CSS (see "Renderer Styling Guide" below). Use inline styles with CSS variables for layout and theming. Use `<style>` injection for animations and pseudo-classes.
 3. **Mobile-first**: Design for phone screens (375px width). The platform is a PWA.
 4. **No direct socket access**: Only use `platform.send()` and `platform.on()`.
 5. **Chinese UI text**: The platform targets Chinese-speaking users.
 6. **Responsive touch targets**: Buttons should be at least 44x44px for mobile.
 
+### Renderer Styling Guide
+
+**Do NOT use Tailwind CSS in game renderers.** The production platform pre-compiles Tailwind at build time and only scans the platform's own source code — game bundles are loaded dynamically at runtime, so Tailwind utility classes (especially arbitrary values like `w-[280px]`, `text-[18px]`) will silently fail in production even though they work in the dev-kit.
+
+Use **inline styles** as the primary styling method, with **`<style>` injection** for features that inline styles can't express (animations, pseudo-classes, hover states).
+
+#### Inline styles (primary)
+
+```tsx
+// ✅ Use inline styles with CSS variables
+<div style={{ width: 280, height: 60, fontSize: 18, color: "var(--text-primary)" }}>
+
+// ❌ Do NOT use Tailwind classes
+<div className="w-[280px] h-[60px] text-[18px] text-text-primary">
+```
+
+#### `<style>` injection (for animations and pseudo-classes)
+
+```tsx
+const GameStyles = () => (
+  <style>{`
+    @keyframes card-flip {
+      0% { transform: rotateY(0deg); }
+      50% { transform: rotateY(90deg); scale: 1.1; }
+      100% { transform: rotateY(180deg); }
+    }
+    .my-game-card-flip { animation: card-flip 0.6s ease-in-out; }
+    .my-game-btn:disabled { opacity: 0.4; }
+    .my-game-input:focus { outline: none; border-color: var(--accent-primary); }
+  `}</style>
+);
+
+export default function GameRenderer({ platform, state }: GameRendererProps) {
+  return (
+    <div>
+      <GameStyles />
+      <div className="my-game-card-flip" style={{ width: 120, height: 180 }}>
+        {/* card content */}
+      </div>
+    </div>
+  );
+}
+```
+
+> **Tip:** Prefix your CSS class names with your game name (e.g., `my-game-`) to avoid conflicts when multiple games coexist.
+
+#### Why this approach
+
+- **Zero dependencies**: No CSS framework needed
+- **Consistent across environments**: Inline styles work identically in dev-kit and production
+- **No conflicts**: Inline styles are naturally isolated; multiple games won't interfere
+- **More flexible animations**: Native CSS keyframes support multi-stage animations, cubic-bezier curves, and staggered delays — more powerful than Tailwind's preset `animate-*` classes
+
 ### Design Token Reference
 
-Use these CSS variables / Tailwind classes for consistent styling:
-
-| Purpose | CSS Variable | Tailwind Class |
-|---------|-------------|----------------|
-| Page background | `--bg-primary` | `bg-bg-primary` |
-| Card background | `--bg-secondary` | `bg-bg-secondary` |
-| Elevated surface | `--bg-tertiary` | `bg-bg-tertiary` |
-| Primary accent | `--accent-primary` | `text-accent` / `bg-accent` |
-| Primary text | `--text-primary` | `text-text-primary` |
-| Secondary text | `--text-secondary` | `text-text-secondary` |
-| Muted text | `--text-tertiary` | `text-text-tertiary` |
-| Border | `--border-default` | `border-border-default` |
-| Success | `--success` | `text-success` |
-| Error | `--error` | `text-error` |
-| Display font | `--font-display` | `font-display` |
-| Body font | `--font-body` | `font-body` |
+Use these CSS variables in your inline styles for consistent theming:
+
+| Purpose | CSS Variable | Inline Style Example |
+|---------|-------------|---------------------|
+| Page background | `--bg-primary` | `background: "var(--bg-primary)"` |
+| Card background | `--bg-secondary` | `background: "var(--bg-secondary)"` |
+| Elevated surface | `--bg-tertiary` | `background: "var(--bg-tertiary)"` |
+| Primary accent | `--accent-primary` | `color: "var(--accent-primary)"` |
+| Primary text | `--text-primary` | `color: "var(--text-primary)"` |
+| Secondary text | `--text-secondary` | `color: "var(--text-secondary)"` |
+| Muted text | `--text-tertiary` | `color: "var(--text-tertiary)"` |
+| Border | `--border-default` | `border: "1px solid var(--border-default)"` |
+| Success | `--success` | `color: "var(--success)"` |
+| Error | `--error` | `color: "var(--error)"` |
+| Body font (sans-serif) | `--font-body` | `fontFamily: "var(--font-body)"` |
+| Serif font | `--font-serif` | `fontFamily: "var(--font-serif)"` |
+| Display font | `--font-display` | `fontFamily: "var(--font-display)"` |
+
+### Platform Fonts
+
+The platform self-hosts **Noto Sans SC** (sans-serif) and **Noto Serif SC** (serif) via `next/font/google`, available to all games inside the sandbox container.
+
+| CSS Variable | Font | Type |
+|---|---|---|
+| `--font-body` | Noto Sans SC | sans-serif (default — inherited automatically) |
+| `--font-serif` | Noto Serif SC | serif |
+| `--font-display` | Comfortaa | display / title |
+
+Games inherit `--font-body` (Noto Sans SC) by default — no action needed for sans-serif text.
+
+To use the serif font:
+
+```tsx
+<p style={{ fontFamily: "var(--font-serif)" }}>衬线体文本</p>
+```
+
+**Do NOT reference fonts by name.** The platform uses hashed `font-family` names internally, so literal font names will not match the self-hosted font files:
+
+```css
+/* ✅ Works */
+font-family: var(--font-body);
+font-family: var(--font-serif);
+
+/* ❌ Does NOT work — won't match the self-hosted font */
+font-family: 'Noto Sans SC', sans-serif;
+font-family: 'Noto Serif SC', serif;
+```
 
 ## Platform Runtime Constraints
 

package/dist/interfaces.d.ts

@@ -9,13 +9,13 @@ export interface GameState {
     data: Record<string, unknown>;
 }
 export interface GameAssets {
-    /** 1:1 game list icon (relative path from project root, .png or .webp) */
+    /** 1:1 game list icon (512x512+ recommended, .png or .webp) */
     icon: string;
-    /** 16:9 lobby banner */
+    /** 16:9 lobby banner (1280x720+ recommended, .png or .webp) */
     banner: string;
-    /** 21:9 store/featured cover */
+    /** 21:9 store/featured cover (1260x540+ recommended, .png or .webp) */
     cover: string;
-    /** 9:21 loading/splash screen */
+    /** 9:21 loading/splash screen (1080x2520+ recommended, .png or .webp) */
     splash: string;
 }
 export interface GameConfig {

package/dist/interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACtE,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAChF;;;;;;;;;OASG;IACH,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC;IACtC,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC;IACxC,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CAC3B"}
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACtE,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAChF;;;;;;;;;OASG;IACH,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC;IACtC,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC;IACxC,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CAC3B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlepartytime/sdk",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "Game SDK for Little Party Time platform - type definitions and testing utilities",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",