Tips for Converting HyperCard stacks to HyperCard IIGS (HCGS)

HyperMover GS 1.2

Apple's HyperCard was a powerful Macintosh application development tool conceived by Bill Atkinson that was freely available for MacOS 6 through MacOS 9. In 1990 Apple released HyperCard IIGS 1.0 for their IIGS platform, and then its only official update v1.1 in 1992. HyperCard IIGS (aka HyperCard GS or HCGS) was based on HyperCard 1.2.5 though it sported color and even had some features like button families that were later added to Macintosh HyperCard. By that time thousands of HyperCard stacks had already been created and were available from online services so Apple developed a utility called HyperMover to facilitate the conversion of HyperCard stacks to HCGS and vice versa. HyperMover consists of a pair of stacks that work in together to disassemble and reassemble stacks. (Note that stacks created for Roger Wagner Publishing's HyperStudio application are not compatible with HyperMover or HyperCard.)

MacTech magazine's technical section described HyperMover this way (information likely provided by Apple employees Tim Swihart and Matt Deatherage):

____

HyperMover allows HyperCard 1.2.5 stacks from the Macintosh to run with little or no modification on the Apple II GS with HyperCard IIGS. HyperMover consists of two stacks, one for the Macintosh and one for the Apple II GS. HyperMover for the Macintosh (aka Macintosh HyperMover) creates a folder containing files that describe the stack you wish to convert to the II GS. This folder and the files it contains are then transferred to the II GS via Apple File Exchange or an AppleTalk network. HyperMover for the IIGS (aka HyperMover IIGS) then rebuilds a stack as close as possible to the original stack using the files contained in this folder. The most noticeable difference between the original and the rebuilt stack will be in the graphics. Because the IIGS and the Macintosh have such different sized screen displays, the graphics and objects of the rebuilt stack must be scaled to fit the IIGS screen, resulting in some loss of detail.

HyperMover contains several features designed to make the rebuilt stack as useful and as close to the original stack as possible. It can create scaled representations of Macintosh pictures, convert Macintosh sounds to IIGS sounds and Macintosh icons to IIGS icons, and transfer all HyperCard objects including backgrounds, cards, buttons, and fields and their attributes. However, because HyperMover is a stack, it cannot convert XCMD/XFCNs and cannot fix scripts that need specific Macintosh screen coordinates to function.

____

This is a nice summary of what the HyperMover stacks do, but the opening statement "HyperMover allows HyperCard 1.2.5 stacks from the Macintosh to run with little or no modification on the Apple II GS with HyperCard IIGS" is a marketing exaggeration. Also since Apple continued to enhance HyperCard for several years and chose not to further develop HyperCard GS or the HyperMover stacks, the conversion of HyperCard stacks now becomes even more complicated because Mac stacks may contain objects that have properties, property values, and script syntax that was introduced in HyperCard 2 and is unknown to both the HyperMover stacks and HCGS.

Back in the 1990's I taught what was possibly the first online course on HCGS and published stacks in Script-Central. Since then I have converted many of Apple's HyperCard stacks to HCGS, published my own issues of Script-Central Special Edition, and have released my own update to the HyperMover stacks, version 1.2. I have also created several resources along the way to assist in stack conversions just in case anyone in the future wants to convert a stack from Mac HyperCard to HCGS. This blog post and the resources it refers to should be useful to anyone attempting to use HyperMover. This is intended to be a practical guide based on my decades of experience with HCGS but will not be exhaustive as I had no role in the development of HyperCard, HCGS, or HyperMover and have never been or will be an Apple employee, nor do I have inside knowledge or am omniscient (if I was, I guess I would know it). To further demonstrate the conversion process and its pitfalls, the Macintosh HyperCard stack Concentration version 2.2 by Sioux Lacy will first be enhanced and then converted to HCGS. These stacks and other resources I will refer to are available for download from my Silverwand Software site.

HCGS BugTracker 1.4

In addition to this blog post one of the most important resources to read if you are considering converting a stack is the article included in the HCGS.BugTracker stack on the differences between Mac HyperCard and HCGS. This article is also published in this blog post: https://bbellina.blogspot.com/2026/02/hypercard-iigs-bugtracker-documents.html

The Software Versions

Macintosh HyperCard 2.4.1 (the final release from Apple)

HyperCard GS 1.1 (the final release from Apple), though unofficial release 1.2 (read about it here) could be used as well and does correct a bug in the HCGS 1.1 date routines that Apple corrected in Macintosh HyperCard.

HyperMover 1.2 released by Brendan Bellina in 2024 and available at the Silverwand Software site in Script-Central Special Edition v9n4 for the IIGS and a DiskCopy 6 disk image for MacOS.

Why not HyperMover 1.1 or 1.1u?  HyperMover 1.1 has serious bugs that alter the ordering of objects in the stack. Any stacks that refer to objects by number - which many do - may not convert properly. HyperMover 1.1u was distributed on Script-Central issue #3, however Script-Central did not release a Mac version, so in order to use 1.1u you have to first run the IIGS 1.1u patch stack through HyperMover GS 1.1 and then rebuild it with Mac HyperMover 1.1 so that it can then be applied to the Mac HyperMover 1.1 stack to patch it to 1.1u. While explained in a later version of Script-Central it is kind of a mess to do. Also, version 1.1u of HyperMover still contains a number of bugs and does not handle a number of button and field properties which are handled properly in HyperMover 1.2. The fixes made in 1.1u are included in 1.2.

Determining if a Macintosh HyperCard stack is a Good Candidate for Conversion to HCGS

There are many reasons why a Macintosh stack may not be a good candidate for conversion.

Locked or otherwise password protected stacks cannot be converted by HyperMover. There are stacks that can be used to view the scripts of protected stacks, and using those may allow you to rebuild a stack manually.

Stacks that are applications cannot be converted. An application stack would need to be converted to a normal HyperCard stack in order for HyperMover to disassemble it.

