Farama-FoundationFarama-Foundation/stable-retro/.github/copilot-instructions.md

stable-retro

Copilot instructions1.1k starsChanged 3 months agoMITView on GitHub

Stable Retro is an actively developed Gymnasium-compatible fork of OpenAI Gym Retro. It combines a Python API, a C++14 extension, and vendored libretro emulator cores.

Installs packages

Jun 8, 2024Building manylinux wheels — NetHack-LE/nle2 reactions · 31 comments
Apr 8, 2026Survey candidate RL environment suites not yet covered by EnvPool — sail-sg/envpool1 reaction · 3 comments
Aug 16, 2023Loading a state resets the game — libretro/parallel-n641 reaction
Aug 3, 2026Move packaging setup to pyproject.toml, integrate requirements.txt as an extra — DLR-RM/rl-baselines3-zoo0 reactions · 8 comments
Dec 13, 2025Investigate how Stable Retro works and verify if it can run emulator games — Fernando-crz/Bomberman-RL0 reactions

5 more on GitHub

Feb 25, 2025stable-retro support — dvalenciar/ReinforceUI-Studio0 reactions · 3 comments
Dec 12, 2023Integrate Mario Kart into stable-retro — arvganesh/super-mario-kart-ppo0 reactions
Aug 23, 2023broken-link-checker seems to return a false negative — stevenvachon/broken-link-checker0 reactions
Jul 25, 2023Integrating n64 into stable-retro — bzier/gym-mupen64plus0 reactions · 1 comment
Jul 24, 2023Checklist for Maturity — Farama-Foundation/MiniWoB-plusplus0 reactions

Where files are headingNew Copilot instructions files have more rules about branches and pull requests, and fewer about code style.
Of the Copilot instructions files we read, the 2,336 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repositoryOne other file it gives its agents.
- add-emulator-platformSkill

The file

We split this copilot-instructions.md into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Start with the narrowest relevant test, then run the full command required by the changed boundary.
line 29
Distinctive:
Keep changes focused and preserve existing public APIs unless the task explicitly changes one.
line 33
Distinctive:
Do not commit generated CMake files, compiled objects, core shared libraries, or version-stamp files.
line 34
Distinctive:
Do not add copyrighted commercial ROMs.
line 35

≈ “Common” is an estimate: at least 1 in 5 of the 3,779 Copilot instructions files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

copilot-instructions.md

Stable Retro Repository Instructions

Stable Retro is an actively developed Gymnasium-compatible fork of OpenAI Gym Retro. It combines a Python API, a C++14 extension, and vendored libretro emulator cores.

Repository map

stable_retro/ is the primary Python package. retro/ is a compatibility shim; keep both import paths working.
src/ contains the native runtime, pybind11 bindings, and optional Qt integration UI.
cores/<platform>/ contains vendored emulator source. Avoid broad cleanup or formatting there.
cores/*.json contains the source platform manifests consumed by src/coreinfo.cpp.
stable_retro/cores/ contains generated build outputs. Do not edit its JSON, version stamps, or shared libraries directly.
tests/test_python/ contains Python tests. tests/*.cpp contains native tests and small test ROM fixtures are under tests/roms/.
docs/ is the Sphinx documentation source.

Environment and build

Supported Python versions are 3.11 through 3.14. Do not require a newer Python runtime.
On Debian/Ubuntu, install cmake capnproto zlib1g-dev build-essential pkg-config libzip-dev libbz2-dev xvfb python3-opengl libgl1-mesa-dev libglu1-mesa-dev.
Install the package and development tools with python -m pip install -e '.[dev]'.
The tested native workflow uses an in-source CMake build because native tests resolve cores and ROM fixtures relative to the source tree.
Pass optional native settings through STABLE_RETRO_CMAKE_ARGS or CMAKE_ARGS, for example CMAKE_ARGS='-DBUILD_N64=OFF' python -m pip install -e ..

Validation

Python-only changes: run scripts/test-python.sh, optionally followed by a specific test path.
C++, CMake, core, or binding changes: run CMAKE_BUILD_PARALLEL_LEVEL=2 scripts/test-cpp.sh.
Formatting and repository checks: run python -m pre_commit run --files <changed-files>. Use --all-files before a broad pull request.
Documentation changes: install docs/requirements.txt, then run sphinx-build -b dirhtml -v docs _build.
Start with the narrowest relevant test, then run the full command required by the changed boundary.

Change rules

Keep changes focused and preserve existing public APIs unless the task explicitly changes one.
Do not commit generated CMake files, compiled objects, core shared libraries, or version-stamp files.
Do not add copyrighted commercial ROMs. Only use redistributable fixtures with clear provenance.
A new emulator platform normally requires a vendored libretro core, cores/<platform>.json, an add_core entry in CMakeLists.txt, packaging updates in setup.py, emulator smoke coverage, and documentation updates.
Core-specific runtime options belong in src/emulator.cpp. Add only options needed for deterministic headless execution, serialization, input, or rendering.
Work with existing uncommitted changes. Never clean or revert unrelated files as part of a task.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free