CASCADA Framework

Appearance

Mobile Export (Capacitor) ​

Export CASCADA games to Android and iOS

Status ​

Planned for Implementation

CASCADA games are developed in browser but can be exported to mobile platforms via Capacitor.

Why Capacitor? ​

Capacitor by Ionic is a modern alternative to Cordova:

Advantages over Cordova ​

FeatureCapacitorCordova
ModernActive developmentBecoming outdated
TypeScriptNative supportPlugins
Web-firstWeb = priorityNative = priority
iOS/AndroidXcode/Android StudioCLI
Pluginsnpm + nativeXML config
PWAOut of the boxPlugins

For Phaser 3 ​

  • 100% compatibility - Phaser works great in Capacitor
  • WebGL/Canvas - full support
  • Performance - native speed
  • Plugins - access to camera, geolocation, etc

Architecture ​

┌────────────────────────────────────┐
│      CASCADA Web App               │
│   (Phaser 3 + TypeScript)          │
│                                    │
│   - ViewportManager (adaptation)   │
│   - GameModeManager (NANO↔MACRO)  │
│   - Touch controls                │
└────────────────────────────────────┘
              ↓
        Capacitor
              ↓
      ┌───────┴────────┐
      │                │
┌─────▼──────┐  ┌─────▼──────┐
│  Android   │  │    iOS     │
│   (.apk)   │  │   (.ipa)   │
└────────────┘  └────────────┘

Quick Start (future) ​

1. Install Capacitor ​

bash
# In project root
ppnpm install @capacitor/core @capacitor/cli
ppnpm install @capacitor/android @capacitor/ios

# Initialize
pnpm cap init
# App name: CASCADA
# App ID: com.cascade.game (or yours)

2. Configuration ​

typescript
// capacitor.config.ts
import { CapacitorConfig } from "@capacitor/cli";

const config: CapacitorConfig = {
  appId: "com.cascade.game",
  appName: "CASCADA",
  webDir: "dist",
  server: {
    androidScheme: "https",
  },
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      backgroundColor: "#000000",
      showSpinner: false,
    },
  },
};

export default config;

3. Build ​

bash
# 1. Build web version
pnpm build

# 2. Sync with Capacitor
pnpm cap sync

# 3. Open in IDE
pnpm cap open android  # Android Studio
pnpm cap open ios      # Xcode (macOS only)

4. Run on Device ​

bash
# Android
# In Android Studio: Run → Run 'app'

# iOS (macOS only)
# In Xcode: Product → Run

Mobile Adaptation ​

ViewportManager - automatic adaptation ​

typescript
// src/core/utils/ViewportManager.ts is ready!
const viewportManager = new ViewportManager(this);

viewportManager.init((width, height) => {
  if (viewportManager.getDeviceType() === "mobile") {
    // Mobile adaptation
    this.setupTouchControls();
    this.adjustUIForMobile();
  }
});

Touch Controls ​

typescript
// src/game/controls/TouchControls.ts
export class TouchControls {
  constructor(scene: Phaser.Scene) {
    // Virtual joystick for movement
    this.setupVirtualJoystick(scene);

    // Touch buttons for actions
    this.setupTouchButtons(scene);
  }

  setupVirtualJoystick(scene: Phaser.Scene) {
    // Virtual joystick on the left
    const joystick = scene.add.sprite(100, 500, "joystick");

    scene.input.on("pointermove", (pointer) => {
      if (pointer.isDown) {
        // Control character
        this.handleJoystickMove(pointer);
      }
    });
  }
}

Modes for Mobile ​

CASCADA automatically adapts modes:

typescript
// Mobile Portrait → NANO mode (detailed control)
// Mobile Landscape → MICRO mode (tactics)
// Tablet → MESO mode (strategy)

This already works via GameModeManager!

🔌 Useful Plugins ​

1. Geolocation (for location-based games) ​

bash
ppnpm install @capacitor/geolocation
typescript
import { Geolocation } from "@capacitor/geolocation";

