DEV Community: Kajiru

Simple Ranking with SQLAlchemy

Kajiru — Wed, 21 Jan 2026 15:00:00 +0000

Simple Ranking with SQLAlchemy

In this article, we will create a simple ranking system using SQLAlchemy.

SQLite manages a single database as a single file.

To inspect the generated database file, it is convenient to use dedicated software such as:

DB Browser for SQLite

The complete source code is shown at the end.

1. Preparing the Modules

In your working folder, prepare main.py for execution and util_db.py to collect all database-related logic.

The folder structure is as follows:

# Folder structure
working_folder/
 ├ main.py      # Main program
 └ util_db.py   # Database utility

2. Installing SQLAlchemy

SQLAlchemy is a third-party module, so it must be installed separately.

# Command (Mac)
$ python3 -m pip install sqlalchemy

# Command (Windows)
$ python -m pip install sqlalchemy

3. CRUD Pattern with SQLAlchemy

CRUD stands for Create, Read, Update, and Delete, the four basic database operations.

In util_db.py, import the required modules and define the MyDB class.

In the constructor, the database file name is received as an argument, and create_engine() is used to create the SQLAlchemy engine.

(If echo=True is specified, executed SQL statements will be printed to the console.)

At the same time, sessionmaker() is used to prepare a session factory for database access.

Finally, passing the engine to create_all() creates the tables.

(Only tables that do not already exist in the database will be created.)

# util_db.py (excerpt)
def __init__(self, path):
    """ Constructor """
    self.dir_base = os.path.dirname(__file__)
    self.db_path = "sqlite:///" + os.path.join(self.dir_base, path)
    # Engine, Database
    self.db_engine = create_engine(self.db_path, echo=True)
    self.db_session = sessionmaker(bind=self.db_engine)
    Base.metadata.create_all(self.db_engine)  # Create tables

The initial state of the MyDB class is shown below.

# util_db.py (excerpt)
import datetime
import os
from sqlalchemy import (
    create_engine,
    Column,
    Integer,
    select,
    String
)
from sqlalchemy.orm import declarative_base
from sqlalchemy.orm import sessionmaker

class MyDB():

    def __init__(self, path):
        """ Constructor """
        self.dir_base = os.path.dirname(__file__)
        self.db_path = "sqlite:///" + os.path.join(self.dir_base, path)
        # Engine, Session
        self.db_engine = create_engine(self.db_path, echo=True)
        self.db_session = sessionmaker(bind=self.db_engine)
        Base.metadata.create_all(self.db_engine)  # Create tables

    # CRUD(Create)
    def insert_record(self, name, comment, score):
        """ Insert a record """
        pass

    # CRUD(Read)
    def read_records(self, limit=10):
        """ Read records (up to limit) """
        pass

    def read_record(self, uid):
        """ Read one record """
        pass

    # CRUD(Update)
    def update_record(self, uid, name, comment, score):
        """ Update one record """
        pass

    # CRUD(Delete)
    def delete_record(self, uid):
        """ Delete one record """
        pass

    # Time
    def get_time(self):
        """ Get current datetime """
        return datetime.datetime.now().strftime("%Y/%m/%d %H:%M:%S")

4. Defining the ORM

SQLAlchemy accesses databases using a mechanism called ORM (Object Relational Mapping).

(It is also possible to use raw SQL.)

First, define a Record class in util_db.py that inherits from declarative_base().

This class is designed for a simple ranking system, with the table name set to ranking and the following simple columns:

Column name	Meaning	Example
uid	Sequential ID	1, 2, 3, ...
name	User name	Alex
comment	Comment	I'm champion!!
score	Score	123
time_stamp	Created time	1970/01/01 00:00:00

# util_db.py (excerpt)
# ORM
Base = declarative_base()
class Record(Base):

    # Table
    __tablename__ = "ranking"
    # ID
    uid = Column(Integer, primary_key=True, autoincrement=True)
    # Name
    name = Column(String(12), nullable=False)
    # Comment
    comment = Column(String(24), nullable=False)
    # Score
    score = Column(Integer, nullable=False)
    # Timestamp
    time_stamp = Column(String(24), nullable=False)

    def __str__(self):
        return "uid:{0}, name:{1}, comment:{2}, score:{3}, time_stamp:{4}".format(
            self.uid, self.name, self.comment, self.score, self.time_stamp)

5. Implementing CRUD Operations

Now we implement the CRUD operations in the MyDB class.

5-1. Inserting Data (Create)

This method inserts data into the table.

Pay attention to with self.db_session() as session:.

Here, a temporary session is created, data is added and committed, and the session is automatically closed after leaving the scope.

# util_db.py (excerpt)
# CRUD(Create)
def insert_record(self, name, comment, score):
    """ Insert a record """
    print("insert_record:", name, comment)
    record = Record(
        name=name,
        comment=comment,
        score=score,
        time_stamp=self.get_time())
    with self.db_session() as session:
        session.add(record)
        session.commit()
        return record.uid

5-2. Reading Data (Read)

This method retrieves data from the table.

In read_records(), the top limit records are retrieved in descending order by score.

# util_db.py (excerpt)
# CRUD(Read)
def read_records(self, limit=10):
    """ Read records (up to limit) """
    print("read_records:", limit)
    with self.db_session() as session:
        stmt = select(Record).order_by(Record.score.desc()).limit(limit)
        return session.scalars(stmt).all()

In read_record(), a single record is retrieved.

As shown below, session.get(Record, uid) fetches the record corresponding to uid.

# util_db.py (excerpt)
def read_record(self, uid):
    """ Read one record """
    print("read_record:", uid)
    with self.db_session() as session:
        return session.get(Record, uid)

5-3. Updating Data (Update)

This method updates an existing record.

First, the record is retrieved using session.get(Record, uid), then the object’s attributes are updated directly.

After updating, commit() is called.

# util_db.py (excerpt)
# CRUD(Update)
def update_record(self, uid, name, comment, score):
    """ Update one record """
    print("update_record:", uid)
    with self.db_session() as session:
        record = session.get(Record, uid)
        if record is None:
            return -1
        record.name = name
        record.comment = comment
        record.score = score
        record.time_stamp = self.get_time()
        session.commit()
        return record.uid

5-4. Deleting Data (Delete)

This method deletes a record from the table.

session.delete(record) removes the record, and commit() finalizes the deletion.

# util_db.py (excerpt)
# CRUD(Delete)
def delete_record(self, uid):
    """ Delete one record """
    print("delete_record:", uid)
    with self.db_session() as session:
        record = session.get(Record, uid)
        if record is None:
            return -1
        session.delete(record)
        session.commit()
        return record.uid

Testing

The test procedure is as follows.

Here, a random name, comment, and score are generated and inserted into the table.

(By uncommenting some parts, you can also test update and delete operations.)

# main.py
# Members
names = ["Alex", "Becky", "Christy", "David"]
comments = ["Champion!!", "Nice!!", "Good!!", "OMG...!!"]

# MyDB
my_db = util_db.MyDB("data.sqlite")

# Insert (add one random record)
name = random.choice(names)
comment = random.choice(comments)
score = random.randint(30, 300)
result = my_db.insert_record(name, comment, score)
print("insert:", result)

# Update (a hacker appears and tampers with data)
# my_db.update_record(1, "Thomas", "Hi, I'm hacker!!", 777)

# Delete (delete record with uid=4)
# my_db.delete_record(4)

# Read (get one record with uid=1)
# record = my_db.read_record(1)
# print("Record:", record)

# Read (get top 5 scores)
records = my_db.read_records(limit=5)
print("= Ranking =")
for record in records:
    print("Record:", record)

Execution Result

The output will look like this. (A hacker has taken first place!)

= Ranking =
Record: uid:1, name:Thomas, comment:Hi, I'm hacker!!, score:777, time_stamp:2026/01/10 01:57:14
Record: uid:8, name:Alex, comment:Champion!!, score:291, time_stamp:2026/01/10 00:01:19
Record: uid:33, name:Christy, comment:OMG...!!, score:263, time_stamp:2026/01/10 01:56:35
Record: uid:16, name:Becky, comment:Nice!!, score:256, time_stamp:2026/01/10 00:01:27
Record: uid:18, name:Christy, comment:OMG...!!, score:252, time_stamp:2026/01/10 00:01:29

Complete Code

Below is the complete implementation.

# util_db.py
import datetime
import os
from sqlalchemy import (
    create_engine,
    Column,
    Integer,
    select,
    String
)
from sqlalchemy.orm import declarative_base
from sqlalchemy.orm import sessionmaker

class MyDB():

    def __init__(self, path):
        """ Constructor """
        self.dir_base = os.path.dirname(__file__)
        self.db_path = "sqlite:///" + os.path.join(self.dir_base, path)
        self.db_engine = create_engine(self.db_path, echo=True)
        self.db_session = sessionmaker(bind=self.db_engine)
        Base.metadata.create_all(self.db_engine)

    def insert_record(self, name, comment, score):
        """ Insert a record """
        print("insert_record:", name, comment)
        record = Record(
            name=name,
            comment=comment,
            score=score,
            time_stamp=self.get_time())
        with self.db_session() as session:
            session.add(record)
            session.commit()
            return record.uid

    def read_records(self, limit=10):
        """ Read records """
        print("read_records:", limit)
        with self.db_session() as session:
            stmt = select(Record).order_by(Record.score.desc()).limit(limit)
            return session.scalars(stmt).all()

    def read_record(self, uid):
        """ Read one record """
        print("read_record:", uid)
        with self.db_session() as session:
            return session.get(Record, uid)

    def update_record(self, uid, name, comment, score):
        """ Update one record """
        print("update_record:", uid)
        with self.db_session() as session:
            record = session.get(Record, uid)
            if record is None:
                return -1
            record.name = name
            record.comment = comment
            record.score = score
            record.time_stamp = self.get_time()
            session.commit()
            return record.uid

    def delete_record(self, uid):
        """ Delete one record """
        print("delete_record:", uid)
        with self.db_session() as session:
            record = session.get(Record, uid)
            if record is None:
                return -1
            session.delete(record)
            session.commit()
            return record.uid

    def get_time(self):
        """ Get current datetime """
        return datetime.datetime.now().strftime("%Y/%m/%d %H:%M:%S")

Base = declarative_base()
class Record(Base):

    __tablename__ = "ranking"
    uid = Column(Integer, primary_key=True, autoincrement=True)
    name = Column(String(12), nullable=False)
    comment = Column(String(24), nullable=False)
    score = Column(Integer, nullable=False)
    time_stamp = Column(String(24), nullable=False)

    def __str__(self):
        return "uid:{0}, name:{1}, comment:{2}, score:{3}, time_stamp:{4}".format(
            self.uid, self.name, self.comment, self.score, self.time_stamp)

# main.py
import random
import util_db

def main():

    names = ["Alex", "Becky", "Christy", "David"]
    comments = ["Champion!!", "Nice!!", "Good!!", "OMG...!!"]

    my_db = util_db.MyDB("data.sqlite")

    name = random.choice(names)
    comment = random.choice(comments)
    score = random.randint(30, 300)
    result = my_db.insert_record(name, comment, score)
    print("insert:", result)

    records = my_db.read_records(limit=5)
    print("= Ranking =")
    for record in records:
        print("Record:", record)

if __name__ == "__main__":
    main()

Final Notes

Thank you very much for reading until the end.

SQLAlchemy is a simple and easy-to-use library, and it is definitely worth learning.

If you found this article helpful, a 👍 would be greatly appreciated!

Simple Ranking with SQLite3

Kajiru — Tue, 20 Jan 2026 15:00:00 +0000

SQLite3 Simple Ranking

In this article, we will build a simple ranking system using sqlite3.

SQLite manages a single database as a single file.

To inspect the generated database file, it is convenient to use dedicated software such as:

DB Browser for SQLite

The complete source code is shown at the end.

1. Preparing the Modules

In your working folder, create an executable file main.py and a database utility file util_db.py that contains all database-related logic.

The folder structure should look like this:

