Puzzle Adventure

Inspiration

Puzzle Adventure is the perfect combination of my passion for hiking and my enthusiasm for Flutter. Through this project, I want to give a taste for discovery, adventure is at your doorstep!

The Flutter community communicates a lot about third-party libraries doing complex things, such as state management. Through this project, I would like to show that it is possible to make a beautiful application, with a maintainable code that is readable with a minimum of dependencies.

I recently moved to Montpellier, FRANCE, where I discovered lovely landscape. Through this game, I want to communicate my enthusiasm for the discovery of the secrets of our world.

What it does

Puzzle Adventure is an application available in French and English, built for web, Android and iOS (smartphones and Tablets). An effort has been made to handle light and dark mode for these platforms.

The application is divided in three pages:

the login page, to identify a user
the home page, to select a puzzle (also called board), see players ranking and read rules
the play page, to solve puzzles

The login page lets you create an account, or log into the application. This page is at an early stage, with very basic features and check mechanisms. In this page, you can create an account based on your email. Users also have to provide a password and a username. After having an account created, users can login; no email verification is implemented yet. They will be redirected to the home page.

In there, users can navigate between three sections: new game, ranking and rules (also known as help section). There, they can select a puzzle and a difficulty. The play button is greyed until these two parameters have been chosen.

Added to that board, users have access to the ranking board, displaying the highest scores sorted by difficulty. This section only displays the 20 best scores for each level of difficulty.

Finally, there is the help section where users have access to a short description of how to play the game.

Back to the new game section, after having selected a difficulty and a level, users navigate to the play page by clicking on the play button. That page displays the game status board, showing the time spent and the number of moves, and the puzzle to solve in the middle of the screen.

Every correctly positioned pieces are colorful, whereas pieces in the wrong place are greyed and half-transparent. This allows users to distinguish quickly which pieces of the puzzle to move. This page reveals the entire image when the puzzle is solved, accompanied by a “congratulation” text.

How we built it

You can directly play the game on your browser at : https://puzzle-challenge-a49fc.web.app/#/. But you can also compile and run the application using the ‘flutter run’ command.

Challenges I ran into

My first goal was to go deeper in the understanding of Flutter, by avoiding as much as possible third party libraries, especially state management ones. I was wondering if it was easy to create and maintain a medium-sized application easily. This idea comes from my professional Flutter projects, which I had to repair every six months because of library breakdowns or API changes. For that purpose, I re-implemented the base source code, limiting my dependencies to firebase packages.

In fact, I only used firebase for crashlytics, and my second goal was to learn and use firebase other products. Three of them were useful to my project: firebaseAuth for adding authentication feature to my application, Firestore to store data without having to focus about the data location, and firebase storage to store documents such as puzzle webp files.

Last but not least, I focused my development on maintainability and code reuse. Not especially on unit testing, but on how to organise my code, and how fast (and easy) can I develop complex parts. To be efficient on my work, I applied some rules about my classes:

Split widgets into small and independant classes
Avoid big methods (>30 lines of code)
Avoid complex stack of widgets
Split into some modules (engine and debug are good examples)
Try to split code into modules. It works well for engine module, where all domain code related to the puzzle is organised here. It helped me defining the board api, and is very useful in Android Studio, because the code is displayed as an inner dependency of the application (instead of packages that are shown as folders)

Then, to efficiently develop the theme of my application, I created a toolbox to help me. This toolbox, only available in debug builds, let me change instantly at platform and brightness. This was very useful when it comes to customise the theme. I may have spent four to five hours for light and dark themes on all platforms. It was around three times less than in my previous personal developments, where I hadn’t access to an UI designer.

Accomplishments that I am proud of

 Even if my project is not perfect, I am proud of:

The debug mechanism, that allows me (as developer) to create quickly my theme (light and dark mode). This mode is enabled by long clicking on the title. It shows a dialog where you can select Brightness, override platform, hide banner, …
The idea to render animated images instead of png or jpeg files. Well, that’s not very astonishing in Flutter, but you had to think about it.
The development of an application with shared data through players without developing the backend part, thanks to firebase (firestore and storage)
Create light and dark themes (for web, smartphones and Tablets) very quickly, thanks to my debug toolbox panel and the refactor of widgets into small independent pieces.

But most of all, I am very proud to accomplish this challenge in parallel of my full-time job. I spent around 55 hours, and even if there is still many things to do, it was really quick to integrate features (authentication, database on cloud, cloud storage).

What we learned

I have learned how easy it was to handle firebase in a Flutter application, and how fast it can be. I only known sqlite database, so it was a little bit confusing to use firebase storage and firestore together. I am aware that this project is not big enough to fully understand how to design its data, but the challenge gave me some thoughts about database conception with this technology. Added to that, I also tried the FirebaseAuth api, really convenient to add an authentication mechanism quickly. And to complete about firebase, this is the first time I used the ‘firebase cli’ tool to deploy my application as a website.

I also learned a pragmatic way to design a multi platform application. First, I imagined a full dart package for handling that purpose, but then I realised that it was not enough flexible. So I refactored my code, especially the ‘home page’, to avoid as much as possible dependencies. Like that, I were able to define layout widgets, on per design.

And it works pretty well: layout widgets were only defining position of ‘feature widgets’, without retaining more information.

What's next for Puzzle Adventure

This project gave me plenty of ideas to enhance my application:

create a training mode where the user will be able to upload his own pictures (Gif, webp,...)
Enhance the board display by rendering a video (mp4) instead of image (gif, webp). It may require me to develop a specific package to retrieve raw frames directly through natives API.
Add user profile, and store preferences in firestore
Create a story around levels, to explain the hiking paths and rewards (point of interests)
Add more ways to log in, and an email checker mechanism