# PYOA for PyGamer/PyBadge - Adding Cursor Support to CircuitPython

## Overview

![](https://cdn-learn.adafruit.com/assets/assets/000/077/537/medium800thumb/lcds___displays_ezgif.com-gif-maker_%281%29.jpg?1561585569)

_Want to control your CircuitPython game with your PyGamer's Joystick? Click buttons on the display using the buttons on your PyGamer/PyBadge?_

We've created a **Cursor** module for **CircuitPython**. This module provides an **interactive mouse cursor to add to your game or interface.**

In this guide, **you'll learn how to add a cursor to your CircuitPython device's display and control it with your PyBadge or PyGamer**.

Then, we added cursor support to the **Python Choose your Own Adventure gaming framework (PYOA)** so you can play choose-your-own-adventure games on your PyBadge/PyGamer.

## Parts

Any of the Adafruit Open-Source gaming platforms will work with this guide:

### Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino

[Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino](https://www.adafruit.com/product/4242)
What fits in your pocket, is fully Open Source, and can run CircuitPython, MakeCode Arcade or Arduino games you write yourself? That's right, it's the **Adafruit PyGamer!** We wanted to make an entry-level gaming handheld for DIY gaming, and maybe a little...

Out of Stock
[Buy Now](https://www.adafruit.com/product/4242)
[Related Guides to the Product](https://learn.adafruit.com/products/4242/guides)
![Angled shot of Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino.](https://cdn-shop.adafruit.com/640x480/4242-00.jpg)

### Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino

[Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino](https://www.adafruit.com/product/4200)
What's the size of a credit card and can run CircuitPython, MakeCode Arcade or Arduino? That's right, its the **Adafruit PyBadge!** We wanted to see how much we could cram into a ​3 3⁄8 × ​2 1⁄8 inch rounded rectangle, to make an all-in-one dev board with...

Out of Stock
[Buy Now](https://www.adafruit.com/product/4200)
[Related Guides to the Product](https://learn.adafruit.com/products/4200/guides)
![Angled shot of a Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino. ](https://cdn-shop.adafruit.com/640x480/4200-01.jpg)

### Adafruit PyBadge LC - MakeCode Arcade, CircuitPython, or Arduino

[Adafruit PyBadge LC - MakeCode Arcade, CircuitPython, or Arduino](https://www.adafruit.com/product/3939)
What's the size of a credit card and can run CircuitPython, MakeCode Arcade or Arduino even when you're on a budget? That's right, it's the  **Adafruit PyBadge LC!**  We wanted to see how much we could cram into a ​3 3⁄8 × ​2 1⁄8 inch...

In Stock
[Buy Now](https://www.adafruit.com/product/3939)
[Related Guides to the Product](https://learn.adafruit.com/products/3939/guides)
![Angled Shot of Adafruit PyBadge - Low Cost. ](https://cdn-shop.adafruit.com/640x480/3939-05.jpg)

### Adafruit PyGamer Starter Kit

[Adafruit PyGamer Starter Kit](https://www.adafruit.com/product/4277)
**Please note: you may get a royal blue _or_ purple case with your starter kit (they're both lovely colors)**

What fits in your pocket, is fully Open Source, and can run CircuitPython, MakeCode Arcade or Arduino games you write yourself? That's right,...

Out of Stock
[Buy Now](https://www.adafruit.com/product/4277)
[Related Guides to the Product](https://learn.adafruit.com/products/4277/guides)
![Adafruit PyGamer Starter Kit with PCB, enclosure, buttons, and storage bag](https://cdn-shop.adafruit.com/640x480/4277-08.jpg)

## Materials
### Part: USB Cable
quantity: 1
USB Cable - USB A to Micro-B
[USB Cable](https://www.adafruit.com/product/592)

### Part: USB Cable
quantity: 1
USB Cable - USB A to micro-B, purple, 2m long
[USB Cable](https://www.adafruit.com/product/4148)

# PYOA for PyGamer/PyBadge - Adding Cursor Support to CircuitPython

## Code Overview 

It's easy to use the [CursorControl module](https://github.com/adafruit/Adafruit_CircuitPython_CursorControl) with CircuitPython.  This module allows you to easily write Python code which generates and controls a mouse cursor on your CircuitPython device's display.

## CursorControl Module Installation

Next you'll need to install the [Adafruit CircuitPython CursorControl](https://github.com/adafruit/Adafruit_CircuitPython_CursorControl) library on your CircuitPython board.  

First make sure you are running the [latest version of Adafruit CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython) for your board.

Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from [Adafruit's CircuitPython library bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle).  Our introduction guide has [a great page on how to install the library bundle](https://learn.adafruit.com/welcome-to-circuitpython/circuitpython-libraries) for both express and non-express boards.

Remember for non-express boards like the, you'll need to manually install the necessary libraries from the bundle:

- **adafruit\_cursorcontrol.mpy**
- **cursorcontrol\_cursormanager.mpy**

You can also download the **adafruit\_cursorcontrol.mpy**  from [its releases page on Github](https://github.com/adafruit/Adafruit_CircuitPython_CursorControl/releases).

Before continuing make sure your board's lib folder or root filesystem has the  **adafruit\_cursorcontrol.mpy**  and  **cursorcontrol\_cursormanager.mpy ** files are copied over.

Next[ connect to the board's serial REPL](https://learn.adafruit.com/welcome-to-circuitpython/the-repl) so you are at the CircuitPython  **\>\>\>**  prompt.

## CircuitPython Usage

To demonstrate the usage of the CursorControl library, we'll use the example below. Save the file below to a **code.py** file. Then, upload the  **code.py file**  to the  **CIRCUITPY**  drive.

https://github.com/adafruit/Adafruit_CircuitPython_CursorControl/blob/main/examples/cursorcontrol_simpletest.py

After saving the **code.py** to your **CIRCUITPY** drive, you should see a cursor appear on your device's display.

**Move the cursor around by pressing the PyBadge's D-Pad buttons or moving the PyGamer's Joystick!**

![](https://cdn-learn.adafruit.com/assets/assets/000/077/535/medium800thumb/lcds___displays_ezgif.com-video-to-gif_%281%29.jpg?1561584594)

## CursorControl Module Overview

The [CursorControl library](https://github.com/adafruit/Adafruit_CircuitPython_CursorControl/) contains two classes, `Cursor` and `CursorManager`. The `Cursor` class is responsible for generating a cursor bitmap, displaying it on the screen, and adjusting the cursor's properties.

The `CursorManager` is a high-level class responsible for initializing a hardware interface for the cursor. This includes methods to set up the joystick or buttons and control the cursor's properties using them.

Let's take a look at a short example to understand how these two classes interact.

First, the example creates a display object (using the board's builtin `DISPLAY`) and a displayio group. This step is required - the `Cursor` class does **not** handle generating a displayio group.

- For more information about DisplayIO Groups in CircuitPython, [check out this guide.](https://learn.adafruit.com/circuitpython-display-support-using-displayio/group)

```auto
# Create the display
display = board.DISPLAY

# Create the display context
splash = displayio.Group(max_size=5)
```

The example next initializes the `Cursor` object by passing it the board's display interface and the display group.

If you want to set the cursor's properties during `Cursor` initialization (to hide the cursor when a game starts or increase the cursor's scale) - take a look at the ` __init__ ` keyword arguments for this class [here](https://github.com/adafruit/Adafruit_CircuitPython_CursorControl/blob/master/adafruit_cursorcontrol/cursorcontrol.py).

```auto
# initialize the mouse cursor object
mouse_cursor = Cursor(display, display_group=splash)
```

 **While you now have a cursor object** (and loading the code so far will make a cursor appear on your display)  - **you need a way of controlling it.** You _could_ control it from the loop and create methods to read the joystick and buttons, but we've already gone ahead and built a class to do this.

If you're using a PyGamer or PyBadge, all you need to do to control a `Cursor` is **pass the `Cursor` object to the `CursorManager`**

```auto
# initialize the cursormanager
cursor = CursorManager(mouse_cursor)

```

Then, you'll set the display to "show" the displayio _splash_ group

```auto
# show displayio group
display.show(splash)

```

The top of the loop calls `cursor.update()`. This method within `CursorManager` handles button presses, joystick movement and d-pad button clicks. It also sets the `CursorManager`'s `is_clicked` property. 

```auto
while True:
    cursor.update()
    if cursor.is_clicked:
        if mouse_cursor.hide:
            mouse_cursor.hide = False
        else:
            mouse_cursor.hide = True
    time.sleep(0.01)
```

Next, we'll want to see if the cursor was clicked. The `.is_clicked` property is set by a call to `cursor.update()` and is a boolean. If it's true, you can hide the `Cursor` by setting its `.hide` property.

## Buttons and Text Elements with Cursor

Below is an advanced example which uses the Display Text module as well as the Button module. Moving the cursors over the button and clicking set different Cursor attributes such as cursor speed and cursor scale size. 

https://github.com/adafruit/Adafruit_CircuitPython_CursorControl/blob/main/examples/cursorcontrol_buttons_text.py

![](https://cdn-learn.adafruit.com/assets/assets/000/077/534/medium800thumb/lcds___displays_ezgif.com-gif-maker_%281%29.jpg?1561584070)

# PYOA for PyGamer/PyBadge - Adding Cursor Support to CircuitPython

## CursorControl Docs

# PYOA for PyGamer/PyBadge - Adding Cursor Support to CircuitPython

## Adding Cursor to PYOA

We enjoyed Dave Astel's [CircuitPython Choose your Own Adventure guide](https://learn.adafruit.com/circuit-python-choose-you-own-adventure) - but it required a PyPortal to _tap_ the buttons on the display. We wanted to play PYOA games on our PyBadge/PyGamer, so **we added CursorControl** to PYOA framework to let you _click_ the buttons instead of tapping them.

If you want to use PYOA on your PyBadge/PyGamer, follow along below!

Before you get started, you'll want to **prepare your PyBadge/PyGamer with the required libraries to build a choose your own adventure game** :

- [Follow the steps listed on this page](https://learn.adafruit.com/circuit-python-choose-you-own-adventure/preparing-your-pyportal) and come back here when you've followed them.

## Code Setup

Clicking on download _ **Project zip** _ below will give you a zip file that you will need to dig into to get the  **cave**  directory. Copy this directory to your  **CIRCUITPY**  drive.

https://github.com/adafruit/Adafruit_CircuitPython_PYOA/blob/main/examples/cave/cyoa.json

 In the `code.py` file on your device, set the example as the **cave** example. You can do this by  **changing the following line from:**

`gfx.load_game("/cyoa")`

**to**

`gfx.load_game("/cave")`

## Code Overview
Your PyGamer/PyBadge will automatically load the cave game and create a cursor overlay. You can **move the cursor around using the joystick** on the PyGamer **or the D-Pad buttons** on the PyBadge. 

![](https://cdn-learn.adafruit.com/assets/assets/000/077/527/medium800thumb/lcds___displays_ezgif.com-video-to-gif.jpg?1561579957)

 **To click the buttons on the display, press the A button**. This is the same button for both the PyBadge and the PyGamer.

![](https://cdn-learn.adafruit.com/assets/assets/000/077/528/medium800thumb/lcds___displays_ezgif.com-gif-maker.jpg?1561580221)

 **That's it! **** If you would like to try your hand at designing or writing your own adventure game**, [check out this page on Dave Astel's guide](https://learn.adafruit.com/circuit-python-choose-you-own-adventure/writing-an-adventure).


## Featured Products

### Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino

[Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino](https://www.adafruit.com/product/4242)
What fits in your pocket, is fully Open Source, and can run CircuitPython, MakeCode Arcade or Arduino games you write yourself? That's right, it's the **Adafruit PyGamer!** We wanted to make an entry-level gaming handheld for DIY gaming, and maybe a little...

Out of Stock
[Buy Now](https://www.adafruit.com/product/4242)
[Related Guides to the Product](https://learn.adafruit.com/products/4242/guides)
### Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino

[Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino](https://www.adafruit.com/product/4200)
What's the size of a credit card and can run CircuitPython, MakeCode Arcade or Arduino? That's right, its the **Adafruit PyBadge!** We wanted to see how much we could cram into a ​3 3⁄8 × ​2 1⁄8 inch rounded rectangle, to make an all-in-one dev board with...

Out of Stock
[Buy Now](https://www.adafruit.com/product/4200)
[Related Guides to the Product](https://learn.adafruit.com/products/4200/guides)
### Adafruit PyBadge LC - MakeCode Arcade, CircuitPython, or Arduino

[Adafruit PyBadge LC - MakeCode Arcade, CircuitPython, or Arduino](https://www.adafruit.com/product/3939)
What's the size of a credit card and can run CircuitPython, MakeCode Arcade or Arduino even when you're on a budget? That's right, it's the  **Adafruit PyBadge LC!**  We wanted to see how much we could cram into a ​3 3⁄8 × ​2 1⁄8 inch...

In Stock
[Buy Now](https://www.adafruit.com/product/3939)
[Related Guides to the Product](https://learn.adafruit.com/products/3939/guides)
### Adafruit PyGamer Starter Kit

[Adafruit PyGamer Starter Kit](https://www.adafruit.com/product/4277)
**Please note: you may get a royal blue _or_ purple case with your starter kit (they're both lovely colors)**

What fits in your pocket, is fully Open Source, and can run CircuitPython, MakeCode Arcade or Arduino games you write yourself? That's right,...

Out of Stock
[Buy Now](https://www.adafruit.com/product/4277)
[Related Guides to the Product](https://learn.adafruit.com/products/4277/guides)
### USB cable - USB A to Micro-B

[USB cable - USB A to Micro-B](https://www.adafruit.com/product/592)
This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or microcontroller

Approximately 3 feet / 1 meter long

Out of Stock
[Buy Now](https://www.adafruit.com/product/592)
[Related Guides to the Product](https://learn.adafruit.com/products/592/guides)
### Pink and Purple Braided USB A to Micro B Cable - 2 meter long

[Pink and Purple Braided USB A to Micro B Cable - 2 meter long](https://www.adafruit.com/product/4148)
This cable is super-fashionable with a woven pink and purple Blinka-like pattern!

First let's talk about the cover and over-molding. We got these in custom colors, and if you _have_ to have visible cables, then you might as well have the nicest fabric-bound...

No Longer Stocked
[Buy Now](https://www.adafruit.com/product/4148)
[Related Guides to the Product](https://learn.adafruit.com/products/4148/guides)

## Related Guides

- [Adafruit PyBadge and PyBadge LC](https://learn.adafruit.com/adafruit-pybadge.md)
- [Introducing Adafruit PyGamer](https://learn.adafruit.com/adafruit-pygamer.md)
- [Re-MakeCode the Classics: Arkanoid](https://learn.adafruit.com/re-makecode-the-classics-arkanoid.md)
- [Creating Your First Tilemap Game with CircuitPython](https://learn.adafruit.com/creating-your-first-tilemap-game-with-circuitpython.md)
- [Two Player Game System for PyGamer and RFM69HCW Radio Wing](https://learn.adafruit.com/two-player-game-system-for-pygamer-and-rfm69hcw-radio-wing.md)
- [Game & Watch Octopus](https://learn.adafruit.com/game-watch-octopus.md)
- [PixelDust Digital Sand Demos for Arcada](https://learn.adafruit.com/pixeldust-digital-sand-demos-for-arcada.md)
- [Arcada Animated GIF Display](https://learn.adafruit.com/pyportal-animated-gif-display.md)
- [Program in Logo on an Apple II](https://learn.adafruit.com/program-logo-on-an-apple-ii.md)
- [JOY of Arcada — USB Game Pad for Adafruit PyGamer and PyBadge](https://learn.adafruit.com/joy-of-arcada-usb-game-pad-for-adafruit-pygamer-pybadge.md)
- [PyGamer - Gaming Handheld Crank](https://learn.adafruit.com/gaming-handheld-crank.md)
- [Trash Panda 2: Garbage Day](https://learn.adafruit.com/trash-panda-2-dumpster-dive.md)
- [PyGamer Marble Labyrinth in MakeCode Arcade](https://learn.adafruit.com/pygamer-marble-labyrinth-in-makecode-arcade.md)
- [Custom Color Palettes for MakeCode Arcade Games](https://learn.adafruit.com/custom-color-palettes-for-makecode-arcade-games.md)
- [Make a Zelda Master Sword with the RP2040 Prop-Maker Feather](https://learn.adafruit.com/master-sword-rp2040.md)
- [Which CircuitPython Board is Right for You?](https://learn.adafruit.com/choose-your-circuitpython-board.md)
- [CircuitPython Turtle Graphics](https://learn.adafruit.com/circuitpython-turtle-graphics.md)