.Markku Reunanen.

• Blogi
• ¡Tequila!
• Tietotekniikka
• Projects
• Tietoja

PETSCII (Marq’s PETSCII Editor)

Welcome to the PETSCII page, where you can find out everything you ever wanted to know about the crossplatform PETSCII editor ingeniously called PETSCII. The tool lets you create character-based screens and animations for the Commodore 64, VIC-20, PET and Plus/4 computers. Enjoy!

News

• 3.11.2024: Plenty of various PETSCII works at Zoo 2024. Also check out Ventti’s expanded version of the editor!
• 11.8.2024: Pågadata PETSCIIS available
• 11.2.2024: Fjälldata PETSCIIs right here
• 10.10.2023: DART 1.2 released with support for creating dirart from .c and .pet files
• 28.9.2023: The editor turned 10 years old. There’s even cake!
• 29.7.2023: Vammala Party PETSCIIs here
• 3.6.2023: X PETSCII entries are starting to appear here
• 12.2.2023: Quality PETSCII art at Fjälldata.
• 31.10.2022: The page got a little update with clearer, up to date instructions.

Usage

It should be straightforward to download and unzip the package (see downloads below), after which you can run the version that corresponds to your operating system of choice: Linux, Mac or Windows. 32-bit binaries are still included, but you may encounter problems with old Windows or Mac OS versions – I can’t support and test each and every one of them.

Use the GUI buttons for saving your work. The native file format is a C array, which is why the file extension should be “.c”. In addition, the automatic backup will create a file called _backup_.c in the program directory every two minutes or so. The Ref. button will load a reference image (png/jpg/gif) that can either be overlaid with the characters or converted to PETSCII.

For showing the piece on a real machine you need to export the picture to a .prg file. At the moment animations can’t be exported as standalone executables. See the keyboard shortcuts below, and in the case of source code exports check the generated file for further instructions. Not all the export options are available for all the target platforms. Optionally, create a d64 image (c1541 is part of VICE):

c1541 -format mypic,0 d64 mypic.d64 -attach mypic.d64 -write image.prg image

There’s also a video tutorial on the basic functions of the editor. See here: https://www.scenesat.com/videoarchive/250b4ced-b90e-11ea-b68e-00505685775e?t=55337

Mouse Buttons

• left mouse button – draw, select pen color, select char from the selector
• middle mouse button – char picker, select border color from the selector
• right mouse button – eraser, select bg color from the selector, lock/unlock frame on timeline, toggle lowercase on char selector
• mouse wheel – darken or lighten the shade on the Plus/4

Editing Commands

• C – convert colors to Plus/4 after loading a C64 image (Plus/4 only, not necessary with recent files any more)
• enter – switch to typing mode, shift-enter for inverted chars
  • Alt (+shift) will let you type graphic characters like on a real machine
  • Color selection and reverse, likewise
  • Ins/Del/Backspace/PageUp/Dn/Home/End work
  • Window managers etc. might reserve some key combinations for their own purposes, so beware
• esc – exit from typing mode, remove selection
• f – floodfill (keep it pressed and click), shift-f fills color only
• h – smart horizontal flip, shift-h at cursor
• r – smart rotate clockwise, shift-r at cursor
• space – toggle selection on/off
• T – convert the reference image to PETSCII – set a suitable background color yourself first. If the reference image has changed, it’ll be reloaded.
• tab – walk through predefined sets of related characters
• u – undo
• U – redo
• up/down arrow – grow and shrink stick characters
• v – smart vertical flip, shift-v at cursor
• x – invert, shift-x inverts at cursor
• +/- – shift horizontal and vertical stick character one step up/down or right/left
• ,/. – cycle through bg and border colors
• § – pick character+color (same as mmb), shift-§ (° or ½) to pick color only

GUI Toggles

• c – toggle crosshair
• g – toggle grid
• i – toggle info display
• t – cycle through different levels of reference image transparency

Animation Related

• 1..0 – jump to frame 1..10
• d – duplicate frame to the left
• end – jump to last frame
• home – jump to first frame
• l – lock/unlock frame from editing
• left/right – jump one frame

Modifier Keys

