Parrot Cart developersGet a Parrot Cart

What your release needs

Three things are required. The rest are optional.

PartWhat it is
The .CVPRequiredYour plugin, built with the SDK. Its image can be up to 2 MB less 4K.
READMERequiredIt goes inside the .CVP so the cart can show it. The SDK puts your README.md there for you.
LICENSERequiredYour public repo needs a LICENSE file at the release’s tag.
Release notesOptionalThe text of your GitHub release. We show it for each version.
ScreenshotsOptionalUp to three PNGs, each 256 × 192, attached to your release.
Two iconsOptionalTwo 8 × 8 one-color icons, one for the plugin and one for the files it opens.

One README for the web and the TV

Write README.md once. It shows on your plugin’s page here, and the SDK adds it to the .CVP for the cart.

The starter kit has this as docs/readme-spec.md.

Back to the top

A README on the cart30 × 19

What to write

People read it on the TV, often with no computer nearby.

  • What it does

    Start with a line or two about what it does. The cart shows 19 lines at a time.

  • How to use it

    List the controls, and say which folder the files go in.

  • Credits

    Under a Credits heading, say whose work it uses. This part is required.

  • Source

    Add a line with the word “source” and a link to your code. This part is required too.

How the SDK converts it

It happens each time you build your plugin.

MarkdownOn the cart
A headingIt’s shown in capitals, with a blank line before and after.
A paragraphIt’s wrapped to 30 characters.
A listEach item starts with - or 1., and wrapped lines are indented under the first word.
A linkYou get the text, then the URL. A long URL goes on a line by itself.
CodeInline code stays as plain text. A code block stays as it is, but each line is cut at 30 characters.
Bold and italicsThey’re dropped, since the cart only has one style of text.
An imageIt shows up as [image: alt].
A tableEach cell becomes a header: value line, row by row.
Raw HTMLThe tags are dropped, but the text inside them stays.
Non-ASCII charactersCurly quotes, dashes and accented letters become plain look-alikes. Anything else becomes ?.
cvcart_plugin(sweeper ID author.sweeper NAME "Star Sweeper" VERSION 1.0.0
               README README.md)

python3 cvreadme.py README.md    # prints what the cart will show

Both come with the starter kit. If the text is over 16384 bytes, the SDK cuts it at the end of a line and adds a last line that says so.

The format in the .CVP

You only need this if you build a .CVP without the SDK.

WhereTypeWhat
Offset 280u32, little-endianWhere the text starts, counted from the start of the file. A 0 means there’s no README.
Offset 284u32, little-endianThe length of the text in bytes, up to 16384.
The textAfter the imageIt can only hold printable ASCII (0x20 to 0x7E) and line feeds. No line can be over 30 characters, and the last line ends with a line feed.
SHA-256UnchangedThe image’s hash doesn’t include the README. Changing the README won’t make the cart copy the plugin again.

What we check

We never change your text. Your page shows it exactly as it is in the .CVP.

CheckRuleIf it fails
In boundsThe text starts after the image and ends inside the file.We can’t list it.
LengthUp to 16384 bytes.We can’t list it.
CharactersOnly 0x20 to 0x7E and line feeds, with no tabs or carriage returns.We can’t list it.
WidthUp to 30 characters per line.We can’t list it.
No README at allBoth fields are 0. Plugins built before the README existed look like this.We list it, with a note on its page.

On your plugin’s page

We show the README.md from your release’s tag, with GitHub’s Markdown formatting.

PartWhat happens
ShownHeadings, lists, task lists, tables, code, quotes and links.
ImagesThey show up as links, because the plugins site doesn’t load anything from other sites.
Raw HTMLIt’s dropped, along with any scripts or styles, but the text stays.
LinksOnly https links work. Relative links point to your repo at the release’s tag.
SizeIt can be up to 64 KB. If it’s bigger, we link to it instead.

Screenshots at the console’s real size

Attach up to three PNGs to your release, each 256 × 192.

The starter kit has this as docs/screenshots.md.

Back to the top

A 256 by 192 picture in the TV frame, from Hello
Send the picture only. We add the TV frame.256 × 192

Requirements

The console’s picture is 256 × 192 pixels.