Stacks that rely on the non-standard card sizes introduced after HC 1.2.5 cannot be converted. If the stacks can be redesigned to use the standard 512x342 card size then HyperMover can disassemble them.

Stacks that rely heavily on Mac only externals (XCMDs and XFCNs) will require significant post-conversion work because externals cannot be migrated by HyperMover.  There are over 100 IIGS externals that were developed and it is possible that the functionality provided by a Mac external can be met with a IIGS external or HyperTalk script.  The stacks HCGS.Xtras (which is a collection of all HCGS externals) and HCGS.BugTracker and the document "Mac HyperCard Resources" on the HCGS Best of 32 MB image available at the Silverwand Software site can assist in identifying substitutes.

Stacks that heavily rely on HyperCard 2 features may require significant post-conversion work.  Alternatives for some features have been developed in stacks and are available on the HCGS Best of 32 MB image available at the Silverwand Software site. The HCGS.BugTracker stack includes an article on the differences between HCGS and Mac HyperCard (also found here) and suggests many replacements for HC features and syntax changes that may be needed in HyperTalk scripts when converting from Mac HC to HCGS since there are several inconsistencies between Mac HyperTalk and IIGS HyperTalk.

• MenuMaster to help implement menus (only HC 1.2.5 menu style can be used, not the HC 2.0 menu style)
• BalloonMaker GS to help implement balloon help (this provides limited functionality using hidden buttons and fields)
• HCGS.Palettes to implement navigation palettes in HCGS (note that these are more limited than Mac palettes and require the stack be structured in specific ways. Template stacks created by Brendan Bellina can be used to assist in developing stacks that use the navigation palettes.)
• FastTalking to implement talking within a stack using the ByteWorks Talking Tools (far more limited that the MacinTalk speech capabilites.)
• HyperTexting to implement hypertext behavior in a stack
• Marking.Cards to implement marking cards in a stack
• MultiFontDemo to implement a font that allows both plain and underlined text in a single field
• PopUp buttons
• A number of scripts and functions published in Script-Central Special Edition issues to mimic Mac HyperCard commands and messages missing in HCGS such as exitField.

Stacks that are highly dependent on graphics will not convert well. HyperMover scales background and card pictures to match the 320x200 HCGS screen and they rarely look good enough to use and generally have to be redone from scratch.

Stacks that rely on Mac HyperCard 2 ability to use multiple fonts and font faces within a single text field. HCGS lacks this ability. The MultiFont font can be used to allow combined plain and underlined text, but only in its typeface. See the MultiFont stack for more information on use of this font.

Stacks that use non-standard fonts for text fields or displayed button names. HyperMover cannot migrate font resources and Macintosh fonts may be difficult to convert. Mac HyperCard allows fonts to be attached to a stack and used without requiring them to be installed in the MacOS system folder. HCGS does not have this native ability, though the FontZ XCMD by Richard Bennett published in Script-Central #18 and also available on the HCGS Best of 32 MB image can be used to attach bitmap fonts to HCGS stacks. A stack developer should be aware that the standard fonts available in HCGS are not the same as MacOS. The standard fonts for HCGS are:

• Courier 10, 12 (a full install will also include 9, 14, 18, 20, 24)
• Geneva 10, 12 (a full install will also include 14, 16, 18, 20, 24)
• Helvetica 10, 12 (a full install will also include 9, 14, 18, 20, 24) 
• Shaston 8, 16
• Times 10, 12 (a full install will also include 9, 14, 18, 20, 24)
• Venice 14 (a full install will also include 12, 24)

Stacks that rely heavily on custom icons. HyperMover can be allowed to attempt to convert icons but the results will generally look terrible and just take up space in the resource fork of the target stack. It makes more sense to utilize standard icons or make custom icons on the IIGS using the Icon Editor stack. Unfortunately many of the standard Mac HyperCard icons are not built into HCGS, even though many can be found in Apple's stacks. Also, icon IDs are not consistent between Mac HC and HCGS. Resources available to assist in dealing with icons include the stacks HCMacIcons and TheMissingIcons on the HCGS Best of 32 MB image.

Custom cursors can be migrated from Mac HyperCard stacks but because of the screen resolution differences they will be appear much larger in HCGS than they appeared in Macintosh HyperCard.

HCGS Button Field Probe

HC Button Field Probe

There are a small number of button and field properties that were available in Mac HyperCard that are not available in HCGS and are not handled properly by HyperMover. Generally these will not be critical but may need to be addressed in the target stack. To easily identify these properties use Brendan Bellina's HCGSBtnFldProbe and HCBtnFldProbe stacks.

In the 1990's conversion of Macintosh stacks that do a significant amount of heavy processing would not be recommended because HCGS is slower in execution than Mac HyperCard. With modern emulators this is no longer a significant reason to avoid conversion of a stack. Only a small number of purists are likely to be using physical unaccelerated hardware from 40 plus years ago.

While the above are all technical reasons, the most important reason that a stack would not be a good candidate is if the person attempting to convert it is not intimately familiar with it. Familiarity is crucial in order to determine what pre-conversion changes should be made, what post-conversion changes will be necessary, and what testing will be required. Ideally the person converting a stack should be its author and a stack would be developed knowing that it would be converted.

Notable

Understanding all of the above, it is possible to get close to feature parity on both platforms in many cases. Examples of my own stacks that do so include my Merlin stacks (MerlinGS/MacMerlin), my Eliza (TheDoctorIsIn) stacks, Notable, the Button Field Probe utility stacks, Balloon Maker, and the slot machine stack One Arm Bandit.

With HyperMover and some creativity and patience I have been able to make many stacks available for both Mac HyperCard and HCGS, including Script-Central's HyperSonic (converted from HCGS to Mac HC), Cyan's MenuMaster,  Sioux Lacy's Groupies 3.2, the Apple Guidelines stack, the Apple HCGS Course stack , the Apple //c Plus Technical Look stack, the Apple HC Supplement 1987, the Apple Phone Dialer stack, the Apple Readymade Fields stack, the Apple Readymade Buttons stack, the Apple Stack Templates stack, the Apple BackgroundArt stack, and Joseph Terrari's GraffitiMaker. All of these and more are available on the HCGS Best Of 32 MB image and issues of Script-Central Special Edition, all freely available at my Silverwand Software site.

