ᗧ • • • MATH-PAC

MATH-PAC is a 3D browser-based educational game designed to help children master numbers and counting in multiple languages. The player controls a 3D character (Pacman style), eating numbers in the correct sequence to progress.

The project is built with Three.js and features a YouTube API integration for a reward system.

https://math-pac.sysop.cat/

• 3D Gameplay: Full 3D board with character movement physics.
• Educational Value: Teaches number sequences, even/odd numbers, tens, etc.
• Multilingual: Supports 4 languages (English, Polish, German, French) – both text and audio (TTS).
• Smart Reward System: Completing a level triggers a 60-second bonus video from YouTube (e.g., cartoons).
• "Safe Spawn" System: Logic ensures numbers do not spawn on top of the player or overlap with each other, ensuring readability.
• Visual Hints: Color-coded system (Green/Red) to help identify the next target (toggleable via H key).

The game runs in a browser but requires a local server (due to CORS security policies and ES6 modules) and audio file generation.

git  clone https://github.com/dzaczek/MATH-PAC
cd MATH-PAC 
python3 -m http.server

OPEN WEBBROWSER: localhost:8000

Clone the repository or download the files to a folder, e.g., math-pac.

The game relies on Google Text-to-Speech assets. You must run the provided script to download .mp3 files into the assets folder.

In a Terminal (Linux/Mac) or Git Bash (Windows):

chmod +x getsound.sh
./getsound.sh

This script downloads numbers 1-39 and error messages for all 4 languages.

Do not open index.html by double-clicking. Use one of the following methods:

• VS Code (Recommended): Install the "Live Server" extension, right-click index.html, and select "Open with Live Server".
• Python:

python3 -m http.server

• Node.js:

npx http-server .

Open your browser at the address provided (usually http://localhost:8000 or http://127.0.0.1:5500).

• W / Arrow Up – Move Forward
• S / Arrow Down – Move Backward
• A / Arrow Left – Turn/Move Left
• D / Arrow Right – Turn/Move Right
• H – Toggle Hints (Turn target color highlighting On/Off)

All game settings are located at the top of the game.js file.

You can define custom levels in the LEVEL_CONFIG array.

const LEVEL_CONFIG = [
    // Range Mode: Generates numbers from min to max sequentially
    { mode: 'range', min: 1, max: 10 },
    
    // List Mode: Spawns specific numbers in the defined order
    { mode: 'list', numbers: [2, 4, 6, 8, 10] } 
];

To change the cartoons played after completing a level, edit the BONUS_PLAYLIST array in game.js. Paste the YouTube Video ID (the part after v= in the URL).

const BONUS_PLAYLIST = [
    "wzb0uolNv5c", // Video ID for Level 1 reward
    "dQw4w9WgXcQ", // Video ID for Level 2 reward
];

math-pac/
├── index.html       # Main HTML (UI, Menu, YouTube Player container)
├── game.js          # Game Logic (Three.js scene, config, controls)
├── getsound.sh      # Bash script for downloading TTS audio
└── assets/
    └── sounds/      # Audio folder (generated by the script)
        ├── pl/      # Polish
        ├── en/      # English
        ├── de/      # German
        └── fr/      # French

• HTML5 / CSS3
• JavaScript (ES6 Modules)
• Three.js (3D Graphics Rendering)
• YouTube IFrame Player API (Video handling)
• Google Translate TTS (Audio generation)

1. No Sound: Modern browsers block auto-playing audio. You must interact with the page (click the language button in the menu) for audio to work.
2. CORS Error (Access to script blocked): If you see this error in the console, you are likely opening the file directly from the disk. Please follow the Run Local Server step in the Installation section.