The Memory Challenge Game

Using strings as labels has a small problem. If you make a typo in these strings somewhere in the code, that typo will go undetected until you realize that things are not working (in the UI probably) and try to find that typo manually. Many developers can tell countless stories of the amount of time they wasted on a silly typo.

A better way of doing this is to introduce an ENUM holding the specific values for gameStatus. This way, if you use an invalid ENUM value that problem will be a lot easier to find (especially if your editor uses a type checker like TypeScript).

Unfortunately, JavaScript does not have an ENUM data structure but we can use a simple object to represent one:

The values can be anything. You can use numbers or symbols but simple strings there are okay too.

Similarly, we should introduce an ENUM for the different cell statuses. Let’s give each a label as well:

Since these cell statuses directly drive the color values, I’ll make their ENUM value the colors themselves:

This way, in the Cell component, given that we compute the cell status correctly, we can just use its value as the backgroundColor value:

The last ENUM we need for this game is for the game messages. Should these messages be placed on the state?

Not really. These messages will be directly derived from the gameStatus value as well. We can actually include them in the GameStatus ENUM itself but I’ll just give them their own ENUM for simplicity.

For each gameStatus value, let’s give the player a helpful hint or let them know they won or lost:

Now the content of the message div can simply be: Messages[gameStatus].

Because we moved the message div into the Footer component, we’ll need to flow the gameStatus variable from Game into Footer to be able to lookup the game message in Footer. We could alternatively lookup the game message in the Game component and flow that to the Footer component but I think it’s cleaner to have that logic in the Footer component. Besides, the rendering of the Footer button will also depend on gameStatus.

Let’s now think about how to highlight the challenge cells. When the game starts, we need to randomly pick challengeSize elements from the grid array that has all of the cells' IDs (which is cellIds). I’ll put these in a challengeCellIds array.

To compute this array, we can use the provided utils function sampleArray, which takes an origArray and a sampleSize and returns a new array with sampleSize elements randomly picked from origArray.

The important question now is: should we place this challengeCellIds array on the state of the Game component?

To answer this question, think about whether this challengeCellIds array will change during a game session or not.

It will not! It is another a fixed value that does not need to be part of the game state. Deciding on the optimal elements that need to be placed on a component state is one of the most important skills of a React developer.

The challengeCellIds array can be a plain-old variable in the Game component:

The Game component is now aware which cells it should highlight when the gameStatus becomes CHALLENGE.

However, since challengeCellIds (and cellIds) are computed from props and do not depend on the state of the Game component, co-locating them with the stateful elements in the Game component is a problem!

To see the problem I am talking about, log the value of challengeCellIds after the line that defines it:

Try to render the Game component a few times. On each render, we get a different set of challengeCellIds. That’s great. The sampleArray function is working as expected.

Now render a game session and click "Start Game". What’s your observation?

The challengeCellIds array was regenerated when we clicked on that button.

That’s not good. This challengeCellIds should be a fixed value during a single game session. Once it’s generated, it should not change. It should only be re-generated when we need a new game session (with the "Play Again" button).

So why is this happening? Didn’t we define challengeCellIds using the const keyword? How is it changing when we click that button?

You need to keep in mind that each time you invoke a useState updater function, which is what we’re doing in the onClick handler for the button using the setGameStatus updater function, React will re-render the whole component that asked for that state. In this case, it is the Game component.

Re-rendering means React will call the Game function again, discard all variables that were defined in the previous render, and create new variables for the new render. It’ll create a new challengeCellIds variable (and a new cellIds and cellWidth variables too).

These 3 variables should not be recreated. They should be "immutable" once a game "instance" is rendered. One way of doing that is to make them into global variables. However, that means when we’re ready to implement the "Play Again" button all new games will use the exact same challenge cells. That’s not good either.

We want a game session’s fixed values (cellIds, challengeCellIds, and cellWidth) to be global to that session but not to whole app. This means we can’t have the Game component as a top-level one. We’ll need a "game generator" component that renders (and later re-renders) a game session. That new component can be responsible for the app-global variables that are needed for each top-level render.

The problem starts with the fact that I am mixing many responsibilities in the one component that I named Game. Naming matters here, a lot! What exactly did I mean by Game? Is it referring to the game in general, the app that renders many game sessions, or the single playable game session?

