Edenwaith Blog

DOSBox: Tips + Tricks

22nd June 2019 | Tutorial

DOSBox has been a godsend in being able to play older DOS games on modern systems, but its interface and user-friendliness leave much to be desired. DOSBox contains a number of options, but it requires the necessary know-how to properly configure these settings to get the best use out of this utility. This blog post will outline a number of tricks I've used to get the most out of DOSBox.

Keyboard Shortcuts

Since DOSBox does not display a standard menu bar, there are a number of hidden, but useful, keyboard shortcuts available.

Toggle full screen: ALT/Option + Enter
Increase CPU speed: CTRL + F12
Decrease CPU speed: CTRL + F11

Mounting and Unmounting Drives

On initial launch, DOSBox doesn't seem very useful, and the user is being stared at by a non-helpful Z: prompt. The first step is to tell DOSBox where you have stored your DOS programs. On my Mac, I have a folder where I keep all of my DOS games.

Mac: mount c /Applications/Games
Windows: mount c D:\Games\

Mounting a CD is a little more involved, and the interface between Windows and Mac is also a little different to indicate the source path of the CD.

Mac: mount d /Volumes/Name_of_CD -t cdrom -usecd 0
Windows: mount d d: -t cdrom -usecd 0

DOSBox will allow you to associate a mount point to whichever drive letter you choose. Even if your CD drive is actually the E: drive on your Windows computer, you can specify it to be drive D: under DOSBox.

If you need to unmount a drive (such as the CD drive), add the -u switch and the letter of the drive:

mount -u d

Automounting a Drive

The next several tips involve editing the configuration file. The configuration file is just a plain text file, so you can use any text editor to open up and modify the file. The file can be found in the following locations, depending upon which operating system you are using:

Windows XP: %USERPROFILE%\Local Settings\Application Data\DOSBox\dosbox-{version}.conf
Windows Vista and later: {system drive}:\Users\{username}\AppData\Local\DOSBox\dosbox-{version}.conf
Mac: ~/Library/Preferences/DOSBox {version} Preferences

Note: The version number will correspond to the version number of DOSBox.

Each time that DOSBox is restarted, it forgets the previously set mount points, so it defaults to the unhelpful Z: prompt. To set up DOSBox so it will automatically mount a particular "drive" each time it launches, go to the autoexec section in the configuration file, and add a couple of lines to mount a given drive. Once this is saved, DOSBox will run these commands on start up so the drive will be automatically mounted, reducing the amount of steps you'll need to make each time you use DOSBox.

[autoexec]
# Lines in this section will be run at startup.
# You can put your MOUNT lines here.
mount c /Applications/Games
c:

Changing to Tandy Mode

One of the advantages of having a Tandy computer in the 1980s was its 3-voice sound system, which produced far superior audio to that of the standard PC which had a simplistic speaker that could only create single voice beeps. By default, DOSBox does not have the Tandy mode enabled, but it can be set to produce Tandy-style audio and visual effects.

To enable the Tandy mode, change the machine to type tandy under the [dosbox] section:

[dosbox]
language=
machine=tandy
captures=capture
memsize=16

This works out well to enable the 3-voice sound for early Sierra games such as King's Quest 3, but I have noticed that some early SCI games (e.g. Space Quest 3, Colonel's Bequest) do not load so I had to set the machine type back to svga_s3.

References

BBEdit Codeless Language Module for Sierra's AGI LOGIC

21st May 2019 | Programming

I've spent a good portion of the past year learning how to deconstruct, modify, and then reconstruct Sierra On-Line's AGI adventure games. With the right tools, it is not too difficult to change the appearance of a background picture or an inventory object's image. Tweaking the occasional image makes for a fun experiment, but the true magic comes from altering the underlying logic of the game to provide additional functionality.

The AGI games were developed using a custom scripting language called LOGIC. One of the interesting side effects of modifying a LOGIC source file in AGI Studio for Mac is that it saves out a copy of the file (e.g. logic.045) into the project's src directory. Unfortunately, the text editor in AGI Studio is quite simplistic and doesn't work too well. Fortunately, one can directly edit the LOGIC files stored in the src directory using their preferred text editor, instead of editing the source file directly inside AGI Studio. Once I discovered I could use an external text editor to modify the LOGIC files, that became my standard workflow. (Note: the code still needs to compiled within AGI Studio, but it will read in any changes to the saved files in the src directory.)

One downside to working with an old, obscure, and proprietary language such as LOGIC is that modern day text editors will likely not know how to properly provide syntax coloring. Fortunately, there is a way to work around this issue in BBEdit by creating a Codeless Language Module. I had recently encountered a similar issue when reading a C# file on a Mac, which prompted me to learn about the Codeless Language Modules in BBEdit. After doing some research, I learned that it was very feasible to design my own module for AGI LOGIC. Below is the current version of the AGI LOGIC Codeless Language Module for BBEdit.

To install, download and unzip the agi-logic.plist file and copy it into the ~/Library/Application Support/BBEdit/Language Modules/ directory on your Mac.

