CS101: Introduction to Computer Science

Activity 02: Firefly Collector - Debugging Lists, Dictionaries, and Literals

Assigned and Due

• Assigned: Friday, 11th September 2026

• Due and Expiration: Monday, 14th September 2026 by class time.

• Estimated Time: Approximately 60 minutes

Note 1: The expiration date is the last date you can submit your work for a grade.

Note 2: This is a checkmark grade

Table of contents

• CS101: Introduction to Computer Science
  • Assigned and Due
  • Table of contents
  • Deliverables
  • Project Goals
  • The Game
  • Getting Started with uv
  • Part 1: Fix the Settings (config.py)
  • Part 2: Fix the Forest Creatures (entities.py)
  • Part 3: Fix the Scoreboard (game.py)
  • The Ten Bugs at a Glance
  • Running the Tests
  • Reflection Questions
  • Checking Your Work
  • Getting Help

Note: Parts of this work were enhanced by Claude.

Deliverables

You are to complete and push to your repository the following files:

• src/firefly_collector/config.py - Bugs 1 through 5 repaired
• src/firefly_collector/entities.py - Bugs 6 through 9 repaired
• src/firefly_collector/game.py - Bug 10 repaired
• writing/reflection.md - Reflection document with answers to all questions

Project Goals

• To read Python code that someone else wrote and find the mistakes in it.
• To tell the difference between a string literal ("900") and an integer literal (900), and to explain why that difference matters.
• To build and read tuple literals, such as the three-number colors (255, 255, 120).
• To look values up in a dictionary by key, and to understand why a misspelled key raises a KeyError.
• To store many similar things in a list and to add to that list with .append().
• To recognize the classic bug of removing items from a list while looping over it.
• To update a value that is already stored in a dictionary, instead of overwriting it.
• To read a Python error message, find the file and line it names, and use it to guide a repair.
• To use the uv project manager to create a virtual environment and install a library.

The Game

You play as a small glowing figure wandering a dark forest at night. Fireflies drift into view around you, and every one you touch is worth 10 points. You have 60 seconds.

But the forest is not entirely safe. With 30 seconds left, an owl wakes up and begins hunting you. With 15 seconds left, a shadow creature starts its slow, patient chase. Touch either one and you lose a life. Lose all three and the forest goes quiet.

A round looks roughly like this:

      🌲          🌲

            ✨


   🌲       🧑        🌲

                  ✨

      🦉
            ✨

   🌲                 🌲

Move with WASD or the arrow keys. Press Q to quit, and R to play again once a round ends.

There is no artwork anywhere in this project. Every single thing you see is drawn from Pygame circles, rectangles, and triangles. The glow around each firefly is nothing more than four translucent circles stacked on top of one another, largest first:

pygame.draw.circle(screen, (255, 255, 120), position, 4)

There is just one problem. The game does not run. A previous programmer left ten bugs behind, and every single one of them has to do with a list, a dictionary, or a literal value. Your job is to hunt them down.

Getting Started with uv

This project uses uv, a fast project manager for Python. It reads pyproject.toml, builds a private virtual environment inside the project folder, and installs Pygame into it. You never have to activate anything by hand.

1. Check that uv is installed:

   uv --version

   If that command is not found, install it with curl -LsSf https://astral.sh/uv/install.sh | sh on macOS or Linux, or see the installation guide.

2. From the top of this project, create the environment and install Pygame:

   uv sync

3. Try to start the game:

   uv run firefly-collector

   It will crash. That is expected, and it is where the activity begins. Read the last few lines of the error carefully. Python tells you the file, the line number, and the kind of mistake. Follow it to your first bug.

Tip: fix one bug, run the game again, and read the next error. Each repair gets you a little further. This is exactly how real programmers work, and it is much easier than trying to fix all ten at once.

Part 1: Fix the Settings (config.py)

Location: src/firefly_collector/config.py

This file holds every number, color, and word the game needs. Nothing here does any work; it is pure data. That makes it the perfect place to practice reading literals, dictionaries, and lists.

What you will do:

1. TODO 1 - The window width is stored as a string instead of a number.
2. TODO 2 - A key in the COLORS dictionary is misspelled, so a lookup fails.
3. TODO 3 - A color tuple is missing one of its three components.
4. TODO 4 - The length of a round is stored as a string, so the timer cannot do arithmetic.
5. TODO 5 - One tuple in the TREE_POSITIONS list is missing a value.

Tips:

