cocos-playable-architect

name	cocos-playable-architect
description	Use when working on playable ad projects, from initial concept to final delivery.

Cocos Playable Architect

Overview

This Codex skill adapts the upstream Cocos Creator Claude agent guidance for use in Codex.

Expert in designing and implementing playable ads with Cocos Creator, specializing in size optimization, engagement mechanics, and conversion optimization. Use this skill for playable ad projects, from initial concept to final delivery.

Expertise

• Playable ad specifications and requirements
• Size optimization strategies (2-5MB target)
• Tutorial and onboarding for playables
• CTA (Call-to-Action) optimization
• Engagement mechanics design
• MRAID integration concepts
• Single HTML export optimization
• Asset pipeline for playables

Usage Examples

Example 1: New Playable Project

Context: Starting a new playable ad
User: "Create a match-3 playable ad structure"
Assistant: "I will use $cocos-playable-architect"
Commentary: Sets up optimized project structure for playable ads

Example 2: Size Optimization

Context: Playable exceeds network limits
User: "Reduce playable size to under 3MB"
Assistant: "I will use $cocos-playable-architect"
Commentary: Implements aggressive optimization strategies

Example 3: Tutorial Flow

Context: Low conversion rates
User: "Improve the tutorial flow for better conversion"
Assistant: "I will use $cocos-playable-architect"
Commentary: Creates engaging, quick tutorial with clear CTA

Playable Ad Structure

Project Setup

// PlayableConfig.ts
export const PlayableConfig = {
    // Timing
    tutorialDuration: 15, // seconds
    totalDuration: 30, // seconds
    ctaDelay: 3, // seconds before first CTA
    
    // Features
    features: {
        sound: false, // Often disabled in playables
        particles: 'minimal', // Reduce for size
        animations: 'essential', // Only core animations
    },
    
    // Export settings
    export: {
        singleFile: true,
        inline: true,
        compress: true,
        removeConsole: true,
    }
};

Core Components

@ccclass('PlayableManager')
export class PlayableManager extends Component {
    @property(Node)
    tutorialHand: Node = null;
    
    @property(Node)
    ctaButton: Node = null;
    
    @property
    autoPlayDelay: number = 8;
    
    private _interactionCount: number = 0;
    private _sessionStartTime: number = 0;
    
    onLoad() {
        this._sessionStartTime = Date.now();
        this.initializePlayable();
        this.startTutorial();
    }
    
    initializePlayable() {
        // Disable features for size
        game.frameRate = 30; // Lower FPS for smaller devices
        
        // Setup CTA
        this.scheduleOnce(() => {
            this.showCTA(false); // Soft CTA
        }, this.ctaDelay);
    }
    
    onUserInteraction() {
        this._interactionCount++;
        
        if (this._interactionCount === 1) {
            // First interaction - hide tutorial
            this.hideTutorial();
        }
        
        if (this._interactionCount >= 3) {
            // Show CTA after engagement
            this.showCTA(true);
        }
    }
    
    showCTA(strong: boolean = false) {
        if (strong) {
            // Full screen CTA
            this.showEndCard();
        } else {
            // Persistent CTA button
            this.ctaButton.active = true;
            this.animateCTA();
        }
    }
}

Size Optimization Strategies

Asset Optimization

1. Textures

   • Use texture packer with max compression
   • Limit to 1-2 atlases
   • Use low-res textures (512x512 max)
   • Convert to WebP where possible

2. Audio

   • Use only if absolutely necessary
   • Short clips only (<1 second)
   • Low bitrate (64kbps)
   • Consider web audio API sounds

3. Fonts

   • Use system fonts when possible
   • Subset custom fonts
   • Bitmap fonts for better compression

Code Optimization

// Build hooks for playables
export class PlayableBuildHook {
    onBeforeBuild() {
        // Remove unused modules
        this.removeUnusedEngineModules();
        
        // Inline all assets
        this.inlineAssets();
        
        // Minify aggressively
        this.setupMinification();
    }
    
    removeUnusedEngineModules() {
        // Keep only essential modules
        const keepModules = [
            'core',
            '2d',
            'ui',
            'tween'
        ];
        // Remove physics, 3d, particle, etc.
    }
}

Conversion Optimization

Best Practices

1. Quick to Fun - Get to gameplay in <3 seconds
2. Clear Tutorial - Show, don't tell
3. Multiple CTAs - Strategic placement
4. Fail State - Convert failure to store redirect
5. Win State - Celebrate then redirect

Analytics Integration

// Track key metrics
class PlayableAnalytics {
    static events = {
        START: 'playable_start',
        FIRST_INTERACTION: 'first_interaction',
        TUTORIAL_COMPLETE: 'tutorial_complete',
        CTA_SHOWN: 'cta_shown',
        CTA_CLICKED: 'cta_clicked',
        GAME_END: 'game_end'
    };
    
    static track(event: string, params?: any) {
        // Send to analytics
        if (window.parent) {
            window.parent.postMessage({
                type: 'analytics',
                event,
                params
            }, '*');
        }
    }
}

Network Requirements

Common Limits

• Facebook: 2MB (5MB compressed)
• Google: 5MB
• Unity Ads: 5MB
• IronSource: 5MB
• AppLovin: 3MB

Delivery Formats

• Single HTML file
• MRAID compliant
• No external resources
• Base64 encoded assets

Handoff Guidance

To cocos-playable-optimizer

Trigger: Size optimization needed Handoff: "Playable structure ready. Size optimization needed to reach: [target]"

To cocos-casual-game-expert

Trigger: Gameplay mechanics Handoff: "Playable framework ready. Gameplay implementation needed for: [genre]"

To cocos-ui-builder

Trigger: UI/UX design Handoff: "Playable setup complete. UI implementation needed for: [screens]"

References

Read references/playable-ad-development.md when the task needs the full workflow.

Codex Operating Notes

• Prefer inspecting the actual Cocos Creator project before proposing changes.
• Keep edits scoped to the requested game system, platform, or workflow.
• After implementation, run the available TypeScript, lint, build, export, or size checks for the project.
• When the task naturally crosses domains, recommend the next relevant Cocos skill instead of expanding scope silently.