const position = await Geolocation.getCurrentPosition();
console.log("Location:", position.coords);

2. Haptics (for feedback) ​

bash
ppnpm install @capacitor/haptics
typescript
import { Haptics, ImpactStyle } from "@capacitor/haptics";

// On player action
await Haptics.impact({ style: ImpactStyle.Medium });

3. Network (for MMO) ​

bash
ppnpm install @capacitor/network
typescript
import { Network } from "@capacitor/network";

Network.addListener("networkStatusChange", (status) => {
  if (!status.connected) {
    this.showOfflineMessage();
  }
});

4. Storage (for saves) ​

bash
ppnpm install @capacitor/preferences
typescript
import { Preferences } from "@capacitor/preferences";

// Save
await Preferences.set({
  key: "game_progress",
  value: JSON.stringify(gameState),
});

// Load
const { value } = await Preferences.get({ key: "game_progress" });

📐 Adaptive Design ​

Screen Orientation ​

typescript
// capacitor.config.ts
{
  "plugins": {
    "ScreenOrientation": {
      "orientation": "landscape" // or "portrait", "any"
    }
  }
}

Safe Area (iPhone notch, etc) ​

css
/* index.html */
body {
  /* Padding for notch/home indicator */
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
}

Screen Sizes ​

CASCADA already adapts via ViewportManager:

iPhone SE:        375 x 667  → NANO mode
iPhone 14 Pro:    393 x 852  → NANO mode
iPad Mini:        744 x 1133 → MESO mode
iPad Pro:         1024 x 1366 → MACRO mode

Performance Optimization ​

1. Textures ​

typescript
// Use texture atlases
this.load.atlas("sprites", "sprites.png", "sprites.json");

// Instead of separate files
// this.load.image('sprite1', 'sprite1.png');
// this.load.image('sprite2', 'sprite2.png');

2. Audio ​

typescript
// Use Web Audio API (Phaser default)
this.sound.add("music", { loop: true });

// For mobile - compress audio (AAC/OGG)

3. Physics ​

typescript
// Limit number of physics bodies
const MAX_BODIES =
  viewportManager.getDeviceType() === "mobile"
    ? 50 // Mobile
    : 200; // Desktop

Publishing ​

Google Play (Android) ​

bash
# 1. Create keystore
keytool -genkey -v -keystore cascade.keystore \
  -alias cascade -keyalg RSA -keysize 2048 -validity 10000

# 2. Build release APK in Android Studio
# Build → Generate Signed Bundle / APK

# 3. Upload to Google Play Console

App Store (iOS) ​

bash
# 1. Configure in Xcode:
#    - Bundle Identifier
#    - Signing & Capabilities
#    - App Icons

# 2. Archive
# Product → Archive

# 3. Upload via Xcode Organizer

Roadmap ​

Phase 1: Setup (Q2 2025) ​

  • Capacitor integration
  • Basic touch controls
  • Android build

Phase 2: Polish (Q3 2025) ​

  • iOS build
  • Advanced touch controls
  • Performance optimization

Phase 3: Release (Q4 2025) ​

  • Google Play publishing
  • App Store publishing
  • In-app purchases (optional)

📚 Resources ​

Tips ​

Touch vs Mouse ​

typescript
// Phaser handles automatically
this.input.on("pointerdown", (pointer) => {
  // Works for both touch and mouse
  console.log(pointer.x, pointer.y);
});

Testing on Desktop ​

bash
# Chrome DevTools
# F12 → Toggle Device Toolbar (Ctrl+Shift+M)
# Select device (iPhone, iPad, etc)

# Or just resize browser window!
# ViewportManager adapts automatically

Debug on Device ​

bash
# Android
# Chrome → chrome://inspect

# iOS (macOS + Safari)
# Safari → Develop → [Your Device]

🤝 Contributing ​

Want to help with mobile export?

  1. Install Android Studio / Xcode
  2. Try exporting a prototype
  3. Create a PR with instructions!

Status: In Development
Planned Release: Q2 2025

← Back to guide

MIT Licensed

Copyright © 2025