• alt – 1/4 char pixel drawing mode (keep alt pressed)
• ctrl (command on Macs) – selection mode: drag with lmb pressed to select a region, rmb to select free-form areas, ctrl-a selects the whole image
• shift (left) – coloring mode, only the color is replaced (keep shift pressed)
• shift (right) – character-only mode

File Operations

• a – export file as asm data
• A – export file as self-contained asm viewer (ACME format)
• b – export as self-contained BASIC viewer
• e – export a self-contained PRG that can be run directly
• E – export a .pet file
• p – export all frames as PNG images, shift-p includes borders. Note that the clickable button only exports the current frame with borders.
• q – export as SEQ (C-64 only)
• s – save (plain C data, the default image format)
• S – export as self-contained C viewer (cc65 format)

Cheat Sheet

Forgot some keys? Of course you did – even I don’t remember them all. Print out this handy cheat sheet to support your failing memory:

On Macs use the Command key instead of Ctrl.

Settings

You can control some general settings with a file called prefs.txt which should be in the same directory as the actual program. So far the following settings are recognized:

• ZOOM – editor pixel size. 2 by default. 1 is the minimum and anything beyond 3 might be rather unusable.
• FRAMERATE – update rate. 60 fps by default. Decrement for less CPU use, increment for better responsiveness. Going above the screen refresh rate might be impossible depending on the platform and system settings.
• MACHINE – one of C64, VIC20, PET, PETHI, PLUS4, DIRART. Leave empty to get the normal selector at start.
• ASPECT – aspect ratio on the machines where it counts. One of PAL/NTSC/SQUARE. If not set, default to PAL.
• PATH – default path for your images. Give a full path like /home/marq/Pictures. No quotation marks.
• BACKUPFILE – the name and optionally the full path of the backup file. If empty, defaults to the application folder and _backup_.c
• OFFSET – 0 or 1 to show canvas memory offsets.
• XSIZE and YSIZE – set a nonstandard canvas size.
• UNDODEPTH – Increase or decrease the amount of undo steps, 32 by default.
• TABLET – 1 to use the experimental tablet mode which makes it easier to click UI buttons when using a touchscreen. 0 for normal operation (default).
• FORCEMETAL – 1 to revert to the Metal UI style regardless of the platform default
• AWTSELECTOR – 1 to use AWT’s fileselector, 0 to use Swing. Leave empty to use the platform-specific default.
• DISABLEWHEEL – 1 to disable mouse wheel functionality in case it bugs you
• CONVERTER – command to run when exporting multiple frames (mostly meant for animated gifs). With ImageMagick use something like this: convert -delay 20 -loop 0 -scale 200%

Assign a new value like this: ZOOM=2. Note that on recent versions of macOS the prefs file might need to be in your home folder, e.g. /Users/marq.

There are some simple command line parameters as well. The parameters override prefs.txt.

• -c64, -vic20, -pet and so on will let you skip the initial dialog
• -zoom x sets, eh, the zoom
• -size x y for non-standard canvas sizes

Protips

• The selection can be used in several ways: it can be rotated, flipped, or even used for coloring regions (try pressing shift).
• Rotation, flipping, inverting etc. affect the character under the cursor when shift is pressed.
• The image -> PETSCII conversion depends on the selected background color, so experiment with multiple options. Three grayscale levels in the source image with bg color set as middle gray seems to work pretty well for photos.
• As of the latest versions, you can make converting much faster and iterative, as the reference image is reloaded if its timestamp has changed.
• You can reconvert existing images back to PETSCII as long as the palette is close enough and the dimensions match (320×200 and no borders for C64).
• PETSCII uses these C64 color values by Pepto, so do the same when working with external programs to ensure a faithful conversion. See m_c64.pde, m_vic20.pde and m_plus4.pde for the RGB values.
• Shift-mmb will pick just the color instead of character+color
• Select a pen color and ctrl-click another color on the selector to remap all the chars of the same color. If there’s a selection, only it will be affected.
• You can delete chars from a selection by clicking the char selector. It’ll leave you holes that don’t affect drawing – useful for example for cutting out “sprites”.
• Want to make animated gifs? Install ImageMagick command line tools, export as png (press p or P) and then simply:
  convert -resize 200% -loop 0 -delay 10 frames*.png animation.gif
• There are only a few flicker colors that are steady in large quantities. Don’t use a flicker color for the border or even the bg, small details work better.
• For making some actual use of the dirart mode, try DART.

