Contributing

Contributing

The canonical version of this page is CONTRIBUTING.md in the repository.

Setup

git clone https://github.com/magmacrunchmedia/texastoast.git
cd texastoast
pip install -e ".[dev,sprites]"

Add hardware only if you need to talk to a physical bus — it pulls in smbus2, which is Linux-only. You do not need it to work on the I2C layer: since 0.4.0 that work is done against SimBus, which runs the real bus, protocol and hub code on any platform. Without smbus2 and without a simulator, I2CBus falls back to mock mode, where reads simply report failure.

Tests

pytest                            # 161 tests
pytest tests/test_collision.py -v

Some tests drive a real tkinter canvas: the renderer, the game loop, Game lifecycle, the tile editor, the UI widgets against a live canvas, protocol conformance, and the controller bench. They skip themselves when no display is available, so a green run on a headless box does not mean they passed. CI runs them under xvfb on Linux with TEXASTOAST_REQUIRE_TK=1, which turns a missing display into a hard failure rather than a silent skip.

Everything else — including every hardware path — runs headless with no I2C. That is the point of the bus-level simulator: tests/test_sim.py, test_poller.py and test_recording.py exercise the real protocol code with nothing attached.

If you see invalid command name "tcl_findLibrary", something created a second Tk root after destroying the first. The suite shares one root for exactly this reason — use the tk_root fixture rather than making your own.

Lint

ruff check .
ruff check . --fix

CI fails on any finding.

Conventions

• Rates are per second. Speeds and velocities are pixels per second, and anything taking a per-frame step takes dt explicitly.
• Failure is not data. An error that means "the hardware is not there" must be distinguishable from valid zero data. Return None; never fabricate a zero buffer.
• Regressions get tests. A bug fix comes with a test that fails against the old behavior, and a comment saying what used to go wrong. There are plenty of examples in tests/ to copy the style from.
• Docs get run. Code in the README or this wiki should be executed before it ships, not eyeballed. Several long-standing bugs were only found by running the documented examples.
• Hardware paths are testable without hardware. Test them through SimBus, which exercises the real bus, protocol and hub code. Do not add a test that needs a physical hub — the Pi checklist in Hardware Dev Kit is the manual gate for that.
• texastoast/devtools/ imports tkinter inside functions only, never at module import time. It ships in the wheel, and the package has to stay importable on a headless system.

Where things live

Path	Contents
texastoast/core/	Game, GameLoop, Config
texastoast/world/	TileMap, Entity, collision
texastoast/render/	CanvasRenderer, Camera, SpriteSheet, the Renderer/UISurface protocols
texastoast/input/	InputState, KeyboardInput, composite input, recording and replay
texastoast/i2c/	I2CBus, MagmaHub, protocol constants, the simulator, the background poller
texastoast/ui/	DialogueBox, Menu, HUD
texastoast/devtools/	Controller bench — shipped in the wheel as texastoast-bench
tools/	Tile editor, controller-bench shim (not shipped in the wheel)
examples/	Runnable demos (not shipped in the wheel)

devtools/ is inside the package on purpose: tools/ goes into the sdist only, and a Pi installing from a wheel still needs the bench.