Digging for treasure in Aladdin’s source code

by Rich Whitehouse October 7, 2017

When it was released back in 1993, Disney’s Aladdin for the Sega Genesis (or Mega Drive, depending on which side of the pond you lived on through the early 90’s) was really a visually striking game.

Powered by what eventually became known as “Digicel” technology, along with a solid selection of middleware and some impressive talent, Aladdin managed to set itself apart from other Genesis titles of the era. Aladdin’s beautifully hand-crafted, surprisingly well-quantized artwork set new expectations for many in the realm of what could be accomplished on Genesis hardware. It did so not by leveraging any particularly fancy raster effects or obscure hardware techniques, but rather by pairing effective artwork and design with just the right technology.

This unique blend of artwork and technology is a large part of what gives Aladdin a special place in video game history. It’s also a large part of what made it such a joy to discover an archive featuring the complete source code for the game in the Video Game History Foundation collection! In addition to being a treasure trove of data, this archive represented a great opportunity for me to begin establishing standards for source code archival, curating practices, tool dependency tracking, and a lot of other process-oriented things at the VGHF.

Almost all of the development tools and materials were still intact in this archive. I quickly started piecing processes together, and began working on getting the source code (which is written entirely in M68K assembly) built into a working binary. I’m going to walk you through the journey and reveal my discoveries at each step of the way. That includes finding a plethora of unreleased material, and even re-implementing entire objects and enemies that had been removed by the time Aladdin saw its commercial release!

Hopefully you like technical talk, because I’m not holding anything back. If not, well, there are pictures! (and you can skip straight to the cool section) You might also want a copy of Noesis on hand to explore along with me. In case you aren’t familiar, in short summary, it’s a tool built on a framework to assist in reverse engineering and exploring all manner of data. It includes a script, fmt_virginmd_chopper.py, which will allow you to dig all of the Chopper tile data out of any known (commercial or otherwise) Aladdin ROM image. The resulting data can then be viewed directly by Noesis. While it won’t give you access to the materials that didn’t actually make it to retail, it will allow you to flip through frames and observe tile usage in the finished product.

It’s also worth noting that Noesis can dig the Chopper data back up out of the Aladdin CES demo build. This reveals a few interesting things exclusive to that build, including some additional sketch material that does not appear to be accessible in the build through normal gameplay.

The CES demo build is labeled as a Chicago CES demo, but as noted in the build’s TCRF article, the SNASM-generated timestamp reflects June 27th, 1993. This indicates that the build was produced several weeks after the show had taken place.

Referencing our source archive, we can see that some source art was modified as late as mid June, and is already removed from ROM in the CES demo build. This is far from conclusive (we have no way of knowing if source art continued to be modified after being removed from the Chopper database), but supports the idea that the CES demo build may have been produced from an active development branch on June 27th, 1993, rather than being further developed on a branch of an earlier development snapshot. For simplicity’s sake, though, I’ll continue to refer to this build as the CES demo build when the material I’m discussing relates to the build in some way.


1. Overview

The archive containing Aladdin is laid out such that it looks to have been someone’s working copy of the game’s source code and data, as opposed to being a shared repository of any sort. A few of the data dependencies were missing in the archive, which was a little surprising, with the game having been built out of this very workspace at some point. However, I was able to reproduce the missing data without much trouble to get a usable binary building again.

Although content otherwise seems to match the retail distributions of Aladdin, modified dates for some of the source files in this archive are as late as September 30, 1993. That’s 10 days later than the build date of the Japanese distribution, which is September 20, 1993. There are no apparent data changes, but a thorough byte to byte comparison is somewhat problematic due to the drastically different build circumstances.

The really fun part here is that this archive includes a big chunk of source art material! That’s where the stuff that never made it into the game is hiding. That material is generally built into a more ideal/compact form by some other tool(s) before finally being included in the ROM itself. We’ll be taking a look at all of those tools and processes in this article.

An example of animation sequence source data.

The other big discovery in this Aladdin archive is that there are large swaths of commented out code for prototyped and/or removed features. These days, if a programmer were to comment out hundreds of lines of newly-unused code instead of removing them outright, they’d probably get chewed out in their code review. But thanks to that wonderful practice, we get to enjoy true-to-intent features, enemies, and more, 24 years into the future! Take that, coding standards!

2. Tools

From building the code to creating and preparing the data for use, Aladdin leverages a pretty sizable toolset, all within the friendly confines of MS-DOS. This archive gives us an effective view into the actual content creation processes that were used at Virgin to bring this game to life. In this section, I’ll discuss what each tool is/does, and chronicle my experience in discovering and using it.

2.1. SNASM68K

An old log in the archive appeared to implicate version 1.29 (or 1.30, at odds with some code comments) of SNASM68K as the original assembler of choice for Aladdin. I was already somewhat familiar with SNASM, after a brief foray into Sega CD development many years ago, but I only had access to newer versions of the tool. That meant I had to make a few changes to get the source built again. The most unpleasant change there was due to the fact that SNASM decided to switch between “!” and “|” for the OR operator at some point, which led to some sweeping macro changes. A few branch relays were also required here and there, despite the fact that memory layout remains relatively faithful to the commercial binary.

Assessing the code itself, it was readily apparent that a file called FOLDER.68K was intended to be the entrypoint for the assembler. This file defines a number of “build configuration”-esque variables, many of which conditionally include/exclude bits of code elsewhere, or determine whether PAL or NTSC data get pulled into ROM. After getting familiar with things and dealing with the assorted SNASM version-related issues, I tried booting up the resulting binary, and was delighted to see:

This is actually from the cheat screen that appears still enabled at retail, and it appears on startup by default in this archive’s code drop, with an updated SNASM-supplied timestamp. Its appearance at startup is contingent upon one of those “build configuration” variables as well.

I happily proceeded further into the game, and was greeted with a hang when loading into the first level. Time to bust out the debugger! Oh wait, I don’t have a debugger. After a couple rounds of troubleshooting by way of inserting jump-to-selfs to narrow down the hang window, I decided to stop being a terrible person and go see if there were any Genesis emulators out there with built-in debuggers that didn’t require me to download 50 separate libraries in order to produce a custom debugger-enabled build. I came across a debugger-enabled build of Regen at this point, and away I went!

