Skip to content

PLAN.md

Latest commit

 

History

History
251 lines (202 loc) · 5.97 KB

PLAN.md

File metadata and controls

251 lines (202 loc) · 5.97 KB

A language‑learning RPG built with RPGJS + TypeScript works best when you treat the game world as the “classroom” and every quest, NPC, and mechanic as a language‑learning interaction. The plan below gives you a full blueprint: architecture, game loop, learning mechanics, data structures, and how to integrate language‑learning logic into RPGJS.

🎮 Core Vision for the RPG

A top‑down RPG where the player explores towns, talks to NPCs, completes quests, and battles enemies — but progress depends on using the target language. Every interaction becomes a learning moment: vocabulary, grammar, listening, speaking, and reading.

🧱 High‑Level Architecture (RPGJS + TypeScript)

RPGJS uses a modular structure similar to Vue + Node. Your project will have:

  • Client (browser)

    • Game scenes
    • Maps, sprites, UI
    • Dialogue UI with input fields
    • Audio for listening exercises
    • Speech recognition (Web Speech API)

  • Server (Node.js)

    • Player save data
    • Quest progression
    • Language-learning engine (validation, spaced repetition)
    • AI‑generated dialogue variations (optional)

  • Shared TypeScript models

    • Vocabulary items
    • Grammar rules
    • Quest definitions
    • NPC dialogue trees

🗺️ Game Structure and World Design

Regions as Learning Levels

  • Starter Village — basic greetings, numbers, simple verbs
  • Forest of Verbs — conjugations, tenses
  • Marketplace City — shopping vocabulary, bargaining dialogues
  • Academy of Grammar — sentence structure, particles, cases
  • Kingdom of Fluency — advanced quests, long dialogues, storytelling

Each region introduces new language mechanics and vocabulary.

NPC Types

  • Trainers — teach vocabulary or grammar
  • Quest Givers — require language tasks to progress
  • Merchants — require correct phrases to buy/sell
  • Enemies — defeated by answering language questions

🧩 Core Learning Mechanics

1. Dialogue Challenges

NPCs speak in the target language. The player must:

  • Choose the correct response
  • Type the correct phrase
  • Speak the phrase (speech recognition)

If correct → XP, coins, story progress
If wrong → hint, retry, or mini‑lesson

2. Battle System Based on Language Tasks

Instead of attacking with weapons:

  • Correct answer = damage to enemy
  • Wrong answer = enemy attacks you

Task types:

  • Translate a sentence
  • Conjugate a verb
  • Fill in the blank
  • Listen and repeat

3. Vocabulary Collection

Every new word becomes an item in the player’s Lexicon Inventory:

  • Word
  • Meaning
  • Example sentence
  • Audio
  • Spaced repetition score

4. Quests as Learning Modules

Quest example:

  • NPC: “I lost my shopping list. Can you help me buy the right items?”
  • Player must identify items in the target language at the market.

🧠 Language Engine (Server-Side)

A simple TypeScript module handles:

  • Vocabulary database
  • Grammar rules
  • Acceptable answer variations
  • Spaced repetition scheduling
  • Difficulty scaling

Example TypeScript Model

export interface VocabItem {
  id: string;
  word: string;
  translation: string;
  audioUrl: string;
  difficulty: number;
  lastReviewed: Date;
  nextReview: Date;
}

export interface GrammarRule {
  id: string;
  description: string;
  examples: string[];
  validate: (input: string) => boolean;
}

🏗️ RPGJS Implementation Plan

Step 1 — Project Setup

npx degit rpgjs/starter my-language-rpg
cd my-language-rpg
npm install

Add TypeScript config:

npm install --save-dev typescript ts-node @types/node

Step 2 — Create Maps and Scenes

  • /maps/village.tmx
  • /maps/forest.tmx
  • /maps/academy.tmx

Use Tiled to design maps.

Step 3 — NPC Dialogue System

RPGJS supports events with custom logic.

Example NPC event:

import { EventData, RpgEvent, RpgEventHooks } from '@rpgjs/server';

@EventData({
  name: 'npc_teacher'
})
export class TeacherEvent extends RpgEvent {
  onAction(player) {
    player.showText([
      { text: "Bonjour! Comment ça va ?", choices: ["Bien", "Mal", "Je ne sais pas"] }
    ], (choice) => {
      if (choice === "Bien") {
        player.showText("Très bien !");
        player.giveExp(10);
      } else {
        player.showText("Essayons encore !");
      }
    });
  }
}

Step 4 — Battle System with Language Tasks

Override the battle logic:

import { RpgPlayer } from '@rpgjs/server';

function askQuestion(player: RpgPlayer, enemy) {
  const question = getRandomVocabQuestion();
  player.showInputText(question.prompt, (answer) => {
    if (question.validate(answer)) {
      enemy.hp -= 10;
      player.showText("Correct!");
    } else {
      player.hp -= 5;
      player.showText("Incorrect!");
    }
  });
}

Step 5 — Vocabulary Inventory UI

Create a custom UI component:

  • List of collected words
  • Audio playback
  • Review button
  • SRS next-review timer

Step 6 — Quest System

Define quests in TypeScript:

export interface Quest {
  id: string;
  title: string;
  description: string;
  tasks: QuestTask[];
  rewards: { xp: number; items?: string[] };
}

Quest tasks:

  • Talk to NPC
  • Answer language questions
  • Collect vocabulary items
  • Complete a dialogue challenge

Step 7 — Save System

Store:

  • Player stats
  • Vocabulary progress
  • Quest progression
  • SRS schedule

Step 8 — Audio + Speech Recognition

Use Web Speech API on the client:

const recognition = new webkitSpeechRecognition();
recognition.lang = "fr-FR";
recognition.onresult = (event) => {
  const spoken = event.results[0][0].transcript;
  validateAnswer(spoken);
};

📦 Optional Advanced Features

  • AI‑generated NPC dialogue variations
  • Multiplayer cooperative quests
  • Daily challenges
  • Leaderboards
  • Dynamic difficulty adjustment
  • Real‑world AR scavenger hunts (scan objects to learn vocabulary)