Editor setup (VS Code / Pylance)

Autocomplete and type checking for picogame games on your PC — two things to wire up, because a picogame program uses two kinds of modules:

1. The picogame_* helper libraries are plain Python. Pylance resolves them from python.analysis.extraPaths — but it must point at a folder with the .py sources, e.g. a clone of picogame-libs — not at the board’s /lib, which holds .mpy bytecode Pylance can’t read.
2. The native modules (picogame — the C engine — plus CircuitPython’s board, displayio, synthio, …) have no Python source, so they need stubs:
   • pip install circuitpython-stubs covers every upstream CircuitPython module;
   • picogame itself isn’t upstream yet, so its stub ships separately as picogame-stubs — a wheel attached to every picogame-libs release (generated from the engine’s own docstrings, the same source as the reference).

Setup

git clone https://github.com/MakerClassCZ/picogame-libs ~/picogame-libs
pip install circuitpython-stubs
pip install https://github.com/MakerClassCZ/picogame-libs/releases/latest/download/picogame_stubs-latest-py3-none-any.whl

(or, from the repo: pip install "git+https://github.com/MakerClassCZ/picogame-libs#subdirectory=stubs")

.vscode/settings.json in your game folder:

{
  "python.analysis.extraPaths": ["~/picogame-libs"],
  "python.analysis.typeCheckingMode": "basic",
  "python.analysis.diagnosticSeverityOverrides": { "reportMissingModuleSource": "none" }
}

That last line matters: picogame-stubs is a stub-only package (there is no picogame.py — the module lives in the firmware), so Pylance completes pg.Sprite and pg.rgb565 from the stub but still marks the import picogame line with “could not be resolved from source”. It is a warning about missing runtime source, not about missing types; the override hides it. The same applies to board, displayio and the rest of circuitpython-stubs.

Then import picogame as pg completes pg.Sprite, pg.Scene, pg.rgb565(...) with signatures and docstrings, import picogame_input resolves, and a typo like sprite.frmae is flagged.

Without pip

If you’d rather drop the stub in by hand, mind where the path points — the folder that must sit on the search path is picogame-stubs itself (the PEP 561 <module>-stubs convention), so:

• "python.analysis.extraPaths": [".../stubs"] — the folder containing picogame-stubs/. ✅
• "python.analysis.extraPaths": [".../stubs/picogame-stubs"] — pointing inside it. ❌ import picogame stays unresolved (picogame-stubs isn’t a module name).

The other manual option is VS Code’s default stub folder: copy the .pyi to typings/picogame/__init__.pyi in your workspace — Pylance picks that up with no settings at all.

Pyright / mypy users: the same stubs work (pyrightconfig.json → extraPaths, or install the wheel into the environment Pyright analyses).

Where the stub comes from

picogame-stubs/__init__.pyi is generated by CircuitPython’s tools/extract_pyi.py from the //| docstrings in shared-bindings/picogame — the same text the docs and the firmware’s help() carry, so the stub can’t drift from the engine. To regenerate against a firmware tree: stubs/regen.sh /path/to/circuitpython in the picogame-libs repo.