Adrien Ufferte
0b9d5f216e
Follow-up to the previous download fix: the old pack was no longer deleted before the download, but it was still deleted at the start of the extraction step. If the app crashed mid-extraction or the archive was truncated, the device was left without a valid pack; worse, a partially extracted directory containing language.db would pass is_language_directory_valid() on the next offline launch and be accepted as a working pack. The extraction thread now follows an extract / verify / swap sequence: 1. Extract the archive into <lang>_tmp instead of the final location, leaving the current pack untouched and avoiding any risk of merging old and new files. 2. Validate the extracted pack (non-empty, language.db present) before touching the current one; on failure, discard the temp directory and the archive, show the invalid-directory error, and keep playing with the current pack. 3. Only then delete the previous pack and rename the new one into place. The window without a valid pack shrinks from the whole extraction to two filesystem operations. If the final rename fails, the temp directory is kept (the data is intact on disk) and the error popup is shown; the next launch detects the missing pack and downloads it again. A leftover temp directory from a crash is removed at the start of the next extraction. Verified with the GUT test suite (62/62 passing).
📖 Kalulu — Learn to Read, the Smart Way
🌍 Available Languages
- 🇪🇸 Español
- 🇫🇷 Français
- 🇧🇷 Português (Brasil)
📑 Table of Contents
🧠 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.
- Go to the Kalulu GitHub Repository.
- Click the Fork button at the top-right corner to create your own copy of the repo.
- Once forked, open your terminal and run the following commands:
# 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.
- Visit the official Godot Engine website: https://godotengine.org/
- Click on Download and choose the version compatible with your operating system.
- 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/binis 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
-
Set up the Project
See the Installation section to learn how to fork and clone the repository. -
Create a New Branch
git checkout -b feature/your-feature-name -
Make Your Changes
Implement your changes or improvements. -
Commit and Push
git add . git commit -m "Describe your changes" git push origin feature/your-feature-name -
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:
💻 Is Kalulu available on desktop?
Yes! Desktop versions for Windows, Mac, and Linux are available in the Releases section.
🌐 Is Kalulu available directly on the web?
We are working on it, stay tuned!
Related Repositories
| Repository | Description |
|---|---|
| Kalulu Backend | Serverless API — authentication, sync, dashboards, and data management |
| Kalulu Language Lambda | Pipeline that processes language packs and updates the database |
| Kalulu Languages | Linguistic data packs (French, Spanish, Portuguese etc...) |
Built with care by Excello Recherche & Education
We also have a website