ACK v2024

In many cases conversion becomes an opportunity to enhance stacks such as I have done with Mark-Jason Dominus's Adventure Construction Kit (ACK) v2024 allowing the creation of my text adventure stack "ESC from LaLaLand", Andy Burns' BingoCaller stack, Apple's Graph Maker stack, and Sioux Lacy's Concentration v2.2 (the topic of the remainder of this post), all of which are available on the Silverwand Software site.

In addition to my work with HyperMover and stack conversion, HangTime also converted several stacks using HyperMover and released them on the 1993 and 1994 issues of Script-Central.  Geoff Weiss converted John Stiles' LOGO v2.1 stack to HCGS adding many features.

Enhancing and Converting Sioux Lacy's 1987 Concentration version 2.2 stack

Concentration version 2.2 is a memory matching game by Sioux Lacy. The game deals 52 cards from a standard deck of cards face down and the object is to eliminate pairs of cards by matching them on their card value (2's, 3's, 4's, etc.). I chose this stack for conversion for a few reasons. First, its author Sioux Lacy worked at Apple, developed the Groupies utility stack, and knew the members of the HyperCard development team, so it feels historically significant. Second, it is a simple stack that consists of only 4 cards and one background with no graphics, and so seemed a good technical candidate. Third, I recently learned of SK8 which was an internal prototyping tool used at Apple that was based on HyperCard and in its documentation a similar Concentration game is suggested that matches on sound effects rather than images; knowing of no Concentration games on Macintosh or IIGS that matched on sound effects I decided I could add this capability to Concentration version 2.2 fairly easily.

It didn't take long to create Concentration GS (G for graphics and S for sound), an enhanced version of Concentration v 2.2 that allowed matching on sounds in addition to card values. At the same time I made a small number of changes to the stack to take advantage of button families, added code to check for minimum required HyperCard version, corrected a few bugs having to do with global variables not being cleared properly, and added a new preference setting to disable flashing when a match was found as flashing can trigger seizures for some people.

Concentration GS (Mac HyperCard 2.4.1 version)

Concentration GS About...

Concentration GS Instructions

Concentration GS with cards dealt for a game

Concentration GS showing card values using peek

To assist in development and testing Sioux Lacy included a function "peek", which when typed in the HyperCard message box shows all of the card values. What appears to be graphics is actually implemented using a custom bitmap font called "Deck" which has 52 characters defined with each being a card value over a card suit. The values shown on the cards is actually just the names of the cards using the Deck font. While this is fast and slick the use of this custom font did create a challenge because HyperMover is unable to convert font resources. I do not know the origins of this font but my guess is that it was created by someone with the intent of using it in multiple HyperCard stacks. Randomly assigning values to the cards was done with an XCMD "Deal" and an XFCN "IsMatch" was used to determine when two cards matched. To retrieve sounds from the stack I used the standard Macintosh XFCN "Resources". Since externals also do not convert I knew I would have to find or develop substitutes for these as well.

While making enhancements it is important to understand the potential impact to looping routines of adding or removing buttons and fields. Scripts may assume that they should loop from button n to m on a card, but if you create a new button and move it so it is closer to the card than button n than button n will now be button n + 1 and the loop will no longer work. Consider coding changes carefully.

Using HyperMover

Using HyperMover is the simplest and quickest part of the process, especially when using emulators to convert stacks with a small number of cards.

For my HyperCard work these days I use an old Intel MacBook Air running OS X 10.11.6 (El Capitan). I use the MacOS emulator SheepShaver running MacOS 9.0.4 and HyperCard 2.4.1 and Eric Shepherd's Sweet 16 IIGS emulator running System 6.01 and HyperCard 1.1 simultaneously and since SheepShaver can access a host folder as a drive and Sweet 16 supports dragging and dropping files from the host into Finder windows, it is very easy to move files back and forth.

Because the stack contains no unique cursors or icons and no significant art I chose the following HyperMover v1.2 settings when dismantling/disassembling the HyperCard stack:

HyperMover settings for disassembling the stack

After conversion I moved the created folder to my IIGS and checked the Resources.txt file to see what was not converted, just to ensure I didn't miss anything. As expected I saw that the Deal XCMD and the IsMatch and Resources XFCNs where not converted. HyperMover doesn't tell you about fonts though, you have to figure that out for yourself. Fortunately sounds are converted and for the most part will sound correct on the IIGS, although they should be tested with the play command after conversion just in case they did not convert correctly.

Resources,txt lists what cannot convert... mostly

I then used the following HyperMover GS v1.2 settings to rebuild/assemble the HCGS stack:

HyperMover GS settings for assembling the stack

Once HyperMover has successfully rebuilt the stack the real work begins. In addition to the XCMDs, XFCNs and other resources that won't convert, there are a large number of syntax and behavior differences between HyperCard and HCGS and extensive testing is required to find these issues and resolve them.

Upon first launching the new HCGS ConcentrationGS stack the following occurred:

There be errors here

In addition to the error a number of other issues become immediately evident.  First, the conversion of graphics and painted text is not very good and will need to be either touched up or redone entirely. Second, while HyperMover does a decent job of rescaling buttons and fields, because the font is changed to Shaston 8 the names of buttons may no longer appear correctly. In addition while HyperMover changed the icon of the home button to a HCGS home icon, it isn't actually the correct one, and some buttons are missing their icons entirely. These kinds of errors are fairly typical after stack conversion. Generally icon issues are easily resolved by assigning icons to the buttons as long as the scripts were not changing the icons by icon id. When assigning icons be sure to use icons that are standard HCGS icons present in HyperCard itself or the standard Home stack, otherwise you will need to import the icons into your new stack so others see them when using it.

Another likely cause of errors when converting old HyperCard stacks is the likely heavy use of card id's rather than card names. In HyperCard referring to objects by id is the fastest way to access the object. Using number is problematic if objects are added, deleted, or moved closer or further. Using name is most legible but also the slowest method. Because using ID is the fastest way, many old Macintosh stacks will eschew using names for backgrounds, cards, and even buttons and fields, making the script much harder to understand to anyone but the author.  HyperMover tries to maintain the ID numbers of objects when it converts a stack so that script changes will not be required, but it is not always possible to do so, particularly with the IDs of backgrounds and cards.  With the conversion of ConversationGS the background and cards in the rebuilt stack have different IDs than the original stack.

Mac BG ID: 2566

Mac Card ID:

3238

2833

3749

2502

IIGS BG ID: 2728

2832

3876

4547

4877

HyperMover is smart enough to automatically adjust scripted lines that look this this:

go to card id x

but more complicated lines like this will not be adjusted and would have to be corrected manually:

if short id of this card is x then ...

This kind of code is often used in openCard or closeCard scripts to hide or show card specific objects. If the wrong id's are referenced then cards may have objects on them that they shouldn't, for example in this card the "New Game" button.

If the converted stack uses ID's then it is important to review all of the script in the stack and correct any lines that refer to the source stack ID numbers. What I generally do is also add a comment to any line that references an ID with the name of the object so it is easier to read and understand the code. Comments do not slow down HyperTalk execution though they do count against the 32k script length limit so they should be used sparingly if the script of an object is lengthy.

After cleaning up graphics, painted text, button and field fonts, missing icons, etc. the stack begins to look a little better. This is also a good opportunity to add a little color and adjust the behavior of buttons to auto-hilite (the Mac default is to not auto-hilite) or provide aural feedback when clicked.

Any card that displays help text or instructions should also be examined because it is likely that the fonts will need to be changed, field sizes altered, and text edited.

The single player and two-player game cards in the stack also required a little clean up due to the fonts and field sizes. The addition of a little color is also a good idea and can make a HCGS stack look more polished.

 

Depending on your interests as a developer you might prioritize clean up and display over correcting the scripting issues, but eventually any missing fonts, XCMDs, and XFCNs will need to be addressed.

Addressing the missing font "Deck 12"

The 12 point size of the font Deck, a bitmap font, was used as a custom resource in the Concentration stack so that card suits can be displayed without using graphic images. Ideally it would be a simple matter to extract the font from the stack using ResEdit and then use it with the IIGS stack.  However there are several issues that make this more challenging:

• Macintosh bitmap fonts are not the same format as IIGS bitmap fonts (Thanks, Apple). Per Andy McFadden, "IIGS fonts are Mac fonts with an extra header and reversed integer byte order" (more info can be found at https://ciderpress2.com/formatdoc/BitmapFont-notes.html)
• HCGS does not natively recognize fonts attached as a resource to the stack. In 1991 Richard Bennett released a HCGS XCMD FontZ which can be used to load a IIGS bitmap font in an HCGS stack resource fork into memory. FontZ was published in Script-Central issue #18 and can also be found in the HCGS.Xtras stack on the HCGS Best of 32 MB image. In my experience it usually works well with fonts with simple names, but fonts that have complex names may not work. Also if HCGS is having memory issues then a font may not load properly. For these reasons it is best to always include the font separately from the stack so that it can be installed into the Systems:Font folder if needed.

Now I did attempt to extract the font from the Macintosh stack and convert it using a number of vintage Mac and IIGS font utilities but I was unsuccessful.  I did some searching online and found that the font was included in the "2000 Shareware Fonts Archive" at macintoshrepository.org, I then asked friends in the Apple II developer community if anyone could convert the font for me and Kelvin Sherlock was kind enough to provide a font Deck.IIGS. Using FontZ I attached the font to the HCGS stack but will also include the font with my distribution of the stack so that it can be installed in the System:Fonts folder if need be.

Examination of the Deck font revealed that it uses ASCII codes 39-90 for the 52 cards with each suit of 13 cards (2-Ace) immediately following the prior suit. Examination of the Deck.IIGS font revealed that it uses different ASCII codes: 65-90 (A-Z) for hearts and spades and 97-122 (a-z) for diamonds and clubs. So while the font appears the same, it is in fact not the same. Since the Deal XCMD and IsMatch XFCN need to be rewritten for the IIGS, understanding the differences in the fonts is essential.

Replacing the Deal XCMD

When Macintosh stacks use XCMDs and XFCNs then you may have to experiment with them to determine their behavior so that you can adequately replace that functionality with a IIGS external or script. The HCGS.Xtras stack is a comprehensive collection of over 100 HCGS externals (all I could find) and as far as I know there is no equivalent to the Macintosh Deal XCMD. Theoretically a IIGS XCMD can be written in C or Pascal but this is not my area of expertise and I prefer to use HyperTalk. Generally the significant advantage of an external is processing speed, but since most stacks will be run on emulators speed is not a significant factor any longer.

The Deal XCMD is used in the Macintosh stack background script setup handler like this:

Deal 1, random(52), 52

Lacking the source code or any documentation in the stack I had to rely on the results of the command to determine what the replacement script should do in the HCGS stack. Following the execution of the Deal command background field 1 (the first parameter) would contain a 52 character string consisting of the characters 39-90, with each character only included once - so basically a shuffled deck of 52 cards. Each of the 52 buttons on the card in sequence would then be named with a character from this string. The font for each button was set to the Deck font, so displaying the name of the card will show the value and suit of the card.

Replicating this behavior in HCGS required looping from 1 to 52, putting the correct ASCII codes into a comma separated variable, then using the sortContainer XFCN to randomly sort that variable, and then looping from 1 to 52 again concatenating each character into a variable that was then put into the background field 1. While setting the card names based on background field 1, if the suit is hearts or diamonds I also set the textColor of the button to red, otherwise it is set to black.

Replacing the IsMatch XFCN

To determine if two cards have the same value the Macintosh stack uses an XFCN IsMatch. The background cardsMatch handler calls the XFCN like this:

return IsMatch(the short name of card button x, the short name of card button y)

Lacking the code for the XFCN I do not know exactly how the XFCN is determining if two cards have the same value. While a series of if else statements would work ideally the solution should be as efficient as possible. I decided to math it. Because each suit contains 13 cards in the order 2-Ace, then as long as the 6 character gap from 91-96 is eliminated then any two cards will have the same value if the difference between them is evenly divisible by 13. The code looks like this:

put charToNum(short name of cd btn x) into x_num

put charToNum (short name of cd btn y) into y_num

if x_num > 90 then subtract 6 from x_num

if y_num > 90 then subtract 6 from y_num

return ((abs(x_num - y_num) mod 13) = 0)

(note that the abs() function I used is actually not necessary and the last line could just be:

return (((x_num - y_num) mod 13) = 0)

which would be slightly faster.)

Considering that the Macintosh Deck font doesn't have the gap, it would have been even simpler and faster to handle this mathematically. The following line would have served as well as the XFCN:

return ((charToNum(short name of cd btn x)-charToNum(short name of cd btn y) mod 13) = 0)

A possibly even faster way might be to calculate the absolute value of the difference and then check if that is equal to 13, 26, or 39, which would avoid using mod.  Like this:

return (comma & abs(charToNum(short name of cd btn x)-charToNum(short name of cd btn y)) & comma is in ",13,26,39,")

But What About Sound?

For the assignment of random sounds to the cards the Macintosh stack using the XFCN "Resources" which is an Apple provided XFCN which can return the list of resources within a stack. Apple provided a similar XFCN for HCGS called "CurResource". Unfortunately while these XFCNs serve the same purpose, they do not use the same parameters or return data in the same format. For that reason I wrote a wrapper script for the "Resources" XFCN which is used in the Macintosh stack, so that it returns the list of sounds in the stack in the same format that the IIGS "CurResource" does. Of course I could have written a wrapper for "CurResource" instead but at the time I first worked on this issue I was converting the HCGS HyperSonic stack to Macintosh HyperCard, so a wrapper in the Macintosh stack made more sense.

The other difference to address is that the Macintosh HyperCard sort command can be used sort the contents of containers and lists. Unfortunately the HCGS sort command is more limited, so the sortContainer XFCN must be used instead. This was needed when sorting the sounds randomly for assignment to the cards.

In post conversion testing I did find that 2 of the sounds were corrupted in the HCGS stack, so I deleted those sounds and added two others using John Miller's "resCopy IIGS" stack.

Wrapping It All Up

As can be seen from this conversion of ConcentrationGS, while HyperMover can help with the conversion process, there is much more than needs to be considered, even for fairly simple stacks.

Anyone interested in playing ConcentrationGS (sound matching is fun) or examining its scripts can download both Macintosh and IIGS stacks from my Silverwand Software site.

Happy scripting and happy Marchintosh!

HyperCard IIGS BugTracker documents

The HyperCard IIGS BugTracker stack was developed by Brendan Bellina to provide information about known bugs in HCGS, errors in the HCGS Script Language Guide, and also provide information about differences in Macintosh HyperCard 2.4.1 and HyperCard IIGS 1.1. Several documents are included in the stack that can be helpful to a HCGS developer. Several of those are also shared in this blog post. The stack is included in the HCGS Best Of 32 MG image available at the Silverwand Software site.

The following documents are included below:

Apple's HCGS Technotes

    HCGS Technote #1 - Corrections in the Script Language Guide

    HCGS Technote #2 - Known HyperCard IIGS Bugs

HCGS Script Language Guide Errata - B Bellina, May 2024 revision

Common Mac HyperCard and HCGS HyperTalk Differences - B Bellina, Nov 2024 revision

Return to Faerun: The SSCAE Campaign for NWN2

It has been almost 8 years since actively working on my Neverwinter Nights 2 campaigns. During this time the NWN/NWN2 community has continued at neverwintervault.org and I have only periodically chimed in on the forums. However, with the completion of my HCGS and Apple II development efforts, I think it reasonable to turn an eye my never completed projects for NWN2, despite the slow decline of players and loss of many regular contributors.

By 2017 I had published two Neverwinter Nights 2 campaigns, released significant mods for the NWN2 OC and MotB, and uploaded a large number of items and scripts intended to help other NWN2 modders. I had contributed to other campaigns and had two campaigns of my own in development - Gems of Power and Farlong and Away.

Gems of Power was intended to be campaign set in Faerun that involved time travel with multiple areas being accessible in different periods of time. My thinking was that seeing the evolution of areas would be interesting to show. This required a significant amount of research and after mapping out a general plot I began building the starting areas.  Then I got distracted by other efforts and it was left in that state.

The Farlong and Away campaign is also set in Faerun and takes place in 1345 DR shortly before NWN2. It details the adventuring of the Farlong brothers Duncan and Daeghun. (Read more about it here: https://bbellina.blogspot.com/2017/01/farlong-and-away-new-campaign-for-nwn2.html). Unfortunately while I did significant research, sketched out the plot, and did a little proof of concept this effort also stalled due to circumstances of life.

This year NWN2 Enhanced Edition was released, and while it is primarily focused on adding console and gamepad support, having it available in Steam means that there are new players and a new platform upon which to release mods, the Steam Workshop. So I have spent some time researching and experimenting with the Steam Workshop, migrating my content to the Steam Workshop, and also developing new items that will work better for players of NWN2 EE. This work has led to my decision to rework my first released campaign - the Silverwand Sample Campaign (SSC).

SSC was released in May 2007 even before the release of the first expansion, Mask of the Betrayer (MotB). At that time most NWN2 modders had been NWN modders and continued to use the techniques they had learned using the NWN toolset. Several stand-alone modules converted from NWN had been released but not a single campaign had been released. I saw a need and decided that while learning the toolset I would intentionally develop a small multi-module campaign that could be played and also serve as an example for other NWN2 modders. I believe the Silverwand Sample Campaign was the first campaign that was released on the old IGN vault. And after doing so I had many conversations in the forums about why a campaign and not a module so that other NWN2 modders would begin to release campaigns. Many NWN2 standalone modules that were released in those days were never converted to campaigns by their authors, so I also published information on how to convert a NWN2 module to a campaign.

After all of this time though SSC is no longer a very good example of how to build a campaign. It includes many useful scripts and demonstrates many useful techniques, but it was released before SoZ and lacks the SoZ party editor and crafting capabilities. From a story perspective it also is not set in Faerun and does not fit into the NWN2 lore in any way other than to allow the young wizard Amie to be used as a companion. Enter the new campaign Taking the High Road: The Silverwand Sample Campaign Anniversary Edition (SSCAE).

SSCAE reuses some of the areas and quests from SSC for its first act but changes the setting to Faerun's Sword Coast in the year 1334 DR, years before both Farlong and Away and the NWN2 OC. The second act of SSCAE initiates the quest for the legendary Unicorn Blade, leading south to the great city of Waterdeep, and then in act 3 northward to the mysterious ruins of an ancient lich-mage's abode.  All of this is compatible with the published lore of the realm and there are connections to Baldur's Gate 2, and the official campaigns of both Neverwinter Nights and the NWN2.

At this time I am developing the areas within the city of Waterdeep. Because these are based on published city maps I am unable to take advantage of existing city areas, so I expect this to take some time.  I am hoping to release SSCAE before the end of the year.

The XTRA8Bit 32 MB image for the Apple II platform

 A Brief History of My Journey with the 8 bit Apple II

When I was still in grade school my father brought home a computer terminal that we could use to connect to a time-sharing mainframe system via acoustic coupler modem.  It was slow. It was primitive. It was fascinating. My brothers and I used it to play Hunt the Wumpus and Star Trek.

Upgrades followed and eventually we had an Apple ][+ with an Amdek Color-I monitor, 2 5.25" Disk II drives, a Hayes Micromodem, a Mountain Hardware clock card, and an Epson MX-80 printer. In addition to being used by my father for a variety of work related purposes and charity work, and school paper writing using Apple Writer, it was also used to play games like Lemonade Stand, Little Brick Out, Autobahn, Olympic Decathlon, Akalabeth, and Wizardry. Of course we had LockSmith and Copy ][+, but we used disk copying tools only to make backups for our original purchased 5.25" disks, because in a family of 5 young boys the fragile floppy 5.25" disks were prone to damage before their time.  My interest gravitated to BASIC programming, initially so that I could customize Little Brick Out and outscore my brothers, but later to develop more sophisticated HELLO programs, a Slot Machine game, and enhance Apple's File Cabinet program to suit the needs of my growing comic book and record collections. I was the only one in the family who caught the programming bug. While this cut significantly into my AD&D time, it seemed a fair trade-off.  All of this was before computer labs were common in schools, the internet, and national BBS systems like AOL, so subscriptions to magazines like Nibble, A+, and InCider were my primary way of gaining knowledge and there was really no way to share anything I was developing.  It never occurred to me to finalize and package anything I was doing for sale, nor did it ever occur to me to steal other people's work. So I was never involved with the communities who did.

I attended a computer summer camp at Rose-Hulman Institute of Technology in Terre Haute focused on Pascal programming, and then took a summer programming course at the University of Notre Dame that used early Macintosh computers so I had to buy a single 800K 3.5" diskette.  It cost me $5 at the ND bookstore.  I remember thinking that $50 for a box of 10 disks was crazy expensive. But my experience with the diskette was so much better than using 5.25" disks that I quickly bought a VTech 3.5" Drive and Universal Disk Controller card so that I could make 3.5" disks my primary development storage. To support DOS 3.3 I bought UniDOS Plus so that I could store DOS 3.3 programs on 3.5" disks as well.  Having 3.5" disks made using ProDOS reasonable so I began playing with Apple's newer operating system for the 64K Apple II family. This opened the door to developing intelligent startup programs that could run on DOS 3.3, UniDOS, or ProDOS disks.  Since ProDOS had clock support and date stamped files, I also started looking more closely at clock routines that worked with the Mountain Hardware clock card.

As the Apple //e gained in popularity more and more of the magazine articles covered //e specific features like Mousetext, DHR graphics, the open and closed Apple keys, and the 80-column card. This was mainly ignored by me as I was starting college and these new features weren't compelling enough for me to switch from my trusty Apple ][+.  My freshman year in college I was one of the only people in the dorm that had a computer, the other being a freshman across the hall with a brand new 512K Macintosh. We connected them using ASCII Express Pro so that he could print his papers on my Apple][+ since we found that the Epson printer fonts made the papers seem slightly longer than when printed on his ImageWriter.

When the IIGS was released I was completely blown away by its capabilities and appearance and bought one - CPU/keyboard/mouse - and the Apple RGB monitor. My UDC card worked in the IIGS in slot 5 and I was able to purchase a custom cable from Redmond Cable that allowed me to connect my 2 Disk ][ drives to the disk port. I later bought an Apple 3.5" drive, but I never did buy an Apple 5.25" drive. My focus switched to 16 bit software, icon creation, and after its release HyperCard IIGS became my favorite development tool. But by 1995 I was no longer developing on the Apple II and that interest slumbered for many, many years.

My Apple II Interest Awakens

During the worldwide COVID pandemic in 2019 I began working from home and decided to set up some of my old Apple II computers in my work area to make it feel more cozy. That has led to my revisiting many of my 1990's development efforts, publishing 9 issues of Script-Central Special Edition and other HCGS efforts, and the BASIC A2.Jukebox program which utilizes Micah Cowan's machine language routine for playing music on any Apple II.

In the early 90's I was on AOL and GEnie and Delphi and uploaded my own developed software as well as downloading freeware and shareware. Some of that was for the 8-bit Apple II and as a result I have a decent amount of software and programs. At times in the early 90's I attended computer swap meets and purchased disks of Apple II software. While these were often advertised as shareware or freeware collections, they sometimes included cracked 8-bit games and so I acquired some of those as well. Nothing like the 4 AM collection available now, but a small number of games and programs, no longer published, that may be of interest to the vintage Apple II community.

About the XTRA8Bit 32 MB Image

The XTRA8Bit image is a 32 MB hard drive image that can be booted on any Apple II that can run ProDOS. This image includes all of the software that I had in my collection that I did not readily find on other published disk images for BOOTi, XDrive, and other current Apple II storage solutions. The image also includes my own 8 bit software development including three new BASIC program launchers.

If you want to learn more about these program launchers keep reading. If you just want to download the image: get it here or browse all of my Apple II downloadable software here.

SoftLaunch

When booting the XTRA8Bit image a short startup program loads that allows setting the ProDOS clock and then launches the program SoftLaunch. SoftLaunch is a BASIC program that works on any 64K Apple II and displays a menu constructed from its preference file. SoftLaunch can display text files (using Karl Bunker's DogPaw) and on mouse-enabled //e and //c computers the mouse can be used to make selections. SoftLaunch will work just as well on a 40 column Apple ][+ as an 80 column Apple //e, //c, or IIGS.

SoftLaunch screen in 80 columns

SoftLaunch can launch only the applications defined in its preferences file and does not do disk browsing. One of the applications it can launch is BREEZE which does allow browsing.  More about BREEZE below.

The Window, Windows, and SneeZe Program Launchers

The Window program launcher was written by Andy Anderson in 1987 and updated by Fred "AG6O" to use Karl Bunker's DogPaw and allow SHR graphics to be displayed. Window allows browsing to launch BASIC, SYS, and BIN programs, view HGR, DHR, and SHR graphics, and reading TXT, SRC, and AppleWorks documents (via DogPaw). Window will not work on an unenhanced //e or earlier Apple II computers. It requires 80 columns, mousetext, and keys that are not on pre-//e keyboards. Written in BASIC though allowed the program to be modified easily.

Window v1.51.2 by Andy Anderson, w/ mods by AG6O

Karl Bunker and Dean Esmay modified Window for the purposes of the disk magazine A2-Central On Disk, renaming it Windows. This version was modified to work on unenhanced //e computers and added several features such as scanning text files for a string and booting from a slot.

Windows 1.95.A2 by Karl Bunker

Karl Bunker wanted to do more with it to support IIGS specific features - like display 3200 mode pictures - and decided to rewrite it entirely and move much of its code into machine language routines. He called his new application SneeZe. The final version was 2.3, though its screen shows 2.2.

SneeZe v2.3 by Karl Bunker

SneeZe is highly dependent on machine language routines for file display, graphic display, and even program launching. Unfortunately this makes further modifications challenging.

Window.Launcher/Window.2025

Window.Launcher/Window.2025 was developed based on the Window.151.2 code (I had not even looked at the Windows 1.95.A2 or SneeZe code). My primary intent was to develop a version of Window that could be used as a program launcher for any Apple II that had lowercase capability. In addition, files are listed in alphabetical order and commands are changed to use keys that are available on all Apple II keyboards. Because of memory restrictions the program was split into Window.Launcher and Window.2025. Window.Launcher loads routines like DogPaw into memory and then initiates Window.2025. If an Apple II only has 40 column capability then Window.2025 will display the file list and allow displaying the commands on a separate Help screen. On Apple II's that have 80 column capability Window.2025 defaults to 80 column mode but can be switched to 40 column mode with a keypress. The auto-advancing Slideshow feature of Window.2025 allows HGR, DHR, and SHR pics to be viewed either once or repeated in a loop until ESCape is pressed.

Window.2025 in 40 column mode

Window.2025 in 80 column mode

However, because all of its code is in BASIC, it was not possible to add all of the features desired.

Breeze and BREEZE.6502

After looking at the features of Karl Bunker's Sneeze, Breeze was written to merge the capabilities of Window.2025 with the more advanced graphic display features of SneeZe and provide a version that would work with even an Apple II that only has uppercase capability and allow mouse use. The Boot Slot command from Windows and SneeZe was added as well as file/folder count display.

Breeze in 40 column mode

Breeze in 80 column mode

Breeze uses the DISPLAY command from the Sneeze.Utils to display HGR, DHR, SHR, and 3200 mode graphics, which allows more graphic types to be displayed but restricts the Slideshow feature to only manually advancing. The Sneeze.Utils are incompatible with 64K Apple II's so the BREEZE.STARTUP program determines the kind of computer being used and launches BREEZE.6502 instead of Breeze if running on an Apple II or ][+.  Since Sneeze.Utils modifies BYE to initiate a program named SNEEZE, there is also a SNEEZE program which duplicates the code of BREEZE.STARTUP.

BREEZE.6502

BREEZE.6502 Help screen

Because Breeze uses Karl Bunker's Sneeze.Utils it was possible to add more BASIC code and so a few features are in Breeze but not in BREEZE.6502.  Breeze displays the day and date and has a command to set the ProDOS clock.

Breeze uses Karl Bunker's DISPLAY command to display graphics, and so requires a keypress to advance through graphics when using the slideshow feature. Breeze.6502 can only display HGR graphics but auto-advances through graphics and can be set to loop the slideshow indefinitely by pressing L. (Window.2025 can loop a slideshow of HGR, DHR, and SHR graphics, so use that launcher rather than Breeze if you need that feature on a //e, //c, or IIGS.)

SneeZe has additional undocumented machine language code for launching programs that Breeze DOES NOT use. SneeZe and Breeze remove DogPaw from memory when launching programs, but BREEZE.6502 does not. So it is possible that SneeZe may be more successful at program launching, although it will not work on all Apple II models.

Both Breeze and Breeze.6502 look for a mouse and will allow it to scroll through files and back up or select a file or directory. However, using a mouse with BASIC is tricky and can sometimes cause the program to become unresponsive. If this is the case then both programs can be changed to ignore the mouse by altering lines 9 and 10. This is explained in the documentation included with Breeze.

Feature Comparison

Feature	Window	Windows	SneeZe	Window.2025	Breeze	Breeze.6502
Apple II and ][+ compatibility*				✅		✅
Unenhanced //e compatibility		✅	✅	✅	✅	✅
Does NOT require lowercase						✅
Does NOT require mousetext		✅	✅	✅	✅	✅
Does NOT require 80 columns				✅	✅	✅
Automatic slideshow advance	✅	✅		✅		✅
Loop slideshow				✅		✅
40/80 column toggle				✅	✅	✅
Mouse support**					✅	✅
Relaunch after BYE		✅	✅		✅
Display HGR	✅	✅	✅	✅	✅	✅
Display DHR	✅	✅	✅	✅	✅
Display SHR (on IIGS)	✅	✅	✅	✅	✅
Display 3200 mode (on IIGS)			✅		✅
Volume selection from list			✅
Volume Prior/Next cmds				✅	✅	✅
Boot Slot			✅		✅	✅
CAT/CATALOG				✅	✅	✅
Dash command (for EXEC)				✅	✅	✅
Sorted File Display				✅	✅	✅
Dynamic File Display	✅	✅		✅	✅	✅
Show Current Slot and Drive				✅	✅	✅
Show Free Space***			✅	✅	✅	✅
Show File Lock Status	✅			✅	✅	✅
Launch S16 (on IIGS)			✅
View TXT, AWP, APW, SRC	✅	✅	✅	✅	✅	✅
Print TXT, AWP, APW, SRC	✅	✅	✅
Delete file	✅		✅
Scan files		✅	✅
Copy files			✅
Display Date correctly****					✅
Set Date and Time					✅
Show file and folder count*****			✅		✅	✅

Note that BREEZE.STARTUP determines whether to initiate Breeze or BREEZE.6502 based on the Apple II machine type.

* Window.2025 will work on any ProDOS capable Apple II that has lowercase.

** Window.2025 does not include mouse support, but there is an alternate version that has limited mouse support but sacrifices displaying graphics.

*** SneeZe shows free space only when typing ?; Window.2025, Breeze, and BREEZE.6502 show free space using the CAT or CATALOG feature

**** SneeZe displays the date, but assumes all years are in the 20th century. Breeze determines the century using a window from 1940 to 2040.

***** File and folder count shown will be low if the number of entries in the directory exceeds 255. Breeze allows up to 255 files in a directory but its practical limit is about 75. Breeze will show a + sign on the file/folder count line when there are more than 255 entries in the directory.

All of the above programs are included on the XTRA8Bit image so if you prefer to launch something other than Breeze you can simply edit the SoftLaunch preferences file to do so.

Even More ProDOS Launchers

The July 6, 2025 and later version of the disk image collects a number of additional ProDOS program launchers (except SoftLaunch and Breeze which are in the root folder) into a single "LAUNCHERS" folder for easier comparison. Most of these required an enhanced //e, //c, or IIGS.

EZ-LAUNCHER v1.0 is a freeware BASIC application by Vernon Mueller released in 1992. This program is compatible with any Apple II and uses pre-constructed menus for launching programs rather browsing.

EZ-LAUNCHER v1.0

Mouse Cat 80 is a BASIC mouse driven 80 column launcher by Travis Jones that was published in the October 1986 issue of InCider magazine. Written primarily as a mouse demonstration, the program requires a mouse since any keypress exits the program. This listing was typed in by Brendan Bellina. There was also a 40 column version also published in the magazine. The program MOUSE.CAT.40.BB is based on that but has some modifications by Brendan Bellina.

Mouse Cat 80 from InCider magazine

MOUSE.CAT.40.BB

Published by NAUG (the National AppleWorks Users Group) ProDesk Plus v4.0 is a shareware program selector and utilities package written mostly in BASIC by Helge Malmgren, based on a program first published in COMPUTE!'s Apple Applications in December 1987. The initial release was in 1990 as PRODESK PLUS v1.3. This program has many features that Karl Bunker's SneeZe has: it can launch large SYS programs, S16 programs, copy files, delete files, and modifies the ProDOS QUIT code to allow returning after leaving an application. In addition it has mouse support and a built-in screen saver. It can also view text files and AppleWorks documents and HGR and DHR pictures, but not SHR or 3200 mode pictures. Some of the functionality requires that the PRODESK PLUS folder be available while running. ProDesk Plus displays files in multiple columns.

ProDesk v4.0

Selector v1.0 by Jeff Blakeney is a BASIC program selector that should work on any Apple II that has 80 column capability. Files are displayed in multiple columns.

Selector v1.0

RunRun v1.0 is a professional program launcher published by Pinpoint Publishing in 1986. The version included on the image came from a Nibble magazine disk and does not include the impressive looking list of optional accessories. The program makes heavy use of mousetext but appears to be keyboard driven only. The program allows both browsing and constructing a launch list of applications. The list of devices displayed is not always complete, which seems to be a serious bug. The program requires rebooting when quitting. I was unable to locate a complete or updated version.

RunRun v1.0

ProDOS File Navigator v3.0 was published in 1998 by Kreative Software. It is based on an earlier limited-release BASIC program called ProDOS File Navigator 2.5. It can view text files and GR and DGR pics, in addition to HGR and DHR pics. And it can copy files.

ProDOS File Navigator v3.0

Super Selector is a program launcher that makes heavy use of mousetext and has mouse support. v3.22 allowed both file browsing and constructing a launch list. v3.3b (a beta release version) eschewed the launch list in favor of constructing a list of launchable applications on the fly (there may be some issues with the 3.3b version recognizing mouseclicks and keypresses, at least in the emulator Sweet16).  As they have significant differences both versions are included on the image. 

Super Selector v3.22

Super Selector v3.3b(eta)

If you have a IIGS then it is particularly important to read the documentation included with these launchers if they include file management features such as copying and deleting. Programs written for ProDOS may not copy or delete forked GS/OS files properly leading to volume corruption. The safest tool to use for file management on a IIGS is the Finder.

To download the image: get it here or browse all of my Apple II downloadable software here.