Rule
How manyUp to three.
FormatA PNG, not animated.
SizeExactly 256 × 192 pixels, with no border, scaling or filters.
File sizeUp to 100 KB each. A real screen is usually only a few KB.
Namesscreenshot-1.png, screenshot-2.png and screenshot-3.png, in lowercase.
WhereAttach them to your GitHub release, next to the .CVP.

What to show

  • The plugin itself

    Show the plugin’s screens, starting with the one people see most.

  • Nothing you can’t share

    For an emulator, show homebrew or your own test files instead of a commercial game.

  • One set per release

    If a release has several .CVP files, they share the screenshots.

How to take one

Use any ColecoVision emulator that can save the picture at its real size.

  • Save at 1x

    Turn off scaling, filters and scanlines.

  • Crop the border

    If the file is bigger than 256 × 192, it includes the border. Crop it out.

  • Save an indexed PNG

    The console only has 15 colors, so an indexed PNG is exact and small.

Screenshots we can’t use

We can’t list your plugin until every screenshot is right. We’ll tell you which one has a problem and why.

ProblemFor example
The wrong size640 × 480, 280 × 216 with the border, or a photo of the TV.
Not a PNGA renamed JPEG, a broken upload or an animated PNG.
Over 100 KBIt was usually scaled up, or saved in full color from a photo.
A fourth screenshotscreenshot-4.png or higher.

Where they show up

They show up in these places once your plugin is listed.

PlaceHow
Your plugin’s pageEach one sits in a TV frame, scaled up without blur.
The plugin listThe first one shows as a thumbnail.
registry.jsonIt links to each one, for apps that install plugins.

Two 8 × 8 icons

You need one for the plugin and one for the files it opens. Each pixel is on or off, and the menu sets the color.

The starter kit has this as docs/icons.md.

Back to the top

Plugin icons in the Plugin Manager/PLUGINS

What an icon is

Both icons together take 16 bytes of the .CVP’s header.

Rule
Size8 × 8 pixels. Each pixel is on or off.
The plugin’s icon8 bytes at header offset 264. It shows next to the plugin in Apps, in its group on Home, in the Plugin Manager and in Open with. A plugin that only opens files shows it in Open with, and the plug everywhere else.
The file icon8 bytes at header offset 272. It shows next to each file the plugin opens.
One byte per rowThe top row comes first. Bit 7 is the left pixel.
ColorThe menu sets it. Plugin icons are magenta and file icons are light green. The background is black, or dark blue on the selected row.
All zerosThat means no icon. The menu shows its window icon for a plugin that starts on its own, the plug in Open with, and the plain file icon for a file.
Per screenA page that lists plugins shows up to 22 different plugin icons, and Open with up to 7. A folder shows up to 6 different file icons. Any more get the menu’s icons.

Start from a file

Download one and change it, or pick a ready-made icon. They’re free to use in any plugin.

A blank icon. Eight lines of dots, ready for your drawing.
Download icon-template.txt
A sample plugin icon. Pad Test’s, as the SDK reads it.
Download sample-icon.txt
A sample file icon. For the files your plugin opens.
Download sample-file-icon.txt

The .txt file the SDK reads

It’s eight lines of eight characters. A # is a pixel and a . is empty.

padtest_icon.txt

..####..
.#....#.
#..##..#
#......#
#..##..#
#..##..#
.#....#.
..####..

In the header

3c 42 99 81 99 99 42 3c

The SDK ignores blank lines and spaces around a line. Anything else stops the build.

cvcart_plugin(padtest ID author.padtest NAME "Pad Test" VERSION 1.0.0
               ICON padtest_icon.txt FILE_ICON padtest_file_icon.txt)

mkcvp.py IN.uf2 OUT.cvp ... --icon padtest_icon.txt --file-icon padtest_file_icon.txt

Tips for a clear icon

Menu rows touch, so there’s no gap between one icon and the next.

A folder
A ROM
A plugin’s file with no icon
A plugin with no icon
Pad Test’s icon
  • Leave an edge clear

    The menu’s icons leave the top row, the bottom row and the right column empty, so they don’t run into each other or into the name beside them.

  • Use solid shapes

    There’s only one color, so the outline does the work. Solid shapes look better than thin lines on a TV.

  • Check it on the selected row

    The selected row is dark blue. The editor shows both backgrounds.

Check your plugin before you release it

Clone the plugins site’s repo and run this command. It shows your plugin’s details, your README and any problem that would keep it from loading on the cart.

python3 tools/cvp.py YOURPLUGIN.CVP