Kalulu/README.md

![Godot Version](https://img.shields.io/badge/Godot-4.6+-blue)

# 📖 Kalulu — Learn to Read, the Smart Way

## 🌍 Available Languages

- 🇪🇸 [Español](README.es.md)
- 🇫🇷 [Français](README.fr.md)
- 🇧🇷 [Português (Brasil)](README.pt-br.md)

---

## 📑 Table of Contents

- [🧠 Why Kalulu?](#why-kalulu)
- [✨ Features](#features)
- [🚀 Installation](#installation)
  - [Clone the Repository](#clone-the-repository)
  - [Install the Godot Engine](#install-the-godot-engine)
- [🧩 Addons](#addons)
- [🤝 Contributing](#contributing)
- [❓ FAQ](#faq)

## 🧠 Why Kalulu?

**Kalulu** is more than just a game — it’s an educational adventure grounded in scientific research that helps children learn to read through a decoding-based method.

Each lesson follows a structured sequence based on linguistic data drawn from children's literature. Learners start with vowels and gradually move on to more complex sounds.

- 🎯 **Goal**: Make learning to read fun and effective  
- 🌟 **Science-Based**: Developed using research in education and neuroscience  
- 👶 **Target Audience**: Primarily children, but useful for anyone wanting to learn to read
- 🔎 **Published Research**: Several articles have been published on Kalulu's design and reading results, read here:  
  https://www.tandfonline.com/doi/pdf/10.1080/00220973.2023.2173129  
  https://hal.science/hal-03015914/document  
  https://hal.science/hal-03702075/document  

---

## ✨ Features

- Interactive grapheme-phoneme reading lessons
- Adaptive difficulty progression
- Child-friendly interface with engaging visuals

---

## 🛠️ Installation

### 📥 Clone the Repository

We recommend forking the repository before cloning, so you can easily contribute or manage your own changes.

1. Go to the [Kalulu GitHub Repository](https://github.com/Excello-Recherche-Education/Kalulu-Frontend).
2. Click the **Fork** button at the top-right corner to create your own copy of the repo.
3. Once forked, open your terminal and run the following commands:

```bash
# Clone your fork of the repository
git clone https://github.com/YOUR_USERNAME/Kalulu-Frontend.git
# Or
git clone git@github.com:YOUR_USERNAME/Kalulu-Frontend.git

# Navigate into the project directory
cd Kalulu-Frontend
```

🔁 *Remember to replace `YOUR_USERNAME` with your actual GitHub username.*

---

### 🎮 Install the Godot Engine

To run Kalulu, you need the Godot Engine installed on your machine.

1. Visit the official Godot Engine website: [https://godotengine.org/](https://godotengine.org/)
2. Click on **Download** and choose the version compatible with your operating system.
3. Extract the downloaded file and run the Godot executable to launch the editor.

That's it! You're now ready to explore the Kalulu project in Godot.

---

## 🧩 Addons

Kalulu includes several useful addons to enhance development and streamline workflow:

### 🔄 EnvironmentSwitcher
A utility to easily switch between development and production environments.

### 📤 export_tool_manager
Facilitates export to various platforms and simplifies the export process for additional tools like `prof_tools`.

### ✅ godot-form-validator
A plugin for Godot 4 that adds validation logic to any control element in your project.

### 🗃️ godot-sqlite
Provides SQLite integration for Godot projects. 

> **Important:** This addon must be downloaded manually from the Godot AssetLib. The folder `addons/godot-sqlite/bin` is excluded from version control due to its large size. Make sure to download and install it after cloning the repository.

---

## 🤝 Contributing

We welcome contributions from everyone! Whether it's fixing bugs, improving documentation, or suggesting new features, your help is greatly appreciated.

### How to Contribute

1. **Set up the Project**  
   See the [Installation section](#installation) to learn how to fork and clone the repository.

2. **Create a New Branch**  
   ```bash
   git checkout -b feature/your-feature-name
   ```

3. **Make Your Changes**  
   Implement your changes or improvements.

4. **Commit and Push**  
   ```bash
   git add .
   git commit -m "Describe your changes"
   git push origin feature/your-feature-name
   ```

5. **Open a Pull Request**  
   Navigate to your forked repository on GitHub and click **Compare & pull request** to submit your changes for review.

Please make sure your code follows our coding conventions and includes relevant tests or documentation updates when appropriate.

---

## ❓ FAQ

### 📱 Is Kalulu available on mobile?

Yes! Kalulu is available on:

- [![Android](https://img.shields.io/badge/PlayStore-Kalulu-green?logo=google-play)](https://play.google.com/store/apps/details?id=org.godotengine.kalulu)
- [![iOS](https://img.shields.io/badge/AppStore-Kalulu-blue?logo=apple)](https://apps.apple.com/fr/app/kalulu-education/id1639075967)

### 💻 Is Kalulu available on desktop?

Yes! Desktop versions for Windows, Mac, and Linux are available in the [Releases](https://github.com/Excello-Recherche-Education/Kalulu-Frontend/releases) section.

### 🌐 Is Kalulu available directly on the web?

We are working on it, stay tuned!

---

## Related Repositories

| Repository | Description |
|---|---|
| [Kalulu Backend](https://github.com/Excello-Recherche-Education/Kalulu-AWS-Lambda) | Serverless API — authentication, sync, dashboards, and data management |
| [Kalulu Language Lambda](https://github.com/Excello-Recherche-Education/Kalulu-Language-Lambda) | Pipeline that processes language packs and updates the database |
| [Kalulu Languages](https://github.com/Excello-Recherche-Education/Kalulu-Languages) | Linguistic data packs (French, Spanish, Portuguese etc...) |

---

Built with care by [Excello Recherche & Education](https://github.com/Excello-Recherche-Education)

We also have a [website](https://excellolab.org/)