Requirements

1. The Tiger install DVD .iso image from Archive.org
2. The Mac OS X 10.4.11 Combo Update (PPC) .dmg file from Apple
3. A modern Mac running macOS, logged into an admin account
4. A 4GB USB thumb drive (USB 2.0 is OK) like these in a color that matches your iBook or these sleek metal ones
5. A USB-A to USB-C adapter to plug the thumb drive into your modern Mac

Installing an SSD

First and foremost, you're going to want to replace the internal drive with a high-capacity, high-speed SSD so you'll have plenty of room for activities. You'll need two parts:

1. A known-compatible M.2 mSATA SSD from Transcend
2. A known-compatible mSATA to IDE adapter

Note: Don't cheap out and get a brand like Dogfish, or you'll suffer from crashes on wake! Stick to the known-compatible SSD!

You'll need a couple tools for this job:

1. 5mm hex nut driver
2. A decent set of precision screwdrivers
3. A paperclip
4. A crushed ice tray to hold screws (I swear by this and use it every time I disassemble an iBook)

Follow the iFixIt guide to swap the hard drive out. As you follow the guide, use one row of the crushed ice tray for each step and one column for each different screw type mentioned in the step, then go backwards to reassemble. With this technique, you're guaranteed to never screw your screws up!

Making the bootable thumb drive

First, download the Tiger install DVD .iso. It'll show up in ~/Downloads.

Then, plug your USB thumb drive into your modern Mac using your USB-A to USB-C adapter.

Next, open Terminal and type the following command:

diskutil list

Generally, your thumb drive will be the last entry and will say (external, physical):

/dev/disk9 (external, physical):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:                            UNTITLED                *15.5 GB   disk9

Remember the value under IDENTIFIER -- that's how we'll refer to the disk going forward. In my case, it's disk9.

Then, we'll unmount the disk to get it ready to copy (be sure to replace diskX with your disk identifier):

sudo diskutil umountDisk /dev/diskX

Next, we'll copy the .iso to the raw disk using dd. Again, be sure to replace diskX with your disk identifier.

sudo dd bs=1m if=~/Downloads/MacOSX.4.iso of=/dev/rdiskX

This can take around 15 minutes. At any time, you can press ⌃ + T (Control + T) to see progress.

When it's done, you'll see something like this:

3615+1 records in
3615+1 records out
3791523840 bytes transferred in 852.228331 secs (4448953 bytes/sec)

And your thumb drive will mount up as Mac OS X Install DVD on your desktop!

But you're not done yet, it's time to modify the installer to work on your old iBook!

Modifying the thumb drive to install on older iBooks

Your new USB thumb drive will install nicely on any Firewire equipped iBook, but if you want to boot it on older Apple hardware, you'll need to modify a file inside of the OSInstall.mpkg.

Open the file directly in TextEdit with the following command:

open -a TextEdit /Volumes/Mac\ OS\ X\ Install\ DVD/System/Installation/Packages/OSInstall.mpkg/Contents/OSInstall.dist

Find the line that looks like this:

function checkSupportedMachine(machineType){
        var badMachines = ['iMac','PowerBook1,1','PowerBook2,1',
        'AAPL,Gossamer', 'AAPL,PowerMac G3', 'AAPL,PowerBook1998',
        'AAPL,PowerBook1999'];

Remove everything between [ and ] so it looks like this, then save changes:

function checkSupportedMachine(machineType){
        var badMachines = [];

Preparing files to update to 10.4.11

Download the Mac OS X 10.4.11 Combo Update (PPC) .dmg file, then copy it to your thumb drive.

After the install is complete, we'll simply mount this disk image and run the updater.

Preparing files to install Mac OS 9 (optional)

Download the Mac OS 9 Boot kit, unzip the file, rename it so it has a .dmg extension, then copy it to your thumb drive.

Adding software

I like to include a few pieces of software from Macintosh Garden on my thumb drive so I can get started using my fresh iBook right away. Download whatever you need and drag it to your thumb drive!

Note: Be sure to leave at least 20 MB of free space on your thumb drive or you may find that the installer never boots. When this happens, verbose mode (hold ⌘ + V when booting) will show a message saying that /private/var/tmp is full. If this happens, simply delete some of your extra software and it will boot right up.

Booting your thumb drive

Using the the new probe-usb boot method, we can boot your new installer thumb drive on any G3 Mac:

First, plug the thumb drive into your iBook.

Next, power the iBook on and immediately hold ⌘ + ⌥ + O + F (Command + Option + O + F) until the machine boots into OpenFirmware and shows a command prompt.

Finally, type this (exactly as written!) and hit Enter:

probe-usb boot usb0/disk:3,\\:tbxi

Your iBook will then begin to boot the Mac OS X installer!

But before you rush through the wizard, partition your drive to dual boot OS X and OS 9!

Partitioning your drive to dual-boot OS X and OS 9

If you plan on dual-booting, I recommend using Disk Utility in the installer to partition your drive to have two separate partitions. This way, you can hold down ⌥ (Option) after powering on your machine to choose which OS to boot.

Note: Obviously, this erases everything on your iBook's hard drive.

1. Select Utilities -> Disk Utility from the main menubar
2. Click your internal drive in the left pane
3. Click the Partition tab
4. Select Volume Scheme: 2 Partitions
5. Click on the first partition, set its name to Mac OS X
6. Click on the second partition, set its name to Mac OS 9
7. Use the slider to give Mac OS X 3/4 or more of the drive space (even 8GB is plenty for OS 9)
8. Check the Install Mac OS 9 Disk Drivers checkbox
9. Click the Partition button

Then, continue with the installation as normal.

Updating to 10.4.11

After your install is complete (remember, you can skip registration with ⌘ + Q), double click your Mac OS X Install DVD thumb drive on the desktop, then double click the MacOSXUpdCombo10.4.11PPC.dmg file.

Follow the wizard, let it reboot, and you're done!

Installing OS 9 (optional)

You can install OS 9 directly from your Mac OS X installation, no need for boot disks!

Launch Disk Utility and use it to restore the Mac OS 9 Boot kit you prepared in the previous step to your Mac OS 9 partition:

After that, run the following command to bless the System file (otherwise it won't boot!):

bless --folder /Volumes/Mac\ OS\ 9/System\ Folder/ --setBoot

Then, you'll be able to boot into either Mac OS X or Mac OS 9 by holding ⌥ (Option) after powering on your machine:

What's next?

Now that you're all set and have a booting iBook, consider rebuilding your iBook's battery, or paying me to do it for ya!

In the interest of seeing more of these beautiful laptops in use, I put together a guide to necromancing iBook batteries, the right way. Follow along and let's get you computing in style!

Feeling lazy? I sell these

This is sort of hard to do. You need about $165 worth of tools and parts, 1-3 hours of time to build it, and 15+ hours to train it.

💣 There can be sparks, red hot glowing metal, fires, and cute little explosions if you do it wrong. Folks that are generally pretty good at what they do have attempted this and they still struggled. But they didn't have this guide ;)

If that sounds like a bad time, then just buy a rebuilt battery from me for $250 + $50 core charge that will be refunded when you send in your Apple OEM iBook battery (BTI or other aftermarket batteries are not accepted as a core). Click the button below and I'll run to the shop and build you a freshie.

If $250 is too steep or you're one of those chaps that lives and dies by DIY, roll up those cuffs and let's continue!

Parts

First, you're going to need some flat top, unprotected 18650 cells. These cells need to be ~65.2mm in length, and 18.5mm in diameter, so check the datasheet of the cells before purchasing.

1. A dead, Apple OEM iBook battery (BTI or other aftermarket batteries won't work, the cases crack when opened)
2. 18650 cells such as Samsung 30Q or Samsung 35E
3. Nickel strips with a minimum length of 75mm, such as these individual strips
4. Solder, I prefer 63/37 rosin core solder for its lower melting temperature
5. Some electrical tape, any will do, Scotch Vinyl 700 electrical tape is cheap and leaves no residue
6. Optionally, some kapton tape to replace the tape you'll remove when you disassemble certain styles of battery packs

Tools

The most important tool you'll need is a spot welder. Personally, I have a cheap Kerpu model from Amazon. It's battery powered and comes with some of the nickel strips you'll need, and you can get these pre-cut nickel strips when you run out.

1. Spot welder, such as the Kerpu Mini Spot Welder
2. Soldering iron, such as the awesome, USB-C powered TS-101
3. Tweezers, such as the Hakko CHP 00D-SA Fine-Tip Tweezers
4. Medium sized flathead screwdriver, or even a couple of of them
5. Multimeter, such as the Fluke 101
6. An iBook, of course, to train and test your new battery

Preparation

First, put your existing dead battery into your iBook. Run the following command:

system_profiler SPPowerDataType

You should see the capacity values for your battery:

Battery Information:

  Battery Installed: Yes
  First low Level warning: No
  Full Charge Capacity (mAh): 509
  Remaining Capacity (mAh): 10
  Amperage (mA): 253
  Voltage (mV): 14558
  Cycle Count: 151

You can also open up System Profiler to get this info, or even use coconutBattery 2.6.6 from coconut-flavor to read this information.

✅ If you see a Full Charge Capacity value of a reasonable positive number, your controller board is good and you're ready to rebuild.

❌ If you see negative numbers, wild numbers like 42124 cycles, or a 10000mAh full charge capacity, or an original capacity of a negative number or insanely high number like 33293mAh, your controller board is bad and you should source a different battery to rebuild

Testing your new batteries

First, get out your multimeter and ensure that each one of your new cells has the same voltage. The charge state of the cells doesn't matter, they just all have to be really close in voltage; 3.84V and 3.85V is fine, but 3.75V and 3.85V is not.

If your cells are different voltages, you can charge them with any old 18650 battery charger.

💣 If you skip this step, your battery will never charge to its full capacity (the iBook BMS doesn't balance well, if at all), and you risk creating an expensive and dangerous handwarmer if you join a fully charged cell and fully discharged cell together in parallel.

Opening the pack

💣 The most important part of this step is to avoid damaging the delicate ribbon cable that runs between the black battery connector and the cells on the thin side of the battery. Under no circumstance should you insert your screwdriver on the side with the connector!

The goal here is to break the adhesive on the top of the case free from the batteries so you can remove the top case.

1. Start with the black connector of the battery facing upwards and away from you (the "iBook Lithium Ion Rechargeable Battery" text should be facing towards the sky, but read upside down).
2. Insert your flathead screwdriver near where the little clear plastic tab is and twist it. Work an inch or so on either side of the tab to get it started
3. Slide your flathead between the batteries and the top case and start working your way to the ends of the battery, levering the case away from the cells as you go, but again, only on the side opposite of the black connector
4. Work your way around the pack, and when you get to the edges, you can switch to using your hands and finger nails to pull the case apart
5. Once you have the top case off, you can insert your screwdriver under the batteries and pop them gently out of the bottom case
6. Gently remove the batteries, black connector, and battery board as one piece
7. Heat up your soldering iron and desolder the 5 nickel strip tabs from the ribbon cable and PCB. As you remove the cells be sure to keep them in the same orientation so you can use them as a guide when you create your new packs.

Take a deep breath and stretch, that was stressful!

Rebuilding

Before you begin, be sure to note the orientation of the batteries, it's best to take a photo you can refer to.

Cut nickel strips

Straighten out each of the 5 nickel strips on the old packs and cut new nickel strips to to length, leaving 5mm+ of extra length you can trim later. Don't cut them to be thinner yet, you'll do that after spot welding. You should end up with:

• 1x ~48mm - this connects the outermost positive side of the pack to the PCB
• 3x ~35mm - these connect the middle sides of the packs and the outermost negative side to the ribbon cable
• 2x ~75mm - these join packs of 2 together and connect to the PCB and ribbon cable

Set these aside, or better yet, line them up with their corresponding locations next to your old pack.

Assemble your first pair (leftmost)

We're going to do this from left to right with black connector facing up and away from you.

1. Start by removing the small white plastic piece from between the first pair of batteries, you'll want to cut or remove the nickel strip to free the plastic piece.
2. Take two new cells, face them the same direction, insert the plastic piece between them, and lash them together with some tape.
3. With the positive side up, take the 2nd longest nickel strip (48mm) and place it on top of cells
4. 💣 At this point, it is critical that you double check that both batteries are facing the same direction
5. Center the nickel strip across the cells and use a small piece of tape across the strip and one of the batteries to hold it in place
6. Turn your spot welder on, without touching the metal tips of the spot welder or the nickel strips with your fingers, and without touching the tips together, place both of the tips on the nickel strip in the center of the battery, 2-3mm apart, and hold them there until the spot welder sparks, then remove the tips
7. Make 1-2 more welds on either side in a ⠶ or ⠿ pattern, making sure you're still above the button on the top of the battery
8. Remove the tape and weld the nickel strip to the other battery
9. Flip the pair over so the negative side is facing up, take the longest nickel strip (75mm) and place it across the the battery, with the long end facing away from the long end on the positive side. If that sounds confusing, just refer to the configuration of the old cells.
10. 💣 At this point, it is critical that you double check that both batteries are facing the same direction. If they're facing opposite directions right now, you will be making an IED, not a battery.
11. Again, center the nickel strip and use a small piece of tape to hold the strip to one of the batteries
12. Do the spot welding thing again
13. Remove the tape, do the spot welding thing again

You should now have a nice pair of cells with nickel strips that match the configuration of the leftmost pair in the original pack. Phew!

Assemble your second pair

This is a lot like the first pair, except you're going to use the shortest nickel strip on the negative side of the battery, and this pair of batteries doesn't use a plastic piece as it needs to leave room for the thermistor.

1. Take two new cells, face them the same direction, and lash them together with some tape
2. With the negative side up, take the shortest nickel strip (35mm) and place it on top of cells
3. 💣 At this point, it is critical that you double check that both batteries are facing the same direction
4. Center the nickel strip across the cells and use a small piece of tape across the strip and one of the batteries to hold it in place
5. Do the spot welding thing
6. Remove the tape, do the spot welding thing again

You should now have a pair of cells that are only connected on the negative side.

Assemble your first set (leftmost)

Now we're going to turn two pairs into a veritable foursome of 18650s in a 2S2P configuration.

1. Take the pair of cells with no plastic piece and the shortest nickel strip and place it positive side up with the nickel strip facing off to the right.
2. Take the pair of cells with the plastic piece, the longest nickel strip, and the 2nd longest nickel strip, and place it positive side down with the longest nickel strip facing to the right, hovering over the positive side of the other pair of cells
3. You should have 4 batteries side-by-side, standing on end.
   • The left 2 batteries should be negative side up and have a long nickel strip going off to the left.
   • The right 2 batteries should be positive side up and have a short nickel strip going off to the right.
4. Use a piece of tape to hold the nickel strip to the rightmost battery in the rightmost pair.
5. Do the spot welding thing again
6. Remove the tape, do the spot welding thing again
7. Bend the longest nickel strip holding 2 pairs of cells together so they're positive to negative

If you did this right, nothing is on fire and you have a battery pack with 2 pairs of 2 cells, the leftmost pair should have a plastic piece and a long nickel strip facing away from you, and the rightmost pair should have no plastic piece, 1 medium nickel strip tab in the middle facing away from you, and one nickel strip tab on the right facing away from you.

Assemble your third pair

Follow the same process as above for the first pair, except this pair will use the shortest nickel strip (35mm) to connect the positive sides of the pair.

Assemble your fourth pair (rightmost)

Follow the same process as above for the second pair, except your fourth pair will use a plastic piece as well.

Assemble your second set (rightmost)

Follow the same process as above and make it look like this. If you're ever lost, compare it to your original battery pack (you kept it in the right orientation, right?).

Trim the nickel strips

Look at your original battery pack -- the nickel strips are thinner where they connect to the ribbon cable and battery board. Trim your nickel strips to match both width and length, and be sure to pay attention to orientation so the thin part you cut is on the correct side. Compare to the old pack every step of the way!

Now you're ready to solder it up!

Solder both sets to the ribbon cable

Now it's time to bend the nickel strip into place and solder them to the PCB! Start by tinning both sides of each nickel strip tabs with solder, then tin the pads on the ribbon cable and PCB, then slip the ribbon cable/connector/battery board assembly into place and bend the tabs so they line up.

This is where the tweezers come in -- I like to use them to hold the tabs in in place while I apply heat. I find the tweezers don't smolder and burn like fingers, and there's no awful smell or searing pain either. Line up the tabs, heat them up real good, hold them in place, then wait a few seconds before removing your tweezers.

Ensure you've made a positive connection, then rejoice -- you're (almost) almost done!

💣 It is imperative that you take care to not touch your soldering iron to the battery while doing this. Your soldering iron will instantly melt the insulation on the battery, and if you're soldering a positive terminal, will short the battery out, causing a big, scary spark.

Pre-assembly testing

First, get out your multimeter measure the voltage between the leftmost nickel strip (connected to the battery board) and the rightmost nickel strip (connected to the ribbon cable).

You should get a voltage reading corresponding to the individual cell voltage multiplied by 4. For instance, if each of your cells measured 3.85V before you build the pack (you made sure they were all the same voltage, right?), your pack should read 15.4V.

Next, double check all solder joints are solid, there are no shorts, no dangly bits, nothing that appears sharp or dangerous.

Partial assembly

Drop the completed pack into the bottom battery case, taking care to ensure that the ribbon cable is not pinched by the edge of the case. Align each of the plastic inserts to the tabs that slot into them, then press the batteries in so they're snug. The black connector slots right in, and everything should fit nicely.

We're not going to put the top case on yet, first we need to test your pack.

Post-partial assembly testing

Insert your partially assembled pack into your iBook and fire it up. Run the following command:

system_profiler SPPowerDataType

The Full Charge Capacity will not have changed, but you should see the same voltage you measure during Pre-assembly testing listed after Voltage.

If your battery is recognized and the voltage is correct, it's time to button things up.

Final assembly

Now that we've confirmed your pack works, it's time to install the top case. Line up the grooves in bottom case with the insert on the edges of the top case and work it into place. Squeeze the case and the edges of the case so it slots into place. The adhesive present on the cases will hold the pack together, there's no need to glue anything.

💣 Be careful while you're doing this -- if something is going to short out and explode, it's probably going to happen now. Be ready to throw your battery our the window.

Smoosh the edges of the battery one more time to get it as svelte as possible, then insert your freshly rebuilt battery into your iBook. Be careful when putting on the bottom battery cover -- make sure the battery is as far to the edge of the iBook as possible and be gentle when putting the cover on. Rebuilt batteries can be a little thicker than the originals, and if you're not careful, you'll crack a tab off your battery cover.

Fire it up, and take a deep breath! You're only 15 hours away from being done!

Retraining

I discovered that retraining the battery involves simply following this little stanza from the Gas gauge operation section of the bq2040 datasheet:

FullChargeCapacity or learned-battery capacity

FCC is the last measured discharge capacity of the battery. On initialization (application of VCC or reset), FCC is set to the value stored in the EEPROM. During subsequent discharges, FCC is updated with the latest measured capacity in the Discharge Count Register, representing a discharge from full to below EDV1. A qualified discharge is necessary for a capacity transfer from the DCR to the FCC register. Once updated, the bq2945 writes the new FCC to the EEPROM. The FCC also serves as the 100% reference threshold used by the relative state-of-charge calculation and display.

So you just drop in, slap the EEPROM value into the FCC wha-pop, drop down to EDV1 wha-paaa, and then after that, you just drop the DCR into the FCC, ride the barrel, put the FCC into EEPROM, then get pitted, so pitted.

Put simply, charge the battery all the way, then drain the battery all the way.

Initial charge

Let your iBook charge the battery all the way. By all the way, I don't mean 100%, I mean to about 16.8V (4.2V multiplied by 4). You'll want to leave it plugged in for several hours, and you'll want to be in the same room and relatively lucid during this time in case something happens during charging and you need to throw your flaming iBook out the window.

Run the following command to monitor battery voltage:

while [ True ]
do
  system_profiler SPPowerDataType | grep Voltage
  sleep 10
done

Once you see it level out at around 16.8V (or 16,800mV), you're ready for the next step.

Initial drain

If you simply unplug the power adapter and let your iBook drain the battery, it will never hit EDV1 (12.0V) -- it will sleep long before that. This means the FCC value will never be written to the EEPROM, and your iBook will sleep long before your battery is drained.

You have two options:

1. Boot into OpenFirmware (hold Command + Option + O + F after pressing the power button) or the Boot Picker (hold Option after pressing the power button)
2. Boot into the Mac OS X installer (you can do this from a thumb drive too)

Once you've booted, unplug the power cord and wait about 9 hours. Once the battery voltage hits 12.0V, the machine will power off.

I prefer to boot the Mac OS X installer and run the loop command from above to monitor battery voltage while it dies. You may wish to unmount your hard disk after booting into the installer so it's unmounted cleanly, because, at the end of this process, the machine powers off.

The moment you've been waiting for

After about 9 hours, and once your iBook has powered itself off, we're ready for the moment of truth.

Plug your power adapter in, boot your iBook, open the Terminal, take a few deep breaths, and run the following command (or pop open coconutBattery):

system_profiler SPPowerDataType

You should see something like this -- a new value for Full Charge Capacity (somewhere around 5,000mAh), and one more cycle added to the Cycle Count:

Battery Information:

  Battery Installed: Yes
  First low level warning: No
  Full Charge Capacity (mAh): 5138
  Remaining Capacity (mAh): 36
  Amperage (mA): 1405
  Voltage (mV): 12787
  Cycle Count: 152

If Full Charge Capacity didn't update, don't panic -- just wait a second and run the command again. It can take a minute for it to update sometimes!

Conclusion

You're finally done! You can now let your iBook battery charge up and should get 5+ hours of runtime!

Be sure to discharge your battery to about 60% and remove it battery from your iBook if you plan on storing it for a long time. iBooks don't have PRAM battery, so it will slowly sip your batteries precious bodily fluids until it's beyond empty if you leave it installed during long term storage, which we all know isn't healthy.

Again, I sell these

If all of this sounds like too much, just buy one of the battery packs I have for sale!

Credits

None of this would be possible without the following resources:

• This MacRumors thread discussing battery rebuilds and retraining
• The datasheet for the magical bq2040

My first truly personal computer -- not the family computer, but mine -- was a Macintosh SE. My Aunt Joan gifted it to me after upgrading to a PowerMac, and though it was already 10 years old, it was brand new to 10-year-old me.

Coming from DOS machines, the elegance and simplicity of the Macintosh completely enthralled me. There was no autoexec.bat, no config.sys, no SoundBlaster, and no IRQs to set. You flip a switch and it just worked.

And the interface, wow. You were greeted by a friendly chime and the happiest little face on the happiest little computer every time you turned it on. Everything was where you expected it should be. The dialog boxes were helpful, the icons friendly, and the applications simple, yet powerful. The Macintosh hooked me right away, and I used it constantly.

My little machine could do tricks. I power it on. It smiles. I smile.

I collected software, arranged my icons, dragged and resized windows in the Finder so they opened just a couple pixels under one another, fixed it, broke it, and fixed it again. I played games on it, scanned pictures, used Graphic Converter and BBEdit, created MOD music. It was my escape from reality, where I could control everything and get lost in a world of creativity. Where I could design a house, then fly a paper airplane through it. A portal to another world.

I visited my first website on a Macintosh. I wrote my first website on a Macintosh.

Fast forward 25 years.

I'm back home during the COVID-19 pandemic, and life is complicated, scary. America is divided. Friends are getting sick, and family members have passed away. Nostalgia for a simpler time is strong.

I've pulled out all my old Macintoshes, my old disks. The same ones 12 year old me had in plastic disk case when a bully pushed me over, causing them to spill on the steps of the portable classroom. Simpler times, maybe, but not perfect.

But I have my little escape; my Performa 200 (aka Mac Classic II). A black and white, 9" display. A clicky mechanical keyboard and a one button mouse.

I plug it in. I power it on. Checkerboard background, a sign of damaged components.

I clean the electrolytic capacitor juice off the components with isopropyl. I replace the PRAM battery with a fresh 14250 cell. It was old, but luckily hadn't ruptured.

I power it on. A question mark blinks inside of a disk icon.

I remove the cover from the hard drive, exposing its platters. I flick the drive's magnetic head to get it going again. It's old and not moving like it used to.

I power it on. It smiles. I smile. A long lost friend.

I back up its hard drive using an external SCSI enclosure and another, internet-connected Mac. I back up every single floppy disk from the plastic disk case. Every byte of data I could read, I saved. All my old high scores. My collection of MOD music. My earliest essays and short stories.

I relive the experience of it all. I relive the wonder. I'm taken back to a time when a black and white screen could show you all the color in the world, as long as you used your imagination.

As old hardware begins to fail and spare parts become scarce, pieces of the experience fall away. Even after recapping the motherboard with fresh tantalum capacitors, there's no guarantee it will continue to function indefinitely, and it's not the same to use old software on a sleek, new MacBook; the feeling just isn't there.

I never want to lose the ability to go back to that time when things were simpler, to feel the wonder I felt when I was a kid, so I built Macinpi; a new computer with the charm of an old computer.

Hardware

No working computers were gutted in the making of this machine. Some of the pieces were leftover bits from someone else's simpler time, some new.

Case

It started with the case. Amidst a pile of computer parts -- buyer must take all -- a Macintosh Classic case. It was in pretty decent condition with a working fan, and it had only a handful of scuffs and scars.

I asked about it. Why just the case? What happened to the rest? The owner explains an Amiga fell on the picture tube, crushing it. The motherboard was donated, the last missing piece to someone else's Classic. The power supply board was sold and shipped, bringing another Mac back to life. They can't find the screws or the cover for the display adjustments, but it's mine for $10 -- and a classic double from Arby's, if it's not too much trouble.

So I drop off the Arby's, send my $10, and pick up the case.

It's very friend-shaped; it just needs something to fill the hole where its display used to be.

Display

I think this little computer deserves a little color in its life. It's got a rainbow logo on the front of it after all, certainly black and white wouldn't suit it.

I choose the Pimoroni 10" display after seeing that it fit the case perfectly in PepPi's build, and was wide enough that no ugly bezels would be visible. And the wiring is clean, I like that. $99 later, it starts to look like a computer again.

CPU

There's a Raspberry Pi 4 2GB lying around I had bought to build another RetroPie box with. $45, at at the time at least. It would plug right into the display, and with an emulator like Basilisk II, could paint a smile on the screen and load all my old Mac applications.

Perfect.

Keyboard & Mouse

An Apple Adjustable Mechanical Keyboard popped up on Craigslist. It's missing the numeric keypad, but who needs that? I chat with the seller for over an hour. We talk about everything from space exploration, to forgotten anniversaries, to what it was like for him growing up in Compton as a black man in the 70s. We shake hands. $100.

I have an Apple mouse from the old days, rectangular and angular, with just one button.

But these won't work with the Pi. They don't have USB, but ADB (Apple Desktop Bus), Apple's proprietary serial connector.

TMK with adb_usb on an old Arduino Pro Micro clone is the answer. I download and flash the firmware. I pull a 1kΩ resistor from my old electronics organizer. 10 year old me categorized it wrong, or maybe it slipped under the dividers in the drawers, but I found it. An old s-video cable, which has the same 4 pin mini-DIN connector as ADB, is chopped up and wired in according to the schematic. Everything works the first try, $5 later.

Connectivity

The vacant holes on the rear of the machine where the old ports were need to be put to good use. My friend Kim helps me weld a steel plate back there. I trace out holes crudely with a pencil, make a few markings, drill a few holes, and route out some ports with my Dremel.

2x panel mount USB-A 3.0. 1x panel mount USB-C. 1x panel mount 4 pin mini-DIN. Some M2 and M3 screws.

$30 or so.

It fits nicely in the case after a little trimming. I harvested a power button from an old Quadra 610 case I had in the attic, and it happens to be exactly the same size as the headphone port where I placed the reset switch. I add a little hot glue and slide it onto the switch.

Supporting electronics

Though I can power the display directly from the Pi, adding any other peripherals means the voltage begins to drop and the Pi flashes its little yellow lightning bolt.

A USB-C PD trigger lets me use any decent USB-C power supply, such as a MacBook charger, and get a solid 9V 3A out of it. 5 for $10, so $2. Now I can power that fan, undervolting it a little bit to keep it quiet.

But the Pi needs power too. Pololu 5V 5A regulator should do the trick. It's not cheap, but it's quality and will provide plenty of clean power. $25.

The old Quadra 610 case donates its speaker. It's old and sounds tinny, but that's part of the charm. $0.

The Raspberry Pi can't drive a speaker directly; it needs an amplifier. A 3-12V mono LM316 amplifier module, two for about $9, will do the trick nicely.

But since the amplifier and fan are powered directly from the USB-C trigger's 9V supply, they stay on when the Pi shuts down. We'll have to fix this.

After a little lesson on basic electrical engineering from some new friends on Discord, a schematic is drawn up. A 100kΩ resistor takes the Pi's 3.3V signal from pin 8 (GPIO14) to a 2N3904 NPN transistor, 1N4007 flyback diode, and a 470µF 35V filter capacitor that bring the fan to life when the Pi powers up. As long as you have serial communication enabled, GPIO14 will provide 3.3V while the Pi is on.

Two 1.2kΩ resistors help me combine the left and right stereo channels into a single mono signal, and a 2N3904 NPN/2N3906 PNP transistor stack with a 1kΩ resistor between them switches the positive of the amplifier when the Pi comes on, because the Pi's headphone ground keeps the amp on if we try to switch the negative using a single NPN.

All of this is placed on a prototype PCB, with a mess of jumper wires underneath, acting as traces.

A momentary switch is wired between the Pi's GLOBAL_EN and J2 pins to reset the Pi from a halted state.

The hardware is ready.

Software

I start with a GUI-free Raspberry Pi OS Lite image on a 32GB SD card.

The display has a 1024ⅹ768 resolution, and its 10" display is larger than the hole in the front of the case. To correct this, I arrive at 928ⅹ672 with 48 left and right overscan, 32 top, and 64 bottom to get it fitting nicely. I edit these values into /boot/config.txt. The display is perfectly centered and has just the right amount of black border around the edges.

I compile Basilisk II without X11. I set the resolution and upload a disk image with System 7.5.3 and my backed up files.

I add initiramfs-splash to show a happy Mac start up screen the second the machine powers up. I touch .hushlogin and sudo truncate -s 0 /etc/motd to quiet things down.

I make sure to set POWER_OFF_ON_HALT=1 in the EEPROM configuration so it shuts down completely when its off, instead of entering a low-power mode.

Autologin takes me straight to a shell, and .bashrc takes it from there. aplay plays a familiar chime, and BasiliskII launches.

Macinpi lives

It's a sunny winter afternoon. I plug in a USB-C PD powerbank and take it outside. I sit at the table in the memorial garden I built for my mom. I remember simpler times.

I power it on. All my old files are there. My old games. My old high scores. The first short stories I ever wrote. My MOD music.

It smiles. I smile.

Boot and shutdown sequence

Macinpi boots with the press of a button, and shuts off completely after selecting Special -> Shutdown in Mac OS.

Scripts and config files

See lazd/macinpi for the scripts and config files I used to build Basilisk II and configure the system.

Parts list

Want to build your own Macinpi? Here are the parts I used.

System

• Raspberry Pi 4 2GB
• Pimoroni 10" display
• Arduino Pro Micro clone for TMK adb_usb

Panel connectors

• USB-A 3.0
• USB-C
• 4 pin mini-DIN

Control and power supply board

• Prototype PCB
• LM316 Audio amplifier module
• 1kΩ, 1.2kΩ, 100kΩ Resistors
• 2N3904/2N3906 Transistors
• 1N4007 Diode
• Capacitor

After making my way through history with Doom and Quake I, it was only natural that I load up Quake II...

A bug right out of the gate

RetroPie ships with support for the yquake2 engine, so it was easy to get up and running. However, I found moving the sticks made my head spin uncontrollably in circles! After a little poking around, I realized yquake2 was interpreting gamepad input as both joystick and mouse events. I found that setting the sensitivity cvar to 0 fixed it, but realized there was no way to set it to 0 using the UI.

Time to fork and clone! A one line fix made it possible to use the sliders in the UI to set sensitivity to 0.

Stick feel is everything

Once I got the controls working, I found that gamepad aiming didn't have a precise feel like I was used to in modern shooters. From my experience with FPV drones, I knew that a little "expo" can go a long way.

"Expo" makes gamepad stick input non-linear, such that small movements on the stick are less pronounced. This enables both precise and fast movements, even at higher sensitivity levels, and is part of the reason why gamepad controls in modern shooters feel more precise. It's called expo because it simply raises the gamepad input value to the specified power, or exponent.

The value of a joystick axis is a floating point number between 0 and 1. Linear joystick input with no expo results in a graph that looks like this:

However, if we apply some expo, say 2, we get a graph that looks more like this:

This means small joystick inputs result in very small movements, but slamming the stick all the way still results in the same movement as without any expo at all. Just by looking at the graphs, you can tell how this will help make aiming on a gamepad way more precise.

With this in mind, I set about adding a new cvar, joy_expo, with a default value of 2. With the new cvar, it was simple to apply joy_expo to gamepad input.

UI is... also everything

Expo made aiming feel quite a bit better, but I needed to tweak a few more settings to get it dialed in. I realized the gamepad controls in yquake2 could only be customized by manually setting cvars in the console, which means quick changes aren't quick and easy.

I set about adding a new menu in the yquake2 UI to enable customizing yaw, pitch, forward, side, and up sensitivity -- and of course, expo. I also took the opportunity to move the haptic controls to the same submenu, bringing everything together in one place.

In old game engines, this usually involves manually calculating the position of controls -- there's no layout system, so you increment a variable like y to store where the next control in the UI is drawn. It's no flexbox, but it gets the job done, and after a little tinkering, I got a nice menu system in place:

Fork it, push it, quick PR it

With all these changes in place on my local branch, the next step was to send a pull request. After a little insight from a fellow contributor, everything was buttoned up and ready to ship.

In the next release of yquake2, I was happy to find my changes released, and I hope others have found that it enhanced their retro Quake II experience just as much as it did for me.

I got excited about tiny laptops. I don't mean netbooks, I mean damn near palmtop laptops, the kind that would just barely fit in an oversized pocket... Something so small it seems impractical. Why? Beyond the needing a field laptop to tune and update FPV drones, I felt like having a tiny computer would make using it more fun. Everything from coding to web browsing, I imagined, would be more entertaining.

I found the Chuwi Minibook, an 8" touchscreen "yogabook" that runs Windows 10, and it seemed to fit the bill -- decent design, both USB-C and USB-A, a card reader, a fast CPU, and of course, a multi-touch touchscreen...

But there's was a caveat: I run macOS. I rely heavily on the ecosystem, from notes, to iMessage, to the UNIX subsystem, to the elegant user interface, it's everything I need in an operating system. Running Windows or Linux was simply not an option, and the smallest thing Apple makes is nowhere near small enough.

So can it run macOS?

Hackintoshing is hard

It just so happened that THEDEVIOUS1 had worked some wicked voodoo magic and managed to get Catalina running on the Minibook!

I was stoked! They had somehow got almost everything working, everything except the card reader, fingerprint scanner, internal storage, the accelerometer, and of course the touchscreen -- but who needs those? The dream seemed within reach; could this be the pocket-sized MacBook I've been daydreaming about?

But what about the touchscreen?

Fast-forward to having a hackintosh'd Minibook, booting Catalina... Naturally I want to try the touchscreen, but how?

It turns out there's a Linux driver for the Goodix touchscreen, and of course there's VoodooI2C, which takes I2C devices and makes them work with macOS.

Could I port the Linux driver to macOS, and somehow enable multi-touch gestures, scrolling, and right clicking? What would it take?

Spoiler alert: the answer is a weekend and a lot of coffee.

Hello touchscreen

As I was unfamiliar with VoodooI2C, I started by cloning an existing driver, VoodooI2CAtmelMXT. This gave me some boilerplate I could try to work on top of. I then stripped the code down to the basics -- methods like start, stop, probe, init as stubs with nothing more than error handling, just so I had the basic structure in place.

The next step was to try to get communication with the touchscreen working. I modeled a method, goodix_read_reg, after the method in the Linux driver, but there was a hurdle -- despite a correctly configured KEXT that should match on the GDX1001 device ID, the touchscreen didn't seem to power on and indicate it was ready for communication, so I couldn't test my method yet.

Waking up a sleepy touchscreen

According to the datasheet for the GT911 touchscreen, a reset sequence needs to be sent over I2C. We weren't doing this yet, which explained why the touchscreen didn't respond to command.

But I had a hunch -- if the touchscreen works in Windows, which would have to send this reset sequence to wake the touchscreen up, perhaps I could warm reboot from Windows, and the touchscreen would stay on? I tried it, and it worked -- after rebooting, it was clear the touchscreen was awake and listening, but all of my attempts to communicate with it were failing. I was getting junk data back and transaction errors:

(VoodooI2CGoodix) VoodooI2CGoodixTouchDriver::Starting
(VoodooI2CGoodix) VoodooI2CGoodixTouchDriver::Reading version...
VoodooI2CControllerDriver::pci8086,9d62 I2C Transaction error details
VoodooI2CControllerDriver::pci8086,9d62 lost arbitration
VoodooI2CControllerDriver::pci8086,9d62 I2C Transaction error: 0x07001000 - aborting
(VoodooI2CGoodix) VoodooI2CGoodixTouchDriver::Read version failed: -536870212
(VoodooI2CGoodix) VoodooI2CGoodixTouchDriver::Failed to init device
(VoodooI2CGoodix) VoodooI2CGoodixTouchDriver::Freeing

Meanwhile, back at the secret mountain lab from which THEDEVIOUS1 probably works from, he'd figured out how to modify the custom DSDT to send the reset sequence on initialization. We chatted on Gitter and worked out the pin addresses by consulting the datasheet and throwing a lot of trial an error at the problem. After some fiddling, we were able to get it to work from a cold boot, no Windows required! There were plenty of issues not worth getting into because they're beyond my understanding, but it involved setting up the pins correctly and coding the reset sequence into the _PS0 method. Finally, I could go back to C code land where I was more comfortable and try to make some more progress.

Endianness is important

It seems the touchscreen and I weren't speaking the same language...

Puzzled, I continued to read the specifications for the touchscreen driver, and I realized the touchscreen expects the register address in big endian, and the CPU, of course, is little endian! I used the OSSwapHostToBigInt16 method to swap the register address to big endian, and to my surprise, I got data back from the touchscreen!

VoodooI2CGoodixTouchDriver::Probing
VoodooI2CGoodixTouchDriver::Starting
VoodooI2CGoodixTouchDriver::Reading version...
VoodooI2CGoodixTouchDriver::ID 9111, version: 2020
VoodooI2CGoodixTouchDriver::Device initialized

This was the breakthrough I needed! I had a working kernel extension that matched on the ID, I was able to communicate over I2C (albeit, only a basic "hello touchscreen"), and now I just needed to... actually implement the entire driver.

Conversations with a touchscreen

After shoehorning some code from the Linux driver in, I was able to read back configuration data from the touchscreen:

VoodooI2CGoodixTouchDriver::Config read successfully
VoodooI2CGoodixTouchDriver::ts->abs_x_max = 1920
VoodooI2CGoodixTouchDriver::ts->abs_y_max = 1080
VoodooI2CGoodixTouchDriver::ts->int_trigger_type = 1
VoodooI2CGoodixTouchDriver::ts->max_touch_num = 10

Using the Atmel driver's technique for responding to interrupts, I was able to get some information back from the touchscreen, but the coordinates were wrong.

It seems I once again forgot about endianness, but this time when writing data to the touchscreen. After correcting that, I got actual, correct data out of the touchscreen:

VoodooI2CGoodixTouchDriver::Touch 0 at 1889, 19 with width 80

Armed with real data, it was time to do something useful with it.

Now let's make it actually do something

The next step was to take this data and turn it into interaction events. macOS exposes methods that let you set up multitouch interfaces, publish events to them, and, in turn, actually control the cursor and interactions in the OS.

Being completely new to this, I started simple and just made the touchscreen act like a gigantic trackpad. This involves using a VoodooI2CDigitiserTransducer and updating coordinates as I get them.

Because the MiniBook can be flipped into a tablet mode, the touchscreen could be configured to be rotated or flipped, so I had to add some basic support for dealing with those values, which was fun because casting, floating point math, and applying inversions and axis swaps in the right order. Most of this was literally poking at the screen and looking at output, as we often do with any code.

The next step was to refactor the code to use an EventDriver and move the code out of actual TouchDriver into the EventDriver. This decoupled the code that reports touch events, sets up and tears down multitouch interfaces, and handles sleep/wake events from the code that communicates with the touch screen. This separation of concerns makes it easier to reason about operations that are going on at the hardware and OS-level. Along the way, I created a Touch struct to store information about the current touches, and used this to pass information from the TouchDriver to the EventDriver for reporting.

Finally, with the correct structure in place and some help from alexandred from VoodooI2C, and some fooling around with fixes for crashes on unload and properly releasing the event driver, I was able to implement support for a touchscreen that moved the mouse to follow your finger! Except it was clicking the entire time...

The problem was that it was unclear when a touch finally ended. Given that touches come from an interrupt that triggers continuously while the user's fingers are contacting the display, I couldn't just assume the finger was lifted after an interrupt was complete. In order to get proper dragging and tapping, I had to assume the finger was down until an amount of time had elapsed, at which point I could dispatch an event that tells the OS the finger has been lifted. This was implemented using an IOTimerEventSource.

Fine-tuning touch behaviors

With basic touchscreen interactions implemented, there were still some behaviors that needed fine-tuning. Right click and tapping are non-trivial interactions that we take for granted, and a complicated system of timers was necessary to determine whether an interaction was a tap, or a tap and hold to indicate a right click.

And then there were bugs

Putting together a driver like this using APIs I'd never seen meant tons of opportunities to do things wrong. Luckily, I had help from THEDEVIOUS1, balopez83, hatran0884, and kostaskas to test and find the bugs.

Occasional kernel panics and hangs on shutdown, phantom touches, timing issues that result in reading data from the touchscreen when it's asleep, proper handling of portrait mode, and of course, that bug where it used 100% of the CPU due to spurious interrupts.

Stylus support

So we've got a touchscreen, but what about a stylus? The Minibook supports Chuwi's HiPen H3 active stylus, so naturally I had to acquire one and test it.

Curiously, the stylus worked, but would click the screen even before you touched it to the display. A little logging revealed that the touchscreen reported a touch with a width of 0 when the stylus was hovering. Armed with this knowledge, I was able to make the stylus move the mouse around.

Some additional reading of the datasheet revealed how the stylus reported button clicks, and with a little work, I was able to get clicking and right clicking working on the stylus. I then refactored the stylus to use a separate transducer to avoid confusion with touch events and called it done!

Demo

Learnings

This project took me completely out of my comfort zone and had me bridging the gap between hardware and software, all the way to the OS-level. I had to consider things like endianness, deal with interrupts and work around quirky hardware that required a little convincing to function right, and work with macOS APIs that weren't quite documented that well.

The biggest thing, however, was not working in a vacuum. Using Github and Gitter, I was able to communicate with people across the world to help test, give feedback, fix issues, and suggest approaches to problems. Without this kind of instant, global pair programming and collaboration, I'd probably still be scratching my head.

The process of creating open source software is often thankless, painful, and confusing but, despite all that, beautiful. The way the internet can connect strangers from across the globe is magical, even if we often lose sight of it amid a sea of scams and misinformation. Look for the good in the world, find something fun to hack, and have fun solving problems with internet friends who you'll never meet and will only ever know by their GitHub username.

I'd press the any key to continue and select Bring 'em, on, then instantly be launched into an exciting 3D world unlike anything I'd ever seen.

I remember spending hours as a kid finding my way through the mazes of Castle Wolfenstein, pushing against walls to find secrets and trying to beat bosses. Sure, I was young and it was violent for the time, but you get to kill Hitler, and killing Nazis is an all-ages activity.

But you couldn't play it with friends, like Super Mario Brothers and Sonic the Hedgehog. My friends and I would take turns, switching off after every level or death, cooperatively making our way through Castle Wolfenstein, hunting down Hitler and his goons. Though this was fun, and left plenty of time for snacking while the other person played, it was a "multiplayer" experience that could be improved upon.

The RetroPie Renaissance

I've often gone back and replayed old games, but when I found RetroPie, it was like I was a kid all over again. I could play anything, all the games I fondly remembered, and some I never got to play. Everything from any platform, with any release date.

Naturally I installed Wolfenstein, bought a copy of the game on Steam to get the full game files, and loaded it up.

Though the keyboard controls worked exactly how I remembered them, the gamepad controls left a lot to be desired. First, there was no way to bind strafe to an axis -- the control stick could only rotate you.

Additionally, when moving with the stick, it was all or nothing. Wolfenstein was designed in an era when gamepads only had a D-pad, and that meant pushing the stick forward on a modern gamepad just moved you forward at full speed. There's no way to creep up behind Nazis real slow and stab them in the back, which of course, is a hard requirement.

Next, there was no way to bind more than 4 buttons on the gamepad. Modern gamepads have tons of buttons, and using trigger to shoot and L1/R1 to cycle through weapons was a must. Again, because Wolfenstein was released when the Gravis Gamepad was the only option around, assumptions were made about the number of possible buttons.

But Wolfenstein's source code has been released to the public, certainly I could fix all of this and have the awesome, Wolf3D experience with modern gamepad controls, right? I had found a thread showing how to manually remap game controllers in Wolf4SDL, so it must be possible!

Let's fork it!

The Wolf4SDL project uses the modern SDL library to draw to the screen, get user input, etc. This made it a great candidate to base my work off of. However, it used the older SDL1 library, which doesn't have great support for gamepads. I looked around a bit and saw ichera had moved things over to SDL2 in a branch on Bitbucket, so I forked that and started in.

After a little cleanup and instructing the linker to use sdl2, I had it launching.

The next step was easy -- I simply hardcoded the controls I wanted into the game code, included the stick position when calculating thurst, and I was off and away! Wolf3d with modern FPS controls, woohoo!

But of course I couldn't stop there, it would feel incomplete to leave this hardcoded. I made it possible to remap all the buttons, and also added support for mapping pause, escape, previous weapon, and next weapon.

Next, it was back to menu code to add support for customizing gamepad sensitivity. Working on old video game codebases is a trip; there's no layout engine, so you're left to position controls, handle state, and even play menuing sounds all manually within your code. Coming from the world of web development where layout is a core and automatic aspect, this manual way of drawing controls is a bit tedious, but presents a fun challenge and makes building UI feel quite rewarding.

After a few fixes for things I broke along the way, I wondered -- could I add support for any gamepad, not just the XBox controller I was using? A quick google found SDL_GameControllerDB, a community-sourced database of game controller mappings. Adding this in made all the other gamepads I tried instantly work, except those with only one stick. A quick fix that checks how many axes the controller has and maps accordingly got things working nicely, even on my old NES USB controller, ironically the thing that most closely resembles the good old Gravis Gamepad.

I added a menu option to disable moving with the mouse and the ability to bind strafe left/right and previous/next weapon on the keyboard and called it done!

But it doesn't stop there, didn't I mention Splitwolf?

Making it multiplayer

While surfing the web and looking for others that had worked on Wolf4SDL on RetroPie, I found this thread on the TeamRaycast development forum, discussing how it's not possible to remap controllers to do things as simple as exit the game in Wolf4SDL. I posted back with a link to my code, showing how I got controller support working for Wolf4SDL, but then I saw another reply:

linuxwolf wrote:

It would be cool if SplitWolf worked with two separate controllers.

What's Splitwolf?!

Splitwolf

Splitwolf is a modification of the Wolf4SDL codebase that effectively makes Wolfenstein 3D a split-screen multiplayer co-op game. If you dig into how it was done, it's absolutely magical. The original structure of the code was kept intact, but methods were added that allow routines to be ran multiple times for each player, and code to stitch it all together was layered on top. Other features were added as well; the menu system was modified to allow customization of controls for multiple players, a map was added showing the location of the other players you're playing with, and of course the ability to draw the other player(s).

But it doesn't stop there. Splitwolf adds several new gamemodes like Capture the Flag, Instagib, Defuse, and more, as well as respawn, new gore, and even TANKS. There's tons of new art to support all of this, and even new weapons.

After seeing everything Splitwolf had to offer, I posted back and asked for a link to the code, promising I could make this work with multiple controllers. linuxwolf replied with the Bitbucket repository and this message:

linuxwolf wrote:

You're about to make wolf3d history if you manage to pull this off.

Bring it on!

DoomJedi is a master pixel artist from Israel, responsible for the art necessary to make Splitwolf work. Things like new player sprites so you can view BJ from the side, the gore, weapons, the vehicles, etc. linuxwolf is a clever and talented programmer from Australia, responsible for not only the magic that makes Splitwolf even work, but the code that layers on the new game modes, respawn, the HUD -- everything.

Me? I'm just here to kill Nazis on my couch with an XBox controller.

So I got to work. After a bit of a struggle getting things to run and a fight with gdb on macOS, I got Splitwolf up and running. There were a segfaults right off the bat that luckily, all had to do with controls and were fixed by remapping things to use the right scan names for SDL.

Since I'd already been in the code, it was pretty easy to get get things working on SDL2, and I started pulling in changes from the other repository, making rapid progress.

I fixed up a little menu code along the way, and got the basics up and running. We started to collaborate on discord, working out details and fixing issues as they came up. Internet magic made it possible for 3 people all thousands of miles away from each other to collaborate in real time. I learned things along the way, both by reading linuxwolf's code and asking questions, and DoomJedi was there every step of the way to test, give direction, and provide art as needed.

Everything was working, and we even fixed a couple bugs along the way. The next step was to make it turnkey in RetroPie.

Make it RetroPie-ready

RetroPie uses a collection of shell scripts to download, compile, and install games. This streamlines the usual step-by-step how tos into a one-click, turnkey operation that makes it accessible to anyone. RetroPie is the perfect platform for a game like Splitwolf to be distributed, so now we just had to write a little bash.

Because there are so many versions of Wolfenstein, from different publishers to different missions, it's necessary to match on the MD5 sum of the game files, choosing the correct binary to launch based on which game is to be played. Luckily, this technique was already implemented in the Wolf4SDL port, so it was easy enough to do the same thing.

With the script ready, I sent the pull request.

This was most definitely not the easy part. joolswills of RetroPie is a master of all things shell script, and my code was not up to snuff. We went back and forth for over a month, with joolswilis requesting several changes to share code with the Wolf4SDL script, correct issues with how I handled variables in bash, and change the way we installed binaries.

In the process, I modified the Wolf4SDL port to download the Spear of Destiny demo files, and exposed a add_ports_wolf4sdl function so I could share code between the two ports. Their data files should live in the same place, after all, so it was natural to share the install code.

I had to go deep into bash, and joolswilis wanted everything to be done right. I learned quite a bit, and in mid-January, a full 2 months and 59 comments later, the script was finally merged and released in RetroPie 4.5 on July 3rd, 2019.

Ready to kill Nazis with your friends?

If you already own Wolf3D or Spear of Destiny, dump all the files directly into roms/ports/wolf3d/ (no sub-folders), then:

1. Run RetroPie Setup
2. Select "Update RetroPie-Setup Script"
3. Select "Manage Packages"
4. Select "Manage experimental Packages"
5. Select "splitwolf"
6. Select "Install from Binary"

Then get in there and waste some Nazi scum with your friends!

See the thread on the RetroPie forum for more details.

Credits

None of this would be possible without the hard work of the following people:

• Multiplayer framework, new game modes: LinuxWolf
• Gamepad support, configuration UI, and RetroPie implementation: lazd
• Additional art: DoomJedi, Untrustable, Atina, PSTrooper, ArmanAhmadi
• Title Screen: Atina
• Title Screen Font: Tormentor667
• SDL Port: Moritz "Ripper" Kroll
• SDL2 Update: Ioan Chera
• Original Wolfenstein 3D: id Software (http://www.idsoftware.com)
• RetroPie: Jools Wills (@BuZz) and the rest of the RetroPie contributors

"The most obvious conclusion of these tests is that innerHTML is faster than "real" W3C DOM methods in all browsers."

— Quirksmode, circa 2008

Newsflash: innerHTML is slow.

The time-honored best-practice is no longer best-practice. While you weren't looking, JavaScript engines have doubled in performance multiple times, numerous optimizations have been made, and it's no longer the case that innerHTML is the fastest way to get elements into the DOM.

So why are we still using innerHTML based templates?

Because the tooling doesn't exist.

We haven't seen a major release of a full-featured, production ready template system that compiles to DOM nodes. transparency and domjs aren't really template systems, pure is magical to the point of confusion, DOMBars is deprecated, and HTMLBars is still in the works.

Enter DOMly

DOMly, named after Dolly, the first mammal to be cloned, is a template system that takes advantage createElement and cloneNode.

DOMly's goal is to be approachable, fast, and lightweight.

Fast. Very fast.

With 7x the performance of doT and Handlebars and 2x the performance of HTMLBars, DOMly is arguably the fastest client-side templating system in existence. Check out the benchmarks.

Furthermore, if you use the handle="someName" feature, you'll end up with references to elements you'll need to mutate in the future -- no querySelector required.

Zero client-side dependencies

DOMly has no runtime library and no dependencies. Compiled templates are simply JavaScript functions that create DOM objects with native methods.

Pre-compile your templates as part of your build process, and when you render them in the browser, you'll get a Node or DocumentFragment that you can appendChild() anywhere in the DOM.

Pretty syntax

The syntax is a combination of HTML for markup and control flow, dot notation for property references, () for invocation, and Mustache-style {{blocks}} for safe variable substitution:

<h1>{{data.header}}</h1>
<if data.items.length>
  <ul>
    <foreach data.items,index>
      <li if-data.current='class="current"'>
        <if data.url>
          <a href="{{data.url}}">{{index}}. {{data.name}}</a>
        <else>
          {{index}}. {{data.name}}
        </if>
      </li>
    </foreach>
  </ul>
<else>
  <p>There are no items yet.</p>
</if>

Powerful (enough)

DOMly supports conditionals, loops, helpers, partials, and even raw JavaScript.

Partials

<partial MyApp.Templates.myPartial(data)></partial>

Block helpers

<helper MyApp.Helpers.myHelper(data)>
  This string is evaluated {{data.forSubstitutions}} and passed as the last argument.
</helper>

Class methods and data

<if this.isFeatured(data.id,this.featured)>
  This item is featured!
</if>

Object iteration with named iterator

<forin data.object,prop>
    {{prop}}: {{data}}
</forin>

Raw JavaScript

<js>
    data.count += 1;
</js>

Helpers & sub-expressions

{{captalize(reverse(data.name))}}

Limitations

No room to grow syntactically

Because DOMly templates are parsable HTML, you can't use /, =, or spaces in statements.

Must be be compiled on the server

Although it would be possible to compile on the client, you shouldn't be doing that anyway.

Doesn't support arbitrary expressions

You won't be able to write {{data.count+1}} anywhere.

DOMly isn't yet battle tested

DOMly is the newest language on the block. Although it's unit tested and benchmarks, it's not battle-tested and can't be guaranteed to be bug-free.

However, in 2014, we'll see a number of template languages switch to pure DOM methods for a performance boost, and DOMly will be there to challenge them to be the best and fastest that they can be.

That's great, but why not base it off an existing template system?

1. It's an experiment

DOMly didn't set out to replace heavy hitters like Handlebars. DOMly started as an experiment to establish the performance gains of using DOM methods for templating, the feasibility of maintaining a set of these templates, and the actual amount of code required to do this from scratch.

The goal was to validate the hypothesis:

It's both possible and simple to build a template language that takes advantage of the performance gains of native DOM methods.

2. Simplicity

Existing template systems are quite complex. From advanced Jison parser tricks to dozens of regular expressions so complex that they've taken on a life of their own, to complex feature sets, these projects aren't very approachable. To re-tool an existing language would be a massive time sink just to validate a hypothesis.

Many existing template systems require runtimes that handle helpers and partials. This results in an additional call on the stack for method invocation which can affect performance. They're tiny, but the size doesn't help either gzipped, Handlebar's runtime is 4kB, Underscore is 5kB.

3. Syntax

After years of staring at PHP and JSPs, I think we could do better than this:

<h1><%- obj.header %></h1>
<% if(obj.hasItems) { %>
  <ul>
  <% _.each(obj.items, function(item) { %>
    <% if(item.current) { %>
      <li><strong><%- item.name %></strong></li>
    <% } else { %>
      <li><a href="<%- item.url %>"><%- item.name %></a></li>
    <% } %>
  <% }); %>
  </ul>
<% } else { %>
  <p>The list is empty.</p>
<% } %>

Your turn. How does this make you feel?

Does the mix of markup and template code bug you, or is the best thing since sliced bread?

See the source on Github and the benchmarks on jsPerf.

Historically impractical

Vertically centering with CSS has always required gross hacks. From negative margins to JavaScript, old-hat devs have brought out the dirtiest of tricks to accomplish this simple and oft needed layout technique.

Things aren't perfect yet, but there are two, no-nonsense techniques that will help you get the job done without making you cringe or want to off yourself with a rusty spoon.

The problem

We need to build a horizontal nav bar with elements about 32px high with vertically centered text in each of the links.

The solution(s)

Though there are a few other solutions, I'm going to talk about two flexible and reliable approaches. The first gives the ultimate in flexibility, and the second works great for situations where old browser support is still on the table.

We'll use the same markup for both solutions:

<nav class="navbar">
    <a href="#">Item 1</a>
    <a href="#">Item 2</a>
    <a href="#">Item 3</a>
    <a href="#">Item 4</a>
</nav>

1. Use the flexible box model

Flexbox is the holy grail of web layouts. It gives web developers the tools they've been clamoring for with a (relatively) simple and easy to understand set of attributes.

The CSS properties for the latest spec are simple:

.navbar-flex {
    /* Behave like a flexible box */
    display: flex;

    height: 32px;
}

.navbar-flex a {
    /* Behave like a flexible box */
    display: flex;

    /* Center items on the cross axis (vertical) */
    align-items: center;
}

Demo

Pros:

• Works with multi-line text and arbitrary elements
• Enables responsive layouts that can convert your horizontal menu to vertical with a single property

Cons:

• Only works on the latest versions of modern browsers
• A bit tough to understand
• Deprecated and prefixed properties required for full support on older browsers

Browser support

• IE 10+
• Safari on desktop and iOS
• Firefox
• Chrome
• Android

See the support tables on caniuse for details.

2. Fake it with fake tables

Layouts done using the <table> tag are hated for the lack of semantics and clumsy syntax, and rightly so.

However, you can have all the power and flexibility of tables without the <table> tag using display: table.

The CSS properties are simple:

.navbar-table {
    /* Behave like a table */
    display: table;

    height: 32px;
}

.navbar-table a {
    /* Behave like a table cell */
    display: table-cell;

    /* Vertically center content */
    vertical-align: middle;
}

Demo

Pros:

• Works in very old browsers
• Works with multi-line text and arbitrary elements

Cons:

• No support for responsive design, so your menu is stuck horizontal
• Feels dirty

Browser support

• IE 8+
• Every other browser ever made

See the support tables on caniuse for details.

It doesn't stop at nav bars

Both of these techniques can be used vertically center anything from images to modal dialogs. Use the above techniques to get full vertical centering satisfaction and avoid the odd hacks that fall apart when the weather changes.

The other techniques

There several other ways to get this done in CSS. A few of the more popular methods are discussed below

Use CSS transforms

As outlined by Brian Gonzalez in his article CSS Vertical Centering, it's possible to vertically center using CSS transform with a negative translateY.

It doesn't work if the parent doesn't have a height specified, and the browser support is less than desirable, with this hack working in IE 9+.

Use a fixed height and absolute positioning

Stephen Shaw outlines a number of techniques in his article Absolute Horizontal and Vertical centering in CSS, two of which there are a few techniques that involve absolute positioning.

The first uses positioning against the sides of a parent element, but requires height to be declared. Browser support is decent, working in IE 8+, but not on Windows Phone.

The next absolute positioning technique requires width and height to be declared and uses negative margins to offset the inner box by half of its width and height. This time-honored technique works everywhere, including IE 6 and 7.

Use a ghost element

As outlined by Chris Coyer in his article Centering in the Unknown, you can use vertical-align and inline-block to center things.

It requires a dirty negative margin hack to keep things aligned, but it works in IE 8+.

The line-height solution

For single-line text, you can set the line-height equal to the height of the box, getting you alignment.

If your text ends up wrapping, the second line falls out of the box. This works everywhere, but it's very brittle.

Calculate with JavaScript

Finally, the oft used technique of measuring height using JavaScript and calculating the correct position on load and every time the window is resized. I'm not even going to link to this, you should be doing your layouts with CSS.

The bottom line and a word on moving the web forward

Flexbox aside, every CSS vertical centering technique is a hack. Your best bet is to suck it up until flexbox support is available everywhere and choose the hack that works best for your use case and target browser environment.

However, if you are in a position to do so, drop support for old browsers. The best way to drag netizens and their governing groups into the future is to level sanctions against them: you can't use my fancy site until you upgrade your browser.

Credit for the title photo goes to Florian of Abandoned Kansai. It's a photo from the kitchen of an abandoned middle school in Pripyat he visited and documented in his article Zone Of Alienation - Pripyat: Middle School #3.

We've taken that already simple process and made it simpler with mdn.io, the "I'm feeling lucky" URL shortener for MDN.

How do I use it?

Simply type something like this in your address bar:

mdn.io/defineproperty

You can even include spaces:

mdn.io/css transitions

Or hashes:

mdn.io/array#Methods_of_Array_instances

Why?

MDN URLs are quite long:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#Methods_of_Array_instances

We needed a way to keep them short so they could be directly included in places we would otherwise say "search for ____."

Code reviews

Let's say you're doing a code review and you need to link a peer to the documentation for the Array object:

// Array has an inbuilt forEach method, see mdn.io/array

Comments

If you're writing JavaScript code that relies on some interesting in-built functionality others aren't familar with, it might be helpful to link to the documentation for it:

// See mdn.io/defineproperty
Object.defineProperty(obj, 'constant', {
    writeable: false,
    enumerable: true
})

Common questions

Sometimes you just get asked the same question so many times you wish your chat client would auto-reply with the URL to the FM:

friend: hey dude, is it call or apply that takes an array?

you: RTFM mdn.io/apply

What is this sorcery?

mdn.io isn't really a URL shortener. There's no need to create an entry for each page you want to link to; mdn.io simply redirects to a Google "I'm feeling lucky" search for your query + site:developer.mozilla.org, which in turn redirects you to the first result.

Simple and hands off, like it should be. Check out the source on Github for more details.

A big thanks

Blake Embrey and I collaborated on this project and he continues to support it by hosting mdn.io. Thanks, Blake!

According to W3 candidate reccomendation, one root elastic measurement (rem) unit is equal to the font-size of the <html> element.

Hello rem

Let's say you've defined the font-size of the <html> element as 16 pixels, and you want a 48 pixel tall <header>. Basic math tells us that's 3 rem.

html {
    font-size: 16px;
}
header {
    height: 3rem;
}

Try it

This blog is built using rem units; click the buttons below to adjust the font-size of the <html> element, and in turn, the entire site.

Wait, how is that different from em?

Elastic measurement units cascade (em spec), whereas root elastic measurement units are always relative to the root element.

With ems, the following situation becomes confusing:

CSS:

.container {
    font-size: 16px;
}
.em1 {
    font-size: 1em;
    border-top: 1em solid red;
}
.em2 {
    font-size: 2em;
    border-top: 1em solid green;
}
.em3 {
    font-size: 1em;
    border-top: 1em solid blue;
}

HTML:

<div class="container">
    <div class="em1">
        Text 1
        <div class="em2">
            Text 2
            <div class="em3">
                Text 3
            </div>
        </div>
    </div>
</div>

Result:

As ems cascade, the font-size of "Text 3" is effectively:

16px × 1 × 2 × 1 = 32px.

The same example, but with rems

If we use rem instead of em in the above example, since rems are always root-relative, the font-size of "Text 3" becomes:

16px × 1 = 16px.

CSS:

html {
    font-size: 16px;
}
.rem1 {
    font-size: 1rem;
    border-top: 1rem solid red;
}
.rem2 {
    font-size: 2rem;
    border-top: 1rem solid green;
}
.rem3 {
    font-size: 1rem;
    border-top: 1rem solid blue;
}

HTML:

<html>
    <div class="rem1">
        Text 1
        <div class="rem2">
            Text 2
            <div class="rem3">
                Text 3
            </div>
        </div>
    </div>
</html>

Result:

Why should we do this again?

If you have a need to dynamically scale your interface, in part or in whole, with absolute precision, rems can be useful.

1. A mobile interface that targets iPad Mini - You may want a slightly larger interface for the oddly sized iPad Mini display
2. User preferences for the size of the site - You could provide a preference to increase the size of your site for a given user across all their devices
3. You just want things a tad bigger - If your designers say "make everything 2 pixels bigger," you're gonna have a bad time, unlesss you're using rem units

Execution

Simply use rems in place of pixels in your CSS:

html {
    font-size: 16px;
}
.header {
    height: 2rem; /* 32px */
    padding: 0.5rem; /* 8px */
}

But fractions are hard, what if I want 9 pixels?

If you're using a CSS preprocessor, which you should be, it's easy to create a variable that represents a pixel:

Stylus:

// The size of 1rem in pixels
$baseSize = 16

// The size of a pixel in rems
$px = 1 / $baseSize + 0rem

Then, in your code, multiply the number of pixels you want by the variable:

Stylus:

html
    font-size: $baseSize

.header
    height: 48*$px
    border: $px solid black
    margin-bottom: -1*$px

Where you should still use px

You'll want to specify the font-size of the <html> element in pixels, but there are a few cases where you might want to use pixels elsewhere in your CSS.

• As the distance for text-shadow when used for a beveled effect
  • Generally, this effect looks bad for > 1px
• Elements that you do not want to scale with the rest of the page
  • Maybe you want the fine print to stay fine

Where you should still use em

If you want the flexibility of resizing a particular widget independently of the rest of the page, you should use a mix of em and rem:

button {
    font-size: 1rem;
    margin: 0.5em;
    border: 0.0625em;
    padding: 0.25em 0.75em;
}

Then, to make a large button:

button.large {
    font-size: 1.5rem;
}

The rest of the properties, specified in em units, will scale to be 50% larger.

Compatibility

Where rems don't work:

• IE 8
• iOS 3
• Safari 4

That said, all modern browsers support rem units. See the caniuse tables for details.

Fallbacks

You can specify units in pixels above if you'd like support for older browsers (minus the scalability):

width: 16px;
width: 1rem;

Show me the code

Take a look at the source of iOCSS and this blog for a few examples that combine rem units with media queries, ems, and CSS preprocessors.