The solution starts with better names! This app should have a GameSession component and a GameGenerator component that’s responsible for generating and rendering a game session. When the GameGenerator component is rendered, it can compute the global values needed to run a GameSession. The GameSession component needs to manage its state independently of the state of the GameGenerator component.

Go ahead and try that on your own first. Rename Game into GameSession and keep the console.log line in there for testing. Create a GameGenerator component and move the computing of all 3 fixed values into it. Then pass them as props to the GameSession component. Test that the challengeCellIds array does not change when you click the "Start Game" button.

Here are the changes we need to make:

Note a few things about these changes:

Now when you click the "Start Game" button, the challengeCellIds array will be exactly the same because it’s just a prop that was not changed. React re-renders the GameSession component with its exact same props when its state changes.

To be able to compute a cell status, we need to design the structure to identify a cell as a correct or wrong pick. Should we have a correctCellIds and wrongCellIds arrays managed on the state of the GameSession component?

We could, but a good practice here is to minimize the elements you make stateful in a component. If something can be computed, don’t place it on the state. Take a moment and think about what structure can be the minimum here to enable us to compute a correct or wrong pick.

These statuses will appear when the player starts clicking on cells to pick them. With each pick, something has to change on the state to make React re-render the picked cell and enable us to recompute its status which will be either CellStatus.CORRECT or CellStatus.WRONG.

However, we don’t need to manage a structure for correct and wrong picks because both of them can be computed from challengeCellIds. Just knowing that a cell was picked allows us to determine if that pick was correct or wrong. All we need to place on the state is the fact that the cell was picked!

Let’s use an array to keep track of pickedCellIds on the state of the GameSession component. This array starts as empty:

We will later design the click behavior on each cell so that it adds the clicked cell’s ID to this pickedCellIds array.

What about winning or losing the game? Do we need to place anything else on the state to make the UI render differently for these states?

No. Both of these cases are also computable. With a challengeSize of 6 and maxWrongAttempts of 3, after every guess if we have 6 correctly guessed cells, the game is won. If we have 3 wrong attempts the game is lost. We actually do not even need to change the gameStatus to WON or LOST because these two statuses are computable. However, computing these status requires some array math and placing them on the state is a form of simply caching this computation.

What about the game timers? Do we need to place anything on the state for them?

The answer depends on what we want to display in the UI. If all we need is a timer ticking in the background that drives nothing in the UI to be changed (on every tick) then we do not need to place anything on the state. However, if we’d like to show a "countdown" value in the UI as the timer is ticking, then that timer needs to update a state element. Let’s do that for the playSeconds timer. Let’s show the countdown from playSeconds down to 0 in the UI. We’ll need a state element to hold these countdown values. I’ll name countdown. It’s initial value is the playSeconds prop:

I think we have all the data and state we need for a game session. This is the easy part though. The next few steps are where the real power of React comes in handy. We can complete the design of our UIs as functions of data and state and then only worry about changing the state afterwards, eliminating the need to do any manual DOM operations.

To keep the code simple, I’ll compute each cell status in the Cell component itself. Does this mean we need to flow down gameStatus, challengeCellIds, and pickedCellIds from the GameSession component to the Cell component?

No. Don’t do that.

The Cell component does not need to know about all challengeCellIds or all pickedCellIds. It only need to know whether it is a challenge cell and a picked cell. What we need are flags like isPicked and isChallenge and we can use a simple Array.includes to compute them:

I’ll refer to this pattern as "props minimization". It is mostly a readability pattern but it is also tied to the responsibility and maintainability of each component. For example, if we later decided to use a different data structure to hold challengeCellIds, ideally the code inside the Cell component should not be affected.

Another way to think about this pattern is to ask yourself this question about each prop you pass to a component: Does this component need to be re-rendered when the value of this prop changes?

For example, think about the pickedCellIds prop we first considered passing to each Cell. This array will be changed on each click of a cell. Since we’re re-rendering a gird of cells (25 cells for example), the props-minimization question becomes: do all 25 grid cells need to be re-rendered every time we click on a cell?

No. Only one cell needs to be re-rendered. That one cell that will change its isPicked value from false to true.

What about gameStatus? is that a minimum prop?

Not really. When that value changes from NEW to CHALLENGE, we only need to re-render a few cells (to highlight them); we don’t need to re-render all cells. We could make this better by not passing the gameStatus down to Cell and instead pass something like shouldBeHighlighted. However, I think it’s cleaner to just pass the gameStatus itself down to the Cell component. It’s really a core primitive value in each cell computation and using it directly will make the code more readable. Besides, if we go the other way, more computational logic will need to exist in the GameSession component. I think all the logic about computing the status of a cell should be inside the Cell component. This is just my preference.