• A literal is a value you type directly into the code. 900 is an integer literal and "900" is a string literal. They look almost the same to you, and they are completely different to Python. Try 900 - 1 and "900" - 1 in uv run python to see why.
• A tuple is a fixed group of values in parentheses. A Pygame color is always a tuple of exactly three integers: (red, green, blue), each from 0 to 255.
• A dictionary key must match exactly. "firefly" and "fire_fly" are as different to Python as "cat" and "dog".

Part 2: Fix the Forest Creatures (entities.py)

Location: src/firefly_collector/entities.py

Every single thing in this game is a dictionary, and every group of things is a list. One firefly looks like this:

{"x": 412, "y": 88, "radius": 4, "flicker": 1.9}

and all of the fireflies together are just a list of those dictionaries:

[{"x": 412, ...}, {"x": 120, ...}, {"x": 733, ...}]

There is no Pygame code in this file at all, which is what makes it easy to test.

What you will do:

6. TODO 6 - A firefly is built with the keys "pos_x" and "pos_y", but the rest of the game asks for "x" and "y".
7. TODO 7 - Each new firefly is wrapped in a list before being appended, so the list fills with lists instead of dictionaries.
8. TODO 8 - Fireflies are removed from the very list that is being looped over, so some of them get skipped.
9. TODO 9 - An off-by-one comparison lets one extra firefly into the forest.

Tips:

• my_list.append(item) adds one item. If you hand it [item], then the one item it adds is a list.
• Never remove items from a list while you are looping over it. Build a new list of the items you want to keep, and return that instead.
• If a list should end up with 8 items, then while len(items) < 8: is right and while len(items) <= 8: gives you 9. Reason it out with a small number, such as 2, if the comparison is hard to picture.

Part 3: Fix the Scoreboard (game.py)

Location: src/firefly_collector/game.py

This is the largest file, and it holds the Pygame window, the main loop, and all of the drawing. You only need to change one line in it.

What you will do:

10. TODO 10 - The score in the state dictionary is replaced each frame instead of being added to, so it never climbs above 10.

Tips:

• To change a value that is already in a dictionary, you have to read the old value out first: state["score"] = state["score"] + points. The shorter += form does exactly the same thing.
• The line directly beneath the bug already does it correctly. Compare the two.
• You are welcome to read the rest of this file even though you do not have to change it. The drawing functions near the top show how the glow effect is built.

The Ten Bugs at a Glance

#	File	Concept	Symptom
1	config.py	Literal (string vs integer)	The window will not open
2	config.py	Dictionary key	KeyError: 'firefly'
3	config.py	Tuple literal	The trees cannot be drawn
4	config.py	Dictionary value literal	TypeError in the timer
5	config.py	List of tuples	One tree has no height
6	entities.py	Dictionary keys	KeyError: 'x'
7	entities.py	List .append()	Fireflies become one-item lists
8	entities.py	Mutating a list while looping	Fireflies get skipped
9	entities.py	List length comparison	One firefly too many
10	game.py	Updating a dictionary value	The score sticks at 10

Running the Tests

This project comes with automatic tests. Each one checks a single bug, and each test name tells you which bug it is watching. Run them with:

uv run pytest -v

At the start, most of them fail. As you repair each bug, more of them turn green. When all of them pass, your game works.

To run only the tests for one file:

uv run pytest tests/test_config.py -v

To prove the game itself starts, plays, and closes cleanly, run the built-in self test. It plays ninety frames with nobody at the keyboard:

uv run firefly-collector --self-test

Reflection Questions

After you have repaired all ten bugs and the game runs, answer the reflection questions in the writing/reflection.md file. These questions connect the bugs you fixed to the ideas about lists, dictionaries, and literals from this week's class.

Please write in complete sentences and be specific. "I fixed the dictionary" says much less than "I renamed the key fire_fly to firefly so that the lookup COLORS["firefly"] would find it."

Checking Your Work

To check if your work meets the assignment requirements, you can use GatorGrade:

gatorgrade --config config/gatorgrade.yml

This will automatically verify:

• All required files exist
• All TODO markers have been removed from the three source files
• The game's tests pass
• The reflection document is complete and has your name on it
• You have made at least 3 commits to your repository

Note: Make sure to commit your changes regularly throughout the activity using:

git add .
git commit -m "Descriptive message about your changes"
git push

Getting Help

If you have any questions, please ask your friendly Technical Leader, or your instructor.

When you ask for help with a crash, bring the whole error message with you, not just the last line. The lines above it tell the story of how Python got there, and they are usually where the answer is hiding.