# Folder structure
working_folder/
 ├ main.py      # Main program
 └ util_db.py   # Database utility

The initial state of util_db.py is as follows.

In the constructor, we prepare the path to the database file and the table name.

# util_db.py (initial state)
import datetime
import os
import sqlite3

class MyDB():

    def __init__(self, path, table):
        """ Constructor """
        self.dir_base = os.path.dirname(__file__)
        self.db_path = os.path.join(self.dir_base, path)
        self.db_table = table

    # Time
    def get_time(self):
        """ Get current datetime """
        return datetime.datetime.now().strftime("%Y/%m/%d %H:%M:%S")

2. CRUD Pattern with SQLite3

CRUD stands for Create, Read, Update, and Delete, the four basic database operations.

Since sqlite3 is part of Python’s standard library, installation is usually not required.

For this simple ranking example, we use the following table structure:

Column name	Meaning	Example
uid	Sequential ID	1, 2, 3, ...
name	User name	Alex
comment	Comment	I'm champion!!
score	Score	123
time_stamp	Created time	1970/01/01 00:00:00

2-1. Creating a Table

This method creates a new table.

We connect to the database using sqlite3.connect() and execute SQL with cur.execute().

The argument is a CREATE TABLE ... SQL statement.

# util_db.py (excerpt)
# Create table
def create_table(self):
    """ Create table """
    # SQLite
    con = sqlite3.connect(self.db_path)
    cur = con.cursor()
    sql = """
        CREATE TABLE IF NOT EXISTS {0}(
        uid INTEGER PRIMARY KEY AUTOINCREMENT,
        name TEXT DEFAULT "noname",
        comment TEXT DEFAULT "nocomment",
        score INTEGER DEFAULT 0,
        time_stamp TEXT DEFAULT "1970/01/01 00:00:00")
        """.format(self.db_table)
    cur.execute(sql)
    con.commit()  # Important
    con.close()

2-2. Inserting Data (Create)

This method inserts a new record into the table.

As before, we use an INSERT INTO ... SQL statement.

# util_db.py (excerpt)
# CRUD(Create)
def insert_record(self, name, comment, score):
    """ Insert a record """
    # SQLite
    con = sqlite3.connect(self.db_path)
    cur = con.cursor()
    sql = """
        INSERT INTO {0} VALUES(?, ?, ?, ?, ?)
        """.format(self.db_table)
    cur.execute(sql, (None, name, comment, score, self.get_time()))
    con.commit()  # Important
    con.close()

2-3. Reading Data (Read)

This method retrieves data from the table.

Using a SELECT ... statement, records are sorted by score in descending order.

The limit argument controls how many top records are returned.

# util_db.py (excerpt)
# CRUD(Read)
def read_records(self, limit=10):
    """ Read records (up to limit) """
    # SQLite
    con = sqlite3.connect(self.db_path)
    cur = con.cursor()
    sql = """
        SELECT * FROM {0} ORDER BY score DESC LIMIT ?
        """.format(self.db_table)
    cur.execute(sql, (limit,))
    records = cur.fetchall()
    con.close()
    return records

2-4. Updating Data (Update)

This method updates an existing record.

An UPDATE ... statement is used to update the record with the specified uid.

# util_db.py (excerpt)
# CRUD(Update)
def update_record(self, uid, name, comment, score):
    """ Update a record """
    # SQLite
    con = sqlite3.connect(self.db_path)
    cur = con.cursor()
    sql = """
        UPDATE {0} SET name=?, comment=?, score=?, time_stamp=? WHERE uid=?
        """.format(self.db_table)
    cur.execute(sql, (name, comment, score, self.get_time(), uid))
    con.commit()  # Important
    con.close()
    return self.read_record(uid)

2-5. Deleting Data (Delete)

This method deletes a record from the table.

A DELETE ... statement is used to remove the record with the specified uid.

# util_db.py (excerpt)
# CRUD(Delete)
def delete_record(self, uid):
    """ Delete a record """
    # SQLite
    con = sqlite3.connect(self.db_path)
    cur = con.cursor()
    sql = """
        DELETE FROM {0} WHERE uid=?
        """.format(self.db_table)
    cur.execute(sql, (uid,))
    con.commit()  # Important
    con.close()

Testing

The test procedure is as follows.

Here, a random name, comment, and score are generated and inserted into the table.

(If you uncomment other sections, you can test update and delete operations.)

# main.py
# Members
names = ["Alex", "Becky", "Christy", "David"]
comments = ["Champion!!", "Nice!!", "Good!!", "OMG...!!"]

# MyDB
my_db = util_db.MyDB("data.sqlite", "ranking")

# Create table
my_db.create_table()

# Insert (Random)
name = random.choice(names)
comment = random.choice(comments)
score = random.randint(30, 300)
my_db.insert_record(name, comment, score)

# Update
# my_db.update_record(1, "Thomas", "Hi, I'm hacker!!", 777)

# Delete
# my_db.delete_record(1)

# Read (Ranking)
records = my_db.read_records(limit=5)
print("= Ranking =")
for record in records:
    print("Record:", record)

Execution Result

The output will look like this:

= Ranking =
Record: (4, 'David', 'Nice!!', 284, '2026/01/04 08:25:02')
Record: (11, 'Christy', 'Champion!!', 282, '2026/01/04 08:31:19')
Record: (8, 'Becky', 'Nice!!', 275, '2026/01/04 08:30:29')
Record: (5, 'David', 'Good!!', 269, '2026/01/04 08:25:54')
Record: (7, 'Christy', 'Good!!', 250, '2026/01/04 08:29:11')

Complete Code

Below is the complete implementation.

# util_db.py
import datetime
import os
import sqlite3

class MyDB():

    def __init__(self, path, table):
        """ Constructor """
        self.dir_base = os.path.dirname(__file__)
        self.db_path = os.path.join(self.dir_base, path)
        self.db_table = table

    # Create table
    def create_table(self):
        """ Create table """
        con = sqlite3.connect(self.db_path)
        cur = con.cursor()
        sql = """
            CREATE TABLE IF NOT EXISTS {0}(
            uid INTEGER PRIMARY KEY AUTOINCREMENT,
            name TEXT DEFAULT "noname",
            comment TEXT DEFAULT "nocomment",
            score INTEGER DEFAULT 0,
            time_stamp TEXT DEFAULT "1970/01/01 00:00:00")
            """.format(self.db_table)
        cur.execute(sql)
        con.commit()
        con.close()

    # CRUD(Create)
    def insert_record(self, name, comment, score):
        """ Insert a record """
        con = sqlite3.connect(self.db_path)
        cur = con.cursor()
        sql = """
            INSERT INTO {0} VALUES(?, ?, ?, ?, ?)
            """.format(self.db_table)
        cur.execute(sql, (None, name, comment, score, self.get_time()))
        con.commit()
        con.close()

    # CRUD(Read)
    def read_records(self, limit=10):
        """ Read records """
        con = sqlite3.connect(self.db_path)
        cur = con.cursor()
        sql = """
            SELECT * FROM {0} ORDER BY score DESC LIMIT ?
            """.format(self.db_table)
        cur.execute(sql, (limit,))
        records = cur.fetchall()
        con.close()
        return records

    def read_record(self, uid):
        """ Read one record """
        con = sqlite3.connect(self.db_path)
        cur = con.cursor()
        sql = """
            SELECT * FROM {0} WHERE uid=?
            """.format(self.db_table)
        cur.execute(sql, (uid,))
        record = cur.fetchone()
        con.close()
        return record

    # CRUD(Update)
    def update_record(self, uid, name, comment, score):
        """ Update a record """
        con = sqlite3.connect(self.db_path)
        cur = con.cursor()
        sql = """
            UPDATE {0} SET name=?, comment=?, score=?, time_stamp=? WHERE uid=?
            """.format(self.db_table)
        cur.execute(sql, (name, comment, score, self.get_time(), uid))
        con.commit()
        con.close()
        return self.read_record(uid)

    # CRUD(Delete)
    def delete_record(self, uid):
        """ Delete a record """
        con = sqlite3.connect(self.db_path)
        cur = con.cursor()
        sql = """
            DELETE FROM {0} WHERE uid=?
            """.format(self.db_table)
        cur.execute(sql, (uid,))
        con.commit()
        con.close()

    # Time
    def get_time(self):
        """ Get current datetime """
        return datetime.datetime.now().strftime("%Y/%m/%d %H:%M:%S")

# main.py
import random
import util_db

def main():
    """ Main process """

    names = ["Alex", "Becky", "Christy", "David"]
    comments = ["Champion!!", "Nice!!", "Good!!", "OMG...!!"]

    my_db = util_db.MyDB("data.sqlite", "ranking")
    my_db.create_table()

    name = random.choice(names)
    comment = random.choice(comments)
    score = random.randint(30, 300)
    my_db.insert_record(name, comment, score)

    records = my_db.read_records(limit=5)
    print("= Ranking =")
    for record in records:
        print("Record:", record)

if __name__ == "__main__":
    main()

Final Notes

Thank you for reading until the end.

sqlite3 is a simple and easy-to-use library, making it perfect for learning SQL basics.

If you found this helpful, a 👍 would be greatly appreciated!

Getting Started with 2D Games Using Pyxel (Part 16): Vampire Shooting Game (Sample)

Kajiru — Mon, 19 Jan 2026 15:00:00 +0000

Vampire Shooting Game (Sample)

In this article, I’ll introduce a simple game where you try to survive while escaping from approaching monsters.

(This article only provides sample code.)

1. Prepare the Assets

Use Pyxel Editor to draw the background assets.

Download the resource file from the link below

(Click the Download button in the top-right corner):

https://github.com/sdkfz181tiger/Zenn/blob/main/images/675e49a3e4d34b/vampire.pyxres

Sample Code

Below is the complete sample code used in this game.

# sprite.py
import pyxel
import math
import random

class BaseSprite:

    def __init__(self, x, y, u, v, spd, w=8, h=8):
        """ Constructor """
        self.x = x
        self.y = y
        self.u = u
        self.v = v
        self.spd = spd
        self.w = w
        self.h = h
        self.vx = 0
        self.vy = 0
        self.right_flg = True  # Facing right flag

    def update(self):
        """ Update """
        self.x += self.vx
        self.y += self.vy

    def draw(self):
        """ Draw """
        u = 0 if self.right_flg else 8
        pyxel.blt(
            self.x, self.y, 0,
            self.u + u, self.v, self.w, self.h, 0
        )

    def get_center(self):
        """ Get center position """
        return (self.x + self.w / 2, self.y + self.h / 2)

    def set_center(self, x, y):
        """ Set center position """
        self.x = x - self.w / 2
        self.y = y - self.h / 2

    def move(self, deg):
        """ Move by angle """
        rad = (deg * math.pi) / 180
        self.vx = self.spd * math.cos(rad)
        self.vy = self.spd * math.sin(rad)
        if deg == 90 or deg == 270:
            return
        self.right_flg = not (90 < deg < 270)

    def stop(self):
        """ Stop movement """
        self.vx = 0
        self.vy = 0

    def intersects(self, other):
        """ Rectangle collision (AABB) """
        if other.x + other.w < self.x:
            return False
        if self.x + self.w < other.x:
            return False
        if other.y + other.h < self.y:
            return False
        if self.y + self.h < other.y:
            return False
        return True

    def contains_center(self, other):
        """ Check if center point is inside another rectangle """
        x, y = self.get_center()
        if other.x + other.w < x:
            return False
        if x < other.x:
            return False
        if other.y + other.h < y:
            return False
        if y < other.y:
            return False
        return True

    def get_distance(self, other):
        """ Calculate distance """
        dx = self.x - other.x
        dy = self.y - other.y
        return math.sqrt(dx * dx + dy * dy)

    def get_direction(self, other):
        """ Calculate direction angle """
        dx = other.x - self.x
        dy = other.y - self.y
        rad = math.atan2(dy, dx)
        return (rad * (180 / math.pi) + 360) % 360


