Pixel Runner

Clear Code’s Pygame endless runner, with Timer signals, flipbook sprites and synthesised audio.

▶ Run in browser

Upstream: https://github.com/clear-code-projects/UltimatePygameIntro

Licence: this port's own code is offered under MIT, not the SimVX Examples Licence the rest of the gallery carries. See ATTRIBUTION.md for the upstream it re-implements, the terms of anything it bundles, and the credit each one requires.

Ports live in the repository only, not in the simvx-examples distribution, because each is a derivative work licensed individually against the game it re-implements. Read it with git clone https://git.simvx.com/simvx/simvx.

Tags: port tier-0

Pixel Runner: SimVX Port

Faithful port of Clear Code’s Ultimate Pygame Intro endless runner to SimVX.

What it demonstrates

The whole game is one root node (nodes/runner.py) holding two states, the title screen and the run, exactly as the upstream tutorial does. Along the way it shows how the pygame idioms the tutorial teaches map onto engine features:

Pygame	SimVX
while True: + pygame.event.get()	on_update(dt) + Input.is_action_just_pressed
pygame.sprite.Group + .update()	child nodes + tree.group("obstacles")
pygame.time.set_timer(USEREVENT)	a Timer child node and its timeout signal
swapping self.image every frame	AnimatedSprite2D.from_frames (one strip atlas flipbook)
screen.blit(sky_surface, (0, 0))	Sprite2D background nodes
screen.blit(score_surf, ...)	Text2D labels with align="centre"
pygame.sprite.spritecollide	Rect2.intersects between node rects
pygame.mixer.Sound("audio/jump.mp3")	AudioPlayer over a synthesised AudioClip
a fixed 800x400 surface	layout driven by the tree’s screen_resized signal

Run

uv run python examples/ports/ultimate_pygame_intro/main.py           # interactive
uv run python examples/ports/ultimate_pygame_intro/main.py --test    # headless capture

Controls

Key	Action
SPACE / ↑ / W / left click (tap)	Jump
SPACE / Enter / left click (tap)	Start / restart after death
Esc	Quit

Web export

uv run simvx export web examples/ports/ultimate_pygame_intro/main.py -o /tmp/pixel_runner.html

Asset licence

No upstream assets are bundled (the upstream repository declares no licence). Character and enemy sprites and the ground tiles are from Kenney’s CC0 Platformer Art Complete Pack (https://kenney.nl / https://opengameart.org/content/platformer-art-complete-pack-often-updated), resized to the original port geometry. The sky is generated, and all audio is synthesised at load time (nodes/audio.py): the music loop through the engine’s AudioSynth, the jump chirp as a swept sine fed to AudioClip.from_pcm. See ATTRIBUTION.md and LICENSE (MIT).

Source files

File	Summary	Lines
main.py	Pixel Runner: Clear Code’s Pygame endless runner, with Timer signals, flipbook sprites and synthesised audio.	60
__init__.py	Pixel Runner: SimVX port package.	1
nodes/__init__.py	Pixel Runner port: node modules.	1
nodes/assets.py	Where the port’s bundled art lives.	10
nodes/audio.py	Procedural audio: built on the engine’s AudioSynth API.	103
nodes/obstacle.py	Obstacle nodes: replaces Pygame Obstacle(sprite.Sprite) for fly + snail.	80
nodes/player.py	Player node: replaces Pygame Player(sprite.Sprite).	137
nodes/runner.py	Pixel Runner: root scene replacing the pygame runner_video.py while loop.	293

Source

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.14"
# dependencies = ["simvx-core", "simvx-graphics", "numpy", "pillow"]
# ///
"""Pixel Runner: Clear Code's Pygame endless runner, with Timer signals, flipbook sprites and synthesised audio.

# /// simvx
# tags = ["port", "tier-0"]
# upstream = "https://github.com/clear-code-projects/UltimatePygameIntro"
# web = { width = 800, height = 400, responsive = true }
# ///

Run::

    uv run python examples/ports/ultimate_pygame_intro/main.py
    uv run python examples/ports/ultimate_pygame_intro/main.py --test   # headless capture

Web export::

    uv run simvx export web examples/ports/ultimate_pygame_intro/main.py -o /tmp/pixel_runner.html
"""

import os
import sys

# Allow running this file directly via ``python main.py``: make the package
# importable by adding its parent directory to sys.path.
_HERE = os.path.abspath(os.path.dirname(__file__))
if _HERE not in sys.path:
    sys.path.insert(0, _HERE)

from nodes.runner import Runner  # noqa: E402

from simvx.graphics import App  # noqa: E402

WIDTH, HEIGHT = 800, 400


def main():
    if "--test" in sys.argv:
        from pathlib import Path

        from simvx.graphics import save_png

        capture_at = [30, 60, 120]
        app = App(title="Pixel Runner", width=WIDTH, height=HEIGHT, visible=False)
        frames = app.run_headless(Runner(), frames=130, capture_frames=capture_at)
        out_dir = Path(_HERE) / "screenshots"
        out_dir.mkdir(exist_ok=True)
        for idx, img in zip(capture_at, frames, strict=False):
            out_path = out_dir / f"frame_{idx}.png"
            save_png(img, out_path)
            print(f"saved {out_path}")
    else:
        App(title="Pixel Runner", width=WIDTH, height=HEIGHT).run(Runner())


if __name__ == "__main__":
    main()