A Little Atmosphere

Just a quick progress report: Since my last post, I've finished up the animation bug fixes I was working on, and I'm now doing a little decorating: think of it as turning Solitaire Till Dawn into a place with "a little atmosphere."

Much of this work has actually been done for a long time: selecting cardbacks, royalty images, and window backgrounds is all already working. But the user interface for the Decor window, where you can select these things, was clunky and hard to use. I spent some time on it, and I think it's better now.

By the way, there's one feature from old Solitaire Till Dawn that won't be in the next release: you won't be able to create cardbacks using your own photos. I'm sure people will want that, and it will appear in a later release. But right now I'm focussed on getting a usable release out the door and into your hands, and custom cardbacks would take too much time to implement. (You will be able to use your own photos for the window background; that's already working. Cardbacks are harder because they're small, so you'll want a nice user interface to scale and crop your image so that it fits nicely: that's the hard part.)

I am now adding the old sound effects to the new release. This is another feature I might have skipped if it would have taken very long to do, but Cocoa makes it dead simple. I've spent just part of today on it, and I'm nearly done already.

Update October 11 2013: I am retaining compatibility with Snow Leopard (Mac OS X 10.6.8). Everybody who wants the new version but doesn't want to upgrade to Lion or Mountain Lion, y'all can relax. And thanks for the feedback!

Here's a chance for you to make yourself heard: I am now inclined to make this new version require at least Lion (Mac OS X 10.7) or later. I was going to make it compatible with the older Snow Leopard (10.6) as well, but there are some niceties in Lion that I'd like to take advantage of. The old Solitaire Till Dawn will run in Snow Leopard if you hand-install Rosetta (which is free from Apple), and Lion is now nearly three years old, so I think requiring at-least-Lion is not unreasonable. If you are still running Snow Leopard and you desperately want the new release to work on your current system, please leave a comment here. No promises, but I'll be listening. (If you are not using Snow Leopard, please do not respond. I assume that nearly everyone following this blog is using at-least-Lion, and I only need to hear from the exceptions. Thanks!)

Bloodied but Unbowed

Last post, I mentioned that after a difficult-but-necessary architecture change, I tested all 100 games and discovered some previously-unnoticed bugs. This little status update is to reassure you all, once again, that I'm still working on Solitaire Till Dawn, and to report that I have once again descended into the pit of monsters that is concurrent animation programming, and once again emerged victorious.

I really hate working on the animation stuff. It has to look good (and it has to just plain work), and I'm not an expert on this kind of coding. This latest bug fix took me several days of studying old code and trying to remember how it works, watching the animations fail in veeeerrrryyyy sssssslllooooowwww mmmmooootttiiiooonnn so that I could see exactly what was happening, and experimenting with fixes.

By the way: if it surprises you that I can't remember how my own code works, then you've simply never coded anything very complex yourself. Every experienced programmer knows that within three months, any code written today will become as unfamiliar as if it had been written by a Martian. That's why good programmers comment their code liberally, and write it for clarity even if they don't expect anyone else to ever see it. And I do that; but There Are Times when even that is not enough, and you wind up spending significant amounts of time trying to figure out just exactly what the hell you thought you were doing when you wrote some bit of code or other.

Anyway, I won this round. But there are still more bugs to fix, so I'm going to cut this short and get on with fixing them. Happy Autumn, everybody!

ARC, pronounced "Argh"

When I built the previous (and still current) incarnation of Solitaire Till Dawn, I made the mistake of clinging to an older technology: I used Apple's Carbon API instead of their newer Cocoa framework. I had what I thought were good reasons to do so at the time, but in the long run it was a mistake (chronicled here, if you want the gory details). So this time, I am determined to do everything in the most modern way possible, doing my best to ensure the longevity of this version. In the past couple of weeks, this has caused me to take a bit of a detour to modernize an important part of Solitaire Till Dawn.

I'll explain what this is, but you'll need to be patient while I give you the background info you'll need to follow along.