class PlayerSprite(BaseSprite):

    def __init__(self, x, y, u, v, spd, game):
        """ Constructor """
        super().__init__(x, y, u, v, spd)
        self.shot_interval = 12
        self.shot_counter = 0
        self.game = game

    def update(self):
        """ Update """
        super().update()
        self.shot_counter += 1
        if self.shot_interval < self.shot_counter:
            self.shot_counter = 0
            self.game.on_shot_event(self)


class Monster(BaseSprite):

    def __init__(self, x, y, u, v, spd, think_interval, target):
        """ Constructor """
        super().__init__(x, y, u, v, spd)
        self.think_interval = think_interval
        self.think_counter = 0
        self.target = target

    def update(self):
        """ Update """
        super().update()
        self.think_counter += 1
        if self.think_interval < self.think_counter:
            self.think_counter = 0
            direction = self.get_direction(self.target)
            self.move(direction)


class Bullet(BaseSprite):

    def __init__(self, x, y, spd, life=10):
        """ Constructor """
        super().__init__(x, y, 0, 0, spd)
        self.life = life

    def update(self):
        """ Update """
        super().update()
        self.life -= 1
        if self.life < 0:
            self.stop()

    def draw(self):
        """ Draw """
        pyxel.rect(self.x, self.y, 2, 2, 7)

    def is_dead(self):
        """ Dead flag """
        return self.life < 0


class Particle(BaseSprite):

    def __init__(self, x, y, life=10):
        """ Constructor """
        super().__init__(x, y, 0, 0, 0)
        self.life = life
        self.area_r = 8
        self.circ_r = 0
        self.off_x = 0
        self.off_y = 0

    def update(self):
        """ Update """
        super().update()
        self.life -= 1
        if self.life < 0:
            self.stop()
        self.circ_r = random.randint(2, 4)
        self.off_x = random.randint(0, self.area_r) - self.area_r / 2
        self.off_y = random.randint(0, self.area_r) - self.area_r / 2

    def draw(self):
        """ Draw """
        pyxel.circ(
            self.x + self.off_x,
            self.y + self.off_y,
            self.circ_r,
            7
        )

    def is_dead(self):
        """ Dead flag """
        return self.life < 0

# main.py
import pyxel
import random
import sprite

W, H = 160, 120

START_X = W / 2
START_Y = H / 2 - 10

MODE_TITLE = "title"
MODE_PLAY = "play"
MODE_GAME_OVER = "game_over"

PLAYER_SPD = 1.2
BULLET_SPD = 2.4

MONSTERS = [
    {"u": 32, "v": 72, "spd": 0.1,  "think_interval": 60},
    {"u": 48, "v": 72, "spd": 0.12, "think_interval": 90},
    {"u":  0, "v": 80, "spd": 0.14, "think_interval": 120},
    {"u": 16, "v": 80, "spd": 0.16, "think_interval": 150},
    {"u": 32, "v": 80, "spd": 0.25, "think_interval": 180},
]


class Game:
    def __init__(self):
        """ Constructor """
        self.score = 0
        self.game_mode = MODE_TITLE
        self.player = sprite.PlayerSprite(
            START_X, START_Y, 0, 72, PLAYER_SPD, self
        )
        self.reset()
        pyxel.init(W, H, title="Hello, Pyxel!!")
        pyxel.load("vampire.pyxres")
        pyxel.run(self.update, self.draw)

    def update(self):
        """ Update """
        self.control()
        if self.game_mode != MODE_PLAY:
            return

        self.player.update()
        self.overlap_area(self.player)

        for monster in self.monsters[:]:
            monster.update()
            self.overlap_area(monster)
            if self.player.contains_center(monster):
                self.player.stop()
                self.game_mode = MODE_GAME_OVER
                pyxel.play(0, 16, loop=False)

        for bullet in self.bullets[:]:
            bullet.update()
            if bullet.is_dead():
                self.bullets.remove(bullet)
            else:
                for monster in self.monsters[:]:
                    if monster.intersects(bullet):
                        self.bullets.remove(bullet)
                        self.append_particle(monster)
                        self.kick_area(monster)
                        self.score += 10
                        break

        for particle in self.particles[:]:
            particle.update()
            if particle.is_dead():
                self.particles.remove(particle)

    def draw(self):
        """ Draw """
        pyxel.cls(0)
        pyxel.bltm(0, 0, 0, 0, 128, 192, 128, 0)
        self.player.draw()

        for monster in self.monsters:
            monster.draw()

        for bullet in self.bullets:
            bullet.draw()

        for particle in self.particles:
            particle.draw()

        if self.game_mode == MODE_TITLE:
            msg = "SPACE TO PLAY"
            pyxel.text(W / 2 - len(msg) * 2, H / 2, msg, 7)
            msg = "CONTROL: WASD"
            pyxel.text(W / 2 - len(msg) * 2, H / 2 + 10, msg, 7)
        elif self.game_mode == MODE_GAME_OVER:
            msg = "GAME OVER"
            pyxel.text(W / 2 - len(msg) * 2, H / 2, msg, 7)

        pyxel.text(10, 10, f"SCORE:{self.score:04}", 7)

    def reset(self):
        """ Reset stage """
        self.player.x = START_X
        self.player.y = START_Y

        self.monsters = []
        for _ in range(64):
            x = random.randint(0, W)
            y = random.randint(0, H)
            item = random.choice(MONSTERS)
            monster = sprite.Monster(
                x, y,
                item["u"],
                item["v"],
                item["spd"],
                item["think_interval"],
                self.player
            )
            if monster.get_distance(self.player) < 24:
                continue
            monster.move(monster.get_direction(self.player))
            self.monsters.append(monster)

        self.bullets = []
        self.particles = []

    def control(self):
        """ Control """
        if pyxel.btnp(pyxel.KEY_SPACE):
            if self.game_mode == MODE_TITLE:
                self.game_mode = MODE_PLAY
            elif self.game_mode == MODE_GAME_OVER:
                self.game_mode = MODE_TITLE
                self.reset()
            return

        if self.game_mode == MODE_PLAY:
            if pyxel.btnp(pyxel.KEY_W):
                self.player.move(270)
            elif pyxel.btnr(pyxel.KEY_W):
                self.player.stop()
            if pyxel.btnp(pyxel.KEY_A):
                self.player.move(180)
            elif pyxel.btnr(pyxel.KEY_A):
                self.player.stop()
            if pyxel.btnp(pyxel.KEY_S):
                self.player.move(90)
            elif pyxel.btnr(pyxel.KEY_S):
                self.player.stop()
            if pyxel.btnp(pyxel.KEY_D):
                self.player.move(0)
            elif pyxel.btnr(pyxel.KEY_D):
                self.player.stop()

    def overlap_area(self, spr):
        """ Screen wrap """
        if W < spr.x:
            spr.x = 0
        if spr.x < 0:
            spr.x = W
        if H < spr.y:
            spr.y = 0
        if spr.y < 0:
            spr.y = H

    def kick_area(self, spr):
        """ Force move to screen edge """
        if random.randint(0, 1) == 0:
            spr.set_center(0, random.randint(0, H))
        else:
            spr.set_center(random.randint(0, W), 0)
        pyxel.play(1, 1, loop=False)

    def get_nearest_monster(self):
        """ Get nearest monster """
        nearest = None
        dist_min = 999
        for monster in self.monsters:
            dist = monster.get_distance(self.player)
            if dist < dist_min:
                dist_min = dist
                nearest = monster
        return nearest

    def on_shot_event(self, spr):
        """ Fire bullet """
        if not self.monsters:
            return
        x, y = spr.get_center()
        bullet = sprite.Bullet(x, y, BULLET_SPD)
        monster = self.get_nearest_monster()
        bullet.move(self.player.get_direction(monster))
        self.bullets.append(bullet)

    def append_particle(self, spr):
        """ Spawn particle """
        x, y = spr.get_center()
        self.particles.append(sprite.Particle(x, y))


def main():
    """ Main entry """
    Game()


if __name__ == "__main__":
    main()

Result

The game will run like this:

Final Words

Thank you very much for reading.

I hope this series helps you get started with game development. ޱ(ఠ皿ఠ)ว

(If you enjoyed this article, a 👍 would be greatly appreciated!)

Getting Started with 2D Games Using Pyxel (Part 15): Tunnel Dodge Game 2 (Sample)

Kajiru — Sun, 18 Jan 2026 15:00:00 +0000

Tunnel Dodge Game 2 (Sample)

In this article, we introduce a sample that displays a background using a tilemap.

(This article only introduces the sample code.)

1. Preparing the Assets

Create the background assets using the Pyxel Editor.

Download the resource file

(Click the Download button at the top right to download the file.)

Sample Code

The complete sample code is shown below.

# sprite.py
import pyxel
import math
import random

class BaseSprite:

    def __init__(self, x, y, w=8, h=8):
        """ Constructor """
        self.x = x
        self.y = y
        self.w = w
        self.h = h
        self.vx = 0
        self.vy = 0

    def update(self):
        """ Update processing """
        self.x += self.vx
        self.y += self.vy

    def draw(self):
        """ Draw processing (implemented in subclasses) """
        pass

    def move(self, spd, deg):
        """ Move by speed and angle """
        rad = deg * math.pi / 180
        self.vx = spd * math.cos(rad)  # Velocity on X axis
        self.vy = spd * math.sin(rad)  # Velocity on Y axis

    def intersects(self, other):
        """ Rectangle collision detection (AABB) """
        if other.x + other.w < self.x: return False
        if self.x + self.w < other.x: return False
        if other.y + other.h < self.y: return False
        if self.y + self.h < other.y: return False
        return True


class PlayerSprite(BaseSprite):

    def __init__(self, x, y):
        """ Constructor """
        super().__init__(x, y)
        self.gravity = 0.4    # Gravity
        self.jump_x = 1.0    # Jump X velocity
        self.jump_y = -3.4   # Jump Y velocity

    def update(self):
        """ Update processing """
        super().update()
        self.vy += self.gravity

    def draw(self):
        """ Draw processing """
        pyxel.blt(self.x, self.y, 0,
                  0, 16, self.w, self.h, 0)
        # Debug
        # pyxel.rectb(self.x, self.y, self.w, self.h, 3)

    def jump(self):
        """ Jump """
        self.vx = self.jump_x
        self.vy = self.jump_y


class TunnelSprite(BaseSprite):

    def __init__(self, x, y, length, top_flg=False):
        """ Constructor """
        super().__init__(x, y, 16, length * 8)
        self.length = length  # Tunnel length
        if top_flg:
            self.y -= self.h  # Upper tunnel

    def draw(self):
        """ Draw processing """
        # Top
        pyxel.blt(self.x, self.y, 0,
                  16, 16, self.w, 8, 0)

        # Middle
        for i in range(self.length - 2):
            y = self.y + (i + 1) * 8
            pyxel.blt(self.x, y, 0,
                      16, 24, self.w, 8, 0)

        # Bottom
        y = self.y + (self.length - 1) * 8
        pyxel.blt(self.x, y, 0,
                  16, 32, self.w, 8, 0)

        # Debug
        # pyxel.rectb(self.x, self.y, self.w, self.h, 3)

# main.py
import pyxel
import math
import random
import sprite

W, H = 160, 120

START_X = W / 2 - 48
START_Y = H / 2 - 12

MODE_TITLE = "title"
MODE_PLAY = "play"
MODE_GAME_OVER = "game_over"

TUNNEL_TOTAL = 48


