Home
This page serves as a reference for how our envisioned end product will look and function. Everyone should feel free to edit this wiki whenever it might be appropriate.
AS a LEARNER
I WANT to efficiently remember facts in a gamified way
SO THAT I can consistently recall facts at will
GIVEN sets of decks to study from
WHEN I select a deck
THEN the game loads this deck's contents to be reviewed
WHEN a flashcard shows up
THEN I can select an answer from three possible options
WHEN I select an incorrect answer
THEN the card will show more frequently in the future
WHEN I select a correct answer
THEN the card will show less frequently in the future
WHEN I complete a game (of 15 cards)
THEN I get a summary of how much points I have earned in this session
WHEN I do particularly well in each game
THEN more cards from the deck will be added to the pool
WHEN my score reaches certain milestones
THEN I will have earned a badge to show off on my profile
GIVEN my competitive nature in this gamified environment
WHEN I open my profile page
THEN I see my avatar, cumulative score, and badges I have earned
WHEN I open the leaderboard page
THEN I can see how my score compares with other players
WHEN I click on another player's profile
THEN I can see their avatar, cumulative score, and badges
Major credits to Anagha for creating this diagram of our database. We will have four tables:
- User
- Game
- Deck
- Card
In short summary:
The User table will contain all the information about each player. Each User will have multiple Deck objects that will be copied from the Deck database and injected into the Game table.
The Game table will serve as a state, in the sense that a player will load up a play session from the Game, and the Game will be updated at the end of each play session.
The Card table will contain the different cards that will exist in the decks. Important to note is the difficulty value, as it will range from 1-5, designating which difficulty "bin" they will belong to for each player. Cards will start at a value of 3, and they will go up by one if the user answers the Card correctly, or go down by one if the user answers the Card incorrectly. The graphic below demonstrates this concept:
As each card is answered correctly, they will move up a bin and will have a lower chance of appearing. The opposite true as well, as incorrectly answered cards will show up more frequently hammer in ideas to the user.
Major credits to Shawn for creating the game loop. Hopefully, the example below can serve as a reference as to writing out the actual code for the game logic.
Suppose we have a Deck that tests the user's knowledge of the periodic table of elements. There are 118 elements, and a Card for each element.
Each Card will have a front and back. The front could be a tabular display of the chemical element (ie. 18Ar), and the back could be the element name (ie. Argon).
In order to not overwhelm the player, we will not load all 118 cards into the pool that will be tested right at the start. We will introduce cards in groups. In this example, we'll introduce 15 cards at a time.
Important to note is that each Card will have a difficulty value between 1-5, and will default at 3. As each Card is answered correctly, the difficulty value will increase. As each Card is answered incorrectly, the difficulty value will decrease. The difficulty value and the term "bin" may be used interchangeably below, as it is easy to imagine each difficulty value being a bin of cards, like the graphic in the previous section. We will introduce 15 more cards into the pool when the 70% of the cards in the existing pool are at least in bin 4.
Now, suppose there is a player that wants to test their knowledge of the different elements.
They select the "Periodic Table of Elements Deck". The backend creates a copy of the Deck to the Game (since the deck should stay the same for each User, but the contents within each Deck will change, particularly the difficulty value of the Cards).
At first, the app will load the first 15 Card objects into the pool. It randomly selects cards within each grouping of difficulty value as following (subject to change):
- 1: 40%
- 2: 30%
- 3: 15%
- 4: 10%
- 5: 5%
Note that since this is the first time the user is playing with this Deck, the percentages are currently irrelevant since each card will have a default value of 3 and will all be drawn from the 3 bin.
The player will be presented 10 flashcards. In this example, we will test the player's front-to-back knowledge of each card.
The first card that might be shown, then, is 6C. Three backs will be shown as potential answers. One will always be the correct answer, and the other two will be randomly selected from the pool that is available.
The player might see: Helium, Carbon, or Silicon. Suppose the user correctly selects Carbon. The flashcard will animate with a small bounce with a green checkmark, and the next card will be presented. In the front-end, the difficulty value of the 6C/Carbon Card will increase from 3 to 4.
This time, the player is presented with 3Li. The possible answers are: Lithium, Oxygen, and Sodium. The player incorrectly selects Oxygen, and the flashcard shakes with a red glow. In the front-end, the difficulty value of the 3Li/Lithium card will decrease from 3 to 2.
This repeats until the player has gone through 10 flashcards. They are presented with the game's summary and how much points they have earned or lost.
The player earns 10 points for each card in bin 4, and 20 points for each card in bin 5 (subject to change). Since there is 118 cards in this deck, the maximum number of points that can be earned is 3360 points.
Suppose the player answers 7 answers correctly in this play session. 7 cards are now in bin 4, so the player now has 70 points attributed to this deck.
Now, suppose the player wants to solidify their learnings and earn more points. They play the same deck, except this time, they choose to play the cards from back-to-front.
The first card they get is Oxygen. The possible answers are: 2He, 4Be, and 8O.
This process repeats until the user finishes a set of 10 cards. At the end of the game, the users stats are once again tallied and their deck's score is recalculated based on how many cards are in bin 4 and 5.
Suppose the player now has at least 70% of the cards in the pool in bin 4. A notice will show to the player that they are progressing in their knowledge, and 15 more cards have been added to the pool. Good luck player!
As time progresses and the player becomes more familiar with this deck, they eventually reach the maximum number of points (3380). a notice appears telling the player that they have mastered this deck, and a new badge has been added to their profile to be shown off.
When the player goes to their profile page, they see their cumulative points across every deck, and a badge in the badge section that shows off that they have maxed out the Periodic Table of Elements Deck.
This section elaborates a little on the philosophy behind the difficulty value / bins.
The idea being that all cards starting at the default value of 3, the value of each Card will go down or up depending on how each player performs. The cards that get answered correctly will have a higher value, award points, and be shown infrequently so as to only reinforce the players current knowledge.
As cards are answered incorrectly, the value goes down and they get shown more frequently to make sure that the player gets lots of practice with the cards they struggle with.
With this system, it accounts for each player's individual strengths and weaknesses, and is self-correcting as the player becomes better. In theory, as the player becomes more and more familiar with the Deck's subject, all cards will move towards the 4 and 5 bins.
Note then that this system means that it is technically possible for the player start a game with all cards that belong in bin 5, and that earning points is impossible and only losing points is, but this is highly unlikely given the percentage weighting on each bin the game draws the 10 cards from.
This also means that it is possible that the player may be stuck trying to earn the last few points they need in order to master a deck, but again, this is also unlikely to happen for a long period of time because of the weighting.
Our app will have the following "pages" that make up the structure of the front-end. We can add mockups here once they have been created.
The page that is shown to a new, unsubscribed user. It will have the following sections:
- Teaser / hero banner graphic that welcomes the user.
- An about description that explains the goal of this app.
- How this app functions (and how our flashcard "game" works).
- A call to action to get the user to sign up.
Public profile pages that shows off the accomplishments of each user.
- Graphical avatar and name.
- Accumulated points across all decks.
- Their ranking on the global leaderboard.
- Badge section that shows off the different accomplishments the user has earned.
- This can include mastery badges or sign-in streaks, for example.
Displays the decks that the user can select and "play".
- A grid that contains the different decks that are available to be played.
- We'll probably only make two for our MVP: Periodic Table of Elements, and Countries and their Flags.
- When a deck is selected, a modal appears that describes the content of the deck, a close button, the points earned for this deck, and a "Play" button.
The actual game itself after a deck has been selected to be played.
- The flashcard on the left, and its three possible answers on the right.
- A counter that counts how many flashcards are left in the current play session.
- The number of cards answered correctly.
A place where players can compare their stats.
- A table that shows the top players with their accumulated points.
- Each user's name is clickable to go to their public profile page.
- Cloudinary for storing avatar and miscellaneous graphics.
- Still deciding between Chakra UI and Ant Design.
- Mockflow for mockups of each page.
Of course, everyone is welcome to help out wherever they can, but here are everyone's general assigned roles:
- Esteban: Front-end design and development.
- Shawn: Game design and asset creation.
- Ali: Back-end management, and integration with front-end.
- Anagha: Back-end management, and schema creation.
- Mateo: Back-end design and development.
- Kris: Front-end design and development.
- Ojashri: Back-end design and development.
- Terrence: Game design and asset creation.