Breaking in-place from an already-hung state in Regen, the program counter was off in no man’s land, the register states were generally hosed, and the stack was trashed, such that I could not determine what the last sane place of code execution was, even when attempting to employ Aladdin’s built-in exception handler. This is when you know you’re in for fun times.

After producing an address map with SNASM to see what was actually going where, I got the address for a point in the code that looked about right for where things get kicked off for a level load. Set a PC breakpoint on that address and ran. Breakpoint hit, so I stepped through a bit, and determined it was diverging into oblivion somewhere within the ProPack decompress-to-RAM routine. Namely, when decompressing the level’s “FLOOR” data. This is what it sounds like, it’s a look-up table that defines the level’s floor tiles.

I stepped through the decompression loop quite a bit, observing no problems, until I finally noticed the destination address. It was decompressing floor data all over the user stack. That didn’t seem right! I looked over to the labels that defined the location of the active floor in RAM, and it was indeed right above the user stack.

As it turned out, there was some macro magic in there to get the maximum size of all the uncompressed floor files, and use that to determine the size of the floor region in RAM. Said macro magic was managing to wind up calculating a nice value of “0” in my version of SNASM. Fixed that, vetted for any other locations in the code using similar macro magic, and it was smooth sailing from there. No more apparent issues from a cursory run-through of the game.

2.2. Chopper

Chopper is probably the unsung hero behind what Virgin referred to as “Digicel” technology. Unfortunately, I don’t really have any visibility over the process that was used to take hand-drawn art and digitize it, other than that it seems to, at some point, end up with the art being imported into DeluxePaint Animation. I don’t know whether it was largely driven by generic hardware/software solutions, or if Virgin introduced something proprietary into the mix. What I do know is that once something had made its way down to DeluxePaint Animation, Chopper took it from there.

Chopper is a wholly-proprietary interface-driven tool, which works off of its own sprite database format. It was principally developed by Andy Astor, but looks to have been touched by quite a few hands. This includes David Perry, who specified the Genesis output format. Unfortunately, Chopper’s source code is not included in the archive, so our visibility into its development is limited to accompanying documentation.

Chopper’s primary role is to chop imported animations up into tiles, varying in sizes from 1×1 to 4×4. (inclusive of rectangular dimensions, and where each tile is 8×8 pixels) It has a variety of chopping options, as well as options for how to default each animation frame’s collision box, and whether to consider frame, sequence, or whole database when deciding how to chop. The interface itself looks like this:

Above, I’ve imported the Prisoner, who was removed from the retail version of the game. We can see the distinct boundaries where the current frame has been chopped into groups of tiles. The yellow rectangle represents the collision box for the frame, and each number represents the number of times that tile group is reused.

Although Chopper operates on its own proprietary database format, it’s capable of exporting tile data to a variety of ideal platform target formats, aimed primarily at the Genesis and SNES. In the case of Aladdin/Genesis, Chopper writes out a number of .SEG (Sega, rather than segment as the programmer or Doom mapper in you might initially suspect) files, which represents the whole of raw tile data for each 1×1 – 4×4 size. Chopper also generates a number of .68K files, which are meant to be assembled as code, and define additional properties for each frame. (part count, collision, and per-part properties like tile size, offset, and index) These files also define the intended order of data inclusion, reflecting the data’s final placement in ROM, and dictating any necessary alignment restrictions for the tile data itself.

The Noesis script mentioned earlier in this article, fmt_virginmd_chopper.py, will attempt to locate frame data in the expected Genesis form, and convert it back up into a series of .SEG files with a plain-text .68K file that references back into the .SEG files using the same naming conventions as native Chopper Sega data. You’re free to play around with the plain text file in order to observe how changing the properties affects use of the tiles, just as it would on hardware.

Another interesting aspect of Chopper is that it’s set up to explicitly look for a single-pixel rectangle to define the desired bounds of an animation sequence. I’ve also coded up a parameter option to mimic this for the DeluxePaint Animation importer in Noesis. A lot of the animation sources therefore look something like this:

Many sources contain active image data outside of the desired rectangle, which was probably commonly used as a scratch pad and for reference. After Chopper imports the sequence with its default handling, it ends up looking like this:

Another tool was also written as part of Aladdin’s Chopper import process, which trivially digests Chopper’s native .68K output to spit out some additional per-frame tables/lists. This includes a linear list of pointers to each frame, probably born of a desire to be able to increment frames by jumping between pointers instead of dealing with the variable size (due to a variable number of parts) of each frame.

2.3. tUME

Aladdin makes use of tUME, which is a generic tile-based map editor. Like every other game of the era that used tUME, Aladdin has its very own custom tUME packer. The packer is a standalone tool, which exports data in a collection of formats ideally suited to the platform and to the particular title.

In the case of Aladdin, the tUME packer is named “tPJungle”, presumably named after its intended use in The Jungle Book. tPJungle spits out a variety of files, including block/character data, contour data (which is typically shared between levels), floor look-up/tile data, a variety of room data types (depending on whether the level is a traditional room, or a picture room like the Genie bonus screen and other cameo screens seen in the game), palettes, and parallax files which allow multiple room layers to reference into the character/tile data.

The output of the tUME packer tends to then be compressed as part of a separate batch process, and the compressed (or in some cases still not compressed) data is manually referenced within a .68K file.

Enemies and objects are placed according to their tile number. This means that the following tile table bitmap corresponds directly to a table in code which triggers the appropriate object spawner/generator based on the tile index:

There are a good many unused slots, as well as slots that were previously referencing now-removed objects (like the Prisoner or Sword Swallower) which now direct to stub functions. Unfortunately, the removed enemies don’t look to be placed in any of the tUME sources, so outside of hints from the design document, we don’t get any free indicators of how/where these enemies were meant to be placed.

2.4. GEMS