The practice I can get behind here is to try to only flow down the minimum props that a component needs to re-render itself but don’t sacrifice readability and responsibility managements to be 100% exact about that.

I think that’s a good starting point. Let’s now compute the cellStatus value based on these 3 values.

We have the 3 variables that are directly responsible for the value of each cell status. We can come up with rough description of the conditions around these variables that are responsible for what status a cell should have. It often helps to start with the pseudo-code natural description of the computation we’re about to make. Here’s what I came up with based on the 3 points we analyzed when we came up with the cellStatus ENUM.

Technically, if "the cell is picked" condition should also account for what game-status we want the correct/wrong cell statuses to appear. Do we want the green/pink highlights to stay when the game is won or lost? I think so. It is nice to have the players see the original challenge cells that they failed to guess. This is why I did not include a condition about game-status in the is-picked branch. The only other game-status value there is CHALLENGE and we know for a fact that when the game has that status, no cell has been picked yet.

Here’s one way to translate the pseudo-code in the Cell component:

Note how I added the LOST gameStatus case to show the cell as highlighted. There is no need to add the WON status there because all cells will be correctly picked in that case.

We can partially test this change by clicking on the "Start Game" button. That click changes gameStatus into CHALLENGE and the UI will show the 6 random blue cells. Render the UI a few times and click on that button to verify that the random blue cells are different on each game render.

How can we test the rest of this logic? we have not implemented the "pick-cell" UI behavior yet. We don’t have a way to win or lose the game yet.

We can use mock state values!

The state usually starts with empty values (like the empty pickedCellIds array). It is hard to design the UI without testing using actual values. Mock values to the rescue.

For example, we can start the pickedCellIds with some mock values and start the gameStatus with a value of GameStatus.PLAYING:

With these temporary changes in the initial values, and based on the randomly assigned challenge cells, the grid should show the first and last three cells as either pink or green. Print the challengeCellIds array to make sure the right cells are displayed green or pink:

Note how cells #1 and #24 were green because they happen to be part of both the pickedCellIds and challengeCellIds when I took the screenshot. The other picked cells were pink because they are wrong picks for this mock state.

Using this strategy, we do not have to worry about behavior and user interactions (yet). We can focus on just having the UI designed as functions of data and (mock) state.

For example, another thing that needs to change in the UI based on the different states is the appearance of the button in the Footer component. The "Start Game" button should only show up with when gameStatus is NEW. When the player wins or loses the game, a Play Again button should show up instead. While the player is playing the game, let’s just show the countdown value in the button area. A few if statements in the Footer component will do the trick:

Note a few things about what I did:

I think compromises like these are okay for prototyping but you should get in the habit of trying to cover all the cases and think a tiny bit forward about the extendibility of your code. I think I’d like the buttonAreaContent function better with a switch statement that does that:

You can test this new UI logic by just changing the initial value of gameStatus in the GameSession component.

Now all we need is to implement the user interactions and have them change the state. Then we’ll be done! React will always reflect the current values in data/state in the UI using the functions that we already defined.

We implemented the first step of the "Start Game" button already. It changes the gameStatus value into CHALLENGE. What we need now is to change that value into PLAYING after 3 seconds (or whatever challengeSeconds value we end up using).

This is where we can use a timer object. The source of the behaviors that change the state is not always directly from the user (click or other events). Sometimes the behavior comes from a timer in the background.

We can start this timer in the same function that’s invoked when the "Start Game" button is clicked, the one where we inlined the call to setGameStatus. However, React has a different place for this logic. We can use a side effect hook (through the React.useEffect function).

Starting the timer is a side effect for changing the gameStatus value to CHALLENGE. Every time the gameStatus value change to CHALLENGE, we need to start that timer. Every time the gameStatus is no longer CHALLENGE, we need to clear that timer if it’s still running.

The React.useEffect hook function is designed to implement that exact logic. It takes a callback function and a list of dependencies:

After any rendering of the component, if the values of the dependencies are different from the last time useEffect was invoked it’ll invoke its callback function. We can start the timer inside a side effect hook if we can determine that the gameStatus has changed to CHALLENGE. To do that, we can make gameStatus a dependency for our timer side effect hook.

