# Match3 Game on the Fruit Jam and Adafruit Metro RP2350
## Overview
This CircuitPython project brings a game inspired by the [Set card game](https://en.wikipedia.org/wiki/Set_(card_game)) to the Adafruit Fruit Jam, and Metro RP2350. A [CH334F USB Hub](https://www.adafruit.com/product/5999) allows two mice to be connected to the Metro at once.
The game can be displayed on any HDMI compatible display using the HSTX ribbon connector on the Metro and a DVI breakout.
The Fruit Jam has the DVI connector and USB Hub ports built-in to the main board so peripherals can be connected directly.
Players face off with each other searching for sets of 3 cards that either all match or all differ in each of four different properties: shape, color, count, and fill. Players use right click on their mouse to buzz in, declaring that they've found a set. Then they click on the 3 cards they've found. If it was a valid set the cards are removed, the player is awarded a point and more cards are dealt. If all players indicate that they cannot find any sets then new cards are dealt.
### Parts
### Adafruit Fruit Jam - Mini RP2350 Computer
[Adafruit Fruit Jam - Mini RP2350 Computer](https://www.adafruit.com/product/6200)
We were catching up on a recent [hackaday hackchat with eben upton](https://hackaday.io/event/202122-raspberry-pi-hack-chat-with-eben-upton) and learned some fun facts: such as the DVI hack for the RP2040 was inspired by
Out of Stock
[Buy Now](https://www.adafruit.com/product/6200)
[Related Guides to the Product](https://learn.adafruit.com/products/6200/guides)
### Adafruit Metro RP2350 with PSRAM
[Adafruit Metro RP2350 with PSRAM](https://www.adafruit.com/product/6267)
Choo! Choo! This is the RP2350 Metro Line, making all station stops at "Dual Cortex M33 mountain", "528K RAM round-about" and "16 Megabytes of Flash town" and a bonus stop at "8 Megabytes of PSRAM village". This train is piled high with hardware that...
In Stock
[Buy Now](https://www.adafruit.com/product/6267)
[Related Guides to the Product](https://learn.adafruit.com/products/6267/guides)
### Adafruit RP2350 22-pin FPC HSTX to DVI Adapter for HDMI Displays
[Adafruit RP2350 22-pin FPC HSTX to DVI Adapter for HDMI Displays](https://www.adafruit.com/product/6055)
You may have noticed that our [RP2350 Feather](https://www.adafruit.com/product/6000) has an FPC output connector on the end for accessing the HSTX (High Speed Transmission) peripheral. This new capability, not available on the RP2040, is specifically designed to allow the...
In Stock
[Buy Now](https://www.adafruit.com/product/6055)
[Related Guides to the Product](https://learn.adafruit.com/products/6055/guides)
### Adafruit CH334F Mini 2-Port USB Hub Breakout
[Adafruit CH334F Mini 2-Port USB Hub Breakout](https://www.adafruit.com/product/5999)
Sometimes, you've got something with a USB host, like an embedded Linux board, and you want to connect more than one thing. Or maybe you want to turn something like a keyboard into a multi-device USB peripheral. The **Adafruit CH334F Mini 2-Port USB Hub...**
Out of Stock
[Buy Now](https://www.adafruit.com/product/5999)
[Related Guides to the Product](https://learn.adafruit.com/products/5999/guides)
2x USB Type A Jack Breakout:
### USB Type A Jack Breakout Cable with Premium Female Jumpers
[USB Type A Jack Breakout Cable with Premium Female Jumpers](https://www.adafruit.com/product/4449)
If you'd like to connect a USB-host-capable chip to your USB peripheral, this cable will make the task very simple. **There is no converter chip in this cable!** It's basically a plain USB cable that's cut in half and with jumper sockets on the power and data...
In Stock
[Buy Now](https://www.adafruit.com/product/4449)
[Related Guides to the Product](https://learn.adafruit.com/products/4449/guides)
### Break-away 0.1" 36-pin strip male header - Black - 10 pack
[Break-away 0.1" 36-pin strip male header - Black - 10 pack](https://www.adafruit.com/product/392)
Breakaway header is like the duct tape of electronics. It's great for connecting things together, soldering to perf-boards, fits into any breakout or breadboard, etc. We go through these guys real fast, and thought that given how handy they are, we'd offer them in a pack of ten!
In Stock
[Buy Now](https://www.adafruit.com/product/392)
[Related Guides to the Product](https://learn.adafruit.com/products/392/guides)
### Premium Female/Female Jumper Wires - 20 x 3" (75mm)
[Premium Female/Female Jumper Wires - 20 x 3" (75mm)](https://www.adafruit.com/product/1951)
These female-female premium jumper wires are handy for making wire harnesses or jumpering between headers on PCB's. They're 3" (75mm) long and come in a 'strip' of 20 (2 pieces of each of ten rainbow colors). They have 0.1" female header contacts on either end...
In Stock
[Buy Now](https://www.adafruit.com/product/1951)
[Related Guides to the Product](https://learn.adafruit.com/products/1951/guides)
### 22-pin 0.5mm pitch FPC Flex Cable for DSI CSI or HSTX - 20cm
[22-pin 0.5mm pitch FPC Flex Cable for DSI CSI or HSTX - 20cm](https://www.adafruit.com/product/6036)
Connect this to that when a 22-pin FPC connector is needed. This 20 cm long cable is made of a flexible PCB. It's A-B style, meaning that pin one on one side will match with pin one on the other. How handy!
[We're stocking this to...](https://www.adafruit.com/category/360)
In Stock
[Buy Now](https://www.adafruit.com/product/6036)
[Related Guides to the Product](https://learn.adafruit.com/products/6036/guides)
### USB Type A to Type C Cable - approx 1 meter / 3 ft long
[USB Type A to Type C Cable - approx 1 meter / 3 ft long](https://www.adafruit.com/product/4474)
As technology changes and adapts, so does Adafruit. This **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop.
USB C is the latest industry-standard connector for...
In Stock
[Buy Now](https://www.adafruit.com/product/4474)
[Related Guides to the Product](https://learn.adafruit.com/products/4474/guides)
### HDMI Cable - 1 meter
[HDMI Cable - 1 meter](https://www.adafruit.com/product/608)
Connect two HDMI devices together with this basic HDMI cable. It has nice molded grips for easy installation, and is 1 meter long (about 3 feet). This is a HDMI 1.3 cable.
We're now stocking a very fancy Official Raspberry Pi cable with overmolding and a Pi logo. Please note...
In Stock
[Buy Now](https://www.adafruit.com/product/608)
[Related Guides to the Product](https://learn.adafruit.com/products/608/guides)
### USB Wired Mouse - Two Buttons plus Wheel
[USB Wired Mouse - Two Buttons plus Wheel](https://www.adafruit.com/product/2025)
This is a mouse. A nice, simple mouse. No bells or whistles. Just a mouse.
But that doesn't mean it's not the best simple mouse! We compared a few and liked this one quite a bit. It's optical for good resolution and precision, has two...
In Stock
[Buy Now](https://www.adafruit.com/product/2025)
[Related Guides to the Product](https://learn.adafruit.com/products/2025/guides)
# Match3 Game on the Fruit Jam and Adafruit Metro RP2350
## Preparing the Metro RP2350
The USB Host port on the Metro RP2350, and the pins on the CH334F are the only parts of this project that require soldering.
The USB Host pin connections are highlighted on the Metro image to the left. You will need a small piece of standard 0.1 inch male header, with 4 pins, to fit the holes.
You can cut header with diagonal cutters or break them with pliers or even your fingers.
Be sure to wear eye protection as header pieces can fly when cut.
Put the short end of the header into the holes in the Metro marked USB Host and secure them with putty, blutack, tape, etc. Turn the Metro over and you should see the header barely poking out of the bottom of the board. If the pins stick through a great deal you may have the header pins upside down, double check the short end is sticking into the board.
Solder the 4 pin "nubbins" to the board.
Turn the board over and remove the material securing the pins. Now there is a new 4-pin header, which will get connected to the USB Hub on the next page.
## HSTX Connection to DVI
Get the HSTX cable. Any length Adafruit sells is fine. CAREFULLY lift the dark grey bar up on the Metro, insert the cable silver side down, blue side up, then put the bar CAREFULLY down, ensuring it locks. If it feels like it doesn't want to go, do not force it.
Do the same with the other end and the DVI breakout. Note that the DVI breakout will be inverted/upside down when compared to the Metro - this is normal for these boards and the Adafruit cables.
# Match3 Game on the Fruit Jam and Adafruit Metro RP2350
## USB Hub
This project uses the CH334F USB Hub breakout to connect two mice to the Metro RP2350. In order to prepare the hub breakout for this project there are 3 rows of 4 header pins that need to be soldered to the breakout.
Each row of header pins will get soldered to the 4 pin holes along the sides of the breakout. The two sides next to the USB C plug are the two ports on the hub. The side opposite the USB C plug is the connection back to the Metro acting as USB Host.
Soldering the pins with the long sides going upwards makes connecting to them easier because you can see the labels on the silkscreen, though having them go downwards instead could work as well.
Next connect the two USB Port Breakout cables and 4 female header wires to each of the 3 rows of pins. Be sure to match the following wiring for the USB Host connectors:
- **GND** to **Black** or **Blue**
- **D+** to **Green**
- **D-** to **White**
- **5V** to **Red**
I used a **Blue** header wire for **GND** instead of **Black**.
Connect the other end of the header wires to the USB Host pins soldered to the Metro RP2350 on the previous page.
- **GND** to **Black** or **Blue**
- **D+** to **Green**
- **D-** to **White**
- **5V** to **Red**
Note that the data pins are swapped on the Metro compared to the CH334F breakout. On the Metro **D-** is next to **5V** , whereas on the CH334F **D-** is next to **GND**.
Be sure to connect **D-** on the breakout to **D-** on the Metro, and **D+** on the breakout to **D+** on the Metro.
With everything connected it will look like this:
# Match3 Game on the Fruit Jam and Adafruit Metro RP2350
## Install CircuitPython Metro
[CircuitPython](https://github.com/adafruit/circuitpython) is a derivative of [MicroPython](https://micropython.org) designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. Simply copy and edit files on the **CIRCUITPY** drive to iterate.
## CircuitPython Quickstart
Follow this step-by-step to quickly get CircuitPython running on your board.
[Download the latest version of CircuitPython for this board via circuitpython.org](https://circuitpython.org/board/adafruit_metro_rp2350/)
**Click the link above to download the latest CircuitPython UF2 file.**
Save it wherever is convenient for you.
To enter the bootloader, hold down the **BOOT/**** BOOTSEL button**(highlighted in red above), and while continuing to hold it (don't let go!), press and release the**reset button**(highlighted in red or blue above). **Continue to hold the BOOT/BOOTSEL button until the RP2350 drive appears!**
If the drive does not appear, release all the buttons, and then repeat the process above.
You can also start with your board unplugged from USB, press and hold the BOOTSEL button (highlighted in red above), continue to hold it while plugging it into USB, and wait for the drive to appear before releasing the button.
A lot of people end up using charge-only USB cables and it is very frustrating! **Make sure you have a USB cable you know is good for data sync.**
You will see a new disk drive appear called **RP2350**.
Drag the **adafruit-circuitpython-_boardname_-_language_-_version_.uf2** file to **RP2350.**
The **RP2350** drive will disappear and a new disk drive called **CIRCUITPY** will appear.
That's it, you're done! :)
## Safe Mode
You want to edit your **code.py** or modify the files on your **CIRCUITPY** drive, but find that you can't. Perhaps your board has gotten into a state where **CIRCUITPY** is read-only. You may have turned off the **CIRCUITPY** drive altogether. Whatever the reason, safe mode can help.
Safe mode in CircuitPython does not run any user code on startup, and disables auto-reload. This means a few things. First, safe mode _bypasses any code in_ **boot.py** (where you can set **CIRCUITPY** read-only or turn it off completely). Second, _it does not run the code in_ **code.py**. And finally, _it does not automatically soft-reload when data is written to the_ **CIRCUITPY** _drive_.
Therefore, whatever you may have done to put your board in a non-interactive state, safe mode gives you the opportunity to correct it without losing all of the data on the **CIRCUITPY** drive.
### Entering Safe Mode
To enter safe mode when using CircuitPython, plug in your board or hit reset (highlighted in red above). Immediately after the board starts up or resets, it waits 1000ms. On some boards, the onboard status LED (highlighted in green above) will blink yellow during that time. If you press reset during that 1000ms, the board will start up in safe mode. It can be difficult to react to the yellow LED, so you may want to think of it simply as a slow double click of the reset button. (Remember, a fast double click of reset enters the bootloader.)
### In Safe Mode
If you successfully enter safe mode on CircuitPython, the LED will intermittently blink yellow three times.
If you connect to the serial console, you'll find the following message.
```terminal
Auto-reload is off.
Running in safe mode! Not running saved code.
CircuitPython is in safe mode because you pressed the reset button during boot. Press again to exit safe mode.
Press any key to enter the REPL. Use CTRL-D to reload.
```
You can now edit the contents of the **CIRCUITPY** drive. Remember, _your code will not run until you press the reset button, or unplug and plug in your board, to get out of safe mode._
## Flash Resetting UF2
If your board ever gets into a really _weird_ state and CIRCUITPY doesn't show up as a disk drive after installing CircuitPython, try loading this 'nuke' UF2 to RP2350. which will do a 'deep clean' on your Flash Memory. **You will lose all the files on the board** , but at least you'll be able to revive it! After loading this UF2, follow the steps above to re-install CircuitPython.
[Download flash erasing "nuke" UF2 for RP2350](https://cdn-learn.adafruit.com/assets/assets/000/132/526/original/rp2350_flash_nuke.uf2)
# Match3 Game on the Fruit Jam and Adafruit Metro RP2350
## Install CircuitPython Fruit Jam
[CircuitPython](https://github.com/adafruit/circuitpython) is a derivative of [MicroPython](https://micropython.org) designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. Simply copy and edit files on the **CIRCUITPY** drive to iterate.
## CircuitPython Quickstart
Follow this step-by-step to quickly get CircuitPython running on your board.
Warning: Please use the latest release of 10.x or higher for the Fruit Jam. Also use the latest libraries for the best functionality.
[Download the latest version of CircuitPython for this board via circuitpython.org](https://circuitpython.org/board/adafruit_fruit_jam/)
**Click the link above to download the latest CircuitPython UF2 file.**
Save it wherever is convenient for you.
To enter the bootloader, hold down the **BOOT/**** BOOTSEL button**(highlighted in red above), and while continuing to hold it (don't let go!), press and release the**reset button**(highlighted in red or blue above). **Continue to hold the BOOT/BOOTSEL button until the RP2350 drive appears!**
If the drive does not appear, release all the buttons, and then repeat the process above.
You can also start with your board unplugged from USB, press and hold the BOOTSEL button (highlighted in red above), continue to hold it while plugging it into USB, and wait for the drive to appear before releasing the button.
A lot of people end up using charge-only USB cables and it is very frustrating! **Make sure you have a USB cable you know is good for data sync.**
You will see a new disk drive appear called **RP2350**.
Drag the **adafruit-circuitpython-_boardname_-_language_-_version_.uf2** file to **RP2350.**
The **RP2350** drive will disappear and a new disk drive called **CIRCUITPY** will appear.
That's it, you're done! :)
## Safe Mode
You want to edit your **code.py** or modify the files on your **CIRCUITPY** drive, but find that you can't. Perhaps your board has gotten into a state where **CIRCUITPY** is read-only. You may have turned off the **CIRCUITPY** drive altogether. Whatever the reason, safe mode can help.
Safe mode in CircuitPython does not run any user code on startup, and disables auto-reload. This means a few things. First, safe mode _bypasses any code in_ **boot.py** (where you can set **CIRCUITPY** read-only or turn it off completely). Second, _it does not run the code in_ **code.py**. And finally, _it does not automatically soft-reload when data is written to the_ **CIRCUITPY** _drive_.
Therefore, whatever you may have done to put your board in a non-interactive state, safe mode gives you the opportunity to correct it without losing all of the data on the **CIRCUITPY** drive.
### Entering Safe Mode
To enter safe mode when using CircuitPython, plug in your board or hit reset (highlighted in red above). Immediately after the board starts up or resets, it waits 1000ms. On some boards, the onboard status LED (highlighted in green above) will blink yellow during that time. If you press reset during that 1000ms, the board will start up in safe mode. It can be difficult to react to the yellow LED, so you may want to think of it simply as a slow double click of the reset button. (Remember, a fast double click of reset enters the bootloader.)
### In Safe Mode
If you successfully enter safe mode on CircuitPython, the LED will intermittently blink yellow three times.
If you connect to the serial console, you'll find the following message.
```terminal
Auto-reload is off.
Running in safe mode! Not running saved code.
CircuitPython is in safe mode because you pressed the reset button during boot. Press again to exit safe mode.
Press any key to enter the REPL. Use CTRL-D to reload.
```
You can now edit the contents of the **CIRCUITPY** drive. Remember, _your code will not run until you press the reset button, or unplug and plug in your board, to get out of safe mode._
## Flash Resetting UF2
If your board ever gets into a really _weird_ state and CIRCUITPY doesn't show up as a disk drive after installing CircuitPython, try loading this 'nuke' UF2 to RP2350. which will do a 'deep clean' on your Flash Memory. **You will lose all the files on the board** , but at least you'll be able to revive it! After loading this UF2, follow the steps above to re-install CircuitPython.
[Download flash erasing "nuke" UF2 for RP2350](https://cdn-learn.adafruit.com/assets/assets/000/132/526/original/rp2350_flash_nuke.uf2)
# Match3 Game on the Fruit Jam and Adafruit Metro RP2350
## Wrangling Two Mice
The Match3 game uses two different USB mice for input from the players, each player gets their own mouse. This builds on top of the basic code for handling a single mouse. If you are unfamiliar with the concepts involved, first read the basic single [Mouse Input guide page](https://learn.adafruit.com/create-a-memory-game-on-metro-rp2350/mouse-input) then return here.
To use two mice, start with with the example below. It illustrates finding the connected mice, initializing them, reading data, and moving two cursors around the display.
The basic mouse example is embedded below. Click the 'Download Project Bundle' button to download a zip containing this example and the associated image file and required libraries. Unzip and copy them to the **CIRCUITPY** drive on the Metro which shows up in your computer file application (Explorer or Finder) to run the example.
Info: There is active development work underway for USB Host support. If you are having trouble with your mice, try upgrading your device to CircuitPython 10.0.0-alpha.6 or newer.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Metro/Metro_RP2350_Match3/two_mice_demo/code.py
The code contains comments describing the purpose of each section. An overview of the code functionality can be found below. Reading both will give you a good understanding of one of the core principals that will get used by the Match3 game.
### Default Display
This demo code uses the built-in display which is the HSTX ribbon connector PicoDVI display for the Metro RP2350. In older versions of CircuitPython, the display was not automatically initialized. If you get errors dealing with `None` trying to access the display size or setting its `root_group`, then update your Metro RP2350 to the latest stable release of CircuitPython listed on [the downloads page](https://circuitpython.org/board/adafruit_metro_rp2350/).
### Visual Elements Setup
`main_group` is a `Group` created to hold all of the other visual elements, it gets set as `display.root_display`. `mouse_bmp` holds the loaded mouse cursor bitmap image file. For the rest of the display related objects there will be two of each type, one for each of the mice. The objects are held in lists that will contain 2 elements each after the setup is complete. `output_lbls` list holds the `Label` objects that are used to display the mouse positions and buttons pressed. `mouse_tgs` list holds the `TileGrid` objects that will draw the visual mouse cursors. `palettes` list holds a `Palette` object for each cursor. The palettes both contain the same colors as the mouse cursor bitmap for indexes `0` and `1`, and each has their own color at index `2` which is the color that the outline of the cursor will be drawn with. In the demo code the colors are pink and green.
### Finding Connected Mice
There are three additional lists declared that will hold two elements, one for each of the USB mice found connected via the [USB Host API](https://docs.circuitpython.org/en/latest/shared-bindings/usb/index.html). `mouse_interface_indexes` list will hold the interface index within connected USB device. `mouse_endpoint_addresses` will hold the address of the mouse endpoint within the USB device. Finally, the `mice` list will hold a USB `Device` object for each mouse which will be used to read data from that device during the main loop.
The code scans for connected USB devices with `usb.core.find(find_all=True)` and iterates over the returned device objects. Each device object is passed to `adafruit_usb_host_descriptors.find_boot_mouse_endpoint()` to check if it represents a boot mouse and find its interface index and endpoint address if so. If the device is found to be a mouse the appropriate values and object will get added to the respective lists.
For each mouse device object it is also detached from the kernel if needed, and its configuration is set so that data can be read from it.
### Mouse Deltas Helper Function
The code defines a helper function `get_mouse_deltas()` which accepts a `buffer` and a `read_count` as arguments. This function will check the appropriate indexes within the buffer based on the `read_count` and return the delta x and y values contained within the buffer. These values represent how far the mouse has moved, and in which directions.
### Main Loop
Inside the main loop is a `for` loop that iterates over each mouse device object. Inside of that, the code attempts to read data from the mouse device object. If there is no data to read, the `read()` call will raise the `USBTimeoutError` which is caught by the code and causes it to skip the rest of the loop and go on to check the next mouse object.
If there was data read, the x and y delta values will be found using the helper function and then the mouse `TileGrid` has its `x` and `y` properties updated based on the delta values, clamped to the display size.
# Match3 Game on the Fruit Jam and Adafruit Metro RP2350
## Sprites & Colors
The Match3 game makes use of the new `tilepalettemapper`[core module](https://docs.circuitpython.org/en/latest/shared-bindings/tilepalettemapper/index.html#module-tilepalettemapper) which was added in CircuitPython 9.2.5. You must update your device if its version of CircuitPython is 9.2.4 or older. It is generally recommended to run the latest stable version of CircuitPython.
This demo program will illustrate how `tilepalettemapper` works and how the Match3 game code uses it to have one set of card sprites and re-map them to the 3 different possible colors, instead of needing one sprite for each of the different colors which would mean needing 3x as many sprites.
### Spritesheet
This is a zoomed in look at the spritesheet used by the Match3 game.
There are a few important things to note about the spritesheet:
- The sprites are arranged into a 7x4 grid of tiles. There are 28 total sprites in the full sheet.
- 27 of the sprites are Match3 game cards. Do not worry about the different shapes and types just yet, they'll be used by the game but aren't important to this demo.
- All of the game card sprites have a white background with black foreground pixels, drawing its shape and fill type.
- The last sprite in the bottom right corner isn't a game card. It has 3 small colored blocks within it. Those 3 colors are the possible colors that the cards will get mapped to when drawn on the display: red, green, and purple. Any pixel in a card that is black in the spritesheet will be mapped one of those other 3 colors when shown with a `TileGrid`.
This is the palette for the spritesheet image. It contains the following colors at their respective indexes.
- 0: white
- 1: black
- 2: purple
- 3: red
- 4: green
The `TilePaletteMapper` object maps the indexes within the palette for each tile within a `TileGrid` to different chosen indexes. For the Match3 game, and in this demo script the code maps index `1` to use one of indexes `2`, `3`, or `4`. Since black is at index `1` and the card designs are drawn in black in the spritesheet, this will have the effect of changing the card to either purple, red, or green depending on which index is chosen for the mapping.
### Demo Code
The demo code is shown below followed by a screenshot of the cards that it displays. If you want to run it on your own device click the "Download Project Bundle" button, unzip the project files and copy them to the CIRCUITPY drive.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Metro/Metro_RP2350_Match3/tilepalettemapper_demo/code.py
## TilePaletteMapper Usage
The code creates a `TilePalleteMapper` instance, supplying an input color count, grid width, and grid height as arguments.
```python
tile_palette_mapper = TilePaletteMapper(
spritesheet_bmp.pixel_shader, # input pixel_shader
5, # input color count
3, # grid width
1 # grid height
)
```
`tile_palette_mapper` is then used as the `pixel_shader` for a `TileGrid`
```python
cards_tilegrid = TileGrid(spritesheet_bmp, pixel_shader=tile_palette_mapper,
width=3, height=1, tile_width=24, tile_height=32)
```
To re-map the colors the code sets new color index lists at the desired tile locations.
```python
# re-map each tile in the grid to use a different color for index 1
# all other indexes remain their default values
tile_palette_mapper[0, 0] = [0, 2, 2, 3, 4]
tile_palette_mapper[1, 0] = [0, 3, 2, 3, 4]
tile_palette_mapper[2, 0] = [0, 4, 2, 3, 4]
```
To change the foreground color of each card a new color index is supplied for the second value in the list. By default it would be index `1` to match its own index within the list. The code sets the 3 different tile positions to `2`, `3`, and `4` which are the indexes for purple, red, and green respectively.
# Match3 Game on the Fruit Jam and Adafruit Metro RP2350
## Game Mechanics: Autosave & Resume
The Match3 game supports auto-save and resume if an SD Card is inserted into the Metro. Without an SD Card, the game will work as normal, but progress will be lost if the device loses power or resets.
In order to understand how the auto-save and resume mechanics work, first consider this simplified demo script.
## Demo Code
The demo code is shown below followed by a screenshot and explanation. If you want to run it on your own device click the "Download Project Bundle" button, unzip the project files and copy them to the **CIRCUITPY** drive.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Metro/Metro_RP2350_Match3/autosave_resume_demo/code.py
## Auto-save & Resume Functionality
Before the code can read and write files on the SD Card, it must be initialized and mounted. In version 10.0, CircuitPython will begin initializing and mounting the SD Card automatically. For any versions prior to that, the user code must handle the initialization and mounting. This demo script supports both by first checking if the SD Card is already mounted and only trying to initialize and mount it if it wasn't.
```auto
# The SD_CS pin is the chip select line.
SD_CS = board.SD_CS
# try to Connect to the sdcard card and mount the filesystem.
try:
# initialze CS pin
cs = digitalio.DigitalInOut(SD_CS)
except ValueError:
# likely the SDCard was auto-initialized by the core
sd_pins_in_use = True
try:
# if sd CS pin was not in use
if not sd_pins_in_use:
# try to initialize and mount the SDCard
sdcard = adafruit_sdcard.SDCard(busio.SPI(board.SD_SCK, board.SD_MOSI, board.SD_MISO), cs)
vfs = storage.VfsFat(sdcard)
storage.mount(vfs, "/sd")
```
Next the code will attempt to read the **autosave\_demo.dat** file and load `game_state` from it. For storing the `game_state` more efficiently, the [msgpack module](https://docs.circuitpython.org/en/latest/shared-bindings/msgpack/index.html) is used.
```auto
# check for the autosave data file
if "autosave_demo.dat" in os.listdir("/sd/"):
# if the file is found read data from it into a BytesIO buffer
buffer = BytesIO()
with open("/sd/autosave_demo.dat", "rb") as f:
buffer.write(f.read())
buffer.seek(0)
# unpack the game_state object from the read data in the buffer
game_state = msgpack.unpack(buffer)
print(game_state)
```
If there was no autosave file, but the SD Card was mounted successfully, then the code will set up the `save_to` variable holding a file path to the location where the autosave file will get written.
If no game state was loaded, then a new one is initialized with `0` values for the button counts.
```auto
# if placeholder.txt file does not exist
if "placeholder.txt" not in os.listdir("/sd/"):
# if we made it to here then /sd/ exists and has a card
# so use it for save data
save_to = "/sd/autosave_demo.dat"
except OSError:
# sdcard init or mounting failed
raise OSError(
"This demo requires an SDCard. Please power off the device insert an SDCard and then plug it back in.")
# if no saved game_state was loaded
if game_state is None:
# create a new game state dictionary
game_state = {'pink_count': 0, 'blue_count': 0}
```
### Saving Game State
A helper function is defined that saves the game state when it is called.
```auto
def save_game_state():
"""
msgpack the game_state and save it to the autosave data file
:return:
"""
b = BytesIO()
msgpack.pack(game_state, b)
b.seek(0)
with open(save_to, "wb") as f:
f.write(b.read())
```
### Click For Points
The rest of the code handles the mouse movement and waits for the buttons to be clicked. Once a button is clicked, the `game_state` is updated by incrementing the count for the corresponding color, and then the `game_state` is saved by calling the helper function.
# Match3 Game on the Fruit Jam and Adafruit Metro RP2350
## Code
## CircuitPython Usage
To use the game, you need to update **code.py** with the game program to the **CIRCUITPY** drive.
Thankfully, this can be done in one go. In the example below, click the **Download Project Bundle** button below to download the necessary libraries and the **code.py** file in a zip file.
Connect your board to your computer via a known good data+power USB cable. The board should show up in your File Explorer/Finder (depending on your operating system) as a flash drive named **CIRCUITPY**.
Extract the contents of the zip file, copy the **lib** directory files to **CIRCUITPY/lib**. Copy the **code.py** file to your **CIRCUITPY** drive. The program should self start.
Info: There is active development work underway for USB Host support. If you are having trouble with your mice, try upgrading your device to CircuitPython 10.0.0-alpha.6 or newer.
## Drive Structure
After copying the files, your drive should look like the listing below. It can contain other files as well, but must contain these at a minimum.
Note that the **CIRCUITPY/sd** directory is required.
## Code
The **code.py** for the Memory game is shown below.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Metro/Metro_RP2350_Match3/match3_game/code.py
# Match3 Game on the Fruit Jam and Adafruit Metro RP2350
## Code Explanation
The code for the Match3 game is thoroughly commented with explanations of what each line or section are for. This page will provide a higher level summary of the major components.
## Hardware Principals
This game is designed around a few primary hardware peripherals: the HSTX connector with a DVI breakout for the display, a CH334F USB Hub and two USB Mice connected for player input.
### HSTX Display
The code will use the built-in display from `supervisor.runtime.display`. Depending on what version of CircuitPython you have, the default size that the display is configured for can be different. The code for this game checks the size of the display and automatically scales up the `main_group` by `2` if it finds that it is running on the larger display resolution. That allows the game to look visually the same on the screen no matter which size it is configured for.
```auto
scale_factor = 1
if display.width > 360:
scale_factor = 2
main_group.scale = scale_factor
```
The `scale_factor` variable is also used in various other calculations within the code to account for the differences in resolution.
### USB Mice
The USB mouse setup, data reading, and cursor movement are all documented on the [Wrangling Two Mice guide page](https://learn.adafruit.com/match3-game-on-metro-rp2350/wrangling-two-mice). See that page for more details.
### Helper Classes
Inside of **match3\_game\_helpers.py** there are 4 class definitions and 2 functions which help with various parts of the game. A brief description of each can be found below. The code for each contains comments explaining them in more depth.
- `Match3Card` - This class encapsulates the graphics and functionality for a single Match3 card. It holds the `TileGrid` and `TilePaletteMapper` that work together to draw the card visually. See the [Sprites & Colors guide page](https://learn.adafruit.com/match3-game-on-metro-rp2350/sprites-colors) for more details on how they are used. When initialized, `Match3Card` is passed `card_tuple` as an argument. `card_tuple` contains four numbers that each range from `0` to `2`, this is a numerical representation of the unique card within the deck. The four numbers represent: color, shapes, fill, and count respectively. There is a commented block in the code which contains a table showing what all the possible values mean. `Match3Card` also has a `contains()` function which accepts x,y coordinates and returns `True` if the coordinate point is within the bounding box of the card.
- `Match3Game` - The `Match3Game` class manages most of the functionality of the game. It extends `Group` and holds all of the other primary visual elements of the game. It uses a state machine with four possible states.
- Title State - Showing the title screen, waiting for the user to click either the resume or new game buttons.
- Open Playing State - One of two game play states. This one is when the play is open meaning any player may call set by right clicking their mouse. During this state players may also click the "no set" button to indicate they can't find a set and would like more cards dealt. Both players must click before the cards are actually dealt.
- Playing Set Called State - Once set is called a countdown with a visible progress bar begins and the player who called must click three cards that they believe makes a set before it runs out.
- Game Over State - This state is used at the end of the game once there are no more cards in the deck and both players have declared they can find no more sets.
`Match3Game` uses a `GridLayout` to arrange the cards on the display. Mouse click events are sent in to the Game object with the functions `handle_right_click()` and `handle_left_click()` which carry out the appropriate action based on the current state. There are functions for saving and loading the game state which use the same technique shown on the [Game Mechanics: Autosave & Resume guide page](https://learn.adafruit.com/match3-game-on-metro-rp2350/game-mechanics-autosave-resume).
- `GameOverException` - A simple `Exception` wrapper class that gets raised when the game has ended.
- `Match3TitleScreen` - A class that extends `Group` and contains all of the visual elements used for the title screen. The class holds visual elements only, it does not handle functionality of the title screen.
### Helper Functions
The two helper functions inside of **match3\_game\_helpers.py** are used by `Match3Game`. They are:
- `random_selection()` - A function that accepts a `list` and an int `count` as arguments. It selects `count` items from `list` and removes them from the `list` then returns them. It gets used when the game needs to deal cards from the deck.
- `validate_set()` - This function accepts three `Match3Card` instances and returns True if they make up a valid set. It uses matrix addition and modulus on the `card_tuple` attribute values to determine whether the cards are a valid set. This technique is detailed in an excellent episode of [Numberphile on Youtube](https://www.youtube.com/watch?v=EkFX9jUJPKk). The video was instrumental in the making of this implementation of the game. Specifically the details of the numerical representation, and mathematical way to check for sets start around 5:40 into the video, but the whole thing is well worth a watch.
# Match3 Game on the Fruit Jam and Adafruit Metro RP2350
## Usage
Ensure that the CH334F USB Hub has two USB mice plugged into it, and is connected to the USB Host port on the Metro RP2350 that was wired up previously. Reset the board by cycling power or pressing the Reset button if you happen to plug in a mouse after power up.
Be sure you connect the DVI breakout to an HDMI monitor and the monitor is on. You might need a long cable if your monitor is not near the Metro RP2350 (like a television). The cables are standard and may be obtained from any trusted retail outlet. Also reset the Metro if you plug in HDMI after powering the Metro.
Once connections are all set, power the Metro RP2350 either via USB C (5 volts) or the barrel connection (5.5 to 17 volts DC, center positive).
## Gameplay
When the game first launches the title screen is shown. The title screen always contains a "New Game" button which will clear out any previously saved data and begin a new game. If there is previously saved data, then the title screen will also have a "Resume" button which can be clicked to pick up where the previous game left off.
During the game, players look at the cards on the board, trying to find valid sets of 3. Once a player spots a set, they click the right mouse to buzz in and begin their countdown. They then click the 3 cards that make up the set they found. If the set was valid, they are awarded a point and the cards are removed. If it wasn't a set, or they run out of time, a point is deducted.
During open play, while no one has called set, the players may click on the "No Set" button in the bottom right corner to indicate they can't find a set and want more cards to be dealt. Once both players click the button, the game will will deal an additional 3 cards, if there is room on the board, or shuffle the cards on the board back in and deal 12 new ones if the board was full.
If both the deck and board are empty, then the game is over and winner is determined by the high score. A more likely game ending occurs if the deck is empty, some cards remain on the board, but both players have clicked "No Set" indicating they cannot find any sets in the cards that do remain.
## Featured Products
### Adafruit Metro RP2350 with PSRAM
[Adafruit Metro RP2350 with PSRAM](https://www.adafruit.com/product/6267)
Choo! Choo! This is the RP2350 Metro Line, making all station stops at "Dual Cortex M33 mountain", "528K RAM round-about" and "16 Megabytes of Flash town" and a bonus stop at "8 Megabytes of PSRAM village". This train is piled high with hardware that...
In Stock
[Buy Now](https://www.adafruit.com/product/6267)
[Related Guides to the Product](https://learn.adafruit.com/products/6267/guides)
### Adafruit RP2350 22-pin FPC HSTX to DVI Adapter for HDMI Displays
[Adafruit RP2350 22-pin FPC HSTX to DVI Adapter for HDMI Displays](https://www.adafruit.com/product/6055)
You may have noticed that our [RP2350 Feather](https://www.adafruit.com/product/6000) has an FPC output connector on the end for accessing the HSTX (High Speed Transmission) peripheral. This new capability, not available on the RP2040, is specifically designed to allow the...
In Stock
[Buy Now](https://www.adafruit.com/product/6055)
[Related Guides to the Product](https://learn.adafruit.com/products/6055/guides)
### Adafruit CH334F Mini 2-Port USB Hub Breakout
[Adafruit CH334F Mini 2-Port USB Hub Breakout](https://www.adafruit.com/product/5999)
Sometimes, you've got something with a USB host, like an embedded Linux board, and you want to connect more than one thing. Or maybe you want to turn something like a keyboard into a multi-device USB peripheral. The **Adafruit CH334F Mini 2-Port USB Hub...**
Out of Stock
[Buy Now](https://www.adafruit.com/product/5999)
[Related Guides to the Product](https://learn.adafruit.com/products/5999/guides)
### USB Type A Jack Breakout Cable with Premium Female Jumpers
[USB Type A Jack Breakout Cable with Premium Female Jumpers](https://www.adafruit.com/product/4449)
If you'd like to connect a USB-host-capable chip to your USB peripheral, this cable will make the task very simple. **There is no converter chip in this cable!** It's basically a plain USB cable that's cut in half and with jumper sockets on the power and data...
In Stock
[Buy Now](https://www.adafruit.com/product/4449)
[Related Guides to the Product](https://learn.adafruit.com/products/4449/guides)
### Break-away 0.1" 36-pin strip male header - Black - 10 pack
[Break-away 0.1" 36-pin strip male header - Black - 10 pack](https://www.adafruit.com/product/392)
Breakaway header is like the duct tape of electronics. It's great for connecting things together, soldering to perf-boards, fits into any breakout or breadboard, etc. We go through these guys real fast, and thought that given how handy they are, we'd offer them in a pack of ten!
In Stock
[Buy Now](https://www.adafruit.com/product/392)
[Related Guides to the Product](https://learn.adafruit.com/products/392/guides)
### Premium Female/Female Jumper Wires - 20 x 3" (75mm)
[Premium Female/Female Jumper Wires - 20 x 3" (75mm)](https://www.adafruit.com/product/1951)
These female-female premium jumper wires are handy for making wire harnesses or jumpering between headers on PCB's. They're 3" (75mm) long and come in a 'strip' of 20 (2 pieces of each of ten rainbow colors). They have 0.1" female header contacts on either end...
In Stock
[Buy Now](https://www.adafruit.com/product/1951)
[Related Guides to the Product](https://learn.adafruit.com/products/1951/guides)
### 22-pin 0.5mm pitch FPC Flex Cable for DSI CSI or HSTX - 20cm
[22-pin 0.5mm pitch FPC Flex Cable for DSI CSI or HSTX - 20cm](https://www.adafruit.com/product/6036)
Connect this to that when a 22-pin FPC connector is needed. This 20 cm long cable is made of a flexible PCB. It's A-B style, meaning that pin one on one side will match with pin one on the other. How handy!
[We're stocking this to...](https://www.adafruit.com/category/360)
In Stock
[Buy Now](https://www.adafruit.com/product/6036)
[Related Guides to the Product](https://learn.adafruit.com/products/6036/guides)
### USB Type A to Type C Cable - approx 1 meter / 3 ft long
[USB Type A to Type C Cable - approx 1 meter / 3 ft long](https://www.adafruit.com/product/4474)
As technology changes and adapts, so does Adafruit. This **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop.
USB C is the latest industry-standard connector for...
In Stock
[Buy Now](https://www.adafruit.com/product/4474)
[Related Guides to the Product](https://learn.adafruit.com/products/4474/guides)
## Related Guides
- [Adafruit CH334F Mini USB Hub Breakouts](https://learn.adafruit.com/adafruit-ch334f-mini-4-port-usb-hub-breakout.md)
- [Adafruit RP2350 22-pin FPC HSTX to DVI Adapter](https://learn.adafruit.com/adafruit-rp2350-22-pin-fpc-hstx-to-dvi-adapter.md)
- [Adafruit Metro RP2350](https://learn.adafruit.com/adafruit-metro-rp2350.md)
- [Using a Mouse with USB Host](https://learn.adafruit.com/using-a-mouse-with-usb-host.md)
- [Adafruit Fruit Jam](https://learn.adafruit.com/adafruit-fruit-jam.md)
- [Larsio Paint Music](https://learn.adafruit.com/larsio-paint-music.md)
- [Minesweeper on the Fruit Jam and Metro RP2350](https://learn.adafruit.com/minesweeper-on-metro-rp2350.md)
- [Using DVI Video in CircuitPython](https://learn.adafruit.com/using-dvi-video-in-circuitpython.md)
- [Return to The Matrix with the Metro RP2350 or Fruit Jam](https://learn.adafruit.com/return-to-the-matrix-with-the-metro-rp2350.md)
- [Snake Game on Metro RP2350](https://learn.adafruit.com/snake-game-on-metro-rp2350.md)
- [DOOM Keeb](https://learn.adafruit.com/doom-keeb.md)
- [Tile-Matching Game on the Fruit Jam and Metro RP2350](https://learn.adafruit.com/tile-matching-game-on-the-adafruit-metro-rp2350.md)
- [Using a Keyboard with USB Host](https://learn.adafruit.com/using-a-keyboard-with-usb-host.md)
- [Adafruit BME280 Humidity + Barometric Pressure + Temperature Sensor Breakout](https://learn.adafruit.com/adafruit-bme280-humidity-barometric-pressure-temperature-sensor-breakout.md)
- [Tiny Autostereogram Construction Kit](https://learn.adafruit.com/tiny-autostereogram-construction-kit.md)
- [Microsoft Azure Cost Monitor](https://learn.adafruit.com/azure-cost-monitor.md)
- [LED Emerald with Circuit Playground Bluefruit](https://learn.adafruit.com/led-emerald-with-circuit-playground.md)