class Game:
    def __init__(self):
        """ Constructor """

        # Initialize score
        self.score = 0

        # Game mode
        self.game_mode = MODE_TITLE

        # Initialize player
        self.player = sprite.PlayerSprite(START_X, START_Y)

        # Initialize stage
        self.reset()

        # Start Pyxel
        pyxel.init(W, H, title="Hello, Pyxel!!")
        pyxel.load("flappy.pyxres")
        pyxel.run(self.update, self.draw)

    def update(self):
        """ Update processing """

        # Update score
        self.score = int(self.player.x - START_X)

        # Control input
        self.control()

        # Check play state
        if self.game_mode != MODE_PLAY:
            return

        # Update player
        self.player.update()

        # Update tunnels
        for tunnel in self.tunnels:
            tunnel.update()
            if tunnel.intersects(self.player):
                self.game_mode = MODE_GAME_OVER
                break

        # Falling check
        if H < self.player.y:
            self.game_mode = MODE_GAME_OVER

    def draw(self):
        """ Draw processing """
        pyxel.cls(6)

        # Tilemap background
        pyxel.bltm(0, 0, 0, 0, 0, 192, 128, 0)

        # Camera (set)
        pyxel.camera(self.player.x - START_X, 0)

        # Draw player
        self.player.draw()

        # Draw tunnels
        for tunnel in self.tunnels:
            tunnel.draw()

        # Camera (reset)
        pyxel.camera()

        # Messages
        if self.game_mode == MODE_TITLE:
            msg = "SPACE TO PLAY"
            pyxel.text(W / 2 - len(msg) * 2, H / 2, msg, 1)
        elif self.game_mode == MODE_GAME_OVER:
            msg = "GAME OVER"
            pyxel.text(W / 2 - len(msg) * 2, H / 2, msg, 1)

        # Draw score
        pyxel.text(10, 10,
                   "SCORE:{:04}".format(self.score), 1)

    def reset(self):
        """ Initialize stage """

        # Player position
        self.player.x = START_X
        self.player.y = START_Y

        # Tunnels
        self.tunnels = []
        for i in range(TUNNEL_TOTAL):
            pad_x = 42
            pad_y = random.randint(2, 3) * 8
            x = START_X + pad_x * i + 32
            y = H / 2 + random.randint(-2, 2) * 8

            t_top = sprite.TunnelSprite(x, y - pad_y, 10, True)
            self.tunnels.append(t_top)

            t_bottom = sprite.TunnelSprite(x, y + pad_y, 10)
            self.tunnels.append(t_bottom)

    def control(self):
        """ Control input """
        if not pyxel.btnp(pyxel.KEY_SPACE):
            return

        # Title -> Play
        if self.game_mode == MODE_TITLE:
            self.game_mode = MODE_PLAY

        # Game Over -> Title
        if self.game_mode == MODE_GAME_OVER:
            self.game_mode = MODE_TITLE
            self.reset()

        # Jump
        if self.game_mode == MODE_PLAY:
            self.player.jump()


def main():
    """ Main process """
    Game()


if __name__ == "__main__":
    main()

Result

The game will look like this when running.

Conclusion

Thank you very much for reading this article.

I hope this series helps you get started with game development.

(If you enjoyed it, a 👍 would be greatly appreciated!)

Getting Started with 2D Games Using Pyxel (Part 14): Tunnel Dodge Game 1 (Sample)

Kajiru — Sat, 17 Jan 2026 15:00:00 +0000

Tunnel Dodge Game 1 (Sample)

In this article, we introduce a somewhat nostalgic game where you jump through gaps in tunnels.

Here, we only provide sample code.

1. Preparing the Assets

Using the Pyxel Editor, draw the assets for the player and the tunnels.

Download the resource file (Click the “Download” button in the top-right corner of the page.)

Sample Code

The sample code for this game is shown below.

# sprite.py
import pyxel
import math
import random

class BaseSprite:

    def __init__(self, x, y, w=8, h=8):
        """ Constructor """
        self.x = x
        self.y = y
        self.w = w
        self.h = h
        self.vx = 0
        self.vy = 0

    def update(self):
        """ Update process """
        self.x += self.vx
        self.y += self.vy

    def draw(self):
        """ Draw process (implemented in subclasses) """
        pass

    def move(self, spd, deg):
        """ Move sprite """
        rad = deg * math.pi / 180
        self.vx = spd * math.cos(rad)  # Velocity in x direction
        self.vy = spd * math.sin(rad)  # Velocity in y direction

    def intersects(self, other):
        """ AABB collision detection """
        if other.x + other.w < self.x:
            return False
        if self.x + self.w < other.x:
            return False
        if other.y + other.h < self.y:
            return False
        if self.y + self.h < other.y:
            return False
        return True

class PlayerSprite(BaseSprite):

    def __init__(self, x, y):
        """ Constructor """
        super().__init__(x, y)
        self.gravity = 0.4   # Gravity
        self.jump_x = 1.0    # Jump velocity (x)
        self.jump_y = -3.4   # Jump velocity (y)

    def update(self):
        """ Update process """
        super().update()
        self.vy += self.gravity  # Apply gravity

    def draw(self):
        """ Draw process """
        pyxel.blt(
            self.x, self.y, 0,
            0, 16, self.w, self.h, 0
        )
        # Debug
        # pyxel.rectb(self.x, self.y, self.w, self.h, 3)

    def jump(self):
        """ Jump """
        self.vx = self.jump_x
        self.vy = self.jump_y

class TunnelSprite(BaseSprite):

    def __init__(self, x, y, length, top_flg=False):
        """ Constructor """
        super().__init__(x, y, 16, length * 8)
        self.length = length  # Tunnel length
        if top_flg:
            self.y -= self.h  # Upper tunnel

    def draw(self):
        """ Draw process """
        # Top
        pyxel.blt(
            self.x, self.y, 0,
            16, 16, self.w, 8, 0
        )
        # Middle
        for i in range(self.length - 2):
            y = self.y + (i + 1) * 8
            pyxel.blt(
                self.x, y, 0,
                16, 24, self.w, 8, 0
            )
        # Bottom
        y = self.y + (self.length - 1) * 8
        pyxel.blt(
            self.x, y, 0,
            16, 32, self.w, 8, 0
        )
        # Debug
        # pyxel.rectb(self.x, self.y, self.w, self.h, 3)

# main.py
import pyxel
import math
import random
import sprite

W, H = 120, 120

START_X = W / 3
START_Y = H / 2 - 12

MODE_TITLE = "title"
MODE_PLAY = "play"
MODE_GAME_OVER = "game_over"

class Game:
    def __init__(self):
        """ Constructor """

        # Initialize score
        self.score = 0

        # Game mode
        self.game_mode = MODE_TITLE

        # Initialize player
        self.player = sprite.PlayerSprite(START_X, START_Y)

        # Initialize stage
        self.reset()

        # Initialize Pyxel
        pyxel.init(W, H, title="Hello, Pyxel!!")
        pyxel.load("shooter.pyxres")
        pyxel.run(self.update, self.draw)

    def update(self):
        """ Update process """

        # Update score
        self.score = int(self.player.x - START_X)

        # Control input
        self.control()

        # Only update during play mode
        if self.game_mode != MODE_PLAY:
            return

        # Update player
        self.player.update()

        # Update tunnels
        for tunnel in self.tunnels:
            tunnel.update()
            if tunnel.intersects(self.player):
                self.game_mode = MODE_GAME_OVER
                break

        # Falling check
        if H < self.player.y:
            self.game_mode = MODE_GAME_OVER

    def draw(self):
        """ Draw process """
        pyxel.cls(0)

        # Camera (set)
        pyxel.camera(self.player.x - START_X, 0)

        # Draw player
        self.player.draw()

        # Draw tunnels
        for tunnel in self.tunnels:
            tunnel.draw()

        # Camera (reset)
        pyxel.camera()

        # Messages
        if self.game_mode == MODE_TITLE:
            msg = "SPACE TO PLAY"
            pyxel.text(W / 2 - len(msg) * 2, H / 2, msg, 13)
        elif self.game_mode == MODE_GAME_OVER:
            msg = "GAME OVER"
            pyxel.text(W / 2 - len(msg) * 2, H / 2, msg, 13)

        # Draw score
        pyxel.text(
            10, 10,
            "SCORE:{:04}".format(self.score), 12
        )

    def reset(self):
        """ Reset stage """

        # Player
        self.player.x = START_X
        self.player.y = START_Y

        # Tunnels
        self.tunnels = []
        for i in range(24):
            pad_x = 42
            pad_y = random.randint(2, 3) * 8
            x = START_X + pad_x * i + 24
            y = H / 2 + random.randint(-2, 2) * 8
            t_top = sprite.TunnelSprite(x, y - pad_y, 10, True)
            self.tunnels.append(t_top)
            t_bottom = sprite.TunnelSprite(x, y + pad_y, 10)
            self.tunnels.append(t_bottom)

    def control(self):
        """ Control """
        if not pyxel.btnp(pyxel.KEY_SPACE):
            return

        # Title -> Play
        if self.game_mode == MODE_TITLE:
            self.game_mode = MODE_PLAY

        # Game Over -> Title
        if self.game_mode == MODE_GAME_OVER:
            self.game_mode = MODE_TITLE
            self.reset()

        # Jump
        if self.game_mode == MODE_PLAY:
            self.player.jump()

def main():
    """ Main process """
    Game()

if __name__ == "__main__":
    main()

Result

When you run the game, it will look like this.

Final Words

Thank you very much for reading until the end.

I hope this series becomes a starting point for your game development journey.

If you enjoyed it, a 👍 would be greatly appreciated!

Getting Started with 2D Games Using Pyxel (Part 13): Creating a Scrolling Star Background

Kajiru — Fri, 16 Jan 2026 15:00:00 +0000

Creating a Scrolling Star Background

In this article, we will create a scrolling star background to make the game screen more lively.

Here, we focus on introducing sample code only.

The complete source code is provided at the end.

1. Creating Classes to Draw Stars

In sprite.py, we define a Star class for drawing individual stars, and a Background class that updates and draws all stars in the background.

# sprite.py (excerpt)
class Star:

    def __init__(self, x, y, w, h):
        """ Constructor """
        self.x = x
        self.y = y
        self.w = w
        self.h = h
        self.c = random.randint(0, 15)  # Color
        self.spd = random.randint(1, 3) # Falling speed

    def update(self):
        """ Update process """
        self.y += self.spd
        if self.h < self.y:
            self.y = 0

    def draw(self):
        """ Draw process """
        pyxel.pset(self.x, self.y, self.c)

class Background:

    def __init__(self, w, h):
        """ Constructor """
        self.w = w  # Screen width
        self.h = h  # Screen height
        self.stars = []  # List to manage stars
        for _ in range(30):
            x = random.randint(0, w)
            y = random.randint(0, h)
            star = Star(x, y, self.w, self.h)
            self.stars.append(star)

    def update(self):
        """ Update process """
        for star in self.stars:
            star.update()

    def draw(self):
        """ Draw process """
        for star in self.stars:
            star.draw()

2. Using the Background Class

First, create a Background instance in the constructor of the Game class in main.py.

# main.py (inside Game.__init__)
# Background
self.background = sprite.Background(W, H)

Next, call the update process inside update().

# main.py (inside Game.update)
# Background
self.background.update()

Finally, call the draw process inside draw().

# main.py (inside Game.draw)
# Background
self.background.draw()

By grouping related processes into classes like this, you can keep your code clean and easy to read.

Complete Code

Below is the complete code implementing all the features introduced in this article.

# sprite.py
import pyxel
import math
import random

class BaseSprite:

    def __init__(self, x, y, w=8, h=8):
        """ Constructor """
        self.x = x
        self.y = y
        self.w = w
        self.h = h
        self.vx = 0
        self.vy = 0

    def update(self):
        """ Update process """
        self.x += self.vx
        self.y += self.vy

    def draw(self):
        """ Draw process (implemented in subclasses) """
        pass

    def move(self, spd, deg):
        """ Move sprite """
        rad = deg * math.pi / 180
        self.vx = spd * math.cos(rad)
        self.vy = spd * math.sin(rad)

    def flip_x(self):
        """ Flip movement in x direction """
        self.vx *= -1

    def intersects(self, other):
        """ AABB collision detection """
        if other.x + other.w < self.x:
            return False
        if self.x + self.w < other.x:
            return False
        if other.y + other.h < self.y:
            return False
        if self.y + self.h < other.y:
            return False
        return True

class ShipSprite(BaseSprite):

    def __init__(self, x, y):
        """ Constructor """
        super().__init__(x, y)

    def draw(self):
        """ Draw process """
        pyxel.blt(self.x, self.y, 0, 0, 0, self.w, self.h, 0)