Furthermore, if the component is re-rendered or removed from the DOM, a side effect can invoke a cleanup function. That cleanup function can be returned from the useEffect callback function. We should clean any timers we start in a side effect’s callback function in that side effect’s cleanup function.

Here’s what we need to change the gameStatus into PLAYING after 3 seconds using a side effect hook:

Because gameStatus is a dependency, this useEffect hook will invoke its callback function every time that value changes. When it changes into CHALLENGE, the if statement will become true and we’ll start a timer. In the cleanup function, we clear the timer.

For the sake of completeness, I also included the challengeSeconds as a dependency although that value will not change during a single game. You should always include all the variables a side effect hook is using in its list of dependencies. You can even automate that in your editor using React ESLint tools like the eslint-plugin-react-hooks package.

Now the game will go into PLAYING mode after 3 seconds of clicking the "Start Game" button the highlighting of challenge cells should go away. Test that.

When gameStatus changes into PLAYING, we need to start another timer! This time we need a timer that ticks 10 times repeatedly and modifies the countdown state element. This is where we can use a setInterval call. We’ll need to put this new logic in a side effect hook as well.

Because it’ll also depend on gameStatus, we can use the same hook for both timers. They just have different branches that we can do through different if statements. Don’t forget that we need an exit condition for this new branch, we can check the countdown value to determine if the interval is to be stopped:

Here’s a way to do that:

This will not work! The interval timer will continue to run. Test it and try to figure out why.

Because the code depended on the value of countdown and we have not included it as a dependency, the callback function will have a "stale" closure when the countdown value changes. That’s why you should always include all the dependencies. Adding countdown to the list of dependencies will solve the problem, but it’s not ideal.

By adding the countdown as a dependency, the hook callback function (and its cleanup one) will be invoked every time the countdown value changes. That means every second we will clear the interval timer and start a new one. We don’t even need an interval, we can replace setInterval with setTimeout and things will still work because of the recursive nature of repeated update. A setTimeout changes the countdown value, React re-renders, the hook’s callback function is invoked again, A setTimeout changes the countdown value, and so on.

The question is: How can we use a setInterval that updates the state then?

You’ll need the state-update logic to not depend on the current value of the state. We needed the countdown dependency in the first place because we’re decrementing the current value of that state element. However, all React state updater functions support their own callback-form. You can pass a function to any updater function (like setCountdown) and that function will be called with the current value of the state as its argument. Whatever that function returns becomes the new value for that state element.

For this example, we just need to move the logic that depends on countdown into the setCountdown callback function and we can keep the setInterval use that way:

This version does not depend on the value of countdown at all. React will make the current value of countdown available to setCountdown when it invokes it. This will work fine.

This callback version of React state updater functions is much better because it allows you to optimize any code that updates the state. I’d go as far as saying you should always use the callback version if your state update logic depend on current value of the state (like the decrement logic we had).

The core user-interaction in this game and the one that’ll be responsible for the rest of computations we need to make is the pick-cell behavior.

When a player clicks a cell 2 things are affected:

Because these states are managed in the GameSession component we need to place the pick-cell behavior on that level.

Let’s start by defining an empty pickCell function in GameSession and pass that function to Cell so that we can make the Cell component click handler. We’ll wire it to receive the id of the cell being clicked:

The first change this new function is going to do is straightforward. We can use array destructuring to append the new clicked cellId to the pickedCellIds array:

Note a few things about this code:

With this code, you can now partially play the game. You can pick cells and see them change to green/pink but you cannot win/lose the game through picking (the game will be over after 10 seconds through the timer code).

Where can we implement the win/lose game status logic?

We can put it in the pickCell function itself! After all, we need to check if the game is WON or LOST after each pick. There is a problem though. This logic will depend on the new value for pickedCellIds after each pick. We need to do it after the setPickedCellIds call. All React state updater functions are asynchronous. We can’t do anything after them directly.

We could work around this problem by using the new pickedCellIds array before we use it with setPickedCellIds. Here’s a version of the code to do that:

The math logic to compute the new gameStatus values is not really important but I am basically using the utils.arrayCrossCounts array to count how many correctPicks and wrongPicks the player has made so far (including the current pick), then compare these numbers with challengeSize/maxWrongAttempts to determine the new gameStatus value.

By inserting this logic right before the return value, I get to use the value of "the state to be"! Go ahead and try to play now. You can win and lose the game!

What’s wrong with this code though? Nothing, right? SHIP IT!