Aladdin uses the GEMS driver for sound, leveraging FM and PSG patches a good bit in its music playback. A separately generated data set is also provided for the PAL distribution. Our archive does not contain the GEMS intermediate sources, and the GEMS-generated code/data is accompanied by a batch file that shows it being copied locally from a network location. This means that anything we can divine from this archive, we can also divine from the retail game by digging the GEMS sequence/sample/patch/etc. data back up from the binary.

What is present in this archive, however, is the actual Cakewalk MIDI source (used to feed the sequencer which fed GEMS) and linear PCM samples provided directly by Tommy Tallarico! You can read more about that over in Sound and Music.

2.5. ProPack

Rob Northen’s ProPack is used pretty extensively in Aladdin on a variety of data types, including floor look-up tables and character (but not animated/chopped) tile data. Aladdin uses method 1, as outlined in the Sega Retro article I just linked, exclusively. Having plenty of decoder references (in 8086, M68K, and 6502 assembly to name a few) available, I also wrote an implementation of the decoder for Noesis.

Numerous batch files are present in the Aladdin archive, which appear to have been manually maintained to convert and compress all of the relevant level data for direct inclusion in ROM. Presumably, the level design workflow here was something like “Modify in tUME, save, exit tUME, run batch, assemble, run game”.

3.0. Buried Treasure

The most exciting thing about digging into this archive was unearthing the wealth of material present that hadn’t managed to make its way into the retail game. I was very surprised to find so much stuff still intact, and even more surprised to find out how much relevant code still existed (albeit not assembled into the retail ROM image) in the codebase.

After getting familiar with Chopper and the rest of the tools, I set about re-importing some of the removed assets and re-adding various bits of code for things like old object generators, animations, and alien (more commonly known these days as actors, or entities if you’ve got Quake in your blood) logic. I bumped the ROM size up to 4MB (32Mbit), so that I’d have plenty of room to pile all of that glorious film back in straight from the cutting room floor, and not have to do any picking and choosing over what I wanted to bring back. Some of the code was ready to roll right out of the box, but in other cases I had to do some fixing up and tweaking to get things fully operational again.

Another amazing bonus found within these files was a copy of the game’s original design document, version 3.3, dated from April 27, 1993. I’ve used this document as a reference to help me determine original intent for the incomplete code and features I’ve come across in my travels.

I’m not even covering the whole body of extra material here, but these are the big highlights thus far. I’ve also found game-ready animations for the skeleton from the CES demo build, with the addition of a walking sequence. It appears there may have been some intent to have him stumble toward the player before exploding. There’s no related code in place, and I haven’t gotten around to writing up brand new animation/state logic for him, so that’s something else to look forward to.

3.1. Bonus Round

One of the first things I came across was a bunch of old Genie bonus round code. It explicitly sets up an “arm” alien which represents the slot machine lever, and uses some additional movement and state code. I brought the old Genie slot code back wholesale, and re-imported all of the animation dependencies through Chopper. I also noticed there was a spinning Genie coin animation in the source art, which made sense with this slot machine theme, so I brought that back in too. Here’s the result:

You’ll notice the background doesn’t quite match up with the slot arm. Fortunately, I managed to locate the tUME map source for the background that it does belong to, buried in a “TRASH” directory. I exported the old tUME map with tPJungle, and got it plugged back into the game:

However, this background comes with its own issues. The foreground layer doesn’t appear to be set up quite correctly, and there’s no remaining logic in code that meshes with the idea of a 3-reel slot machine as the background itself would seem to indicate. It’s hard to say whether this background didn’t actually make its way into prototyping before being taken to the chopping block, or if the code related to it was completely removed. It’s also possible that this “TRASH” copy is not the final background that was used prior to the removal of this slot machine themed bonus round.

We’d have to adjust quite a few things on our own to bring back this bonus game in a way that makes sense and meshes with the original slot machine theme. We do, however, still have all of the data we’d need to be able to faithfully reflect the original intent in a new implementation. The slot machine version of this bonus game is described in great detail in the game’s design document. A rock, paper, scissors bonus game is also described, but there is no trace of it in source code or art, so it seems that the idea never got off the ground.

3.2. Enemies

Numerous enemies were removed from the game prior to the retail distribution. The considerations for removal probably varied on a case-by-case basis, between design/appeal reasons, development time, and ROM space limitations. Given how tightly the retail game was butting up against the 2MB (16Mbit) ROM constraint, we can only speculate on the decision balance for each case. Some of these enemies were fully functional, while others required a bit of love and care to restore.

Sword Swallower

The Sword Swallower is a close design relative of the Knife Juggler, and was intended to be part of the marketplace enemy lineup. He sits in one location, and pulls an endless stream of swords out of his throat to toss across the screen. He needed his projectiles hooked back up as well, but was functional without additional modification, and appears to behave in keeping with his CES demo build implementation.

The Sword Swallower in action.


The Prisoner was intended to help populate the Sultan’s Dungeon, and comes complete with several separate animation sequences. He idly files away at the chain on his leg, and begins swinging the ball and chain around his leg when approached. He also has a pain/reaction sequence, which I had to implement from scratch, as no traces of related code remained. The Prisoner also appears in the CES demo build, but with an incorrect palette, and with no reaction sequence present in the ROM.

The cut Prisoner enemy, rebuilt and reborn!

Golden Monkey

Shown here in what’s certainly an inappropriate context (he’s intended for the Cave of Wonders), the Golden Monkey is a relatively simple enemy that just tosses an endless stream of jewels at the player. No other animations are provided for this guy, and no additional code was required to get him back up and running.

The design document describes the Golden Monkey as behaving identically to the Shiva statue in the retail game. Likewise, the Shiva statue was intended to be a more involved encounter, triggered by Iago flying by and dropping a vial. It seems the decision was made, at some point, to simply drop the Golden Monkey and use the Shiva statue in its place.

The Golden Monkey, out of its element (it was meant to appear in the Cave of Wonders stage).

Flamingo Iago

In the Sultan’s Palace level, Iago was meant to make an appearance in a flamingo getup. He marches across the screen on stilts, and damages the player on contact.