class AsteroidSprite(BaseSprite):

    def __init__(self, x, y):
        """ Constructor """
        super().__init__(x, y)
        self.index = random.randint(2, 7)  # Asteroid image index

    def draw(self):
        """ Draw process """
        pyxel.blt(
            self.x,
            self.y,
            0,
            self.w * self.index,
            0,
            self.w,
            self.h,
            0
        )

class BulletSprite(BaseSprite):

    def __init__(self, x, y):
        """ Constructor """
        super().__init__(x, y)
        self.x += self.w / 2 - 1  # Center adjustment

    def draw(self):
        """ Draw process """
        pyxel.rect(self.x, self.y, 2, 2, 12)

class Star:

    def __init__(self, x, y, w, h):
        """ Constructor """
        self.x = x
        self.y = y
        self.w = w
        self.h = h
        self.c = random.randint(0, 15)
        self.spd = random.randint(1, 3)

    def update(self):
        """ Update process """
        self.y += self.spd
        if self.h < self.y:
            self.y = 0

    def draw(self):
        """ Draw process """
        pyxel.pset(self.x, self.y, self.c)

class Background:

    def __init__(self, w, h):
        """ Constructor """
        self.w = w  # Screen width
        self.h = h  # Screen height
        self.stars = []  # List of stars
        for _ in range(30):
            x = random.randint(0, w)
            y = random.randint(0, h)
            star = Star(x, y, self.w, self.h)
            self.stars.append(star)

    def update(self):
        """ Update process """
        for star in self.stars:
            star.update()

    def draw(self):
        """ Draw process """
        for star in self.stars:
            star.draw()

# main.py
import pyxel
import math
import random
import sprite

W, H = 160, 120
SHIP_SPD = 1.4

ASTEROID_INTERVAL = 20
ASTEROID_LIMIT = 30

ASTEROID_SPD_MIN = 1.0
ASTEROID_SPD_MAX = 2.0
ASTEROID_DEG_MIN = 30
ASTEROID_DEG_MAX = 150

BULLET_SPD = 3

class Game:
    def __init__(self):
        """ Constructor """

        # Game over flag
        self.game_over_flg = False

        # Initialize score
        self.score = 0

        # Background
        self.background = sprite.Background(W, H)

        # Initialize player
        self.ship = sprite.ShipSprite(W / 2, H - 40)
        deg = 0 if random.random() < 0.5 else 180
        self.ship.move(SHIP_SPD, deg)

        # Asteroids
        self.asteroid_time = 0
        self.asteroids = []

        # Bullets
        self.bullets = []

        # Initialize Pyxel
        pyxel.init(W, H, title="Hello, Pyxel!!")
        pyxel.load("shooter.pyxres")

        # Sound (shot)
        pyxel.sound(0).set(
            "c4g3",
            tones="p",
            volumes="76",
            effects="f",
            speed=20
        )

        # Sound (hit)
        pyxel.sound(1).set(
            "e4d4c4",
            tones="p",
            volumes="76",
            effects="n",
            speed=20
        )

        pyxel.run(self.update, self.draw)

    def update(self):
        """ Update process """

        if self.game_over_flg:
            return

        # Background
        self.background.update()

        # Player
        self.ship.update()
        self.control_ship()
        self.overlap_spr(self.ship)

        self.check_interval()

        # Asteroids
        for asteroid in self.asteroids:
            asteroid.update()
            self.overlap_spr(asteroid)
            if asteroid.intersects(self.ship):
                self.game_over_flg = True

        # Bullets (reverse order)
        for bullet in self.bullets[::-1]:
            bullet.update()
            if bullet.y < 0:
                self.bullets.remove(bullet)
                continue
            for asteroid in self.asteroids[::-1]:
                if asteroid.intersects(bullet):
                    self.score += 1
                    self.bullets.remove(bullet)
                    self.asteroids.remove(asteroid)
                    pyxel.play(1, 1)
                    return

    def draw(self):
        """ Draw process """
        pyxel.cls(0)

        # Background
        self.background.draw()

        if self.game_over_flg:
            msg = "GAME OVER"
            pyxel.text(W / 2 - len(msg) * 2, H / 2, msg, 13)

        pyxel.text(10, 10, f"SCORE:{self.score:04}", 12)

        self.ship.draw()

        for asteroid in self.asteroids:
            asteroid.draw()

        for bullet in self.bullets:
            bullet.draw()

    def control_ship(self):
        """ Player action """
        if pyxel.btnp(pyxel.KEY_SPACE):
            self.ship.flip_x()
            bullet = sprite.BulletSprite(self.ship.x, self.ship.y)
            bullet.move(BULLET_SPD, 270)
            self.bullets.append(bullet)
            pyxel.play(0, 0)

    def overlap_spr(self, spr):
        """ Wrap around screen """
        if spr.x < -spr.w:
            spr.x = W
            return
        if W < spr.x:
            spr.x = -spr.w
            return
        if spr.y < -spr.h:
            spr.y = H
            return
        if H < spr.y:
            spr.y = -spr.h
            return

    def check_interval(self):
        self.asteroid_time += 1
        if self.asteroid_time < ASTEROID_INTERVAL:
            return
        self.asteroid_time = 0
        if ASTEROID_LIMIT < len(self.asteroids):
            return
        x = random.random() * W
        y = 0
        spd = random.uniform(ASTEROID_SPD_MIN, ASTEROID_SPD_MAX)
        deg = random.uniform(ASTEROID_DEG_MIN, ASTEROID_DEG_MAX)
        asteroid = sprite.AsteroidSprite(x, y)
        asteroid.move(spd, deg)
        self.asteroids.append(asteroid)

def main():
    """ Main process """
    Game()

if __name__ == "__main__":
    main()

Result

The game will look like this when running.

Final Words

Thank you for reading until the end.

I hope this series becomes a trigger for starting game development.

If you liked it, a 👍 would be greatly appreciated!

Getting Started with 2D Games Using Pyxel (Part 12): Playing Sound Effects

Kajiru — Thu, 15 Jan 2026 15:00:00 +0000

Playing Sound Effects

In this article, we will play sound effects (SE) in a game.

Instead of using external audio files, we will introduce how to create simple sound effects directly in code by writing musical notes.

The complete source code is provided at the end.

1. Registering a Sound

First, register a sound inside the constructor of the Game class.

The argument of pyxel.sound() specifies the sound ID.

Sound ID: This number is used later when playing the sound.

Next, pass the following data to the set() method:

Notes (score): Specifies the pitch
tones: Type of waveform (e.g. p = pulse wave)
volumes: Volume
effects: Sound effect (e.g. f = fade out)
speed: Playback speed (lower values play faster)

# main.py
pyxel.sound(0).set(
    "c4g3",
    tones="p",
    volumes="76",
    effects="f",
    speed=20
)

2. Playing a Sound

With pyxel.play(), up to four sounds can be played simultaneously.

The first argument specifies the channel number (0–3).
- If the same channel is used, the new sound overwrites the previous one.
The second argument specifies the sound ID.

# main.py
pyxel.play(0, 0)

Complete Code

Below is the complete code implementing the features introduced in this article.

(The sprite.py file is the same as in the previous chapter.)

# main.py
import pyxel
import math
import random
import sprite

W, H = 160, 120
SHIP_SPD = 1.4

ASTEROID_INTERVAL = 20
ASTEROID_LIMIT = 30

ASTEROID_SPD_MIN = 1.0
ASTEROID_SPD_MAX = 2.0
ASTEROID_DEG_MIN = 30
ASTEROID_DEG_MAX = 150

BULLET_SPD = 3

# Game
class Game:
    def __init__(self):
        """ Constructor """

        # Game over flag
        self.game_over_flg = False

        # Initialize score
        self.score = 0

        # Initialize player
        self.ship = sprite.ShipSprite(W / 2, H - 40)
        deg = 0 if random.random() < 0.5 else 180
        self.ship.move(SHIP_SPD, deg)

        # Asteroids
        self.asteroid_time = 0
        self.asteroids = []

        # Bullets
        self.bullets = []

        # Initialize Pyxel
        pyxel.init(W, H, title="Hello, Pyxel!!")
        pyxel.load("shooter.pyxres")

        # Sound (shot)
        pyxel.sound(0).set(
            "c4g3",
            tones="p",
            volumes="76",
            effects="f",
            speed=20
        )

        # Sound (hit)
        pyxel.sound(1).set(
            "e4d4c4",
            tones="p",
            volumes="76",
            effects="n",
            speed=20
        )

        pyxel.run(self.update, self.draw)

    def update(self):
        """ Update process """

        # Game over
        if self.game_over_flg:
            return

        # Update player
        self.ship.update()
        self.control_ship()
        self.overlap_spr(self.ship)

        self.check_interval()  # Add asteroids

        # Update asteroids
        for asteroid in self.asteroids:
            asteroid.update()
            self.overlap_spr(asteroid)
            # Collision check (asteroid x player)
            if asteroid.intersects(self.ship):
                self.game_over_flg = True

        # Update bullets (reverse order)
        for bullet in self.bullets[::-1]:
            bullet.update()
            # Remove if outside screen
            if bullet.y < 0:
                self.bullets.remove(bullet)
                continue
            # Collision check (bullet x asteroid)
            for asteroid in self.asteroids[::-1]:
                if asteroid.intersects(bullet):
                    self.score += 1
                    self.bullets.remove(bullet)
                    self.asteroids.remove(asteroid)

                    # Sound (hit)
                    pyxel.play(1, 1)
                    return

    def draw(self):
        """ Draw process """
        pyxel.cls(0)

        # Game over
        if self.game_over_flg:
            msg = "GAME OVER"
            pyxel.text(W / 2 - len(msg) * 2, H / 2, msg, 13)

        # Draw score
        pyxel.text(10, 10, f"SCORE:{self.score:04}", 12)

        # Draw player
        self.ship.draw()

        # Draw asteroids
        for asteroid in self.asteroids:
            asteroid.draw()

        # Draw bullets
        for bullet in self.bullets:
            bullet.draw()

    def control_ship(self):
        """ Player action """
        if pyxel.btnp(pyxel.KEY_SPACE):
            self.ship.flip_x()

            # Fire bullet
            bullet = sprite.BulletSprite(self.ship.x, self.ship.y)
            bullet.move(BULLET_SPD, 270)
            self.bullets.append(bullet)

            # Sound (shot)
            pyxel.play(0, 0)

    def overlap_spr(self, spr):
        """ Wrap sprite around the screen """
        if spr.x < -spr.w:
            spr.x = W
            return
        if W < spr.x:
            spr.x = -spr.w
            return
        if spr.y < -spr.h:
            spr.y = H
            return
        if H < spr.y:
            spr.y = -spr.h
            return

    def check_interval(self):
        # Asteroid spawn interval
        self.asteroid_time += 1
        if self.asteroid_time < ASTEROID_INTERVAL:
            return
        self.asteroid_time = 0

        # Limit number of asteroids
        if ASTEROID_LIMIT < len(self.asteroids):
            return

        # Add asteroid
        x = random.random() * W
        y = 0
        spd = random.uniform(ASTEROID_SPD_MIN, ASTEROID_SPD_MAX)
        deg = random.uniform(ASTEROID_DEG_MIN, ASTEROID_DEG_MAX)
        asteroid = sprite.AsteroidSprite(x, y)
        asteroid.move(spd, deg)
        self.asteroids.append(asteroid)

def main():
    """ Main process """
    Game()

if __name__ == "__main__":
    main()

Final Words

Thank you for reading this far.

I hope this series becomes a starting point for your own game development journey.

If you enjoyed it, a 👍 would mean a lot!

Getting Started with 2D Games Using Pyxel (Part 11): Implement Game Over Detection

Kajiru — Wed, 14 Jan 2026 15:00:00 +0000

Implement Game Over Detection

In this chapter, we will detect collisions between the player and asteroids

and display “GAME OVER” on the screen.

The complete code is provided at the end.

