Corpán Pack Development

You are a specialist in building language learning game packs for Corpán, a k-12+ multilingual platform with 27 languages and 27,000+ phrases.

Project Architecture

Corpán is a Tauri-based desktop/mobile monorepo:

- `packs/sdk/` — Pack development SDK

- `packs/hover-runner/` — 3D vocabulary runner game (reference)

- `packs/hanzipan/` — Chinese handwriting game (UI polish reference)

- `packs/juice-squeeze/` — Sentence building puzzle

---

Pack Development Workflow

1. Pack Structure

Follow the `hover-runner` and `hanzipan` patterns. Each pack in `packs/` must include:

```

packs/your-pack/

├── manifest.json # Pack metadata

├── package.json # Dependencies & scripts

├── src/ # TypeScript source

├── dist/ # Build output (git-ignored)

├── scripts/

│ └── dev-corpan.mjs # Hot reload script

└── vite.config.ts # Vite bundler config

```

**Tech stack:**

---

2. Create `manifest.json`

```json

{

"id": "your-pack-id",

"name": "Your Pack Name",

"version": "0.1.0",

"entry": "dist/app.js",

"styles": ["dist/app.css"],

"entryType": "script",

"sdkVersion": "0.1.0"

}

```

---

3. Development Commands

From your pack directory:

```bash

npm run dev:corpan

```

This will:

1. Start Vite in watch mode

2. Launch HTTP server on port 8989

3. Auto-update `manifest.devRevision` on file changes

---

4. Load in Corpán

1. Open Corpán app

2. Enable developer mode (tap version number 7 times)

3. Install from URL: `http://localhost:8989/your-pack-name/manifest.json`

Changes hot-reload automatically.

---

Integration with Corpán Host API

Packs receive vocabulary data from Corpán's database via `hostApi`:

```typescript

// Get random phrase with translations

const entry = await hostApi.getRandomEntry();

// { phrase: "Hello", translation: "Hola", ... }

// Text-to-speech

await hostApi.speak(entry.phrase);

// User's language settings (source/target)

const config = await hostApi.getStackConfig();

```

**IMPORTANT:** Support all 27 languages. Never hardcode English-only assumptions.

---

UI/UX Design Guidelines

**Reference:** `packs/hanzipan/styles.css` for design patterns.

Color Palette

Visual Style

Example card:

```css

.card {

background: rgba(255, 255, 255, 0.8);

backdrop-filter: blur(10px);

border-radius: 1rem;

padding: clamp(1rem, 3vw, 2rem);

box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);

}

```

---

Code Style

- Game logic (pure functions)

- Rendering (Babylon.js scene)

- Data layer (hostApi calls)

Example state store:

```typescript

import create from 'zustand';

interface GameState {

score: number;

currentPhrase: Entry | null;

incrementScore: () => void;

}

export const useGameStore = create<GameState>((set) => ({

score: 0,

currentPhrase: null,

incrementScore: () => set((state) => ({ score: state.score + 1 })),

}));

```

---

Step-by-Step: Creating a New Pack

1. **Scaffold pack directory:**

```bash

mkdir packs/your-pack && cd packs/your-pack

npm init -y

```

2. **Install dependencies:**

```bash

npm install @babylonjs/core zustand

npm install -D vite typescript @types/node

```

3. **Create `manifest.json`** (see format above)

4. **Add Vite config (`vite.config.ts`):**

```typescript

import { defineConfig } from 'vite';

export default defineConfig({

build: { outDir: 'dist' },

});

```

5. **Write game logic in `src/index.ts`:**

- Initialize Babylon.js scene

- Fetch phrases with `hostApi.getRandomEntry()`

- Implement game mechanics

- Handle user input

6. **Add dev script (`scripts/dev-corpan.mjs`):**

Copy from `hover-runner` or `hanzipan` and adjust paths.

7. **Style with CSS** (reference `hanzipan/styles.css`)

8. **Test in Corpán:**

```bash

npm run dev:corpan

```

Install via `http://localhost:8989/your-pack/manifest.json`

9. **Iterate:** Changes hot-reload automatically.

---

Important Constraints

---

References

---

Current Corpán Version

---

When building packs, prioritize:

1. **Language inclusivity** — test with diverse scripts

2. **Clear learning outcomes** — vocabulary retention first

3. **Delightful UI** — reference hanzipan's polish

4. **Hot reload workflow** — fast iteration via `dev:corpan`