Flamingo Iago obviously would have walked on this level’s water sections, you’ll have to use your imagination a little bit here.

Flamingo Iago’s animation sequence is also present in the CES demo build’s ROM, even though it does not appear to be used in the game.

Rolly Snake

While the snake did make his way into the retail version of the game, he was originally intended to roll. His internal name is, in fact, ROLLY_SNAKE. I came across some code that indicated he was meant to do a roll if he was close enough to the player after an attack. I hooked that code back up and was greeted by some curious behavior, where the direction of the roll was very random and occasionally would leave the snake stuck in “rolling” mode even after the animation had stopped. I had to do a bit of fixing up, but was able to get his roll attack back in a state that at least looked like it made some sense.

A simple implementation of the snake’s unused rolling animation.

Interestingly, our copy of the design document outlines behavior quite different from what was indicated by the code:

If the snake is hit by 2 throwable objects in a row, it will become a snake-wheel and roll to the right, over other enemies, killing them. The snake will roll fast enough so that Aladdin will not be able to catch up to it, and it will roll off the screen.

There are no indications in the source code that this behavior ever made its way into the game. In speculation, this might be an indication that the present implementation of rolling was a test, compromising the feature while still attempting to utilize the animation work that had been done. The snake’s animations (including the roll sequence) are also present in the CES demo build’s ROM, even though the snake doesn’t make an appearance in the demo.

3.3. Genie Parts

Several environmental Genie objects were removed from the retail game, although none of them appear to have managed to get to the point of being fully polished. These objects were intended to be used on the “Inside the Lamp” level, and pertained to affecting player mobility throughout the map.

Genie Arm

The Genie Arm is a Genie hand connected to 6 orbs. It moves on a fixed path upon contact, carrying the player with it.

The Genie Arm was likely intended to supplement the existing hand platforms (which did make it into the retail game), as described in the design document:

These are the main ‘building blocks’ of the level and form the majority of the platforms that Aladdin moves on. Some of these platforms will shrink and grow back to their original size in regular patterns. Obviously the larger the hand, the easier it is to jump onto as it presents a larger target. The level design will use this timing mechanic to the full.

Other hand platforms will look slightly different and will be made out of tiles rather than sprites. This will enable us to avoid embarrassing sprite flicker.

Due to a quirk of the implementation, only one Genie Arm can exist at a time, because it’s effectively coded up as a singleton. When a new arm comes into the view, the previous arm becomes that arm, causing the previous arm to effectively disappear.

Genie Hands

The Genie Hands don’t seem to have a direct design correlation, and in what is left of the implementation, it’s just a pair of hands clapping. It can’t be interacted with.

It’s difficult to say whether this might’ve been some kind of hazard, or if it affected mobility in some other way. It’s possible that some vital/associated code was removed (rather than being left for reference) because it tied into other (player-related) logic.

Genie Ball

The Genie Ball pops into existence when the player approaches, then locks the player in place on top of it upon contact:

The Genie Ball’s intended design is called out in the design document:

These are a double-edged sword. If Aladdin can get on top of a rolling Genie ball, he can use it as a kind of moving elevator to get around various sections of the lamp. The ball also offers the additional height sometimes required to make a jump up to a bonus or secret area, but Aladdin may have to balance on the ball for a while before the ball is in the correct place from which to make the jump.

The Genie Ball code integrates pretty significantly into player movement code, so it wouldn’t be too surprising if something is very broken in its newly-resurrected form. The object may also have additional setup requirements that aren’t being fulfilled here, as indicated by its working behavior in the CES demo build.

3.4. Sketches

Within the source art, there are a few digitized pieces in sketch form. As an example, here’s a sketching of each frame of Aladdin’s falling animation:

We have more details provided in the sketch for Aladdin’s second falling animation. The image itself calls out specific frames for loops and holds:

This provides a tiny glimpse back upward into the actual art creation process. Of particular note is a game-ready Abu animation that I came across, which is still in sketch form:

This particular bit of art is for Abu looking into a bag, which doesn’t seem to be reflected by any particular game event or remaining prototype code. However, a related mechanic that would affect boss battles is called out in the design document:

Aladdin arrives at the boss, the scroll stops and the music changes to the boss music we will use for every boss. As the music changes, Abu will dart into view from off screen and place a magic bag of gems, which he is prepared to reluctantly lend to Aladdin, somewhere on the screen (in more inaccessible places in the later levels and also in the hard difficulty setting), in order to help him defeat the boss.

Abu then darts off screen again as he certainly doesn’t want to stay around for the ensuing ‘fun’! All Aladdin has to do is move over the bag (as he would to collect any other object or throwable) and the bag will disappear (into Aladdin’s inventory).

Abu’s bag is magic because it contains a never-ending supply of gems so Aladdin will never run out.  Abu, though, as we know, is partial to the odd gem and takes the bag back off of Aladdin after the defeat of each boss (the bag will automatically be thrown to one side of Aladdin after a boss has been defeated), Abu will dart back into view, once again, to retrieve the bag before disappearing off screen again.

When he retrieves his magic bag, Abu’s reaction/behavior will depend on the number of gems used by Aladdin in defeating the boss. The more gems used, the more angry he will be in his gesticulation. If Aladdin uses no gems, Abu will show his pleasure in some Abu like way. There will probably be three different Abu reactions in the cartridge version (ecstatic, nonchalant and angry) and five in the CD one.

In a similar vein, this fish animation, also present in the CES demo build, still lives alongside its completed version in the source art:

It may be a bit telling that we have masked, game-ready artwork still in sketch form and ready to go, and that some of it was even employed in the game for the CES demo build. It’s unlikely that this would occur if the process of getting art to this point weren’t already incredibly streamlined, and reveals a rather interesting workflow!

3.5. Sound and Music

Although we don’t have any intermediary source/project data relating to GEMS, we have something even better hidden within this archive, which is the raw Cakewalk MIDI files and sample data provided by Tommy Tallarico. All of the digital samples were delivered in the form of raw 8-bit linear PCM blobs, such that Tommy calls out the sample frequencies in his accompanying letter:

You might want to check the tempos for all the songs in case some weird PAL-NTSC thing happens. I’m sure by now you know the deal! All of the samples are at 10.4 khz except the following:jl87.vmd 8.7honk.vmd 5.2xplode2.vmd 5.8camel2.vmd 8.7finger.vmd 7.3feet2.vmd 7.3feet3.vmd 8.7cash2.vmd 7.3feet5.vmd 8.7

Tommy also calls out the timing difference between NTSC and PAL here, which is a special consideration when using GEMS, as timing is effectively baked into the final sequence data that the GEMS driver digests. Aladdin does indeed take special care to include separate PAL audio data.

The tools and hardware that were used to feed the Cakewalk sequencer data to GEMS are unknown, but the raw blobs of linear PCM are in keeping with the way GEMS expects to directly digest sample data. Loading up the Cakewalk project files gives us a bit of a cleaner glimpse (than digging back up from the binary targeted at the GEMS driver) into the original tracks as well.

It might be interesting to dig in further to draw more comparisons between the MIDI sources and the GEMS data that was cooked into the retail game, but we’ll have to save that for another day.

3.6. The Design Document

I was shocked when I saw this thing buried down in a zip file within a zip file. There’s a massive wealth of information, and more what-could-have-beens than you can shake an apple at in here. The design document is specified as version 3.3, and the file is dated April 27, 1993. It has contributions from many individuals, with the doc itself attributing David Bishop, Seth Mendelsohn, Mike Dietz, and Mark Yamada, with a sanity check by David Perry.

There are a great many disparities between what went into this design doc, and what ended up in the game. I could write an entire article on that material alone, but I am going to highlight some of the more interesting disparities in this section.

On the whole, this document gives us a lot of material with which to resurrect old ideas and features, especially those that already had some degree of art put in place. It also gives us more clues about small one-off bits of art that are never referenced in the game/code, like this one:

The original design intent was that bananas would be collected, and actually trigger Abu to appear at random points on the level. This animation appears to have been crafted so that Abu could be scooped up during a carpet ride (hinted at by the posture and the hair movement), but no traces of Abu-scooping otherwise remain. It’s also quite interesting to note that this animation exists inside the CES demo build’s ROM, even though it doesn’t appear to be used in gameplay!

Whatever we end up doing with this source code and data, this design document will be an exceptionally valuable resource.

The Levels

We have a breakdown in the design doc of what was planned to be the original level layout:

Level                        Goal               Boss
1.    Marketplace            Rescue Jasmine     Razoul
2.    Desert                 Find Scarab #1     None
3.    Marketplace rooftops   Find Scarab #2     Gazeem
4.    Prison                 Escape from prison None
5.    Cave of Wonders (gold) Reach lamp chamber Shiva monkey
6     Cave of Wonders (lamp) Get the lamp       None
7.    Fly out of cave        Escape from cave   None
8.    Inside the lamp        Find the Genie     None
9.    'Good' Palace          Capture Jafar      Iago
10.   Marketplace            Fight to palace    Razoul 2
11.   'Evil' Palace          Destroy Jafar      Jafar

There were also plans for different levels and bosses for the Sega CD version of the game, which we’ll get to in the Sega CD section. The level structure survived mostly intact, with a few notable changes:

  • Both Gazeem and Razoul appear on the rooftops, with level 1 having no boss.
  • The Cave of Wonders sequences seems to have been streamlined a bit, into an on-foot escape sequence leading into the carpet escape sequence.
  • The marketplace fight toward the palace is gone, transitioning straight from the Sultan’s Palace to Jafar’s Palace. There was also a second encounter planned with Razoul for this stage.

No traces of the missing marketplace level remain, so it’s possible that it was never started, likely either due to development timeline constraints or ROM space constraints.

Player Mechanics

There were quite a few changes to player mechanics, in between this design doc revision and the final game. Some of the more interesting highlights include:

  • Aladdin was not intended to be able to attack or throw objects while falling, and rather only when jumping, presumably during the upward arc. This certainly would have resulted in a very different game!
  • The design doc specifically calls out that Aladdin’s sword slash will not be used to block hand to hand and sword attacks from enemies, but this seems to generally be the opposite of behavior at retail, and is often a vital part of avoiding damage from guards.
  • Holding different directions on the pad was originally intended to allow Aladdin to target thrown objects in the directions of up-left, up, and up-right.
  • The delay to shift the view up/down when holding up/down on the pad was originally specified as 3 seconds each.
  • Even in the non-CD version of the game, melons and rocks were intended to be throwable objects for some levels in addition to apples. Although not mentioned in the document, lemon projectiles were also in the game at some point. Speculatively, with rocks being intended to show up on levels like the desert, the idea of stoning people and animals to death may have been received poorly by Disney!
  • Aladdin was to be dropped into some levels by the Genie. I’ve located a pair of animations that look like they were meant for this sequence.
  • Additional idle animations were planned, even for the cartridge version of the game:

    Thought bubble appears above Aladdin containing a graphic of the princess (only after he knows the girl in the market place was Jasmine) to re-enforce that he wants to see her again.

    Thought bubble appears above Aladdin containing a graphic of the girl he rescued in the market place. (only after he rescues her but before he finds out she is the princess – this may change depending on how Razoul is re-introduced into the game at the expense of the Apple Merchant)

    Carpet flies in and gestures to the player to get with the program. (only after cave level)

  • It was planned that when Aladdin’s health lowered to a certain point, on outdoor maps, several vultures would appear in the parallax layer and “circle in anticipation of failure”.

On the whole, things seem to have worked out for the best in the retail game, although directional throwing and extra throwables, as well as the pure aesthetic additions, could have been fun!


As indicated by the enemies that I found in the source art, there are quite a few differences between what was laid out in the design doc and what made it to retail. Rather than laying out a central list of enemies and specifying them by level, the document defines unique enemies within the scope of each level.