1. Prepare a Game Over Flag

In the constructor of the Game class in main.py,

add a flag to manage the game over state.

When the player collides with an asteroid,

this flag will be set to True.

# main.py (inside the Game class constructor)

# Game over flag
self.game_over_flg = False

2. Monitor the Flag in the Update Process

In the update() method of the Game class,

check the game over flag.

If the flag is True,

use return to stop further processing.

This ensures that after the game is over,

the player, bullets, and other objects are no longer updated.

# main.py (inside the Game.update() method)

# Game over
if self.game_over_flg:
    return

3. Display Text in the Draw Process

In the draw() method of the Game class,

display the text “GAME OVER” only when the game is over.

# main.py (inside the Game.draw() method)

# Game over
if self.game_over_flg:
    msg = "GAME OVER"
    pyxel.text(W / 2 - len(msg) * 2, H / 2, msg, 13)

4. Detect Collision Between Player and Asteroids

Inside the update() method of the Game class,

check for collisions between the player and asteroids.

When a collision occurs,

set self.game_over_flg to True to trigger game over.

# main.py (inside the Game.update() method)

# Update asteroids
for asteroid in self.asteroids:
    asteroid.update()
    self.overlap_spr(asteroid)
    # Collision detection (asteroid x player)
    if asteroid.intersects(self.ship):
        self.game_over_flg = True  # Game over

Complete Code

Below is the complete code with all features implemented.

# sprite.py
import pyxel
import math
import random

class BaseSprite:

    def __init__(self, x, y, w=8, h=8):
        """ Constructor """
        self.x = x
        self.y = y
        self.w = w
        self.h = h
        self.vx = 0
        self.vy = 0

    def update(self):
        """ Update """
        self.x += self.vx
        self.y += self.vy

    def draw(self):
        """ Draw (implemented in subclasses) """
        pass

    def move(self, spd, deg):
        """ Move """
        rad = deg * math.pi / 180
        self.vx = spd * math.cos(rad)  # X velocity
        self.vy = spd * math.sin(rad)  # Y velocity

    def flip_x(self):
        """ Flip X direction """
        self.vx *= -1

    def intersects(self, other):
        """ Rectangle-based collision detection (AABB) """
        if other.x + other.w < self.x: return False
        if self.x + self.w < other.x: return False
        if other.y + other.h < self.y: return False
        if self.y + self.h < other.y: return False
        return True

class ShipSprite(BaseSprite):

    def __init__(self, x, y):
        """ Constructor """
        super().__init__(x, y)

    def draw(self):
        """ Draw """
        pyxel.blt(
            self.x, self.y, 0,
            0, 0,
            self.w, self.h, 0  # Ship
        )

class AsteroidSprite(BaseSprite):

    def __init__(self, x, y):
        """ Constructor """
        super().__init__(x, y)
        self.index = random.randint(2, 7)  # Asteroid image index

    def draw(self):
        """ Draw """
        pyxel.blt(
            self.x, self.y, 0,
            self.w * self.index, 0,
            self.w, self.h, 0  # Asteroid
        )

class BulletSprite(BaseSprite):

    def __init__(self, x, y):
        """ Constructor """
        super().__init__(x, y)
        self.x += self.w / 2 - 1  # Center alignment

    def draw(self):
        """ Draw """
        pyxel.rect(self.x, self.y, 2, 2, 12)

# main.py
import pyxel
import math
import random
import sprite

W, H = 160, 120
SHIP_SPD = 1.4

ASTEROID_INTERVAL = 20
ASTEROID_LIMIT = 30

ASTEROID_SPD_MIN = 1.0
ASTEROID_SPD_MAX = 2.0
ASTEROID_DEG_MIN = 30
ASTEROID_DEG_MAX = 150

BULLET_SPD = 3

# Game
class Game:
    def __init__(self):
        """ Constructor """

        # Game over flag
        self.game_over_flg = False

        # Initialize score
        self.score = 0

        # Initialize player
        self.ship = sprite.ShipSprite(W / 2, H - 40)
        deg = 0 if random.random() < 0.5 else 180
        self.ship.move(SHIP_SPD, deg)

        # Asteroids
        self.asteroid_time = 0
        self.asteroids = []

        # Bullets
        self.bullets = []

        # Start Pyxel
        pyxel.init(W, H, title="Hello, Pyxel!!")
        pyxel.load("shooter.pyxres")
        pyxel.run(self.update, self.draw)

    def update(self):
        """ Update """

        # Game over
        if self.game_over_flg:
            return

        # Update player
        self.ship.update()
        self.control_ship()
        self.overlap_spr(self.ship)

        self.check_interval()  # Spawn asteroids

        # Update asteroids
        for asteroid in self.asteroids:
            asteroid.update()
            self.overlap_spr(asteroid)
            # Collision detection (asteroid x player)
            if asteroid.intersects(self.ship):
                self.game_over_flg = True

        # Update bullets (reverse order)
        for bullet in self.bullets[::-1]:
            bullet.update()
            # Remove bullets that leave the screen
            if bullet.y < 0:
                self.bullets.remove(bullet)
                continue
            # Collision detection (bullet x asteroid)
            for asteroid in self.asteroids[::-1]:
                if asteroid.intersects(bullet):
                    self.score += 1
                    self.bullets.remove(bullet)
                    self.asteroids.remove(asteroid)
                    return

    def draw(self):
        """ Draw """
        pyxel.cls(0)

        # Game over
        if self.game_over_flg:
            msg = "GAME OVER"
            pyxel.text(W / 2 - len(msg) * 2, H / 2, msg, 13)

        # Draw score
        pyxel.text(10, 10, "SCORE:{:04}".format(self.score), 12)

        # Draw player
        self.ship.draw()

        # Draw asteroids
        for asteroid in self.asteroids:
            asteroid.draw()

        # Draw bullets
        for bullet in self.bullets:
            bullet.draw()

    def control_ship(self):
        """ Player action """
        if pyxel.btnp(pyxel.KEY_SPACE):
            self.ship.flip_x()  # Reverse movement
            # Fire bullet
            bullet = sprite.BulletSprite(self.ship.x, self.ship.y)
            bullet.move(BULLET_SPD, 270)
            self.bullets.append(bullet)

    def overlap_spr(self, spr):
        """ Wrap sprite around the screen """
        if spr.x < -spr.w:
            spr.x = W
            return
        if W < spr.x:
            spr.x = -spr.w
            return
        if spr.y < -spr.h:
            spr.y = H
            return
        if H < spr.y:
            spr.y = -spr.h
            return

    def check_interval(self):
        # Asteroid spawn interval
        self.asteroid_time += 1
        if self.asteroid_time < ASTEROID_INTERVAL:
            return
        self.asteroid_time = 0
        # Limit asteroid count
        if ASTEROID_LIMIT < len(self.asteroids):
            return
        # Spawn asteroid
        x = random.random() * W
        y = 0
        spd = random.uniform(ASTEROID_SPD_MIN, ASTEROID_SPD_MAX)
        deg = random.uniform(ASTEROID_DEG_MIN, ASTEROID_DEG_MAX)
        asteroid = sprite.AsteroidSprite(x, y)
        asteroid.move(spd, deg)
        self.asteroids.append(asteroid)

def main():
    """ Main process """
    Game()

if __name__ == "__main__":
    main()

Result

Running the game produces the following result:

Final Thoughts

Thank you very much for reading this far.

This concludes “Getting Started with 2D Games Using Pyxel”.

Although the game we built is very simple, it includes core elements of game development:

Sprite management
Keyboard input
Collision detection and object removal

If you understand everything up to this point,

you should now be able to create simple games using Pyxel.

I hope this series becomes a stepping stone into game development for you.

(If you enjoyed it, a 👍 would be greatly appreciated!!)

Getting Started with 2D Games Using Pyxel (Part 10): Implement Collision Detection

Kajiru — Tue, 13 Jan 2026 15:00:00 +0000

Implement Collision Detection

In this chapter, we will implement collision detection between bullets and asteroids.

The complete code is provided at the end.

1. Implement Collision Detection Logic

First, add a new intersects() method to the BaseSprite class in sprite.py.

This method checks whether the sprite overlaps with another sprite passed as an argument.

It returns True if they are colliding, and False otherwise.

(This implementation uses the AABB concept, but you don’t need to dive deep into it for now.)

# sprite.py (added to BaseSprite)
def intersects(self, other):
    """ Rectangle-based collision detection (AABB) """
    if other.x + other.w < self.x: return False
    if self.x + self.w < other.x: return False
    if other.y + other.h < self.y: return False
    if self.y + self.h < other.y: return False
    return True

2. Bullet and Asteroid Collisions

Next, we check for collisions between bullets and asteroids during the bullet update phase.

As before, since we remove elements from the list while iterating,

we traverse the list in reverse order to avoid index issues.

To keep the logic simple, we immediately return from the update() method

once a collision is detected.

When a collision occurs, the score is incremented by 1.

# main.py (added to the Game.update() method)

# Update bullets (reverse order)
for bullet in self.bullets[::-1]:
    bullet.update()
    # Remove bullets that leave the screen
    if bullet.y < 0:
        self.bullets.remove(bullet)
        continue
    # Collision detection (bullet x asteroid)
    for asteroid in self.asteroids[::-1]:
        if asteroid.intersects(bullet):
            self.score += 1  # Increase score
            self.bullets.remove(bullet)
            self.asteroids.remove(asteroid)
            return  # Simplified handling

Complete Code

Below is the complete code with all features implemented so far.

# sprite.py
import pyxel
import math
import random

class BaseSprite:

    def __init__(self, x, y, w=8, h=8):
        """ Constructor """
        self.x = x
        self.y = y
        self.w = w
        self.h = h
        self.vx = 0
        self.vy = 0

    def update(self):
        """ Update """
        self.x += self.vx
        self.y += self.vy

    def draw(self):
        """ Draw (implemented in subclasses) """
        pass

    def move(self, spd, deg):
        """ Move """
        rad = deg * math.pi / 180
        self.vx = spd * math.cos(rad)  # X velocity
        self.vy = spd * math.sin(rad)  # Y velocity

    def flip_x(self):
        """ Flip X direction """
        self.vx *= -1

    def intersects(self, other):
        """ Rectangle-based collision detection (AABB) """
        if other.x + other.w < self.x: return False
        if self.x + self.w < other.x: return False
        if other.y + other.h < self.y: return False
        if self.y + self.h < other.y: return False
        return True

class ShipSprite(BaseSprite):

    def __init__(self, x, y):
        """ Constructor """
        super().__init__(x, y)

    def draw(self):
        """ Draw """
        pyxel.blt(
            self.x, self.y, 0,
            0, 0,
            self.w, self.h, 0  # Ship
        )

class AsteroidSprite(BaseSprite):

    def __init__(self, x, y):
        """ Constructor """
        super().__init__(x, y)
        self.index = random.randint(2, 7)  # Asteroid image index

    def draw(self):
        """ Draw """
        pyxel.blt(
            self.x, self.y, 0,
            self.w * self.index, 0,
            self.w, self.h, 0  # Asteroid
        )

class BulletSprite(BaseSprite):

    def __init__(self, x, y):
        """ Constructor """
        super().__init__(x, y)
        self.x += self.w / 2 - 1  # Center alignment

    def draw(self):
        """ Draw """
        pyxel.rect(self.x, self.y, 2, 2, 12)

# main.py
import pyxel
import math
import random
import sprite

W, H = 160, 120
SHIP_SPD = 1.4

ASTEROID_INTERVAL = 20
ASTEROID_LIMIT = 30

ASTEROID_SPD_MIN = 1.0
ASTEROID_SPD_MAX = 2.0
ASTEROID_DEG_MIN = 30
ASTEROID_DEG_MAX = 150

BULLET_SPD = 3

