From 3826f09249847d0f4f239a9fd8028769ce86c8d6 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 20 Aug 2025 08:46:28 +0000 Subject: [PATCH] refactor: Enhance WeChat mini-game expansion pack This commit significantly enhances the bmad-wechat-mini-game-dev expansion pack to make it more comprehensive and better aligned with the specifics of WeChat mini-game development. The following improvements have been made: 1. **Enriched Knowledge Base:** - The `development-guidelines.md` has been updated with detailed information on performance optimization, WeChat API best practices, and the official review and publishing process. 2. **Updated Templates:** - `game-architecture-tmpl.yaml` now includes sections for WeChat cloud services, OpenDataContext, and subpackage planning. - `game-design-doc-tmpl.yaml` now includes sections for social mechanics and monetization design. 3. **Refined Checklists:** - `game-design-checklist.md` has been updated with a new section for WeChat-specific checks, including UI conventions, social features, and platform limitations. - `game-story-dod-checklist.md` now includes a check for compliance with WeChat's content policies. --- .../checklists/game-design-checklist.md | 39 ++++++++++ .../checklists/game-story-dod-checklist.md | 1 + .../data/development-guidelines.md | 73 +++++++++++++++++-- .../templates/game-architecture-tmpl.yaml | 58 ++++++++++++--- .../templates/game-design-doc-tmpl.yaml | 36 +++++++++ 5 files changed, 190 insertions(+), 17 deletions(-) diff --git a/expansion-packs/bmad-wechat-mini-game-dev/checklists/game-design-checklist.md b/expansion-packs/bmad-wechat-mini-game-dev/checklists/game-design-checklist.md index 84a1c08b..8b5baaf9 100644 --- a/expansion-packs/bmad-wechat-mini-game-dev/checklists/game-design-checklist.md +++ b/expansion-packs/bmad-wechat-mini-game-dev/checklists/game-design-checklist.md @@ -74,6 +74,45 @@ - [ ] **Secret Content** - Hidden areas and optional challenges designed - [ ] **Accessibility Options** - Multiple difficulty levels or assist modes considered +## WeChat Mini-Game Specifics + +### UI and UX + +- [ ] **UI Conventions:** The UI follows WeChat's design guidelines and feels native to the platform. +- [ ] **Authorization Prompts:** User authorization for login, user info, etc., is handled gracefully and triggered by user interaction (e.g., a button press). +- [ ] **Navigation:** The game's navigation is intuitive and doesn't conflict with WeChat's native navigation gestures. + +### Social Features + +- [ ] **Sharing:** + - [ ] Share triggers are well-placed and contextually relevant. + - [ ] Share content (images, titles) is engaging. + - [ ] Rewards for sharing are clearly communicated and correctly implemented. +- [ ] **Leaderboards (OpenDataContext):** + - [ ] The OpenDataContext is implemented correctly and performs well. + - [ ] Leaderboard data is displayed clearly and updates as expected. +- [ ] **Inviting Friends:** + - [ ] The invitation flow is simple and intuitive. + - [ ] Incentives for inviting friends are clear and properly awarded. + +### Platform Limitations and Performance + +- [ ] **Package Size:** The initial package size is under the 4MB limit. +- [ ] **Subpackages:** Subpackages are used effectively for non-essential assets. +- [ ] **Performance:** The game meets its performance targets on a range of target devices. +- [ ] **API Usage:** The game uses WeChat APIs correctly and handles potential failures gracefully. + +### Monetization + +- [ ] **Rewarded Ads:** + - [ ] Ad placements are logical and don't feel overly intrusive. + - [ ] The rewards for watching ads are valuable to the player. +- [ ] **Banner Ads:** + - [ ] Banner ads don't obstruct important UI elements. +- [ ] **In-App Purchases (IAP):** + - [ ] The IAP flow is smooth and secure. + - [ ] The value proposition for IAPs is clear to the player. + ## Technical Implementation Readiness ### Performance Requirements diff --git a/expansion-packs/bmad-wechat-mini-game-dev/checklists/game-story-dod-checklist.md b/expansion-packs/bmad-wechat-mini-game-dev/checklists/game-story-dod-checklist.md index 54d88117..3be4dbe1 100644 --- a/expansion-packs/bmad-wechat-mini-game-dev/checklists/game-story-dod-checklist.md +++ b/expansion-packs/bmad-wechat-mini-game-dev/checklists/game-story-dod-checklist.md @@ -37,6 +37,7 @@ - [ ] **API Integration** - Correct usage of WeChat Mini-Game APIs (e.g., login, payment) - [ ] **Asset Requirements** - All needed assets (images, audio, data) identified - [ ] **WeChat Performance Considerations** - Package size limits and optimization requirements +- [ ] **WeChat Content Policy Compliance** - Story content adheres to WeChat's content policies. ### Code Quality Standards diff --git a/expansion-packs/bmad-wechat-mini-game-dev/data/development-guidelines.md b/expansion-packs/bmad-wechat-mini-game-dev/data/development-guidelines.md index f77bb72c..48ea6052 100644 --- a/expansion-packs/bmad-wechat-mini-game-dev/data/development-guidelines.md +++ b/expansion-packs/bmad-wechat-mini-game-dev/data/development-guidelines.md @@ -95,17 +95,74 @@ Page({ ## Performance Optimization -### Package Size +### Package Size and Asset Management -- Keep the initial package size under the limit (e.g., 4MB). -- Use subpackages for additional assets and code. -- Compress images and audio files to reduce size. +- **Initial Package Size:** The initial package size is strictly limited (currently 4MB). Keep your core game logic and essential assets in the main package. +- **Subpackages:** Use subpackages for additional levels, features, and non-essential assets. This allows for on-demand loading and keeps the initial download small. +- **Image Compression:** Use appropriate image formats (e.g., PNG, JPG) and compression tools. For games, consider using texture compression formats like ETC1/2 or PVRTC where applicable. +- **Audio Compression:** Use compressed audio formats (e.g., MP3, AAC) and adjust the bitrate to balance quality and size. +- **Font Optimization:** Avoid including large font files. If possible, use the system font or bitmap fonts. If you need a custom font, only include the characters you need. -### Frame Rate Optimization +### Frame Rate and Rendering -- Use `requestAnimationFrame` for animations. -- Avoid expensive operations in rendering loops. -- Offload complex calculations to worker threads if necessary. +- **`requestAnimationFrame`:** Always use `requestAnimationFrame` for game loops and animations. It's more efficient than `setInterval` or `setTimeout` and aligns with the browser's rendering cycle. +- **Off-Screen Canvas:** For complex drawing operations, use an off-screen canvas to pre-render content and then draw the result to the main canvas in a single operation. +- **Avoid Expensive Operations:** Minimize complex calculations, object creation, and memory allocation within the main game loop. +- **Worker Threads:** For heavy computations like AI or physics, offload them to a worker thread to avoid blocking the main rendering thread. + +### Memory Management and Garbage Collection + +- **Object Pooling:** Reuse objects (e.g., bullets, enemies) instead of creating and destroying them frequently. This reduces garbage collection (GC) pressure. +- **Resource Cleanup:** Explicitly destroy objects and release resources when they are no longer needed. This is especially important for event listeners, timers, and large assets like images and audio. +- **`wx.triggerGC()`:** In scenarios where you know a large amount of memory can be freed (e.g., after a level change), you can use `wx.triggerGC()` to suggest a garbage collection cycle. Use this sparingly, as it can cause a performance stutter. + +### Performance Monitoring + +- **`wx.getPerformance()`:** Use this API to get performance metrics like frame rate, memory usage, and draw calls. +- **WeChat DevTools:** The developer tools provide a performance panel for profiling CPU usage, memory, and rendering. +- **Online Diagnosis Tool:** Use the official online performance diagnosis tool to get a detailed report on your game's performance. + +## WeChat API Usage Best Practices + +### Login and User Data + +- **`wx.login()`:** Call this early in your game's lifecycle to get a login code. +- **User Privacy:** When using `wx.getUserInfo()`, you must now use a button to trigger the authorization prompt. Be transparent with players about why you need their information. Refer to the latest user privacy guidelines. + +### Social Features + +- **Sharing (`wx.shareAppMessage`):** + - Provide engaging share titles and images to encourage clicks. + - Use query parameters in your share URLs to track sources and reward players for successful shares. +- **OpenDataContext (Leaderboards):** + - The OpenDataContext is a separate, isolated environment for rendering social data like leaderboards. + - Communication between the main game and the OpenDataContext is done via `postMessage`. + - Keep the OpenDataContext as simple as possible to ensure good performance. + +### File System + +- **`wx.getFileSystemManager()`:** Use this API for all file system operations. +- **Storage Limits:** Be aware of the storage limits for user data. The total size is limited (currently 50MB). +- **Temporary vs. User Files:** Understand the difference between temporary files (cleared on exit) and user files (persistent). Use the appropriate storage for your needs. + +## Review and Publishing Process + +### Key Steps + +1. **Development and Testing:** Complete your game and test it thoroughly. +2. **Submit for Review:** In the WeChat DevTools, upload your code and submit it for review. +3. **Review Process:** The WeChat team will review your game for compliance with their policies and guidelines. This can take several business days. +4. **Approval or Rejection:** You will be notified of the outcome. If rejected, you will be given reasons, and you can resubmit after making the necessary changes. +5. **Publishing:** Once approved, you can publish your game to make it available to all WeChat users. + +### Common Reasons for Rejection + +- **Bugs and Performance Issues:** Games that crash, have significant bugs, or perform poorly are likely to be rejected. +- **Policy Violations:** Ensure your game complies with all of WeChat's content policies (e.g., no gambling, violence, or adult content). +- **Incomplete Information:** Provide all necessary information during the submission process, including test accounts and clear descriptions of your game's features. +- **Lack of "Game-like" Qualities:** Your submission should be a game, not just a simple interactive application. + +Refer to the official [WeChat Mini Game Review Guidelines](https://developers.weixin.qq.com/minigame/product/#%E5%AE%A1%E6%A0%B8%E8%A7%84%E8%8C%83) for the most up-to-date information. ## Input Handling diff --git a/expansion-packs/bmad-wechat-mini-game-dev/templates/game-architecture-tmpl.yaml b/expansion-packs/bmad-wechat-mini-game-dev/templates/game-architecture-tmpl.yaml index 35d9b64a..9878dfba 100644 --- a/expansion-packs/bmad-wechat-mini-game-dev/templates/game-architecture-tmpl.yaml +++ b/expansion-packs/bmad-wechat-mini-game-dev/templates/game-architecture-tmpl.yaml @@ -176,19 +176,59 @@ sections: - `js/input-manager.js` - id: wechat-api-integration title: WeChat API Integration - template: | - **Purpose:** Integrate with WeChat's social features + sections: + - id: wechat-login-and-user-info + title: Login and User Info + template: | + **Purpose:** Handle user authentication and retrieve player profiles. - **Key APIs:** + **Key APIs:** + - `wx.login` for user authentication. + - `wx.getUserInfo` for player profiles (requires user authorization via button). + - **Server-side:** Exchange login code for `session_key` and `openid`. - - `wx.login` for user authentication - - `wx.getUserInfo` for player profiles - - `wx.shareAppMessage` for sharing - - Open Data Context for leaderboards + **Files to Create:** + - `js/wechat-auth.js` - **Files to Create:** + - id: wechat-social-features + title: Social Features + template: | + **Purpose:** Integrate with WeChat's social features to enhance player engagement. - - `js/wechat-api.js` + **Key APIs:** + - `wx.shareAppMessage` for sharing game content with friends. + - **OpenDataContext:** For displaying leaderboards and other social data. + + **Files to Create:** + - `js/wechat-social.js` + - `opendata/index.js` (for OpenDataContext logic) + + - id: wechat-cloud-services + title: WeChat Cloud Services + template: | + **Purpose:** Utilize WeChat's cloud capabilities for backend services. + + **Services to Use:** + - **Cloud Functions:** For serverless backend logic (e.g., handling payments, validating data). + - **Cloud Database:** For storing user data and game state. + - **Cloud Storage:** For storing user-generated content or large assets. + + **Architecture:** + - Define the structure of the cloud database collections. + - List the cloud functions to be created and their purposes. + + - id: subpackage-planning + title: Subpackage Planning + template: | + **Purpose:** Manage the game's package size and optimize loading times. + + **Main Package:** + - Core game logic, essential assets, and the initial loading screen. + + **Subpackages:** + - **package-levels:** Contains assets and data for additional levels. + - **package-high-res-assets:** Contains high-resolution assets for high-end devices. + - **package-extra-features:** Contains code for non-essential features. - id: audio-system title: Audio System template: | diff --git a/expansion-packs/bmad-wechat-mini-game-dev/templates/game-design-doc-tmpl.yaml b/expansion-packs/bmad-wechat-mini-game-dev/templates/game-design-doc-tmpl.yaml index 8f7cd2b1..973be406 100644 --- a/expansion-packs/bmad-wechat-mini-game-dev/templates/game-design-doc-tmpl.yaml +++ b/expansion-packs/bmad-wechat-mini-game-dev/templates/game-design-doc-tmpl.yaml @@ -171,6 +171,42 @@ sections: **Total Levels:** {{number}} **Unlock Pattern:** {{progression_method}} + - id: social-and-monetization + title: Social and Monetization + instruction: Define how the game will integrate with WeChat's social features and generate revenue. + sections: + - id: social-mechanics + title: Social Mechanics + template: | + **Purpose:** Leverage WeChat's social graph to drive engagement and user acquisition. + + **Features:** + - **Leaderboards:** + - Type: (e.g., Friends, Global) + - Update Frequency: (e.g., Weekly, All-time) + - Implementation: Via OpenDataContext + - **Sharing:** + - Share Triggers: (e.g., New high score, Unlocked achievement) + - Share Content: Customizable images and text. + - Rewards: (e.g., In-game currency for successful shares) + - **Inviting Friends:** + - Incentive: (e.g., Reward for each friend who installs the game) + + - id: monetization-design + title: Monetization Design + template: | + **Purpose:** Outline the strategy for generating revenue. + + **Methods:** + - **Rewarded Video Ads:** + - Placement: (e.g., Continue after losing, Get extra currency) + - Frequency Cap: (e.g., 5 per day) + - **Banner Ads:** + - Placement: (e.g., Bottom of the menu screen) + - **In-App Purchases (IAP):** + - Currency: (e.g., Gems) + - Items for Sale: (e.g., Cosmetics, Power-ups, Ad removal) + - id: technical-specifications title: Technical Specifications instruction: Define technical requirements that will guide architecture and implementation decisions. Review any existing technical preferences.