When editing a LOGIC source file in BBEdit, select AGI LOGIC as the Document Language setting from the bottom of the window, which will enable syntax coloring and the ability to quickly (un)comment lines and blocks of code.

References

Easter Egg Hunting in King's Quest 1

21st April 2019 | Programming

Easter eggs have been part of a long standing tradition of hidden secrets and quirks buried in software, particularly video games. On this day of Easter, let's do a little Easter Egg hunting in the original King's Quest. The items shown in this article are mostly about quirks, glitches, and errors that have been discovered which result in some amusing and/or interesting results.

Zombie Goat

One of the things which provides replayability in King's Quest 1 are the multiple options to solve problems. There is often an ideal (generally a more pacifist route) way to conquer certain challenges, but there are also more violent methods, as well. The dagger is intended to cut the well's rope so Graham can obtain the bucket. However, it is possible to kill either the dragon or the goat with the dagger, as well.

If you lack a conscience and are willing to incur the wrath of the ASPCA by killing the goat, you can earn back a few karma points by showing the carrot to the dead goat, who will miraculously resurrect (just like Jesus did on the third day).

Walk On Water

Speaking of Jesus, Sir Graham is not the messiah (especially if he goes about killing defenseless goats), but they both can walk on water. If you go to the screen with the mushroom, move Graham so his feet are about one pixel below the bottom of the screen and then walk to the east. If you line Graham up just right, he can "walk" across the river without drowning.

Walk Through Walls

Walking across water is just one of Sir Graham's many talents. He can also walk through stone walls! This is a bizarre bug I found many years ago. Just before leaving the Leprechauns' kingdom, have Graham duck, eat the magic mushroom, and then finally stand, which will revert Graham's sprite back to the normal view instead of mini-Graham. With the game thinking that you are still mini-Graham, you can walk through the wall to the west.

Medieval Flamethrower

The above demonstration is not actually in the original King's Quest per se, but the lines about the medieval flamethrower were left over lines still left in the source code, as pointed out by The Cutting Room Floor. The screenshot below shows the messages for Room 53, the king's throne room, which includes a couple of unused messages.

Knight Rider Fan