# Game
class Game:
    def __init__(self):
        """ Constructor """

        # Initialize score
        self.score = 0

        # Initialize player
        self.ship = sprite.ShipSprite(W / 2, H - 40)
        deg = 0 if random.random() < 0.5 else 180
        self.ship.move(SHIP_SPD, deg)

        # Asteroids
        self.asteroid_time = 0
        self.asteroids = []

        # Bullets
        self.bullets = []

        # Start Pyxel
        pyxel.init(W, H, title="Hello, Pyxel!!")
        pyxel.load("shooter.pyxres")
        pyxel.run(self.update, self.draw)

    def update(self):
        """ Update """

        # Update player
        self.ship.update()
        self.control_ship()
        self.overlap_spr(self.ship)

        self.check_interval()  # Spawn asteroids

        # Update asteroids
        for asteroid in self.asteroids:
            asteroid.update()
            self.overlap_spr(asteroid)

        # Update bullets (reverse order)
        for bullet in self.bullets[::-1]:
            bullet.update()
            # Remove bullets that leave the screen
            if bullet.y < 0:
                self.bullets.remove(bullet)
                continue
            # Collision detection (bullet x asteroid)
            for asteroid in self.asteroids[::-1]:
                if asteroid.intersects(bullet):
                    self.score += 1
                    self.bullets.remove(bullet)
                    self.asteroids.remove(asteroid)
                    return

    def draw(self):
        """ Draw """
        pyxel.cls(0)

        # Draw score
        pyxel.text(10, 10, "SCORE:{:04}".format(self.score), 12)

        # Draw player
        self.ship.draw()

        # Draw asteroids
        for asteroid in self.asteroids:
            asteroid.draw()

        # Draw bullets
        for bullet in self.bullets:
            bullet.draw()

    def control_ship(self):
        """ Player actions """
        if pyxel.btnp(pyxel.KEY_SPACE):
            self.ship.flip_x()  # Reverse movement
            # Fire bullet
            bullet = sprite.BulletSprite(self.ship.x, self.ship.y)
            bullet.move(BULLET_SPD, 270)
            self.bullets.append(bullet)

    def overlap_spr(self, spr):
        """ Wrap sprite around screen """
        if spr.x < -spr.w:
            spr.x = W
            return
        if W < spr.x:
            spr.x = -spr.w
            return
        if spr.y < -spr.h:
            spr.y = H
            return
        if H < spr.y:
            spr.y = -spr.h
            return

    def check_interval(self):
        # Asteroid spawn interval
        self.asteroid_time += 1
        if self.asteroid_time < ASTEROID_INTERVAL:
            return
        self.asteroid_time = 0
        # Limit asteroid count
        if ASTEROID_LIMIT < len(self.asteroids):
            return
        # Spawn asteroid
        x = random.random() * W
        y = 0
        spd = random.uniform(ASTEROID_SPD_MIN, ASTEROID_SPD_MAX)
        deg = random.uniform(ASTEROID_DEG_MIN, ASTEROID_DEG_MAX)
        asteroid = sprite.AsteroidSprite(x, y)
        asteroid.move(spd, deg)
        self.asteroids.append(asteroid)

def main():
    """ Main entry point """
    Game()

if __name__ == "__main__":
    main()

Result

Running the game produces the following result:

Next Chapter

Thank you for reading!

In the next chapter, we’ll implement game over detection.

Stay tuned!!

Getting Started with 2D Games Using Pyxel (Part 9): Shooting Bullets

Kajiru — Mon, 12 Jan 2026 15:00:00 +0000

Shooting Bullets

In this chapter, we will implement bullet firing from the player sprite.

Here, we will build the core mechanics of a shooting game, including:

Adding a new sprite (bullets)
Managing multiple bullets using a list
Removing bullets that are no longer needed

The complete code is shown at the end of this article.

1. Creating a Bullet Sprite

As in the previous chapter, add a new BulletSprite class to sprite.py.

This time, instead of using an image, we will draw a simple 2×2 square using pyxel.rect().
This is more than enough to represent small bullets.

# sprite.py (add this class)

class BulletSprite(BaseSprite):

    def __init__(self, x, y):
        """ Constructor """
        super().__init__(x, y)
        self.x += self.w / 2 - 1  # Adjust to center

    def draw(self):
        """ Draw processing """
        pyxel.rect(self.x, self.y, 2, 2, 12)

2. Defining Constants

Next, add a constant for bullet speed in main.py.

By defining it as a constant, you can easily tweak the bullet speed later.

# main.py (add a constant)

BULLET_SPD = 3  # Bullet speed

3. Firing Bullets

Now, let’s add the logic for firing bullets.

In this sample, bullets are fired when the player presses the space key—the same timing used to flip the player’s direction left and right.

Bullets will move straight upward (270 degrees).

# main.py (add to the Game class method `control_ship()`)

def control_ship(self):
    """ Action """
    if pyxel.btnp(pyxel.KEY_SPACE):
        self.ship.flip_x()  # Reverse movement
        # Fire a bullet
        bullet = sprite.BulletSprite(self.ship.x, self.ship.y)
        bullet.move(BULLET_SPD, 270)
        self.bullets.append(bullet)

4. Updating and Drawing Bullets

Next, add the update logic for bullets.

In the update() method of the Game class, update all bullets and remove those that go off-screen.

Because elements are removed during iteration, the list is processed in reverse order.
This prevents bugs caused by index shifting.

# main.py (add to the Game class `update()` method)

# Update bullets (reverse order)
for bullet in self.bullets[::-1]:
    bullet.update()
    # Remove bullets that go off-screen
    if bullet.y < 0:
        self.bullets.remove(bullet)
        continue

Then, draw all bullets together in the draw() method.

# main.py (add to the Game class `draw()` method)

# Draw bullets
for bullet in self.bullets:
    bullet.draw()

With this, the player can now shoot bullets.

Complete Code

Below is the complete code with all features implemented so far.

# sprite.py

import pyxel
import math
import random

class BaseSprite:

    def __init__(self, x, y, w=8, h=8):
        """ Constructor """
        self.x = x
        self.y = y
        self.w = w
        self.h = h
        self.vx = 0
        self.vy = 0

    def update(self):
        """ Update processing """
        self.x += self.vx
        self.y += self.vy

    def draw(self):
        """ Draw processing (implemented in subclasses) """
        pass

    def move(self, spd, deg):
        """ Move """
        rad = deg * math.pi / 180
        self.vx = spd * math.cos(rad)  # X-axis speed
        self.vy = spd * math.sin(rad)  # Y-axis speed

    def flip_x(self):
        """ Flip movement on the X-axis """
        self.vx *= -1

class ShipSprite(BaseSprite):

    def __init__(self, x, y):
        """ Constructor """
        super().__init__(x, y)

    def draw(self):
        """ Draw processing """
        pyxel.blt(
            self.x, self.y, 0,
            0, 0,
            self.w, self.h, 0
        )  # Ship

class AsteroidSprite(BaseSprite):

    def __init__(self, x, y):
        """ Constructor """
        super().__init__(x, y)
        self.index = random.randint(2, 7)  # Asteroid image index

    def draw(self):
        """ Draw processing """
        pyxel.blt(
            self.x, self.y, 0,
            self.w * self.index, 0,
            self.w, self.h, 0
        )  # Asteroid

class BulletSprite(BaseSprite):

    def __init__(self, x, y):
        """ Constructor """
        super().__init__(x, y)
        self.x += self.w / 2 - 1  # Adjust to center

    def draw(self):
        """ Draw processing """
        pyxel.rect(self.x, self.y, 2, 2, 12)

# main.py

import pyxel
import math
import random
import sprite

W, H = 160, 120
SHIP_SPD = 1.4

ASTEROID_INTERVAL = 20
ASTEROID_LIMIT = 30

ASTEROID_SPD_MIN = 1.0
ASTEROID_SPD_MAX = 2.0
ASTEROID_DEG_MIN = 30
ASTEROID_DEG_MAX = 150

BULLET_SPD = 3  # Bullet speed

# Game
class Game:
    def __init__(self):
        """ Constructor """

        # Initialize score
        self.score = 0

        # Initialize player
        self.ship = sprite.ShipSprite(W / 2, H - 40)
        deg = 0 if random.random() < 0.5 else 180
        self.ship.move(SHIP_SPD, deg)

        # Asteroids
        self.asteroid_time = 0
        self.asteroids = []

        # Bullets
        self.bullets = []

        # Start Pyxel
        pyxel.init(W, H, title="Hello, Pyxel!!")
        pyxel.load("shooter.pyxres")
        pyxel.run(self.update, self.draw)

    def update(self):
        """ Update processing """

        # Update player
        self.ship.update()
        self.control_ship()
        self.overlap_spr(self.ship)

        self.check_interval()  # Add asteroids

        # Update asteroids
        for asteroid in self.asteroids:
            asteroid.update()
            self.overlap_spr(asteroid)

        # Update bullets (reverse order)
        for bullet in self.bullets[::-1]:
            bullet.update()
            if bullet.y < 0:
                self.bullets.remove(bullet)
                continue

    def draw(self):
        """ Draw processing """
        pyxel.cls(0)

        # Draw score
        pyxel.text(
            10, 10,
            "SCORE:{:04}".format(self.score), 12
        )

        # Draw player
        self.ship.draw()

        # Draw asteroids
        for asteroid in self.asteroids:
            asteroid.draw()

        # Draw bullets
        for bullet in self.bullets:
            bullet.draw()

    def control_ship(self):
        """ Action """
        if pyxel.btnp(pyxel.KEY_SPACE):
            self.ship.flip_x()  # Reverse movement
            # Fire a bullet
            bullet = sprite.BulletSprite(self.ship.x, self.ship.y)
            bullet.move(BULLET_SPD, 270)
            self.bullets.append(bullet)

    def overlap_spr(self, spr):
        """ Wrap around the screen """
        if spr.x < -spr.w:
            spr.x = W
            return
        if W < spr.x:
            spr.x = -spr.w
            return
        if spr.y < -spr.h:
            spr.y = H
            return
        if H < spr.y:
            spr.y = -spr.h
            return

    def check_interval(self):
        # Asteroid spawn interval
        self.asteroid_time += 1
        if self.asteroid_time < ASTEROID_INTERVAL:
            return
        self.asteroid_time = 0
        # Limit the number of asteroids
        if ASTEROID_LIMIT < len(self.asteroids):
            return
        # Add an asteroid
        x = random.random() * W
        y = 0
        spd = random.uniform(ASTEROID_SPD_MIN, ASTEROID_SPD_MAX)
        deg = random.uniform(ASTEROID_DEG_MIN, ASTEROID_DEG_MAX)
        asteroid = sprite.AsteroidSprite(x, y)
        asteroid.move(spd, deg)
        self.asteroids.append(asteroid)

def main():
    """ Main entry point """
    Game()

if __name__ == "__main__":
    main()

When you run this program, the result will look like this:

Coming Up Next...

Thank you for reading!
The next chapter is titled “Implementing Collision Detection.”

Stay tuned!!

Getting Started with 2D Games Using Pyxel (Part 8): Spawning Asteroids

Kajiru — Sun, 11 Jan 2026 15:00:00 +0000

Spawn Asteroids

In this chapter, we implement logic to spawn asteroids at regular intervals.

Here, we’ll build more game-like systems such as:

Managing multiple sprites
Executing actions at fixed time intervals

The complete code is shown at the end of this chapter.

1. Create an Asteroid Sprite

First, let’s prepare a sprite class for asteroids.

Add a new AsteroidSprite class to sprite.py.

In its constructor, we use a random value to select which asteroid image to display.

# sprite.py
# add this class

class AsteroidSprite(BaseSprite):

    def __init__(self, x, y):
        """Constructor"""
        super().__init__(x, y)
        self.index = random.randint(2, 7)  # Asteroid image index

    def draw(self):
        """Draw"""
        pyxel.blt(
            self.x, self.y, 0,
            self.w * self.index, 0,
            self.w, self.h, 0
        )  # Asteroid

With this setup, each asteroid will have a different appearance

every time it is generated.

2. Prepare Constants and Variables

Next, add asteroid-related constants to main.py.

By grouping these values as constants,

it becomes much easier to adjust the game difficulty later.

# main.py
# add constants

