An Idle Clicker

The first game in this part has no movement, no collisions, and nothing on the screen but numbers. It is an idle clicker — a game where a number goes up, partly because you press a button and partly on its own. Cookie Clicker is the famous example; ours will bake cookies too.

We start here because it strips the game loop down to its bones. There is nothing to draw but text, nothing to move, no physics. What is left is the pure skeleton: state lives in instance variables, the update step changes that state, the draw step shows it. Once that is solid, every later game just adds more state and more interesting update logic on top of the same frame.

The Plan

The whole game is one idea: the player has some cookies, and the number of cookies goes up. It goes up by one each time the player presses space (baking a cookie by hand), and it goes up on its own once per second (from the bakers they have hired). The player can spend cookies to hire another baker, which makes the per-second number larger.

So the state is a few numbers:

• cookies — how many the player has now,
• per_click — how many a single space-press adds (we will keep this at 1),
• per_second — how many are added automatically each second,
• and that is almost it.

Everything the game does is some operation on those numbers. This is the simplest kind of state there is: just a handful of integers.

A First Version: Clicking

Start with just the manual clicking and the display:

import pyxel


class App:
    def __init__(self):
        self.cookies = 0
        pyxel.init(160, 120, title="Cookie Clicker")
        pyxel.run(self.update, self.draw)

    def update(self):
        if pyxel.btnp(pyxel.KEY_SPACE):
            self.cookies = self.cookies + 1

    def draw(self):
        pyxel.cls(1)
        pyxel.text(10, 10, f"Cookies: {self.cookies}", 7)
        pyxel.text(10, 100, "SPACE to bake", 13)


if __name__ == "__main__":
    App()

This is already a complete, if dull, game. Run it and tap space, and the count climbs. Notice the use of btnp, not btn: we want one cookie per press, not one per frame the key is held. With btn, holding space would add thirty cookies a second, which is not the game we are making.

Showing text is done with pyxel.text(x, y, string, color). The first two arguments are the pixel coordinates of the top-left corner of the text. The third is a string, which can be an f-string to show numbers. The last is a color number from 0 to 15, which you can see in Pyxel’s Color Palette. The actual text is created with f-strings, just like you’ve done since Getting Started with Programming.

Adding the Idle Part

The “idle” in idle clicker means the number goes up even when you are not touching anything. We want per_second cookies added automatically every second. At 30 frames per second, “every second” means “every 30th frame”, which is exactly the frame_count timer from the previous chapter:

def update(self):
    if pyxel.btnp(pyxel.KEY_SPACE):
        self.cookies = self.cookies + 1

    if pyxel.frame_count % 30 == 0:
        self.cookies = self.cookies + self.per_second

For this to work, per_second has to exist, so add it to __init__:

def __init__(self):
    self.cookies = 0
    self.per_second = 0
    pyxel.init(160, 120, title="Cookie Clicker")
    pyxel.run(self.update, self.draw)

It starts at 0, so at first nothing happens automatically — there are no bakers yet. The next step is to let the player hire some.

Spending Cookies on Upgrades

An upgrade is a trade: spend some cookies now, get a higher per_second forever. We let the player press U to hire a baker, which costs 10 cookies and adds 1 to per_second:

def update(self):
    if pyxel.btnp(pyxel.KEY_SPACE):
        self.cookies = self.cookies + 1

    if pyxel.frame_count % 30 == 0:
        self.cookies = self.cookies + self.per_second

    if pyxel.btnp(pyxel.KEY_U) and self.cookies >= 10:
        self.cookies = self.cookies - 10
        self.per_second = self.per_second + 1

The condition self.cookies >= 10 is the important part. Without it, a player with 3 cookies could still buy an upgrade and end up with -7 cookies. The check uses the same habit as Exceptions and Input Validation: before performing an action that requires a resource, confirm the resource is there.

The Complete Game

Putting it together, with a fuller display:

import pyxel


class App:
    def __init__(self):
        self.cookies = 0
        self.per_second = 0
        pyxel.init(160, 120, title="Cookie Clicker")
        pyxel.run(self.update, self.draw)

    def update(self):
        # bake one by hand
        if pyxel.btnp(pyxel.KEY_SPACE):
            self.cookies = self.cookies + 1

        # the bakers produce, once per second
        if pyxel.frame_count % 30 == 0:
            self.cookies = self.cookies + self.per_second

        # hire a baker if you can afford it
        if pyxel.btnp(pyxel.KEY_U) and self.cookies >= 10:
            self.cookies = self.cookies - 10
            self.per_second = self.per_second + 1

    def draw(self):
        pyxel.cls(1)
        pyxel.text(10, 10, f"Cookies: {self.cookies}", 7)
        pyxel.text(10, 25, f"Per second: {self.per_second}", 6)
        pyxel.text(10, 95, "SPACE  bake a cookie", 13)
        pyxel.text(10, 105, "U      hire a baker (10)", 13)


if __name__ == "__main__":
    App()

Twenty-odd lines, and it is a real game with a real loop: an early-game grind of tapping space, a turning point when you can afford your first baker, and the satisfying moment when the per-second number takes over and the cookies climb on their own. That loop — spend effort, buy something that reduces the effort, repeat — is the heart of a whole genre, and you have just built the smallest possible version of it.

What did the game loop give us here? The update/draw split, the frame_count timer, and a few integers of state. Every game from here on adds more, but none of it is more fundamental than this.

Check Your Understanding

1. Why does the manual-bake action use pyxel.btnp rather than pyxel.btn?
2. The automatic cookies are added when pyxel.frame_count % 30 == 0. What would change if you used % 15 instead? % 60?
3. Why is the condition self.cookies >= 10 necessary on the upgrade? What state could the game reach without it?
4. The game’s entire state is two integers. Which part of the program reads them, and which part changes them?
5. Where in the program would you add a second kind of upgrade — say, one that makes each hand-bake worth 2 cookies instead of 1?