search

johanberntsson / PunyInform

A fast and compact library for writing text adventure games for the Z-machine running on 8-bit computers as well as other platforms.
MIT License
176 stars 17 forks source link
development-environment infocom inform6 punyinform retrocomputing retrogaming text-adventure zcode zmachine

readme

PunyInform

NEWSFLASH: There's a competition coming up, and you can join! Submissions are due 29 December 2024. https://itch.io/jam/punycomp-2024

PunyInform is a library written in Inform 6 which allows authors to create text adventure games / interactive fiction using the Z-machine virtual machine, to be played on 8-bit computers as well as newer platforms. It provides a parser, implementations of common verbs, as well as a framework for writing text adventures.

PunyInform is based on the Inform 6 library, developed by Graham Nelson. We are trying to make it easy for authors used to writing in Inform 6 to start using PunyInform. There is a manual describing the differences.

Games using PunyInform can be compiled to z3, z5 and z8 format. Compared to the Inform 6 library, this means we lack support for Glulx, but we have support for z3 (which the Inform 6 library lacks).

To compile games using PunyInform, we recommend the official Inform 6 compiler maintained by David Kinder, at https://github.com/DavidKinder/Inform6. Binaries can be found at the IF-Archive. PunyInform requires at least Inform v6.36. We recommended using the latest version.

You can use borogove.io to make your PunyInform game playable online. Create an account, upload your game file, and choose whether the game should be visible and playable for all visitors to the site, or only to those who have the link to your game. Another option is to upload your game file (e.g. mygame.z3) to the Parchment HTML Converter and download a single-file HTML file, which can be uploaded to sites such as Itch.io.

A minimal game in PunyInform

Motivation

The main goal of PunyInform is to allow for games which are fast and have a small memory footprint. This should make the games run well on older architectures, such as the 8-bit computers of the 1980s. Our main target is to make it suitable for games on the Commodore 64 using Ozmoo.

Status

PunyInform is fully working and has been used to write several games. We carefully add and change features and fix bugs as they are found. Please check releasenotes.txt for more details.

If you are interested in our progress, please star or follow the project here on Github. Announcements are made on https://twitter.com/FRamsberg and on https://intfiction.org/c/authoring/inform-6/66

You can read the manual on our wiki. It is also included as a PDF when you download PunyInform.

There is also a Game Author's Guide (under Documentation) with various tips for authors writing a game using PunyInform. It's not intended to teach the entire library, but more to give some tips you may find useful when you have a working knowledge of the library and you've started developing a game which you think you will release. All but the chapter on optimization is really required reading for all authors planning to release a game.

You can see what tasks we're currently working on, tasks we've done and tasks coming up on our Trello board: https://trello.com/b/mfGVsB4H/punyinform

Learning PunyInform

There are two manuals you need to know about: DM4 and the PunyInform manual. Read on to learn how to use them and where to find them. Alternatively, you can start learning PunyInform by following the tutorials under Articles.

Writing a game with PunyInform is very similar to writing a game with the Inform 6 standard library - almost everything works the same. If you want to learn PunyInform by reading manuals, you first need to read the official documentation for the Inform 6 standard library, called The Inform Designer's Manual, 4th Edition, or DM4 for short (see links above). You can assume that everything in it also goes for PunyInform (but read the short list stating the biggest differences just below the next paragraph!).

Additionally, there are two more important documents in the PunyInform distribution:

The Game Author's Guide lists some concepts that are often overlooked by new authors, leading to games with errors and problems. There's also a chapter on optimization, which is very useful for authors trying to squeeze the most out of the z3 format, and authors who want to do everything to deliver the best possible player experience on 8-bit computers.

The QuickRef document is an index of all constants, variables, routines etc that you need to know about as an author. It's not meant to be a learning resource for new authors, but to provide a very brief documentation for authors who are reasonably aquainted with the library.

As you start trying out examples, or start writing your own game, and there's something which you don't get to work, you should check the PunyInform manual, which describes everything that is different from the standard library (see links above).

The biggest differences between the standard library and PunyInform are:

Tools

Games Using PunyInform

60+ PunyInform games have been released. You can find just about all of them in this list of PunyInform games.

If you want to see the source code of PunyInform games, you should look at the list of PunyInform games which provide source code.

Most of these games can be downloaded from the links above. Some of the best games are also available at Ozmoo Online where you can create disk images for Commodore C64, C128, Plus/4, MEGA65, Commander X16 and Acorn/BBC computers.

Articles

Fredrik Ramsberg has written a few articles describing PunyInform for beginners:

Fredrik has also written a comparison of PunyInform and the standard Inform 6 library.

Community

If you want to ask questions about PunyInform, these are good places to go:

There are also categories/channels in the above forums where you can discuss plot, story, puzzles etc, and posts requests for beta-testers for your game.

Translations

Credits

PunyInform was conceived, designed and coded by Johan Berntsson and Fredrik Ramsberg.

Additional coding by Pablo Martinez and Tomas Öberg. PunyInform includes code from the Inform 6 standard library, by Graham Nelson.

Thanks to Stefan Vogt, Jason Compton, John Wilson, Hugo Labrande, Richard Fairweather, Adam Sommerfield, auraes, Hannesss and Garry Francis for issue reporting, advice, testing, code contributions and promotion. Thanks to David Kinder and Andrew Plotkin for helping out with compiler issues and sharing their deep knowledge of the compiler. Huge thanks to Graham Nelson for creating the Inform 6 compiler and library in the first place.