Contributing a Core to MiSTer FPGA - MiSTer-devel/Wiki_MiSTer GitHub Wiki

MiSTer is an open project and welcomes developers who want to contribute new cores. MiSTer-devel is one of the many repos of MiSTer cores supported by updaters. This document is to help folks get their cores ready for submission to MiSTer-devel specifically. Other repos may have other guidelines.

If you wish to have your core considered for inclusion in MiSTer-devel, please ensure that it adheres to the following:

1. Your code needs to be published under a compatible open source license like GPLv3 or MIT

2. Follow the standard repository structure described in the MiSTer core template:

   • sys/ — MiSTer framework files
   • rtl/ — Core implementation files
   • releases/ — Binary releases and MRA files

   Include the standard .qpf, .qsf, .srf, .sdc, .sv, files.qip, clean.bat and .gitignore files required by the template. See its README.md for details.

3. Your code should not rely on custom edits to framework files in the sys folder. Repo admins should be able to maintain your core by dropping in a fresh sys folder and building an updated binary.

4. Follow the MiSTer development principles and coding guidelines, and consult the additional core-development resources listed under Development in the wiki sidebar.

5. Add at least one fully functional compiled release to the releases/ folder using this format:

   <core_name>_YYYYMMDD.rbf

   For arcade cores, use:

   Arcade-<core_name>_YYYYMMDD.rbf

6. Arcade cores must also include MRA files in the releases/ folder, and all included games must be fully playable.

   Each MRA must comply with the MRA specification and include:

   <rbf>{core_name}</rbf>

   Place only one primary MRA per game directly under releases/.

   Alternative MRAs may be placed under:

   releases/_alternatives/_<game_name>/<version_name>.mra

   The MRA paths must not conflict with any existing MRA files on the platform.

Once your repo is ready, and your code is properly tested, send a link to your repo to [email protected]. A MiSTer-devel member will reach out once they have a chance to review the repo.

These are much more nebulous than the guidelines above, but will hopefully give you an idea as to what we are looking for when we review a core submission.

• Does the code follow the guidelines above?: This one is obvious, but it should be listed here as it is the first part of the process. One thing to dispel, however, is the idea that if you don't follow one of the guidelines you are automatically disqualified. One of the reasons for review is to give feedback and, if we see that you missed a guideline, we will include it in a list of fixes. It's the refusal to follow the guidelines that will disqualify you.

• Does the developer understand their code?: In this brave new future of AI, a lot of folks are making cores by prompting their favorite LLM to do it, and have little interaction with the process. There is nothing wrong with this, and we don't want folks to feel discouraged. There is something very cool about watching a core come to life, even if your interaction with the bring up is minimal. With that said, if you're submitting to MiSTer-devel, you should understand your code as it is core to the next bullet point.

• Is the developer willing to maintain their code?: Part of being in MiSTer-devel is a commitment to MiSTer users that you intend to maintain your core and code. Fixing bugs, responding to issues, adding features - these are all a part of being a developer on an open source project. Reviewers will be less inclined to believe that this is something you're interested in doing if you are too busy developing your next core.

• Does the developer collaborate well with others?: This is one that is more likely to be disproven than it is proven, but it is a consideration. MiSTer is an open source project, and collaboration is at the forefront of it. If folks show that they cannot be collaborative, then they will be disqualified from MiSTer-devel consideration.

Once your code is reviewed, you'll get an email back with the decision and next steps.

This varies from core to core, but it can take upwards of a month in some situations. Folks doing the reviewing are doing so with their free time, and the number of submissions has been very high. We are doing the best we can. :)

Absolutely not. In fact, if your goal is to get into update_all, MiSTer-devel is just one of the different paths. But, because update_all is its own entity outside of the official MiSTer project, it can include unaffiliated repos like JTCores and Coin-Op Collection. If your primary goal is to be included in update_all, there are other options beyond MiSTer-devel:

• You can reach out to Jotego and see if he has interest in collaborating.
• You can reach out to Coin-Op Collection and see if they have interest in collaborating.
• You can reach out to theypsilon to see if he has interest in collaborating.

And if you prefer not to follow any of the previous paths and don't mind sharing a minimal setup for your users to get updates, consider sharing a drop-in database file:

• You can clone the Custom Database Repo, follow the instructions there, and distribute a downloader_[repo-name].ini file. If a user puts that file in their /media/fat folder, update and update_all will automatically download your cores whenever they're run.

Not at all. There is quite a bit of AI-Assisted code in mister-devel already. We are totally fine with developers using AI to do some of the heavy lifting of core development. Again, as long as a developer understands their code, how they manifested that code is of little consequence.

This is ignoring the larger structural and political impact of AI on the world, but that isn't something that should be litigated here.