One issue that every programmer has to face is memory management. Programs have to store and manipulate data, which takes up space in your computer's memory. Chunks of space get used, and as the program continues to run, may outlive their usefulness. Now, think of what your office would look like if you never threw out any piece of paper, ever, not even your scratched notes: it would soon become cluttered to the point where there was no room for more paper, nor for any work to get done. It's the same way in a computer program: you have to "throw out" the chunks of memory that are no longer useful. In the computer, this is more like erasing the paper so that it can be re-used; but it's still basically the same job of cleaning out the old stuff to make room for the new.

There are a number of ways to go about this. The original way that Apple recommended for their Cocoa framework would semi-automatically clean up some of the disused memory chunks, but required the programmer to keep track of which chunks were still in use, and to explicitly clean up some of the disused ones. The programmer had to say "okay, I'm done with this" for every chunk (except for some very temporary scratch chunks), or else the chunk might be kept forever.

A few years ago, Apple introduced a mechanism called "garbage collection" in which the Cocoa framework tried to do all the work of keeping track of which chunks were still in use, and which could be thrown out. This is a great system for a programmer, because you don't have to keep track yourself. You don't have to mark each chunk as disposable when you're done with it; you just forget about it and it gets cleaned up automagically. It's what I was using for Solitaire Till Dawn up until a couple of weeks ago.

But recently, Apple deprecated garbage collection: this means that, although it still works, Apple is warning us that it will stop working in some not-too-distant future release of Xcode and Cocoa. Apple is abandoning garbage collection because it is slow. Instead, they have come up with yet another way to manage memory, a faster and more efficient way, and this new way is now the recommended method for memory management in Cocoa. They now want all developers to convert their programs to the new way.