The design effectively calls out completely different enemy characteristics and scenarios in a great many cases. Some of the highlights are:

  • The “short tubby round” guards were to intended to swing a stick as their attack, while the “tall thin lanky” guards were to throw knives. Attacks ended up being swapped between the two at retail.
  • The larger guards, in addition to the taunts which survived to retail, were intended to mix up attacks between high and low. Aladdin was to be able to duck under or jump over these attacks.
  • Fat ladies were intended to make an appearance in the marketplace:

    They run left/right being chased by a mouse, and will run over Aladdin if he doesn’t get out of the way (jump over). Fat ladies cannot be killed.

  • The circumstances and pacing of the Razoul battle were originally quite different:

    Razoul will be standing on the roof of the prison building. The width of the building will take up about 1/2 of the screen, and Razoul will be seen behind a wall, so that only his upper torso will be visible, on either side of the roof will be a pile of barrels stacked in a pyramid.

    Razoul will pace back and forth on top of the roof. Since the building will be in the center of the screen Aladdin will be able to climb up the sides by using a series of platforms on the sides of the building, and edges of the screen. The platforms will allow Aladdin to get below, and to the side of Razoul, or by jumping from the upper most platform, just above him. Aladdin will not be able to get on the roof.

    When Razoul gets to the edge of the roof, he will push a barrel off the edge. The barrel will roll downwards, from platform to platform, until it reaches the ground (like in Donkey Kong) and falls into a hole in the center. Razoul will push a barrel off every second or so. Razoul will continue to roll barrels until Aladdin runs to the opposite side of the roof, and then will run to the other side of the roof and start pushing barrels again.

    Razoul can only be hit while he is running from side to side. When Aladdin is on the upper most platform, Razoul will throw knives at him. The knife throws will be between pushing off barrels, making sure Aladdin does not stay in one place for too long.

    The barrels will damage Aladdin, and can not be destroyed expect for specially colored ones, which can be destroyed using a sword slash to revel bonus items (health, tries, etc..). In order for Aladdin to defeat Razoul, he will have to run from side to side, and up the platforms on both sides of the building. In the center of the ground will be a hole over which Aladdin will have jump or lose a try. Above the center of the ground will be a canopy that will prevent Aladdin from throwing any object directly up at Razoul.

  • A “green with yellow hoops” variant of the snake was planned.
  • Periodic attacks from Iago’s cousins (differing from Iago in the color of their plumage) were planned:

    Each of Iago’s cousins can carry one red vial in their claws. Red vials explode on impact with anything. They fly onto the screen, try to line themselves up above Aladdin and then drop their vial. They then fly off screen again (carry on in the direction they were heading when they dropped the vial).

    The vials damage Aladdin if they land on him. Aladdin can also walk into the puff of smoke if a vial lands in front of him and he will still take damage, the puff of smoke will disappear after 0.5 seconds.

  • Mirage enemies were planned for the desert level, which would shimmer in and out, taking the appearance of existing enemies. Mirages can both harm and be harmed by Aladdin.
  • The Prisoner enemy that was unearthed from source art was originally intended to appear in robes with a black and white striped turban. He was also intended to be the size of Aladdin, rather than the very tall, lanky character we see now, and have an additional chain-swinging attack.
  • Bats were originally outlined as having a special dive bomb attack.
  • It was planned that one of Iago’s cousins would fly by and drop a vial on one of the skeletons in the Sultan’s Dungeon, as an initial encounter to help justify the fact that skeletons were coming back to life throughout the level.
  • Golden Monkeys were originally planned for a different gold Cave of Wonders level, where the cave would be filled with golden coins, gems, and other treasures. The Golden Monkey was likely removed when it was decided to cut this level, with his behavior being appropriated over to the Shiva statue.
  • Stone Monkeys were planned for the second Cave of Wonders level, which would have behavior identical to gold monkeys, but they would throw stones instead of coins/gold/jewels.
  • The Shiva statue that appears in the Cave of Wonders with the Gold/Stone Monkey design was originally intended to appear in the palace, with the following design:

    Will remain still as most statues do, until Iago flies by and drops a vial on it. It will then magically come to life and begin to attack Aladdin

    She will use her many arms to pull jewels from her headdress and throw them at Aladdin. When jewels come into contact with the ground they will magically burst into flames and burn for 2-3 seconds. Each time she is hit by Aladdin she will lose one of her arms.

    About the same size as Aladdin, but with 8 arms. Dressed in harem pants, a halter top, and a headdress with many jewels set in it. She will still have the color and texture of a marble statue even after she has come to life.

  • Flamingos in the Sultan’s Palace originally had a slightly more hostile mechanic:

    If the player stands too long on a flamingo, it will turn around and peck at him. One of the flamingos will be Iago in disguise, and will always move out of the way just as the player is about to land on him.

  • The Iago boss battle originally had an emphasis on having to use Abu’s precious gems to attack Iago, with that being the only means of pushing Iago further toward the cogs.
  • Jafar in human form was intended to occasionally throw down red vials, which would create a lasting cloud of damaging smoke.
  • Jafar in snake form was intended to have a tongue attack, and would smile when the attack succeeded, with quite a few other attack/behavioral variations.

This doesn’t touch on everything, by any means, and there are still many other subtle differences between design and implementation throughout the game.

Rock, Paper, Scissors

Although no backing code or data appears to remain, we have an entire outline of a Rock, Paper, Scissors game. It’s worth repeating in whole here:

Having entered this bonus screen, the player will see the carpet in the left center of the screen shaking its upper left tassel, Aladdin will be on the right center of the screen shaking his right hand. A Rock with the letter A below, a Paper with the letter B below, and a pair of Scissors with the letter C below will be displayed, centered along the top of the screen.

The rules are identical to the traditional game where each player picks Rock, Paper, or Scissors. Rock is represented by a fist, Paper by a flat hand, and Scissors by holding out the index and middle fingers in the shape of a V. The player will play Aladdin.