Troubleshooting

Trying to create a reliable crossplatform application in Java is tricky business these days. If all else fails I recommend downloading the source-only version and running it straight from Processing version 3.x. Bug reports can be sent to marq [at] iki [dot] fi or alternatively on CSDb.

• Apple’s so-called security won’t let you run unsigned apps. To make a long story short: go to System Preferences – Security & Privacy and allow apps downloaded from anywhere to run.
• Middle mouse button might not work on all Macs. Use the § key instead to pick a character from the canvas, if your keyboard has one. Border color can be selected by pressing the dot key.
• With all these Mac woes (and there’s probably more to come) you migth even consider running the editor inside a Linux/Windows virtual machine.
• Can’t draw and there’s an asterisk (*) next to the frame number? You’ve locked the frame. Press l or right click on the thumbnail (if any).
• File selector bugs – try setting AWTSELECTOR to 0 or 1. 0 will possibly fix a crashing bug on Linux.
• Some recent Ubuntu-based distros might complain that they Failed to load module “canberra-gtk-module”. The warning appears to be harmless, but if it bugs you, install the missing package libcanberra-gtk-module using apt or whatever package manager you prefer.
• Missed mouse clicks with Lenovo TrackPoint or mouse pad? Try fiddling with the typing delay/sensitivity setting.

Download

The compiled binaries + stable source are available right here: http://www.kameli.net/~marq/kode/petscii.zip. Note that you need to have the Java Runtime Environment installed on your system. I’m using JRE 1.8 (Java 8) myself, so that’s probably your safest bet. The tried and tested 2019 (Processing 2) version, not yet much worse featurewise, is still available here for a while in case you have trouble with the latest one or only have an old version of the JRE available.

WIP source-only release for the adventurous: http://www.kameli.net/~marq/kode/petscii-beta.zip or svn://kameli.net/marq/petscii. Revision 872 in the SVN repository is the last one that works on Processing 2. The code can be used according to the terms of the liberal WTFPL license.

Gallery

Some artistic endeavours to give you a glimpse of what’s possible.

In addition to still images there are demos and games where the editor has been put into good use.

• 2 Fingers, Advanced Pet Dragons, Fort Django, Digiloi, Nine Rings, Petmanbatman and The Last Z-8 by Dr. TerrorZ
• Abre los ojos, Bionary, Ignition, Party Bus, Pets at Zoo, Thermonuclear War and We Are Computers by oobc
• Aerial Core, Smoke on the C64 and Skybox by Extend
• Aerodementic and Pikku Kuusnelonen by Wrenchotron
• Alien Finale by Proxima
• Alien Trailer, Sliced Blue, Awakening Computer – Alien Opening Scene, Broken Record, Petscroll, What Is Special Order #937?, Halloween the 40th Anniversary Celebration Demo, Space Invaders, The Crack in the Cosmic Egg, H.E.R.O. Animated PETSCII Loading Screen, Zeroid Bounce, Cowboynessness and Hokuto Forcer by Hokuto Force
• Beisikki  demo, C-visa 2016, The First Ball, Rock joka tiesi… liikaa!, Nothing but PET SKI and Cosmic Bakery by Fit (& Friends)
• Feelgood and Innerverse by Gorbat Soft
• Je t’aime mon monstre and Lovecats by Atlantis
• Megapetscii by Hackers
• MerryXmas and Nothing But PETSCII by Genesis Project
• On Fire Intro by Fairlight
• PETSCII Intro by Atlantis and F4CG
• PETSCII Reader for Sinclair Spectrum by Carlosanta
• Shareware by Dekadence
• Shine Logo Collection II by Arsenic & Delysid
• Shock by Electric & Vent
• Star Wars PETSCII by Debris & Deetsay
• Tales of Edoras and Lycan by The Solution

Additions and corrections most welcome, as usual.

Acknowledgements

Thanks to Dr. TerrorZ for his artworks, numerous comments and remap tables, Viznut for help with the VIC-20, Six for the SEQ conversion example, BassCadet for bug reports, Groepaz and Deekay for help with dirart, and Rexbeng, Manu, Shine, Electric, Archmage, Hammerfist, Awsm, Redcrab and iLKke for gallery images.