Figuring out the name of the gnome (ifnkovhgroghprm) in this game, was probably the most notorious of all of the puzzles (which was even poked at in the 2015 King's Quest game), but there was one other name which was added as a joke, a reference to the era in which this game was made. If you guess the name Mikel Knight, the gnome will respond, asking if you think he is a car. This is a not-so-subtle reference to Michael Knight, the main character of the TV show Knight Rider which aired from 1982-1986.

The name Mikel Knight makes one additional appearance in the end credits of the game, which initially made it appear that one of the developers was named Mikel Knight, but according to The Sierra Chest there was never a Sierra employee by that name.

Unsympathetic Troll

Sierra generally did an excellent job with proofreading 99.9999% of the time, but every once in a great while, a spelling error did manage to slip by. If you type beg troll at the east bridge leading to the gnome's island, the returned message says Trools have no sympathy.

Water For Alligators

In this screenshot, Sir Graham watches as his doppelgänger King Graham rides an alligator. To reproduce this glitch, you will need to go into debug mode in the game, add the 26th object, which is water, but that object only appears in the game when you fill the water bucket, so when you try and "look" at the water without having the bucket, it creates this glitch.

  1. Type: ALT + D to turn on debug mode
  2. Press ENTER twice to dismiss the two messages
  3. Type: GET OBJECT
  4. Type: 26
  5. Press F4 and look at the WATER

Maximum Points

13 July 2019 Update: The maximum score in King's Quest 1 is 158 points, but there are two methods to be able to exceed this score. I reviewed a list of all of the possible points in KQ1 and if you do everything properly, you can get a score of 159 points. From a points list I found in an earlier edition of the King's Quest Companion, it appears that some points regarding the magic bowl had been changed over time, which results in a couple scoring oddities. If you want to get all of the possible points, here are a couple of easy to miss points:

While inspecting the source code of King's Quest 1, I came across something I had never seen before. If you read the word on the bottom of the bowl, it will give you a single point, but if you then try and fill the bowl with stew, it doesn't give any additional points. Filling the bowl normally gives you two points. But if you eat the stew, it takes away two points, so if you perform the following steps properly, this will result in a net of -1 points.

  1. Get the bowl (3 points)
  2. Read the bowl (1 point)
  3. Fill the bowl (0 points)
  4. Eat the stew (-2 points)
  5. Keep repeating steps 2 - 4 until you have 255 points

If you repeat this enough times, the score will not become -1, but it will instead roll over to 255. The score is stored as an unsigned 8-bit integer, so none of the AGI games has a maximum score of more than 255. Instead of the score becoming a negative number, it will roll over to its maximum value (similar idea if an odometer could turn backwards).

Happy hunting!

EdenList 2.0.1 for iOS

28th March 2019 | EdenList

EdenList 2.0.1 for iOS has been released, featuring the following improvements:

As was discussed in the previous blog post, the app has been improved to more quickly delete selected items from an arbitrarily long list. While this will likely not be observable in real world examples (unless you happen to have a very, very long shopping list), it is still nice to implement these improvements and to safe guard against any extreme cases.

One thing which caught me for a surprise with this release was that I needed to include a privacy policy before submitting the update to Apple. Starting on 3 October 2018, all new apps and updates for Apple's app stores require a privacy policy. I looked at a couple of examples and services to create a privacy policy that would work for EdenList, and I ended up using TermsFeed. Just for additional clarification, EdenList does not obtain or use any personal information from its users.

Embracing Algorithms

27th February 2019 | Programming

One of the most interesting of the WWDC 2018 videos was the Embracing Algorithms session which introduced a couple of interesting new ways to approach common problems using some of the additions provided in Swift.

EdenList for iOS was originally started in 2009 (which was based off of the original Mac project started in 2003), several years before Swift was announced, so it was inevitable that it was to be written in Objective-C. The method deleteCheckedItems is 20 lines of code which iterates through the list and removes any item which has been selected.


- (void) deleteCheckedItems
{
	int recordsCount = [records count];
	
	for (int i = recordsCount-1; i >= 0; i--)
	{
		NSDictionary *rowData = [self.records objectAtIndex: i];
		
		if (rowData != NULL)
		{
			NSNumber *num = [rowData objectForKey: @"CheckBox"];
			
			if (num != nil && [num boolValue] == YES)
			{
				[records removeObjectAtIndex: i];
			}
		}
	}
	
	[self updateVisibleRecords];
}

When I rewrote EdenList in Swift, I was able to reduce the amount of code for the same method by nearly half. This was certainly a nice boon to be working in Swift by writing less, but still readable, code.


func deleteCheckedItems() {
	
	let recordsCount = self.records.count
	
	for (index, record) in self.records.reversed().enumerated() {
		if record.itemChecked == true {
			// index is returned sequentially, not in reverse order, so the proper index needs to be calculated
			let itemIndex = recordsCount - index - 1
			self.records.remove(at: itemIndex)
		}
	}
	
	self.updateVisibleRecords()
	self.saveFile()
}

The Embracing Algorithms session displayed a couple of ways to write this functionality, first by starting with moving sequentially through the array, but then displaying another method which was closer to what I employed by going through the array in reverse. However, the session had an even simpler version than the algorithm I used.


func deleteSelection() {
	for i in (0..<shapes.count).reversed() {
		if shapes[i].isSelected {
			shapes.remove(at: i)
		}
	}
}

Nice. However, as it was pointed out in the session, this algorithm results in a time complexity of O(n2) due to the for loop and then each remove(at:) method taking another O(n) operations. As we learned from our CS 102 class, an algorithm with O(n2) time complexity will grow exponentially, which results in a poor case for arbitrarily large data sets.

For an app like EdenList, any given list probably would not go much past a couple hundred items, but that does not discount other cases where the data sets could easily number in the millions or billions or more. Are there more effective methods? Indeed there are.

Another option to filter the contents of the array using Objective-C is by using a combination of an NSPredicate and NSMutableArray's filterUsingPredicate method. This greatly cuts down on the amount of necessary code.

NSPredicate *predicate = [NSPredicate predicateWithFormat:@"CheckBox == %@", @YES];
[self.records filterUsingPredicate: predicate];

With the introduction of higher order functions (e.g. map, reduce, filter) in Swift, filtering the contents of an array can be easily accomplished with the filter function.

let filteredArray = someArray.filter { $0.someBoolAttribute == true }

However, there is yet another way to remove select items from an array in Swift. Enter the removeAll(where:) method which has a linear O(n) time complexity, far better than the quadratic time that the original algorithm required. The removeAll gains this efficiency by using a half-stable partition to move the items to delete to the end of the array and then removing the subrange at the end of the array, which is far cheaper than removing one item at a time and then having to readjust the ordering of the entire array.


func deleteCheckedItems() {
	self.records.removeAll { $0.itemChecked }
	self.updateVisibleRecords()
	self.saveFile()
}

The final version of deleteCheckedItems has been slimmed down to a mere quarter of the original Objective-C version. Not only is the code much more concise, it is also much faster. Thus is the advantage of better algorithms, but taking advantage of the improvements in the latest version(s) of Swift.

References

QT AGI Studio for Mac

31st January 2019 | Programming

I've spent the past several months learning how to extract the resources from classic Sierra games built using the AGI game engine. I then started to contemplate building my own AGI Viewer program, which might then evolve into a more full featured IDE to be able to create or modify AGI games. Or...I could build upon what tools already exist instead of completely rebuilding the machine from scratch.

There have been numerous utilities around for decades dedicated to working with AGI games, however many of these programs were developed as far back as the 1990s when Windows was very dominant, so it was rare that apps were being built for alternative operating systems. Since most of my work is done on a Mac, I started looking for Mac alternatives.

I first came across Jeremy Penner's Mac port of the Linux version of AGI Studio. This project dates back to 2003, but I was able to download it and install it on my PowerBook G4 and it worked out pretty well to make some minor modifications to King's Quest 1, as seen in the screenshot below.

I started looking into QT AGI Studio which looked fairly complete. This version is for Linux, but I noticed it was built using the Qt frameworks. I've worked with Qt before, so I knew that it was possible to build apps for multiple platforms. As far as cross platform tools go, Qt is not the worst, but it still falls short of properly supporting and building Mac apps. Still, it would probably take less time to port AGI Studio to the Mac than trying to rewrite it in Objective-C and C (however, as I would discover, there are times I almost wished I was working in Xcode).

Setting up Qt and configuring the project to build for the Mac still proved to be an ordeal, as I have recorded below. Trying to find good instructions on building for the Mac with Qt Creator is like a massive treasure hunt. One will find a few hints here, a few hints there, but rarely are all of the steps available in any single location. I am hoping that these steps will also prove useful for anyone who is looking at trying to build an app for the Mac using Qt.

Download Qt Creator and Frameworks

Since the most recent builds of QT AGI Studio were from 2013, I opted to work with the versions of Qt from that time period. I had tried compiling the project with a more modern version of Qt, but it complained about the Qt3 support, and I did not want to have to wrestle with trying to upgrade from deprecated Qt3 frameworks to Qt5.

Qt has passed through several companies over the years, so it was not quite so easy to find the older versions of Qt. After some searching, I did find a good mirror site which provided many versions of both the frameworks and the Qt Creator IDE. The following are the versions I used:

The Qt frameworks will be installed in the /Library/Frameworks folder and other Qt applications and documentation will be installed in /Developer. For my development system (a 2007 MacBook Pro), I also used Xcode 3.2.5 on Mac OS X 10.6 Snow Leopard in addition to the Qt tools.

Modifying the .pro File

Upon the initial attempt to build the project (note: remember to first run qmake on the project), I received the following error:

cc1plus: error: unrecognized command line option "-Wno-unused-result"
make: *** [main.o] Error 1

I tried a variety of options and workarounds until I discovered that I did not need the DEFINES and QMAKE_CXXFLAGS to compile on Mac OS X. I commented out these two lines in the .pro file. The DEFINES section can remain and the app will still compile and run, but since it specifies Win32, I removed it for the Mac build.

# Add these lines
CONFIG += app_bundle
ICON = application.icns
RESOURCES += agistudio.qrc # Not necessary if a qrc file is not added

# Comment out these lines
# DEFINES += QT_DLL QT_THREAD_SUPPORT # win32 
# QMAKE_CXXFLAGS += -Wno-unused-result # -spec macx-g++

I only needed to add three new lines: CONFIG, ICON, and RESOURCES. CONFIG tells Qt Creator to build the app as a Mac app bundle, otherwise the app will be compiled as a single executable file. The ICON line is to specify the name of the icon file to set for the app bundle. RESOURCES is useful if you add a qrc file, such as if you are adding additional images to your project.

Updating the Info.plist

When Qt creates a Mac application, it only provides a bare bones Info.plist file. I ended up manually modifying the Info.plist file to update the necessary values and to add in any missing key-value pairs. This file is then copied into the app bundle to replace the Info.plist generated by Qt Creator. The following is the default Info.plist generated by Qt Creator:


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">
<plist version="0.9">
<dict>
	<key>NSPrincipalClass</key>
	<string>NSApplication</string>
	<key>CFBundleIconFile</key>
	<string>application</string>
	<key>CFBundlePackageType</key>
	<string>APPL</string>
	<key>CFBundleGetInfoString</key>
	<string>Created by Qt/QMake</string>
	<key>CFBundleSignature</key>
	<string>????</string>
	<key>CFBundleExecutable</key>
	<string>agistudio</string>
	<key>CFBundleIdentifier</key>
	<string>com.yourcompany.agistudio</string>
	<key>NOTE</key>
	<string>This file was generated by Qt/QMake.</string>
</dict>
</plist>

The default Info.plist is sparse on the necessary details, so several new key-value pairs needed to be added, a couple modified, and one removed.

After making the necessary updates, the Info.plist will look more like the following:


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">
<plist version="0.9">
<dict>
	<key>NSPrincipalClass</key>
	<string>NSApplication</string>
	<key>CFBundleIconFile</key>
	<string>application</string>
	<key>CFBundlePackageType</key>
	<string>APPL</string>
	<key>CFBundleGetInfoString</key>
	<string>AGI Studio 1.3.0</string>
	<key>CFBundleShortVersionString</key>
	<string>1.3.0</string>
	<key>CFBundleVersion</key>
	<string>1.3.0.1</string>
	<key>CFBundleSignature</key>
	<string>????</string>
	<key>CFBundleInfoDictionaryVersion</key>
	<string>6.0</string>
	<key>CFBundleExecutable</key>
	<string>agistudio</string>
	<key>CFBundleName</key>
	<string>AGI Studio</string>
	<key>CFBundleIdentifier</key>
	<string>com.edenwaith.agistudio</string>
	<key>NSHumanReadableCopyright</key>
	<string>Copyright © 2019. All rights reserved</string>
</dict>
</plist>

Handling the -psn Argument

On older versions of Mac OS X, launching an app will pass a process serial number as an argument to the app's executable in the form of -psn_0_1446241. According to a Stack Overflow post, this argument is no longer passed in newer versions of macOS. I have modified a bit of the code in main.cpp to watch for the -psn argument, and if it is seen, ignore it so the app can continue launching.

// startsWith() is a custom function to check if the argument is prefixed with -psn
if (startsWith("-psn", argv[i])) {
	break;
}

Adding a Custom Icon

Since this is a Mac application, I wanted to provide a high resolution icon, instead of using the generic AGI-character icon that is set in the app.

  1. Using Icon Composer, I generated the app icon, modeled after the traditional Sierra On-line logo.
  2. The .icns file is placed in the src folder along side the rest of the images and source code of the project.
  3. In the .pro file, the line ICON = application.icns is added so Qt Creator knows to add the icon to the app bundle.
  4. In the app's Info.plist, set the value for the CFBundleIconFile key to the name of the icon file (in this example, application.icns). If the icon does not appear once the app has been built, rename the app bundle and that will "refresh" the icon for the app, then you can rename the app back to its original name.

Mac Conditional Checks

Since this Mac app has been set up to use an icns file for the application icon, a bit of platform-specific code is needed so it does not try and set another icon for the app. In the menu.cpp file, I performed a check to see if it was not a Mac that was running the code. In this example, I checked that constant Q_OS_MAC was not defined before setting the icon. On a Mac, this would skip the setIcon method since the application icon has already been set. If this method was called, it would change the app icon. 

// For non-Mac systems, set the application icon to app_icon
#if defined(Q_OS_MAC) == false
  setIcon((const char**)app_icon);
#endif

If you need to check if the app is running on another system such as Linux or Windows, perform a check like #ifdef __linux__ or #ifdef _WIN32.

Modifying XPM Files

The QT AGI Studio project makes use of XPM (X PixMap) files for images, which is an interesting design choice instead of using another common image format such as PNG, GIF, or JPG. The thing which is interesting about XPM files is that they are actually text files which can be read in and treated as C code. I was able to use BBEdit to take any of the XPM files and open them up, which resembled a mix of C, HTML, and ASCII art. This proved to be useful to fix a problem I later encountered.

XPM is not a common image format so few image editors support it. Fortunately, an old version of Pixelmator (v. 1.6.7) on my computer was able to export to XPM. However, after I modified the image and then tried to build the app, I received the following errors:

../src/logo.xpm:215: warning: deprecated conversion from string constant to 'char*'
../src/logo.xpm:215: warning: deprecated conversion from string constant to 'char*'
../src/menu.cpp: In constructor 'About::About(QWidget*, const char*)':
../src/menu.cpp:926: error: 'logo' was not declared in this scope
../src/logo.xpm: At global scope:
../src/logo.xpm:2: warning: 'xpm_' defined but not used

This initially greatly confused me why Qt Creator was complaining just because I modified an image. It wasn't until I investigated the XPM format further that I discovered the source of the conflict. If I opened up the original logo.xpm file in a text editor, the beginning of the file looked like this:

/* XPM */
static const char *logo[] = {
/* columns rows colors chars-per-pixel */
"320 148 68 1",
"  c #000000",
". c #505050",

After I modified the image and then exported it from Pixelmator, it looked like this:

/* XPM */
static char *xpm_[] = {
/* columns rows colors chars-per-pixel */
"320 148 61 1",
"  c #000000",
". c #505050",

It was quick work to spot the difference between the two files, which make it clear what some of the errors and warnings meant. When Pixelmator exported the file, it saved the variable with the generic name of xpm_, but the app was expecting the variable to share the same name as the file. Once I changed xpm_ to logo, the app was able to build again without error.

I also tried to load in other image types (e.g. png) by loading them in a qrc resource file, but for some unknown and odd reason, the AGI Studio project never could see the non-XPM files. At this time, I do not really need to add any other images, but if I do, I can make due with the XPM files. Since this project makes use of Qt 3 frameworks, perhaps there is some odd limitation or other complication which is preventing more common image formats from being used in this project.

macdeployqt

Even though Qt Creator can create a Macintosh application bundle, it is often incomplete and requires some additional manual tweaking to finish the set-up. Since most Qt projects make use of the Qt frameworks, which are not native to the Mac OS, the frameworks need to be provided. One can distribute the frameworks via an installer, but the more Mac-like method is to include the frameworks within the app bundle. This is one of the key pieces of functionality where the macdeployqt utility comes in. If you have installed the Qt frameworks and Qt Creator, macdeployqt should already be set up on your development system. If you are not certain, type which macdeployqt in the Terminal. On my system it is installed at /usr/bin/macdeployqt. It is designed to automate the process of creating a deployable application bundle that contains the Qt libraries as private frameworks.

The basic call to include the frameworks is straightforward by calling macdeployqt on the app bundle.

macdeployqt AGI\ Studio.app

macdeployqt has additional functionality such as packaging the app into a distributable disk image (dmg), or in newer versions of macdeployqt, code sign the app.

Once macdeployqt has been run against the app bundle, the necessary Qt frameworks should be installed within the app's Frameworks folder. Unfortunately, this is still not without its faults. Try running the app, and you will likely see a similar error in the Console:

1/21/19 10:13:35 PM [0x0-0x275275].com.yourcompany.agistudio[15522] On Mac OS X, you might be loading two sets of Qt binaries into the same process. Check that all plugins are compiled against the right Qt binaries. Export DYLD_PRINT_LIBRARIES=1 and check that only one set of binaries are being loaded.

You might even encounter a bevy of other warnings in the background while trying to use the app since it is confused about which version of the Qt frameworks should be used.

objc[10717]: Class QNSImageView is implemented in both /Library/Frameworks/QtGui.framework/Versions/4/QtGui and /Users/admin/Programs/agistudio-1.3.0/agistudio-build-Desktop-Debug/agistudio.app/Contents/MacOS/./../Frameworks/QtGui.framework/Versions/4/QtGui. One of the two will be used. Which one is undefined. QObject::moveToThread: Current thread (0x101911fb0) is not the object's thread (0x113e48c50). Cannot move to target thread (0x101911fb0)

If you try and launch the app from the Terminal by directly calling the app's executable, there might be another set of errors:

$ ./agistudio
dyld: Library not loaded: Qt3Support.framework/Versions/4/Qt3Support
  Referenced from: ./agistudio
  Reason: image not found
Abort trap: 6

The problem here is that the executable (agistudio) does not know about the Qt frameworks, so Mac OS X is confused about which version of the frameworks to use if there are multiple copies on a system. This issue will be addressed in the next section.

otool and install_name_tool

Even if the Qt frameworks are not fully installed yet, the app might still launch, but will likely crash once a Qt library call is made, such as trying to open up the About QT menu. Trying to do so without having the frameworks properly installed will result in the app crashing.

Process:         agistudio [10717]
Path:            /Users/admin/Programs/agistudio-1.3.0/agistudio-build-Desktop-Debug/AGI Studio.app/Contents/MacOS/./agistudio
Identifier:      com.edenwaith.agistudio
Version:         1.3.0 (1.3.0)
Code Type:       X86-64 (Native)
Parent Process:  tcsh [10506]

Date/Time:       2019-01-14 19:04:57.106 -0700
OS Version:      Mac OS X 10.6.8 (10K549)
Report Version:  6

Interval Since Last Report:          1440136 sec
Crashes Since Last Report:           88
Per-App Interval Since Last Report:  2252 sec
Per-App Crashes Since Last Report:   7
Anonymous UUID:                      4FB4767E-3345-46C6-AA9E-288C90CF1074

Exception Type:  EXC_CRASH (SIGABRT)
Exception Codes: 0x0000000000000000, 0x0000000000000000
Crashed Thread:  0  Dispatch queue: com.apple.main-thread

Application Specific Information:
abort() called

Thread 0 Crashed:  Dispatch queue: com.apple.main-thread
0   libSystem.B.dylib             	0x00007fff81e6d0b6 __kill + 10
1   libSystem.B.dylib             	0x00007fff81f0d9f6 abort + 83
2   QtCore                        	0x0000000117254cf5 qt_message_output(QtMsgType, char const*) + 117
3   QtCore                        	0x0000000117254ed7 qt_message_output(QtMsgType, char const*) + 599
4   QtCore                        	0x000000011725509a qFatal(char const*, ...) + 170
5   QtGui                         	0x000000011670ee95 QWidgetPrivate::QWidgetPrivate(int) + 853
6   QtGui                         	0x000000011671e55b QWidget::QWidget(QWidget*, QFlags) + 59
7   QtGui                         	0x000000011667cd39 QDesktopWidget::QDesktopWidget() + 41
8   QtGui                         	0x00000001166c6f2b QApplication::desktop() + 59
9   QtGui                         	0x00000001166781db QMacCocoaAutoReleasePool::~QMacCocoaAutoReleasePool() + 4203
.
.
.
50  QtCore                        	0x00000001013e54c4 QEventLoop::exec(QFlags) + 324
51  QtCore                        	0x00000001013e7bac QCoreApplication::exec() + 188
52  com.edenwaith.agistudio       	0x00000001000388d5 main + 794 (main.cpp:99)
53  com.edenwaith.agistudio       	0x0000000100003a3c start + 52

To notify the executable file where to find the Qt frameworks, we need to use the install_name_tool utility. From the Terminal, change into the directory AGI Studio.app/Contents/MacOS and then run otool -L agistudio.


$ otool -L agistudio 
agistudio:
	Qt3Support.framework/Versions/4/Qt3Support (compatibility version 4.8.0, current version 4.8.4)
	QtGui.framework/Versions/4/QtGui (compatibility version 4.8.0, current version 4.8.4)
	QtCore.framework/Versions/4/QtCore (compatibility version 4.8.0, current version 4.8.4)
	/usr/lib/libstdc++.6.dylib (compatibility version 7.0.0, current version 7.9.0)
	/usr/lib/libgcc_s.1.dylib (compatibility version 1.0.0, current version 103.0.0)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 125.2.11)

Note how the first three lines reference Qt frameworks, yet they are not given a proper relative path to the agistudio executable file. To fix this issue, run the following three lines to resolve the path for each of the three frameworks.

install_name_tool -change Qt3Support.framework/Versions/4/Qt3Support @executable_path/../Frameworks/Qt3Support.framework/Versions/4/Qt3Support ./agistudio
install_name_tool -change QtGui.framework/Versions/4/QtGui @executable_path/../Frameworks/QtGui.framework/Versions/4/QtGui ./agistudio
install_name_tool -change QtCore.framework/Versions/4/QtCore @executable_path/../Frameworks/QtCore.framework/Versions/4/QtCore ./agistudio

Run otool -L agistudio again and you will see that each of the Qt frameworks is now prefixed with @executable_path/../ which references the path of agistudio. 


$ otool -L agistudio
agistudio:
	@executable_path/../Frameworks/Qt3Support.framework/Versions/4/Qt3Support (compatibility version 4.8.0, current version 4.8.4)
	@executable_path/../Frameworks/QtGui.framework/Versions/4/QtGui (compatibility version 4.8.0, current version 4.8.4)
	@executable_path/../Frameworks/QtCore.framework/Versions/4/QtCore (compatibility version 4.8.0, current version 4.8.4)
	/usr/lib/libstdc++.6.dylib (compatibility version 7.0.0, current version 7.9.0)
	/usr/lib/libgcc_s.1.dylib (compatibility version 1.0.0, current version 103.0.0)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 125.2.11)

Now the app can be launched and used without crashing. With the Qt frameworks properly installed, the AGI Studio app can be distributed without the need of an installer.

To Do

This is the initial effort to port AGI Studio to the Mac, but there is still plenty of work to continue improving this project. As I work further with AGI Studio, I am hoping that I will resolve some of these issues over time.

Conclusion

Like any cross-platform toolset, it often settles for the least common denominator, so it will never be a perfect solution, but all things considered, Qt is passable. This process was not without its challenges, but it was ultimately a rewarding and educational endeavor. Getting QT AGI Studio to build on a Mac was just the first step for my next project, and I imagine as I begin to work with AGI Studio for Mac I will continue to refine the program to smooth out the wrinkles and glitches.

The standalone app can be downloaded here and the source code is available on my GitHub page.

References:

Virtual Reality on iOS

8th January 2019 | Programming

Over the past several years, virtual reality (VR) has finally been making some solid inroads towards being a viable commercial technology. Playstation VR seems to be one of the strongest contenders, primarily due to the ubiquitousness of the Playstation 4 and its lower system specs versus high-powered PCs which are needed to run other VR platforms (e.g. Oculus Rift, HTC Vive). The PC market (Windows, Linux, Mac) has the Oculus Rift and HTC Vive as the primary VR products. Xbox does not officially support any VR solutions, even though there are a number of headsets for that platform for varying levels of support. On Android, Google Cardboard, Google Daydream, and Samsung VR (only supported on Samsung's flagship phones) are the big names. But what about iOS?

VR on iOS

Apple took a strong step into the augmented reality (AR) field in 2017 with their introduction of the ARKit framework, which made it much simpler to add AR features to iOS apps. Unfortunately, there is no native Apple-branded VR framework (e.g. "VRKit") at this time. Without strong support from Apple to help define the VR landscape and requirements for its ecosystems, this will result in a bunch of mostly unknown bit-players introducing half-baked products in an effort to enter an emerging market.

Fortunately, the most prominent player for mobile VR is undoubtedly Google with their offerings of Google Cardboard and Google Daydream. Daydream is only available for Android at this time, but Google Cardboard (and the many Cardboard-compatible viewers by other manufacturers) work with both iOS and Android. In addition to the specifications for the construction of the headset, Google also provides a VR SDK for Android and iOS.

I experimented with the Cardboard-compatible Utopia 360° Immersive Bundle which included Bluetooth headphones and a controller, in addition to the headset. The headset by itself is useful for 360° panoramas and immersive videos. I tried a rollercoaster VR app which was interesting to watch, but it gave me motion sickness after just several minutes. The included instructions warn the user to take a 10-15 minute break every half hour of use to prevent the adverse effects of VR such as eye fatigue and motion sickness.

When paired with a controller, VR can provide a new way to reimagine older products, such as the VR adaptation of the classic arcade game XEVIOUS. However, by requiring additional accessories to properly interact with VR limits which apps can be used. The Cardboard specifications provide for a single button on the headset which allows for very limited physical engagement with the phone. For some apps, they need to be manually set up on the phone first, then the phone can be placed into the headset to begin the VR experience. These cases result in awkwardness when interacting with the device. Since a dedicated controller is not guaranteed with all VR kits, this can limit the usefulness and functionality of the current batch of apps. Even the Utopia 360° line of VR products is not consistent since some kits only provide the headset and others may provide additional accessories such as the controller or earbuds.

Without a more "official" solution (such as the Playstation VR), the experience, especially with controls, is limited and inconsistent. This does not establish a good set of guidelines of what should constitute good a VR experience.

Google kicked things off several years ago with Cardboard, but there has been little progress since then, and Apple has been noticeably absent from the VR scene so far. VR for mobile at this time is more of a fun curiosity, but it is lacking the proper dedicated full-time support from the first parties to make it more of a viable reality.

References

Edenwaith 2019

5th January 2019 | Edenwaith

2018 was a continuation of wrapping up the big projects which were being worked on in 2017. As a result, several major projects were completed in the first half of 2018, including a complete rewrite of the Edenwaith website which fully adopted HTML5, CSS3, and responsive web design.

With the major projects being wrapped up early in the year, this left a lot of open time to pursue a number of new projects, which resulted in twenty blog posts being written over the year. This far eclipsed the amount of posts I have written in previous years, the number which often could be counted on just a single hand.

Notable blog posts:

The latter half of 2018 was heavily spent investigating how Sierra's AGI game engine works, and I will continue these explorations and I am currently in the process of porting QT AGI Studio from Linux to Mac. Existing projects such as EdenList and Permanent Eraser will also continue to be developed. As Apple has warned for well over a year, they will be dropping support for 32-bit apps and frameworks with macOS 10.15, so the current version of 33 RPM will likely not work on future versions of macOS.

Exporting and Updating Provisioned Apple Devices

29th November 2018 | Programming

On a yearly basis, Apple allows the developer to reset their list of provisioned test devices so they can delete, rename, or add devices. There are times where Apple requires the developer to reset this list. Fortunately, resetting the list allows them to quickly keep or delete any of the existing devices. If the developer wants to rename a device, the existing device will need to be deleted and then re-added with the new name.

However, let's say you want to get a complete list of all of your devices and their associated Unique Device Identifier (UDID). The following bit of JavaScript code shows how a person can generate such a list, which can be saved to a text file or used to easily upload multiple devices to the Apple Developer Portal. By using a bit of JavaScript, you can generate a list with all of your registered devices and their UDIDs.

Log in to your Apple developer account and then go to the Certificates, Identifiers & Profiles section. Click on the All link in the Devices section which will list all of your provisioned test devices. You will then run the following code snippet in the JavaScript console of your web browser.

5 December 2019 Update: Apple's website has changed again, so here is the updated code needed to create a list of Device IDs and Names.

var data = document.querySelectorAll(".infinite-scroll-component .row");

var deviceListString = "Device ID\tDevice Name\tDevice Platform\n"
for (var i = 1; i < data.length; i++) {
  deviceListString += (data[i].childNodes[1].innerText + "\t" + data[i].childNodes[0].innerText + "\t" + (data[i].childNodes[2].innerText == "iPhone" || data[i].childNodes[2].innerText == "iPad" ? "ios" : "mac") + "\n");
}

console.log(deviceListString);

In Safari, open up the JavaScript Console from the Develop > Show JavaScript Console menu. If the Develop menu is not available, go to the Advanced tab in Preferences and select the Show Develop menu in menu bar checkbox.

In Google Chrome, open up the JavaScript Console from the View > Developer > JavaScript Console menu.

The script will then produce a formatted list of your device IDs and device names. This script works as of this writing in November 2018, but it could easily break if Apple alters the web page.

If you need to upload a bunch of devices, you can take the list generated from the script and save to a file in the following format:

Device ID	Device Name
A123456789012345678901234567890123456789	NAME1
B123456789012345678901234567890123456789	NAME2

If you want to rename, remove or add a device, this is the place to do so. Once complete, this file can then be imported when adding a new device on the Apple Developer Portal.

References

Enabling the Erase Service for Permanent Eraser in macOS Mojave

25th November 2018 | Permanent Eraser

With each new iteration of macOS, Apple continues to strengthen its security measures. While this is essentially a good thing, the additional restrictions result in some frustration and confusion to allow users to continue to work like normal.

One of the newest restrictions introduced in macOS Mojave now requires explicit permission from the user to use third party Automator actions, which is what Permanent Eraser 2 uses for its Erase service. Upon using the Erase service from a contextual menu in Mojave's Finder, the user will see the following prompt:

Click on the Open Automator button, which will launch that application. Next, select the Automator > Third Party Automator Actions... menu.

In the Third Party Automator Actions window which appears, select the Enable Automator actions from third parties checkbox and click the OK button.

You are now set up to use third party Automator actions again.

« Newer posts Older posts »