While the carpet’s tassel and Aladdin’s hand are seen shaking back and forth (this will continue until the player makes a choice), the player must select one of the three buttons A, B, or C to chose which hand shape he wants to play. After selecting the desired shape, the carpet and Aladdin will both shake their tassel and fist two more times and then, on the third shake, display their choices. Whoever wins will celebrate, and the screen will display the winner.

If Aladdin loses, then the game is over and he will be returned to the same spot he left on the map, and will be invincible for a few seconds (this sequences will also occur after the third play of the game regardless of who wins). If Aladdin wins, the screen will show in graphical (as seen if they were being picked up in the regular game) and/or text (if extra score) form, what he has won.

Then the player will be asked if they wish to play again for a chance to win more, or leave the game keeping the items they won. If the player plays again they may lose the game, and lose the item(s) previously won (i.e. if in the first game Aladdin wins a 1up, and wins 10 gems and another 2 1ups in the second game, then loses in the third game he will loose everything previously won: the 10 gems and the 2 1ups).

A maximum of 3 games can be played during a single visit to this bonus game. Aladdin can only play the second game if he wins the first and can only play the third and final game if he wins both the first and second.

In case of a tie the game will be played over until someone wins.

Rock beats Scissors
Paper beats Rock
Scissors beats Paper
If both positions are the same the game is a tie and is replayed.

1st win: 1up
2nd win: 10 gems, and 2 1ups
3rd win: 1 Genie smart bomb, 15 gems, 3 1ups

Note: we may alter what Aladdin wins according to the difficulty setting in which the game is being played (better winnings for the easier settings). This will be decided during tuning.

Note: prizes are cumulative, if Aladdin wins all 3 games, he will receive 6 1ups, 25 gems, and 1 Genie smart bomb

This seems to have been a very early idea, as we can see where some elements of the description no longer mesh with other design and item mechanics.

ROM Breakdown

Although it doesn’t necessarily end up having a full basis in reality, an attempt was made in the design doc to break down the memory requirements of all of the characters, levels, and features ahead of time. This provides a pretty cool retrospective on how closely designers and artists used to have to pay attention to and respect the technical constraints of their target medium.

2048K – Total Memory Available on Cartridge

Proposed memory usage
480K – 8 Levels @ 60K per level (this covers tileset, triggers, contours…everything…)

132K – 3 Levels with out tile sets @ 44K per level
175K – Music and sound effects
64K – Program,
64K – Sprite tables
64K – Control tables
120K – Intro / interlude / outro / finale sequences (each interlude pic = 4K)
30K – Sega, Disney, Aladdin and Virgin logos
491K – Aladdin and all non level specific characters
369K – Level specific sprites
241K – Bosses
80K – All bonus games
2274K Needed
2048K -___________
226K Over… Hmmmmm.

Per Level breakdown:
11500 Bytes – Background Character Data (Compressed)

32768 Bytes – Background Block references and combinations
1200 Bytes – Floor and sprite trigger information (Compressed)
400 Bytes – Contour information
10699 Bytes – Map data (Compressed)
2171 Bytes – Parallax map data (Compressed)
58738 Bytes Per Level roughly.[This figure will reduce if graphic style is more simplistic or if level sizes are smaller than the maximum size available]

This kind of careful coordination and planning is really a healthy exercise for many reasons, and it’s a far cry from the kind of disconnect we often seem to have between art, design, and programming in game development these days. I wish I could say I never had to yell at an artist for things like putting a giant 4096×4096 texture that is a single solid color into the game, or designers when they just assume everything will get fixed for them at some point when they find themselves creating 3 minute load times. I’ve used “your blank texture is larger than an entire game was 20 years ago” as my words of shame before.

3.7. Sega CD

A Sega CD version of the game seems to have been planned from the very beginning. Unfortunately, although the design document has many Sega CD callouts, they generally don’t seem to have survived to the source art in our Aladdin archive here. These are all of the CD-specific features and elements that I managed to parse from the design doc:

  • Aladdin in Prince Ali form was planned to appear in numerous additional Sega CD levels. The design doc calls out that Aladdin would only appear as Prince Ali in one level of the cartridge version, and is intentionally omitted to save ROM space.
  • Jafar was planned to have a third Genie boss form in the CD version of the game. No traces of art for this stage exist in our archive.
  • Had the Abu magic bag feature survived to retail, two additional Abu reactions to Aladdin’s use of Abu’s precious gems were planned for the CD version.
  • An Apple Merchant boss was planned to be the marketplace boss in place of Razoul in the CD version, and Razoul would move over to become the boss of the prison stage instead.
  • The desert was planned to have a Sand Scorpion boss in the CD version. No additional design information is provided on this boss.
  • In the second marketplace stage leading up to the Jafar’s Palace (which didn’t make it to retail), a Fire Eater boss was planned for the CD version instead of a second Razoul encounter.
  • An additional snowball throwable item was planned for the CD version.
  • Even more idle animations were planned specifically for the CD version:
    • Genie floats into view and says one of a number of things. (only after cave level…CD version only)
    • Carpet flies in and taps Aladdin on the shoulder and flies off again. (only after cave level…CD version only)
  • A man would sometimes appear laying on a bed of nails obstacle in the CD version, allowing Aladdin to jump off of him once without being harmed. After being jumped on once, gets up “in disgust” and can no longer be used as a stepping stone.
  • Quick sand was planned for the desert level in the CD version:

    As Aladdin walks over certain sections of sand, he will start to sink. Jumping continually will extract Aladdin from the sand and will allow him to traverse these areas without sinking. If the player leaves it too long, Aladdin will sink beneath the sand and loose a try (or end the game if he was on his final try). Quick sand will look slightly different from regular sand so the observant player will be able to anticipate this hazard.

    One particular patch of quick sand leads down into a secret area. To get there, Aladdin must overcome his natural inclination to save himself from sinking into the desert and stay where he is. If Aladdin drops beneath the surface of this particular patch of quicksand, the Scarabs will slide in and out to reveal him in a new area of the desert, probably cavelike (if we have the tiles available), where Aladdin will find an extra life and a continue and various other goodies.

    The visual and gameplay mechanics we will use to get Aladdin back up onto the desert surface need to be specified but will use another Scarab wipe to maintain consistency.

  • Cacti were also potentially planned for the CD version:

    These come in various shapes and sizes (probably two species). We will remove them from the game if we cannot make them feel like they ‘belong’ in Aladdin’s world. Contact with a cactus will damage Aladdin (1 point of damage per contact).

    One type of cactus can be destroyed if an object is thrown at it or if hit be a sword slash. The other, more substantial looking, genus of cactus isn’t going anywhere and can only be avoided, not ‘removed’.

    Both types of cactus will be designed graphically so that many different looking cactus tree can be created without a huge graphical and therefore memory overhead.

  • Swinging clotheslines (in addition to the rather static ropes that can be climbed across) were planned for the CD version of the marketplace.
  • The carpet would have a special animation with flaming tassels after a close call with a fire jet.

