MonkeyIslandAmigaGraphics is a Python project for parsing and extracting graphical resources from the Amiga version of The Secret of Monkey Island.
The project was created primarily to extract the original room background artwork directly from the Amiga game resources, without objects or other graphical elements being composited over the backgrounds.
An example room background extracted directly from the original Amiga SCUMM resources.
Version 1.2.0 successfully extracts room backgrounds, object images and costume animation cels from all four disks of the Amiga version of The Secret of Monkey Island.
The program:
- Parses the SCUMM resource structure contained within the Amiga
.lecfiles. - Locates room (
RO) resources and their associated palettes andBMbitmap data. - Extracts
OIobject images associated with each room. - Parses
COcostume resources and extracts their individual graphical cels. - Decodes the
BMCOMP_PIX32compression used by Amiga room backgrounds and object images. - Decodes the Amiga BYLE RLE compression used by costume graphics.
- Reconstructs the original indexed graphical resources.
- Saves room backgrounds and object images as 16-colour indexed PNG files.
- Saves costume cels as 16-colour indexed PNG files with transparency.
- Creates palette reference images for each room.
The current implementation has successfully extracted:
- 85 room background images
- 659 object images
- 3,123 costume animation cels from 118 costume resources
across the four game disks.
A complete validation run identified 3,126 candidate costume cels. Of these, 3,123 were successfully decoded and saved. Three candidates were rejected because their interpreted dimensions were implausible. No costume decoding failures, save failures or unsupported costume formats were encountered.
Room backgrounds are deliberately exported without object or costume graphics composited over them, preserving the clean background artwork as stored in the game resources.
Version 1.2.0 represents the current completed extraction milestone for the project. Further graphical resource types may be investigated in the future where practical.
Python 3 and the Pillow imaging library are required.
Pillow can be installed with:
pip install PillowA legally obtained copy of the Amiga version of The Secret of Monkey Island is also required.
The following four resource files are required:
disk01.lec
disk02.lec
disk03.lec
disk04.lec
These should be placed inside a directory named resource in the project root:
MonkeyIslandAmigaGraphics/
├── mi_amiga_graphics.py
├── resource/
│ ├── disk01.lec
│ ├── disk02.lec
│ ├── disk03.lec
│ └── disk04.lec
└── ...
The resource/ directory is excluded from Git and no original game data is distributed with this project.
Development and testing has been performed using resource files from the original, unmodified Amiga release of The Secret of Monkey Island.
Modified or cracked/hacked versions of the game have not currently been tested and may contain differences that affect parsing or extraction. Use of the original, unmodified game data is therefore recommended.
With the four .lec files in the resource/ directory, run:
python mi_amiga_graphics.pyThe program processes all four disks.
Room backgrounds are written to:
Rooms/
├── disk01/
├── disk02/
├── disk03/
└── disk04/
Example BM room background generated by the extractor.
Palette reference images are written to:
Palettes/
├── disk01/
├── disk02/
├── disk03/
└── disk04/
Example 32-colour room palette generated from the original Amiga palette data.
Object images are written to:
Objects/
├── disk01/
│ ├── room_01/
│ ├── room_02/
│ └── ...
├── disk02/
├── disk03/
└── disk04/
Each object image retains the object identifier stored in its OI resource, for example:
Objects/disk01/room_01/object_113.png
Example OI object image extracted independently from its room background.
Costume animation cels are written to:
Costumes/
├── disk01/
│ ├── room_01/
│ │ ├── costume_01/
│ │ │ ├── cel_001.png
│ │ │ ├── cel_002.png
│ │ │ └── ...
│ │ └── ...
│ └── ...
├── disk02/
├── disk03/
└── disk04/
Costume resources can contain multiple graphical cels representing animation frames or other graphical states. Each unique cel discovered by the extractor is saved separately.
Costume palette index 0 is exported as transparent, allowing the extracted artwork to be viewed independently of the room background.
Example CO costume animation cel extracted with palette index 0 represented as transparency.
The generated Rooms/, Palettes/, Objects/ and Costumes/ directories are excluded from Git.
The Amiga room backgrounds and object images are stored as compressed 8-pixel-wide bitmap strips.
For the resources currently supported by this project, each strip uses compression method 0x0A, corresponding to the BMCOMP_PIX32 decoding path used by ScummVM for the Amiga version of The Secret of Monkey Island.
The same strip decoder is used successfully for both main BM room backgrounds and OI object images.
For room backgrounds, the image dimensions are obtained from the room metadata. Object image widths are derived from their strip-offset tables, while their heights are determined by finding the height for which every compressed strip decodes completely and consumes its full payload.
The decoder produces 4-bit colour values representing 16 colours. These correspond to entries 16–31 of the room's 32-entry palette.
Room backgrounds and object images are saved as 4-bit, 16-colour indexed PNG files, preserving the indexed-colour nature of the original Amiga artwork.
Classic CO costume resources contain animation metadata and graphical cels used for characters and other animated elements.
The Amiga costume graphics supported by this project use the 16-colour 0x58 costume format and Amiga BYLE RLE compression.
Costume pixel data is reconstructed vertically, column by column. Each RLE value contains a colour index and run length, with extended run lengths stored in an additional byte when required.
Each costume contains its own 16-entry colour mapping into the associated room palette.
Extracted costume cels are saved as 4-bit, 16-colour indexed PNG files, with costume colour index 0 represented as transparency.
Version 1.0.0 fulfilled the project's original objective of extracting the clean room background artwork.
Version 1.1.0 extended the extractor to OI object images while continuing to preserve room backgrounds as separate, unpopulated images.
Version 1.2.0 adds extraction of CO costume resources, including individual animation cels for characters and other animated graphical elements.
The longer-term aim is to extract as much of the original Amiga graphical artwork as practical while retaining the individual resources rather than compositing them into reconstructed screenshots.
Development continued with MonkeyIsland2AmigaGraphics, a companion project for extracting graphical resources from the Amiga version of Monkey Island 2: LeChuck's Revenge.
Although the two games use different versions of the SCUMM engine and substantially different resource structures and graphical formats, the investigation and extraction work carried out for MonkeyIslandAmigaGraphics provided the foundation for the later project.
The Monkey Island 2 extractor extends the work to SCUMM v5 resources and supports room backgrounds, object image states, costume animation cels, character sets, palette reference images and Z-plane occlusion masks.
The idea behind this project originated in 2022, with the aim of extracting the original background artwork from the Amiga version of The Secret of Monkey Island.
During the early investigation, the author attempted to contact the ExoticA team and subsequently contacted Stuart Caie (Kyzer), whose extensive experience with Amiga data formats and compression made him an obvious person to approach. Kyzer expressed an interest in the project and provided encouragement during its early stages.
Development was later resumed following the completion of the author's Open University commitments.
The project subsequently developed into a broader investigation of the Amiga SCUMM resources, extending beyond the original goal of extracting room backgrounds to include object images and costume animation cels.
The techniques and knowledge gained during this work later provided the foundation for the companion MonkeyIsland2AmigaGraphics project.
The ScummVM source code has been used as an important reference for understanding the structure and decoding of the original SCUMM resources.
The BMCOMP_PIX32 strip decoder in this project is a Python adaptation
of the relevant decoding behaviour in ScummVM's SCUMM engine, including
its drawStripEGA() implementation.
ScummVM's handling of Amiga costume resources and BYLE RLE decoding was also used as a reference while implementing costume extraction. The Python code in this project was written specifically for extracting the resources from the Amiga version of The Secret of Monkey Island rather than reproducing ScummVM's rendering engine.
ScummVM is copyright its respective authors and is distributed under the GNU General Public License.
SCUMM Revisited was used during development to inspect the structure of the original game resources, including their chunk hierarchy, offsets, sizes and raw data.
The SCUMM chunk descriptions used by this project, such as RO, BM,
OI and CO, retain the naming convention presented by SCUMM Revisited,
including question marks where the original utility itself describes a
chunk tentatively.
SCUMM Revisited does not decode the Amiga graphical resources extracted by this project, but its resource browser and HexView were valuable tools during investigation of the original data.
ChatGPT (OpenAI), affectionately referred to during development as Chat Chippy Tea™, was used extensively as a development and research assistant throughout the project.
Its role included helping to analyse SCUMM resource structures, interpret relevant ScummVM C++ implementations, translate decoding behaviour into standalone Python, investigate binary resource data, debug extraction routines and assist with documentation.
The development process remained empirical throughout. The original Amiga game resources were parsed and tested locally, extracted graphics were visually inspected, resource counts and decoder behaviour were validated, and results were compared where useful with SCUMM Revisited and the behaviour documented by ScummVM.
The author supplied the game resources used during development, performed the extraction and validation runs, visually inspected the generated artwork, identified anomalous results, compared resources using external tools and made the final implementation and project decisions.
ChatGPT did not provide or supply any original game data.
Original game data files are not included with this project. A small number of extracted PNG images are included solely as examples of the program's output.
Users must provide their own legally obtained copy of the relevant game data.
The Secret of Monkey Island and its original artwork are the property of their respective copyright holders.
This project is distributed under the terms of the GNU General Public License version 3 (GPL-3.0).
See the LICENSE file for details.
- The ScummVM project and its contributors for their extensive work documenting and implementing support for the SCUMM engine.
- SCUMM Revisited and its developers for providing a valuable resource inspection tool and terminology reference during development.
- The ExoticA contributors and community for their long-standing work preserving and documenting Amiga software and music.
- Stuart Caie (Kyzer) for his interest in and encouragement of the project during its early investigation.
- OpenAI's ChatGPT — affectionately known during development as Chat Chippy Tea™ — for assistance with reverse engineering, Python implementation, debugging and documentation.
- Lucasfilm Games / LucasArts for The Secret of Monkey Island.