While the code above works just fine, putting the logic to update gameStatus in pickCell itself makes the function less readable and harder to reason with. The pickCell function should just pick a cell!

Where are we supposed to put the win/lose logic then?

Think about it. The fact that we need to invoke the win/lose logic is a side effect to updating the pickedCellIds array! Every time we update the pickedCellIds array, we need to invoke this side effect. Although it is really "internal" to React and has nothing to do with anything external to it, we can still use a side effect hook just to separate these 2 different concerns.

Revert pickCell to its first version and move the win/lose logic to its own new useEffect hook:

This is a bit cleaner. There is no mix of concerns or confusing new vs. old picked cells concepts. Each time the pickedCellIds array is different the useEffect callback function will be invoked because we wired pickedCellIds as a dependency for it. There is no need to do any cleanup for this side effect hook because it isn’t really a full side effect that depends on something external to React. It is only used to manage internal concerns.

React offers a trick to combine both actions needed to reset a game session. We can re-render the GameGenerator component (by changing its state) and use a different identity value for the GameSession component through the special "key" prop! That’ll make React render a brand new GameSession instance (using initial state values).

When we use the "key" attribute for a component, React uses it as the unique identity of that component. Say we rendered a component with key="X" and then later re-render the exact same component (same props and state) but with key="Y". React will assume that these 2 are different elements. It’ll completely remove the X component from the DOM (which is known as "unmounting") and then it’ll mount a new version of it as Y. Although nothing else has changed in X besides it key!

This can be used to reset any stateful component. We just give each game instance a key and change that key to reset it. We’ll need to do that in the GameGenerator component and since we need that component to re-render we can use a stateful element for the value of this new key prop.

To make this change, remove the resetGame function from the GameSession component and instead make it receive a prop named resetGame. The GameGenerator component will now be in charge of resetting a game:

Then make the following changes to the GameGenerator component:

That’s it! Now the game will reset properly. All computed data elements in GameGenerator will be re-computed with the gameId state change. All props passed to the GameSession component will be new value. The state of the GameSession component will be re-initialized because it’s now a brand new element in the main tree (because of the new key value).

I would be nice however to auto-start the second game session (and all sessions after that) instead of having the player click the "Start Game" button again after clicking "Play Again".

Try to do that on your own first.

The GameGenerator component is the one that knows if a game was the first one or if it was generated through a resetGame action. In fact, that condition is simply gameId > 1. However, the GameSession component is the one responsible for starting the game (through its gameStatus value). One way to solve this issue is by passing an autoStart prop to GameSession and use it to initialize the gameStatus variable as either NEW or CHALLENGE right away:

The "Play Again" action will now render a brand new game and it will directly be in its CHALLENGE mode.

This game is feature-complete! However, before we conclude, there is one more trick that I’d like you to be aware of. One of the best things about React hooks is that we can extract related logic into a custom function. Let’s do that.

The logic to have a gameId that starts with 1, have an autoStart game flag, and a resetGame function that increments gameId is all related. Right now, it’s within the GameGenerator component mixed with the other logic about cellIds and challengeCellIds.

If we decided later to change the values of gameId to be string-based instead of incrementing number, we’ll have to modify the GameGenerator component. Ideally, this logic should be extracted into its own unit and the GameGenerator can just use that unit. This is exactly like extracting a piece of code into a function and invoking that function but this particular piece of code is stateful! The useState call hooks into React internals to associate a component with a state element.

Luckily, React supports extracting stateful code into a function. You can extract any hooks calls including useState and useEffect into a function (which is known as a custom hook) and React will continue to associate the hooks calls with the component that invoked the custom hook function.

Name your custom hook function as useXYZ. This way linting tools can treat it as yet another React hook and provide helpful hints and warnings about it. This is not a regular function! It’s a function that contain stateful logic for a component.

I’ll name this new custom-hook function useGameId. You can make it receive any arguments you want and make it return any data in any shape or form. It does not have to be similar to useState (or other React hooks) and we don’t need to pass any argument to it in this case. I’ll also make it return the 3 elements related to the game-id concept: the id itself, a way to tell if this is the first id, and a way to generate a new id:

Note how I opted to use different names for elements of the custom hook. This custom hook can be re-usable across components. Different game apps like this one can use the same useGameId custom hook function to provide identity for their components, offer a way to do something for a new or subsequent game, and provide a method to renew the gameId identity.