CD-based plans also occasionally tie into elements/features that were planned (but didn’t survive) for the cartridge version of the game.

3.8. The Code

There’s a lot to talk about regarding the actual source code. One of the more interesting aspects of the game code itself is that it’s all driven by what is effectively an incredibly lightweight state machine. Things like animation sequences are defined in assembly as seen in this tiny snippet:

; Slither along


	mif_within_X 85,AN_ROLLY_SNAKE_BITE



This is emitting bytes/words for each “command”. Each animation frame is specified by emitting a word, and that word is a pointer into a list of frame pointers near-ish the beginning of ROM. We then have a variety of macros for things like the mif_within_X conditional logic that you see there, which emits an appropriate command byte, with the command bytes conveniently falling outside the value range of the known frame pointer values. The result of that command may then be that the state data pointer is set to something else for the next execution cycle.

Aliens (objects/actors) are driven, for the most part, by having code churn through state data like this. Movement is also handled in a similar fashion, where movement logic is defined by emitting bytes, and each alien is allowed to provide a pointer to its movement state data. It’s also fairly common for animation state data to swap out the pointer to movement state data, so there’s a specific macro used to emit the appropriate bytes to do this.

There’s a sizable amount of code dedicated to running through these tiny state blocks, and managing the actual calculations for things like physics/collisions and even basic movement hierarchy. The player is, of course, his own special case. He makes use of state data just like standard aliens, but he has his own boilerplate assembly logic to handle a great deal of the more complicated state logic, which also takes care to often set the state pointers directly.

Doing things this way simplifies the work involved in adding new objects, and it helps keep memory costs down by minimizing the amount of new code needed for each object and by packing logic into reasonably efficient state commands. Combined with the fact that the actual state logic is kept very simple and there are special-case macros for all of the reasonably complex logic cases, this is a great system for a game of Aladdin’s scope.

Beyond that, we have a lot of boilerplate code to handle system-level things like DMA transfers to VRAM, with a routine named “DMA_IT” being the heart of where all of those Chopper tiles we looked at earlier end up getting blasted into VRAM. Chopper has been designed to minimize the cost of this pretty effectively, avoiding CPU decompression costs while still trying to cut down on the number of unique tiles per frame of animation. I haven’t actually profiled Aladdin to see how many cycles are typically spent where, but based on the end result, I’d say it’s doing its job well enough.

We could deep-dive into countless systems here, but without going into too much detail, these are the more notable high-level goings-on in the Aladdin codebase.

With all of that said, here are some other random points of interest that I took note of as I was exploring:

  • There’s a MAKEDEMO assembly-time variable that can be set to on, to record demos. When recording, the game actually writes controller commands at each frame into VRAM. You can see the background tiles gradually corrupting as the demo records, which is fun. Once the designated VRAM buffer is full, the game copies the data back out of VRAM over to main RAM, then spins in place (because it’s just demolished main memory) forever so that you can attach a debugger and dump the demo data from a known address. I created a custom demo this way, just for fun.
  • More demo fun facts: The demo data itself is just a raw stream of controller inputs for each frame, and both demo recording and playback force a random seed of “12345678” to ensure deterministic results.
  • There’s also a MASTER assembly-time variable, which looks like it was actually set to OFF for the retail distribution. When set to ON, it disables parts of the cheat screen that survived at retail, but the code does not assemble without modifications when it’s enabled. One might therefore speculate that the cheat screen (still containing phone and fax numbers) wasn’t actually intended to be left on for the retail distribution.
  • Cheat codes are listed out among a lot of other static data in a file called TABLES.68K, and are read one byte at a time with the cheat code logic incrementing a pointer to the appropriate cheat code table and resetting it back to the beginning when the wrong input is pressed. There are no additional (beyond what’s already known/documented) hidden/disabled-at-retail cheat codes residing in the source.
  • When recording video for this article, I wanted to disable the high-frequency flicker that occurs when Aladdin gets hurt, to avoid having him disappear entirely for multiple frames when downsampling video to lower framerates. Locating the bit of code in question, I discovered an “IF TO_DEMO=OFF” assembler check around it. Apparently I wasn’t the first person to encounter this problem when recording promo footage! TO_DEMO appears to have been left off for the CES demo build, or this particular bit came as a later addition, based on the fact that the flicker still occurs in that build. (when invincibility is not enabled)

I don’t know about you, but this stuff sure makes me miss the golden days of game development.

4.0. What’s Next?

Every game has a story, and sometimes binary speaks louder than words. But source code usually speaks even louder! We’ve already lost a lot of fascinating video game history to cancelled prototypes, discarded demos, and hardware failures. Unless we start considering preservation and archival more seriously in the video game industry, especially when it comes to hardware-based DRM technologies, we stand to lose even more than we’ve already lost.

I started this project with a mind toward wrapping up the Aladdin archive in question for proper preservation, taking the first steps toward standardizing source curating and archival at the VGHF. That meant documenting the source code from a high level, in order to establish its intended target(s) and any external dependencies on other tools and/or data so that we could also start tracking those dependencies in a standardized way. In doing this, it became quickly apparent that Aladdin had quite a story to tell. I expect it’s the first story of many, and I can’t wait to see what pops up next!

Until next time…