The new way is called ARC (which stands for "automatic reference counting", although you don't need to know that). Switching from older methods to ARC is not entirely straightforward: we developers have to make changes to our code in order to use ARC successfully. Apple thoughtfully provided a tool to aid us in converting our code to ARC, and my hat's off to them: the tool was incredibly useful. Unfortunately, it couldn't fix everything for me; in a number of places, it could only flag problems, and leave them to me to work out the fix.

There's a piece of functionality in Solitaire Till Dawn that has, for most of its history, used what is normally considered to be a bad programming practice. By "bad" I mean that the developer (me, in this case) needs to really know what he's doing in order to avoid certain pitfalls; and also that the code written this way may not be portable to new operating systems or CPUs. Well, I will claim that I know what I'm doing, and that code has been working fine in Solitaire Till Dawn for 15 years and more; but the day has come when indeed, it cannot be ported to a new architecture. It is not compatible with ARC.

The piece of functionality in question is the PCode engine, a hidden portion of Solitaire Till Dawn that is used in many of the more complex solitaires. It gives Solitaire Till Dawn a great deal of flexibility and it's the reason that Solitaire Till Dawn can contain such wildly different games as Klondike, TriPeaks, Thirteens, and Grandma's Game. I had to rewrite a big chunk of the PCode engine to make it compatible with ARC, and then I had to debug it.

To ensure that I'd done the job right, I had to play at least a couple of games of each of Solitaire Till Dawn's 100 solitaires. Some of the ones that are difficult to win required playing many more than just a couple of games, to be sure that they were working. And of course, some of them weren't working, and then I had bugs to fix. It was A Big Job, and it has taken me two or three weeks to get through it.

The good news is that it's done, and successful: I now have a fully up-to-date, ARC-compliant Solitaire Till Dawn, and it has no new bugs that I could find in over a week of searching. Yay!

The bad news is that it does have bugs. They weren't introduced by the ARC conversion (I know, because I kept a pre-ARC version for comparison), but of course they still must be fixed. In the end, the ARC conversion didn't cost me as much time as it might seem, because I knew I would have to test all 100 games again anyway. So now I've done that, and I have a list of the bugs I've got to fix. That's a good thing.

A side note: unrelated to (and prior to) the ARC conversion, some bugs cropped up in the behavior of the drawer that displays lists of games and players. I think they appeared when I upgraded to Mac OS X 10.8. I had to rewrite all that code, and that took several days. But that's done too, and was very successful.

My last post was about writing the built-in Help pages. That's still in progress; I put it on hiatus when Xcode started complaining that I was using a deprecated form of memory management. I plan to try to fix some or all of the bugs I've found next, after which I'll return to the Help pages.

As I've said before, it's a big, long job. I am spending as many hours on it as I can, every day, weekends included. We'll get there!

A Different View of the Difference Engine

I couldn't let today's Wondermark comic pass without notice! Click the link to see it.

My thanks to the author David Malki for producing Wondermark; followers of my personal blog know how fond I am of the funnies, and his is a good one. I recommend it, even if it isn't usually quite so relevant to my daily life!

(For those of you who don't recognize the name Charles Babbage or the term "difference engine", Wikipedia is your friend: http://en.wikipedia.org/wiki/Difference_engine.)

And since I know that most of you watch this space for news of Solitaire Till Dawn, here's a small update for you: I'm still working on it of course, and progress is being made daily, but I've been set back a bit by a couple of recent software issues that I'm still working through. I may post details at some point, but right now I'm in the middle of the work and don't want to interrupt it to write a longer post than this.

CSS, pronounced "cuss"

I am currently spending most of my time writing the Help Book, the built-in manual for how to use Solitaire Till Dawn.

Help Books are a collection of pages, all written (like a Web page) in HTML. Apple's Help Viewer is basically a sort of customized Web browser. Pages written for a Help Book can also be viewed in any handy Web browser, and in fact that's handy for debugging.

The Help Book for the last version of Solitaire Till Dawn was mostly written in 2000, a good 13 years ago now. I wrote very simple HTML for those pages. Since then new standards have emerged, so I'm trying to write proper, modern HTML for the new version's Help Book. And this means using CSS.

For those not familiar, CSS ("cascading style sheets") is a way to separate the layout and styling of web pages from the actual text and images. You write a CSS file that defines layouts and styles, and then you write any number of Web (or Help Book) pages that link to that single CSS file. This means that all of those pages share the same layout and styles, and it also means that you can change the layout and styles for all those pages by editing the single CSS file, instead of having to edit all the separate Web pages.

That's a great thing, and it's the reason I'm using CSS for this release. It's really the right way to go. But there is a dark side to the force that is CSS: doing simple things is simple, but anything very fancy can be difficult to figure out and debug. An example: I want my Help pages to have a navigation column on the left, with constant width; and the main text on the right, taking up the rest of the page width. It takes only a few lines of CSS to do this, but it took me hours to figure out what those lines were. I made several attempts that seemed like they ought to work, but didn't. In the end, Google was my friend and found me a tutorial that showed me the right way to do it.

In addition, I'm still working on refining the styles: fonts, faces, lists, headers, menu item and button labels, and so on. Apple's Style Guide is good for this and I'm mostly following it, but there's still room to make my own decisions, good or bad. (I'm trying to make good ones.)

Now that the main layout elements are done, I can mostly concentrate on writing the text. Some of this I can copy from the old Help Book, because a lot of it hasn't changed. Other parts must be heavily edited, and some must be written from scratch. In addition I need a completely new set of screen shots, because the appearance of Solitaire Till Dawn and its dialogs and buttons and menus has changed quite a bit. I think I've got about half of it written by now, although I'll have to go over the whole thing more than once for review and editing and cleanup before it's really done.

A side benefit of writing the Help Book is that it makes me go back and test all of the features, one by one, to make sure they really behave the way I say they do. This has smoked out several bugs that I will have to fix before release.

In other news, I put some time in on Retina-compatible graphics and I'm pleased with the results. I think I won't have to hire out any artwork except for the app icon itself, which will save both money and time.

Mavericks

A few people have asked me about Mavericks, the soon-to-be-released Mac OS X 10.9. (I'm going to miss the cat names that Apple has used for all their earlier releases.)

From what I've seen so far, there's no reason why Solitaire Till Dawn won't be fully compatible with Mavericks  I intend for the new Solitaire Till Dawn to work with any version of Mac OS X from Lion (10.7) at least up through Mavericks—of course I can't promise anything beyond that at this time, since we have no idea what future OS X releases will be like.

My last post went up only about 24 hours ago, but I have been working since then. I am writing the online help. Yesterday I spent mostly fighting with CSS, trying to get the pages nicely laid out. In the process I got the first few pages of help written in the new style; their actual text content I just copied from the old version, because none of that info had changed much in the new release.

I've learned some useful trivia in the process, such as how to write "⌘" in HTML. (It's ⌘ if you're curious.)

Today I'm starting to design the pages for stuff that has changed. So I have to write new text, but at least I've mostly got the formatting problems solved now. Onward!

Back in the Saddle

No news since March! Time for an update.

The house-moving is done, yay! (Well, it's never completely done, but it's 99% done and the rest isn't urgent.) The family's health issues I've been alluding to are also mostly resolved, and in a good way: we're all doing fine, thanks.

So... does that mean I'm finally back to work on Solitaire Till Dawn?

Yes. Yes, it does. It's taken half of a year to get all of these issues taken care of, but life is finally settling back towards sanity, and I have actually been able to spend time on software development during the last few weeks. Here's where we are:

I am nearly done with adding features (whether new or old). Most recently I completed work on the old "Game Number" feature, where every shuffle has a number that can be used to re-create it. You can share a challenge with a friend, for example, by choosing "Show Game Number" from the File menu and sending the number to your friend, who enters it by choosing "Play Game Number" and entering the number you sent.

I have also finished adding in some missing behaviors. For example, until a couple of weeks ago, selecting "New Game" didn't give you any warning or chance to change your mind if you were in the middle of an unfinished game. Now the old preference settings for that sort of thing are fully implemented, and you do get the warning and chance to cancel if, for example, you clicked the New Game button by accident.

This morning I achieved a really good improvement in startup time. It had been taking 30 seconds or longer to launch Solitaire Till Dawn and present the game window; now it takes about 3 seconds.

So all of that is just to show you that yes, I've been working! But I know that what you really want to know is what's left to do, and how long it will take.

Sorry, but I still can't predict how long it will take to finish. (Pause for loud groans from the audience, and a few people shouting boo! and throwing overripe fruit.) This is because much of what's left isn't up to me.

There's still the polish-and-debug stage to get through; that part is up to me. It will be done when I feel like all of the significant bugs are fixed, and when I'm not finding new ones very often. But I've done a lot of that already, as I worked on other things, so I'm not too concerned about it.

I also have to write the online help. That will take time, but it's pretty straightforward and I don't expect any big difficulties or setbacks; so I'm not too concerned about that either.

Then there's artwork. This is a big deal. When I wrote the first version of Solitaire Till Dawn, most of my customers still had black-and-white Macs with a tiny screen. It was fairly easy for me to provide all the artwork, even though I'm not much of an artist. When the Mac II and larger color screens started getting popular, it was harder (because I'm not much of an artist!) but I could still manage on my own. But when really big, deep-color Macs became common, I started having to hire real artists. Nowadays, the App Store and the high-resolution Retina displays have raised the bar absurdly high. All of the artwork must be of professional quality: not only because users have come to expect it, but because the App Store will not accept apps that look slapdash. (For example, every app must have an app icon in deep color, and sized at 1024x1024 pixels! That's bigger than my cards used to be!) So one of my next tasks is to come up with a comprehensive list of images—card art, app icon, toolbar buttons, dialog images, status bar icons, etc.—and hire somebody to make them. And then wait for them to be done.

And when everything is really done and ready to go, I have to submit it to the App Store. Getting a new app approved can take months, from what I'm told.

So hang in there, if you can. I know that inevitably some of you are going to give up on waiting. I'm truly sorry to disappoint you; I probably want this done myself more than anyone else on the planet; but as I keep saying, it's a big job and it will take as long as it takes.

But I am working on it!