ASTEROID_INTERVAL = 20   # Spawn interval
ASTEROID_LIMIT = 30      # Maximum number of asteroids

ASTEROID_SPD_MIN = 1.0   # Minimum speed
ASTEROID_SPD_MAX = 2.0   # Maximum speed
ASTEROID_DEG_MIN = 30    # Minimum angle
ASTEROID_DEG_MAX = 150   # Maximum angle

Next, add variables for managing asteroids

to the constructor of the Game class.

# main.py
# add to Game.__init__()

# Asteroids
self.asteroid_time = 0   # Spawn interval counter
self.asteroids = []      # Asteroid list

3. Asteroid Spawning Logic

Add a check_interval() method to the Game class.

This method spawns asteroids at fixed intervals.

Asteroids appear every ASTEROID_INTERVAL frames.

The total number of asteroids is limited by ASTEROID_LIMIT.

The spawn position is randomly chosen along the top edge of the screen.

Speed and angle are also randomly selected within predefined ranges.

# main.py
# add to Game class

def check_interval(self):
    # Asteroid spawn interval
    self.asteroid_time += 1
    if self.asteroid_time < ASTEROID_INTERVAL:
        return
    self.asteroid_time = 0

    # Do not exceed the maximum number of asteroids
    if ASTEROID_LIMIT < len(self.asteroids):
        return

    # Add a new asteroid
    x = random.random() * W
    y = 0
    spd = random.uniform(ASTEROID_SPD_MIN, ASTEROID_SPD_MAX)
    deg = random.uniform(ASTEROID_DEG_MIN, ASTEROID_DEG_MAX)

    asteroid = sprite.AsteroidSprite(x, y)
    asteroid.move(spd, deg)
    self.asteroids.append(asteroid)

4. Updating and Drawing Asteroids

Next, add update and draw logic for asteroids.

In the update() method of the Game class,

handle asteroid spawning and updating.

# main.py
# add to Game.update()

self.check_interval()  # Spawn asteroids

# Update asteroids
for asteroid in self.asteroids:
    asteroid.update()
    self.overlap_spr(asteroid)

In the draw() method,

draw all asteroids at once.

# main.py
# add to Game.draw()

# Draw asteroids
for asteroid in self.asteroids:
    asteroid.draw()

Now, multiple asteroids will flow across the screen.

Complete Code

Below is the complete code implementing all the features in this chapter.

# sprite.py
import pyxel
import math
import random

class BaseSprite:

    def __init__(self, x, y, w=8, h=8):
        """Constructor"""
        self.x = x
        self.y = y
        self.w = w
        self.h = h
        self.vx = 0
        self.vy = 0

    def update(self):
        """Update"""
        self.x += self.vx
        self.y += self.vy

    def draw(self):
        """Draw (implemented in subclasses)"""
        pass

    def move(self, spd, deg):
        """Move"""
        rad = deg * math.pi / 180
        self.vx = spd * math.cos(rad)  # x-axis velocity
        self.vy = spd * math.sin(rad)  # y-axis velocity

    def flip_x(self):
        """Flip movement in the x direction"""
        self.vx *= -1

class ShipSprite(BaseSprite):

    def __init__(self, x, y):
        """Constructor"""
        super().__init__(x, y)

    def draw(self):
        """Draw"""
        pyxel.blt(
            self.x, self.y, 0,
            0, 0,
            self.w, self.h, 0
        )  # Ship

class AsteroidSprite(BaseSprite):

    def __init__(self, x, y):
        """Constructor"""
        super().__init__(x, y)
        self.index = random.randint(2, 7)  # Asteroid image index

    def draw(self):
        """Draw"""
        pyxel.blt(
            self.x, self.y, 0,
            self.w * self.index, 0,
            self.w, self.h, 0
        )  # Asteroid

# main.py
import pyxel
import math
import random
import sprite

W, H = 160, 120
SHIP_SPD = 1.4

ASTEROID_INTERVAL = 20   # Spawn interval
ASTEROID_LIMIT = 30      # Maximum number of asteroids

ASTEROID_SPD_MIN = 1.0   # Minimum speed
ASTEROID_SPD_MAX = 2.0   # Maximum speed
ASTEROID_DEG_MIN = 30    # Minimum angle
ASTEROID_DEG_MAX = 150   # Maximum angle

# Game
class Game:
    def __init__(self):
        """Constructor"""

        # Initialize score
        self.score = 0

        # Initialize player
        self.ship = sprite.ShipSprite(W / 2, H - 40)
        deg = 0 if random.random() < 0.5 else 180
        self.ship.move(SHIP_SPD, deg)

        # Asteroids
        self.asteroid_time = 0   # Spawn interval counter
        self.asteroids = []      # Asteroid list

        # Start Pyxel
        pyxel.init(W, H, title="Hello, Pyxel!!")
        pyxel.load("shooter.pyxres")
        pyxel.run(self.update, self.draw)

    def update(self):
        """Update"""

        # Update player
        self.ship.update()
        self.control_ship()
        self.overlap_spr(self.ship)

        self.check_interval()  # Spawn asteroids

        # Update asteroids
        for asteroid in self.asteroids:
            asteroid.update()
            self.overlap_spr(asteroid)

    def draw(self):
        """Draw"""
        pyxel.cls(0)

        # Draw score
        pyxel.text(
            10, 10,
            "SCORE:{:04}".format(self.score), 12
        )

        # Draw player
        self.ship.draw()

        # Draw asteroids
        for asteroid in self.asteroids:
            asteroid.draw()

    def control_ship(self):
        """Action"""
        if pyxel.btnp(pyxel.KEY_SPACE):
            self.ship.flip_x()  # Reverse movement

    def overlap_spr(self, spr):
        """Move to the opposite side when leaving the screen"""
        if spr.x < -spr.w:
            spr.x = W
            return
        if W < spr.x:
            spr.x = -spr.w
            return
        if spr.y < -spr.h:
            spr.y = H
            return
        if H < spr.y:
            spr.y = -spr.h
            return

    def check_interval(self):
        # Asteroid spawn interval
        self.asteroid_time += 1
        if self.asteroid_time < ASTEROID_INTERVAL:
            return
        self.asteroid_time = 0

        # Do not exceed the maximum number of asteroids
        if ASTEROID_LIMIT < len(self.asteroids):
            return

        # Add a new asteroid
        x = random.random() * W
        y = 0
        spd = random.uniform(ASTEROID_SPD_MIN, ASTEROID_SPD_MAX)
        deg = random.uniform(ASTEROID_DEG_MIN, ASTEROID_DEG_MAX)

        asteroid = sprite.AsteroidSprite(x, y)
        asteroid.move(spd, deg)
        self.asteroids.append(asteroid)

def main():
    """Main"""
    Game()

if __name__ == "__main__":
    main()

When you run the game, it looks like this.

Next Time...

Thank you for reading!

In the next chapter, we’ll cover “Let’s Fire Bullets.”

Stay tuned!

Getting Started with 2D Games Using Pyxel (Part 7): Control the Character

Kajiru — Sat, 10 Jan 2026 15:00:00 +0000

Control the Character

In this chapter, we detect the timing when the Space key is pressed

and implement logic to flip the player’s movement direction left and right.

This gives a stronger sense that you are directly controlling the player.

The complete code is shown at the end of this chapter.

1. Add a Method to Flip Left and Right

First, set the player’s initial movement direction.

In the constructor of the Game class,

make the player move either to the right (0 degrees) or to the left (180 degrees).

# main.py
# inside Game.__init__()

# Randomly choose left or right
deg = 0 if random.random() < 0.5 else 180
self.ship.move(SHIP_SPD, deg)

Next, add a flip_x() method to switch the movement direction (left/right).

This method multiplies the x-axis velocity vx by -1.

# sprite.py
# added to BaseSprite class

def flip_x(self):
    """Flip movement in the x direction"""
    self.vx *= -1

By reversing the sign of the x-axis velocity,

you can switch directions like this:

Right → Left
Left → Right

2. Handle Keyboard Input

Next, add a method to handle keyboard input.

Add a new method called control_ship() to the Game class.

Here, we use pyxel.btnp() to detect the exact moment a key is pressed.

By passing pyxel.KEY_SPACE as an argument,

we detect when the Space key is pressed.

# main.py
# added to Game class

def control_ship(self):
    """Action"""
    if pyxel.btnp(pyxel.KEY_SPACE):
        self.ship.flip_x()  # Reverse movement

Each time you press the Space key,

the player’s movement direction switches between left and right.

3. Screen Wrap (Overlap) Processing

Finally, add logic for when the character goes off the screen.

We compare the character’s position with the screen boundaries

and add an overlap_spr() method to detect when it leaves the screen.

If the character goes off-screen,

it reappears on the opposite side (left ↔ right, top ↔ bottom).

By using spr as an argument,

this method can be reused not only for the player

but also for future objects such as asteroids.

# main.py
# added to Game class

def overlap_spr(self, spr):
    """Move to the opposite side when leaving the screen"""
    if spr.x < -spr.w:
        spr.x = W
        return
    if W < spr.x:
        spr.x = -spr.w
        return
    if spr.y < -spr.h:
        spr.y = H
        return
    if H < spr.y:
        spr.y = -spr.h
        return

Complete Code

Below is the complete code implementing all the features covered so far.

# sprite.py
import pyxel
import math
import random

class BaseSprite:

    def __init__(self, x, y, w=8, h=8):
        """Constructor"""
        self.x = x
        self.y = y
        self.w = w
        self.h = h
        self.vx = 0
        self.vy = 0

    def update(self):
        """Update"""
        self.x += self.vx
        self.y += self.vy

    def draw(self):
        """Draw (implemented in subclasses)"""
        pass

    def move(self, spd, deg):
        """Move"""
        rad = deg * math.pi / 180
        self.vx = spd * math.cos(rad)  # x-axis velocity
        self.vy = spd * math.sin(rad)  # y-axis velocity

    def flip_x(self):
        """Flip movement in the x direction"""
        self.vx *= -1

class ShipSprite(BaseSprite):

    def __init__(self, x, y):
        """Constructor"""
        super().__init__(x, y)

    def draw(self):
        """Draw"""
        pyxel.blt(
            self.x, self.y, 0,
            0, 0,
            self.w, self.h, 0  # Ship
        )

# main.py
import pyxel
import math
import random
import sprite

W, H = 160, 120
SHIP_SPD = 1.4  # Player speed

# Game
class Game:
    def __init__(self):
        """Constructor"""

        # Initialize score
        self.score = 0

        # Initialize player
        self.ship = sprite.ShipSprite(W / 2, H - 40)

        # Randomly choose left or right
        deg = 0 if random.random() < 0.5 else 180
        self.ship.move(SHIP_SPD, deg)

        # Start Pyxel
        pyxel.init(W, H, title="Hello, Pyxel!!")
        pyxel.load("shooter.pyxres")
        pyxel.run(self.update, self.draw)

    def update(self):
        """Update"""

        # Update player
        self.ship.update()
        # Control player
        self.control_ship()
        # Screen wrap check
        self.overlap_spr(self.ship)

    def draw(self):
        """Draw"""
        pyxel.cls(0)

        # Draw score
        pyxel.text(
            10, 10,
            "SCORE:{:04}".format(self.score), 12
        )

        # Draw player
        self.ship.draw()

    def control_ship(self):
        """Action"""
        if pyxel.btnp(pyxel.KEY_SPACE):
            self.ship.flip_x()  # Reverse movement

    def overlap_spr(self, spr):
        """Move to the opposite side when leaving the screen"""
        if spr.x < -spr.w:
            spr.x = W
            return
        if W < spr.x:
            spr.x = -spr.w
            return
        if spr.y < -spr.h:
            spr.y = H
            return
        if H < spr.y:
            spr.y = -spr.h
            return

def main():
    """Main"""
    Game()

if __name__ == "__main__":
    main()

The result looks like this when you run the game.

Next Time...

Thank you for reading!

In the next chapter, we’ll cover “Let’s Spawn Asteroids.”

Stay tuned!