Welcome to the PETSCII page, where you can find out everything you ever wanted to know about the 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!
- 12.12.2016: One more intro added to the list.
- 30.10.2016: Nice works released this weekend at X’2016. Proud to notice that all of them using my tool, too 🙂
- 13.8.2016: Some rotation in the gallery. Added Zelda PETSCII by Awsm.
- 23.7.2016: Added some demos and games to the gallery.
- 22.7.2016: Please note that latest versions and changelogs are available here only. CSDb hosts some ancient version that simply does not work.
- 20.7.2016: Check out Fort Django, the backgrounds are made with PETSCII 🙂
- 18.7.2016: Some new pics from Vammala Party added to the gallery.
- 3.7.2016: A massive PETSCII demo by Genesis Project. Well done!
- 2.6.2016: A new binary with the two fixes mentioned below.
- 27.5.2016: Source-only: no more crashing if you press both mouse buttons while selecting. Thanks go to Basscadet again for the report.
- 21.5.2016: Source-only: a fix for a rather rare image conversion bug on the PET (80).
- 21.5.2016: The shifting bug fixed in the binary release now.
- 21.5.2016: Oops… a crashing bug with stick character shifting after loading an image. Fixed in the source version(s) and probably soon in the binary too. Thanks to Basscadet for the discovery.
- 17.5.2016: No updates recently? I’ve been working on Pixel Polizei for a while instead.
- 16.5.2016: The very latest bleeding-edge potentially buggy stuff is now available from now on at svn://kameli.net/marq/petscii
- 7.5.2016: Doing things right. From now on Command instead of Ctrl on Macs, because Ctrl-LMB is RMB, which started becoming tedious. Furthermore, it matches with the platform conventions.
It should be straightforward to download and unzip the package, after which you can run the version that corresponds to your operating system of choice: Linux, Mac or Windows. You need to have Java Runtime Environment 1.7 (JSE 7) or higher installed before that. The standalone versions don’t require Processing anymore, but if you’re adventurous and want to tweak the settings, get the beta package or see the src directory. You know what you’re doing 🙂
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 be overlaid with the characters.
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. The easiest way in most cases:
- Save your image and press e (PRG export)
- Run the resulting .prg
- Optionally, create a d64 image (c1541 is part of VICE):
c1541 -format mypic,0 d64 mypic.d64 -attach mypic.d64 -write image.prg image
- 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
- C – convert colors to Plus/4 after loading a C64 image (Plus/4 only)
- enter – 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 use some key combinations for their own purposes, so beware
- esc – exit from typing mode
- 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
- tab – walk through predefined sets of related characters
- u – undo
- U – redo (at least some sort of undo-undo)
- 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/right/left
- ,/. – cycle through bg and border colors
- § – pick character+color (same as mmb), shift-§ (° or ½) to pick color only
- c – toggle crosshair
- g – toggle grid
- i – toggle info display
- t – cycle through different levels of reference image transparency
- 1..0 – jump to frame 1..10
- d – duplicate frame to the right
- end – jump to last frame
- home – jump to first frame
- l – lock/unlock frame from editing
- left/right – jump one frame
- 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
- 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
- p – export as PNG image, shift-p includes 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)
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.
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.
- ASPECT – aspect ratio on the machines where it counts. One of PAL/NTSC/SQUARE. If not set, default to PAL.
- FRAMERATE – update rate. 60 fps by default. Decrement for less CPU use, increment for better responsiveness.
- MACHINE – one of C64, VIC20, PET, PETHI, PLUS4. Leave empty to get the normal selector at start.
- PATH – default path for your images. Give a full path like /home/marq/Pictures. No quotation marks.
- 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%
- XSIZE and YSIZE – set a nonstandard canvas size.
Assign a new value like this: ZOOM=2. The example preference file provided in the package comes with Unix newlines. Try to fare.
- 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.
- 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.
- Background and border colors can be different for each frame. Even if you’re not making an animation, a second frame can be handy as temporary storage.
- 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”.
- Using a slow computer? Disable the crosshair if it’s on (c) and info display (i), plus set ZOOM to 1 and FRAMERATE to 30 using prefs.txt. Lower framerates are possible, of course, but not so nice for drawing.
- 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
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 (2.x).
- “Blah blah is damaged and can’t be opened”. This is because of Apple’s so-called security that won’t let you run other apps than those downloaded from their store. To make a long story short: go to System Preferences – Security & Privacy and allow apps downloaded from anywhere to run.
- OS X users: Java 7 or 8 is required these days, but unfortunately they are a lot slower than the Apple-optimized version 6 used to be. If the normal speedup tricks don’t do it for you, you might even consider installing Apple’s Java 6 package and running PETSCII using an older Processing version (2.0). See here for more info.
- 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 OS X woes (and there’s probably more to come) you migth even consider running the editor inside a Linux/Windows virtual machine.
- On Linux the doubleclick time for file selectors can be frustratingly short. See here for a solution: http://blog.trifork.com/2008/10/13/descrease-the-double-click-speed-for-java-applications-on-ubuntu-linux/
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. WIP source-only release for the adventurous: http://www.kameli.net/~marq/kode/petscii-beta.zip or svn://kameli.net/marq/petscii. The code can be used according to the terms of the liberal WTFPL license. Bug reports can be sent to marq [at] iki [dot] fi.
Some artistic endeavours to give you a glimpse of what’s possible. Please let me know if you’ve done something with the editor, so that I can update the gallery and keep up my motivation 🙂
In addition to still images there are demos and games where the editor has been put into good use. Here’s some:
- Abre los ojos, Ignition, Party Bus, Pets at Zoo, Thermonuclear War and We Are Computers by oobc
- Aerial Core by Extend
- Beisikki demo, The First Ball and Rock joka tiesi… liikaa! by Fit (& Friends)
- Fort Django by Dr. TerrorZ
- Megapetscii by Hackers
- MerryXmas and Nothing But PETSCII by Genesis Project
- PETSCII Intro by Atlantis and F4CG
- Shareware by Dekadence
- Sliced Blue by Hokuto Force
Additions and corrections most welcome, as usual.
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 and Rexbeng, Man, Shine, Electric, Archmage, Hammerfist and Awsm for gallery images.