On February 14th, 2025, Martin Pilkington died.

I don’t remember exactly where I first met Martin. We probably both hung out on Apple’s Cocoa-Dev mailing list or other online spaces, but we first met in person at NSConference, I’m sure. He was immediately likeable, impossibly young, and full of ideas. He made Mac apps and knew a lot. It was fun to talk shop. You could help him out, he could help you out, and everyone came out a smarter, more optimistic person.

After Scotty closed down NSConference, we didn’t run into each other that often anymore. We followed each other on Twitter, and I learned about his first encounter with cancer, and how he’d managed to get past it, and I learned about the apps his M Cubed Software worked on, and we had lots of fun conversations and polite disagreements about things going on in the Apple world. But we didn’t run into each other much, beyond 160-character bursts here and there.

Until a few years ago, he created PilkyCRC on Twitch. There he was, doing what you’d now call a body-doubling stream, of him working on his newest app Coppice, updating his web site, and just conversing with viewers about lots of development questions. He freely gave advice, he also graciously took it. Coppice was a gorgeous mind-mapping app. You just placed stuff on a canvas, dragged connection noodles between them, and there were so many clever small touches to reduce friction in the process. And it looked like it had been built and refined by a team of 20, not a clever young man from the North West of England. But here he was, on stream, building away at it, line by line, both textual and graphical.

Also, he had an amazing setup with a virtual avatar. A 3D-rendered “desk lamp”-style iMac avatar with a face that moved as he spoke. He could push buttons and “Pilky” got angry, desperate, went to sleep … eventually he built an amazing Unity setup. A spaceship with multiple rooms, projection screens to show his screen capture when working on code, or rooms little Pilky iMac could move to for some change of scenery.

There were channel point redeems, where you could spend the “currency” that every viewer accumulates per minute watched to throw “bugs” at him, or turn off gravity, making him float around the space and hearing Martin act everything out hilariously. He also drew the cutest emotes of his avatar. It was nice to have him back, to have those conversations again, to benefit from his experience and pick his brain. To hear him act the grumpy curmudgeon and to hear him laugh.

Then he had a doctor’s visit, symptoms he hadn’t seen before, and the doctors said the cancer was back. As someone who only saw his public face on the ‘net, I don’t know what his immediate reaction was (probably like any of us would react), but by the time I heard about it, Pilky was raring to fight this thing. Do everything he can.

But it had advanced too far, it wasn’t looking good. The day came, sometime late in 2024, when he announced that he was in the process of sorting his affairs.

Fuck he was young.

Fuck he was brave.

And Fuck Cancer.

Under the Hood

A C compiler eventually needs to compile to machine code. Machine code only has hard, fixed-width types like a 32-bit int, 64-bit int etc. (or rather, it has memory blocks of that size + operations that operate on memory of that size and either treat it as signed or unsigned)

The people who created your compiler need to generate these instructions, so had to hard-code a few built-in numeric types. Let’s say they called them __int64, __int32, __int8, __int16, __uint64, __uint32, __uint8 and __uint16. These are non-standard type names specific to this compiler.

Unpredictably-sized Types

In addition, they define long, short etc. as synonyms for these types. These are standard type names that have been around since the birth of C. However, they are not of a fixed size. There are just a few vague rules how these types must relate to each other.

And not all of them are still followed in practice. E.g. the recommendation is that int should be the “native” number type of the computer’s CPU. The one that’s the fastest. But when modern operating systems switched from 32-bit to 64-bit CPUs, they didn’t want everyone to have to rewrite their code. So most 64-bit platforms use a 32-bit int, even though a 64-bit number would be the more natural, correct choice.

Not Breaking Existing Code

To give programmers more control over what size types are, without having to know about the size of long or short on every computer, the new fixed-size types like int32_t were added, a few years later. But now the problem was that some people had already added their own type named int32_t to their code, and their code would have stopped compiling if it was just added to the compiler.

So we have the compiler-specific __int64 type, and know that this is the name you need to give to get a 64-bit signed integer. They chose this name, because the C standard says that type names starting with two underscores are reserved for the compiler maker, so there is no chance of existing C code using the name __int64 already.

This is fine to old code, from the days where int64_t didn’t exist. The only new thing is the __int64 type. Unless the old code’s dev wrote evil code, nothing has changed, no name can collide and that code will still compile.

Making the Standard Name Available on Request

But the people who create your compiler are also the ones who write the <stdint.h> header file. They can use it as a kind of documentation of what they did.

If the compiler writers add a typedef __int64 int64_t; to this header, that will make sure that the standard name int64_t will be translated into __int64, and so your code can be written to use a signed 64-bit integer without having to know that the compiler you’re being compiled by actually named that __int64 under the hood. But this standard name only exists if your code includes the new header, which old code won’t do.

This is why you can’t just copy the standard headers to another compiler. The headers must have been written to detect which compiler is compiling them and insert the right compiler-specific types.

The newest post on Design Delve is about under-water levels: Designing an Underwater Temple That Doesn’t Suck. It made me think of what it is that often makes me unhappy about under-water sections in games, and why I prefer them as occasional places where optional secrets can be hidden, or where you’re given a clear directive that this is the only way to approach an enemy base, and it’s one special set piece that doesn’t take too long.

I also enjoy underwater section as (again, short, or interrupted by equally long “above water”) areas where you go in, find out how to drain the water, and thereby get two radically different views of the same location.

To me, the following things make water levels annoying sometimes:

Water only as an obstacle

In many games, water sections are strictly more restrictive than the base game — often I can’t use weapons, sometimes I can’t even hide. There are currents that push me back even if the game doesn’t have wind to do the same above ground. And to top it all off, water levels are also often slower due to having to move through “thick” water instead of “thin” air. Just viscerally, all these things often conspire to make it feel like someone just tried to increase the difficulty without giving me any other reward for it. To stretch out game time.

Increase in Complexity

By our nature, humans are “bolted to the floor” and need appropriate ways (hand-holds, ladders, elevators etc.) for vertical movement. Water sections, by nature, are 3D: Humans can use buoyancy to ascend vertically. So water sections become more complex to navigate due to a 3rd dimension, instead of being just 2D with ground level deciding where you are, and maybe a grappling hook. Enemies can also get me from more angles under water, as they can be above and below me much more easily.

The Physics of Water

Water is an unfortunate element to be in, for a human. Sound carries farther due to the increased mass, so a developer either ignores that fact like most games, or ends up overwhelming players (and, possibly, their game engine’s audio systems) with sounds from far away that make it difficult to tell how close enemies are. In contrast, water bends light, so I don’t see as far. Moreover, if the developer is emulating natural surroundings, the water should by all means contain small particulate matter (especially during combat, when impacts stir up the soil nearby), further impeding view distance and reducing visible light. In many games, approximating that means that everything looks blueish or greenish, low-contrast and blurry, and I can’t see far nor make out details well, and often it’s quite dark.

Slave to the Cooldown

Often the need for having to get air in under-water levels means I’m much more subject to that particular cooldown, and the end result is usually instant death. If I mis-judge any other cooldown, it usually just means I lose a few HP or don’t do damage for a second, but here, all my progress so far is undone. So many relaxing, explorative games suddenly become hectic by basically putting you on a timer.

Water as an Afterthought

Water sections are often not the focus of the game, but rather just one level among many. This means a lot of systems that can be re-used between levels have to be customized. Often, a few are missed, so I get weird things like characters speaking normally under water and “above water” animations playing that make no sense, or just having no animations to avoid that instead of bothering creating replacements for each character just for one water level.

All of the Above

The lighting, breath time limit and a lack of gameplay hints also often combine to make it difficult to judge whether where I’m going is just tightly timed and I have to be quicker, or whether I’m being level-gated and it’s impossible to get to the end/the next air bubble at the moment. Leading to a bunch of frustrating deaths and reloads in situations where I could have just skipped the location until later.

Repeated deaths just take me out of the story in most games, because it’s a “this is not really what happened — rewind!” moment that reminds me it’s a game. It also often feels like the game is “punishing” me for a death, because it takes a while for the last save point before the death to load back in. Few games e.g. place you back at an earlier safe location with low health and let you continue immediately, instead of triggering a full reload.

So Under-water levels suck?

No. Underwater levels are like anything else in a game: One location, one trope, one tool in your toolkit that you can take advantage of. They are an easy way to add some style and beauty to a level, or to make a level stand out from the others, or to make a level feel dangerous, unknown and oppressive. However, as you see above, they have quite some inherent difficulty in them. So whenever you implement one, it might be a good idea to consider if you really have the time (i.e. budget) to implement it, and how you can avoid the downsides above.

Can you make your character a faster swimmer? Can you give them a re-breather to avoid the infinite deaths of the out-of-air mechanic? Can you make your character comment on level gates so the player doesn’t needlessly try to go down a long tunnel without enough lung capacity? Can you make the water more stylized (e.g. blue tint + parallax bubbles?), so it still “reads” like water, but doesn’t hamper readability of details? Does the player’s entire toolkit still work under water? Or can you modify the player’s toolkit in interesting ways that make it feel more fun under water?

And most importantly: Does this location really need to be in the game, and does it support the story and the development of the player’s abilities? Can players transfer things they learn under water to the world above the surface?

Or should it maybe not be a full-on water level, but rather a mechanic that pops up for short stretches in other levels, as a hindrance or an alternate/fallback route, that is a bigger challenge, but is also quickly over so people can get back to their usual gameplay before they start loathing water?

I can write object-oriented code in C with structs and function pointers. Why is it not considered “object-oriented”?

The distinction between an object-oriented language and some other is not whether you can write a program a certain way (they’re all turing complete, after all), but whether it comes with provisions to support this programming style.

In the end, everything in a program compiles down to machine code. By extension, that means you can write code for any programming paradigm in assembler. If you allow me to horribly simplify, C is basically a portable assembler. You can implement all programming styles in C. You may have to resort to macros for a few things, and it may not be as efficient as in assembler, and may involve a lot more manual work, but you can do it.

You will need to re-implement a lot of the provisions for object-oriented programming yourself that come built into C++, if you use C instead:

You need to manually define each implementation function, the virtual method dispatch tables for each class and subclass, keep them in sync and wildly typecast between base and inherited classes (or just stay aware of which methods are from the base class and call them via a super member or a chain of super.super.super).

Also, C++ knows what an object is, and can detect nonsensical code that a C compiler looking at your re-implementation of everything wouldn’t be able to tell. It won’t just NULL-initialize a missing function pointer at the end of the vtable and move on, it will tell you that you forgot to implement a pure virtual method, or will fill it in itself because it sees it was added to the base class.

Moreover, an OO language constitutes a standard for OO provisions. Your OO-with-C-code will be different from someone else’s. If it’s built into the language, you can just grab someone else’s OO code and use it. If you use different styles for OO-with-C, you may have to create adapter objects, even for simple things like a string object or a smart pointer.

First, what am I streaming, and what features do I want?

1. I currently stream mostly PC games. So, for convenience, and security, I capture on my PC, where I can tell it to capture only a specific game or window, and not risk streaming password dialogs or chat message notifications containing sensitive data.
2. I want audio ducking. That is, I want game audio to be reduced in volume while I speak into the microphone, but want full game volume when I’m quiet. I play story-heavy games, so people being able to hear game audio is important, I don’t just want to turn down game audio volume really low like some streamers do.
3. I want to have overlays that show current chat messages and my channel logo, and notifications about new followers.
4. I want to have a bot running in the channel with which I or viewers can play sound effects.

The Setup

Basic setup

1. OBS streaming software.
2. Streamer.bot bot software.
3. Wired in-ear headphones (with jack plug) from my old cell phone.
4. A USB/XLR adapter with a capacitor cardioid microphone.
5. Gaming PC (+ 2 TFT Displays).
6. A 1080p USB webcam and xSplit VCam background-removal software.
7. An iPad on a stand for stream monitoring.
8. Stream Deck for quick scene-switching, mute buttons, sound board and stream start/stop.
9. An IFTTT account for stream start notifications on Mastodon.

The gaming PC has two displays attached to it. The main screen for playing the game, the second screen for showing the OBS window (including chat!) full screen, and for the occasional web browsing to look up facts or who to raid. It is plugged into wired Ethernet so I don’t have to worry about RF interference from a neighbor’s microwave or other Wifis in the same apartment building (= more stable and faster internet).

I use an out-of-production Blue Icicle XLR-to-USB adapter that I use with my XLR mic for better audio quality at lower price. You can get simple XLR-USB adapters from audio resellers for around 40 bucks, much cheaper than a full mixer. A friend from Germany recommended the T-Bone from audio store Thomann — just make sure that if your microphone says it needs “phantom power”, you get an adapter that can supply “phantom power” and you’re good.

My microphone stand is an adjustable arm that clamps onto my table, It has the microphone itself suspended using a cord, to insulate it from picking up the vibrations from me bumping the desk. If you can’t afford one of those, get a stand that stands on the floor, or at least put the mic on a bookshelf in front of your desk or so. Don’t use a table stand that just sits on your table, people will hear a THUNK for every keypress.

Ducking

OBS’s “Compressor” filter includes support for “sidechain ducking”. Which means you add a Compressor filter to your Desktop Audio track by clicking its little gear icon, set its “sidechain/ducking source” audio device to your microphone and it will go quieter when you speak into that microphone. I also increased its “release” duration to 500ms (which controls how quickly the audio will go back to full volume after you start speaking, the “attack”). My Ratio is 32:1 (the maximum possible), my threshold -35dB (a little below the average volume I talk at). You may want to play around a little with the ratio or threshold depending on how loud your microphone and game audio are.

Encoder settings

Since my internet connection’s upstream isn’t that good and I want good quality for my YouTube archive, I’ve set up the streaming PC to record using the GPU encoder at High quality 1080p with VBR 4000/5000 kbps using nvEnc. For streaming, I use the CPU encoder at fast quality with x264 at 720p and 1100 kbps CBR.

This means my PC needs to be powerful enough to encode twice and to scale down 1080p to 720p for streaming and run the game. To help with this, I let one encoder run on the GPU and the other on the CPU. If you don’t have a PC that can do that, but you have a second old PC or laptop, you should look at my old 2-PC setup and a capture device.

Audio Monitoring

To be able to hear my own voice in the headphones (to be able to tell when I’m muted or too far from the mic), I set the system audio output to be my display (which has no built-in speakers, but a headphone port I’m not using, so audio sent to it isn’t actually audible). This serves as a sort of low-tech “virtual audio cable”. OBS Desktop Audio Capture records audio from there.

Then I set my headphones to be the “monitoring device” in OBS settings. Now I can use the advanced settings on each sound channel in OBS’ main window to play back desktop audio etc. through the monitor, too, so I hear the game. Also, I can have certain sounds (like a sound from my bot that tells me about new chat messages) go directly to my headphones, so they aren’t recorded as desktop audio and viewers don’t hear them.

Webcam

I use a cheap 1080p USB webcam. It’s attached to a flexible phone arm clamped to my desk that I bought on sale, so I can adjust it to be farther back than my display. This way, the captured frame is large enough so my arms aren’t cut off when I make big gestures, and I don’t have to pay attention to staying within frame.

I use the xSplit VCam software to cut away the background behind me. This means I don’t need an actual greenscreen behind me, and my room behind me doesn’t cover half the game. Still, xSplit doesn’t work too well with a busy background, so I made sure to have a reasonably plain wall behind me. It gets the job done though, and means I don’t have to be too worried about leaving a letter with my address in the background or whatever. I plan to eventually go back to a greenscreen though, but that will wait until I move to a new place where I can make the appropriate modifications.

Overlays

I have a bunch of different scenes set up in OBS. Things like “Stream starting” with a countdown, “Stream ending” with info on when I will next stream, a “talking head” scene when I do only chatting etc. There are a few tricks I use to build those:

• I use the “Scene” overlay type to duplicate the same combination of overlays across multiple scenes. For example, I have a “Game” scene, and my “Main” scene and my “Ending” scene embed that scene using the “Scene” overlay. That way, no matter whether I use Game Capture or Window Capture or Display Capture to capture the game, or if I add a background around an old 4:3-sized game, all scenes that show the game update automatically.
• I use Apple’s Keynote presentation software (something like PowerPoint) to create little animations and movies, to e.g. flip through upcoming games. I just export them as MP4 movies.
• I have installed the VLC movie player app. This activates a “VLC playlist” overlay type in OBS that can play random movies from a folder. My “Stream starting” and “Break” screen play back clips I have saved to my computer. This way I don’t get clips someone just made by accident, but people have something fun to watch while I’m gone. Note that all clips have to be the same size, or things will look wrong, so I export all my clips to 720p.
• Before I had a greenscreen, I used a black circular mask image PNG on the Scene overlay for the webcam. That way, I get a nice smooth circle. I also drew a border image that I placed on top of the webcam.
• For the “Talking Head” scene, I duplicated the game scene (with webcam and game) and just scaled everything up until the webcam took up the entire screen. This way, it looks a little like everything being scaled up, with the game still visible behind me. There are plugins that let you actually do a “zoom in” animation on scene change, but I haven’t had time to set that up yet.
• I have some text overlays that show text from a file. My bot is set up to then show/hide a particular overlay on certain events, loading random text, or text with placeholders inserted. Again, these often use their own scenes shown on top of the current scene. I use these to e.g. show an “Achievement Unlocked” overlay as a channel point redeem, or show “fun facts” on the “Stream starting” screen.
• I have several copies of my webcam on the game scene. One in every corner. So if a game has important things in the lower right, I can hide the “WebcamBottomRight” and show “WebcamBottomLeft” to make sure it’s not covering anything important.

Avoiding Trouble

The secret to a good streaming setup is to not fiddle with it too much once you’ve set it up. So my main trick for a reliable setup is that I don’t touch it between streams: I leave all the USB devices plugged in to the exact same ports, and everything is fixed to my desk as much as possible and can’t move. So the only variables are microphone distance (I push the mic back on its arm when I don’t use it, which means I start stream 10 minutes early to do a quick microphone test before I go live), and daylight coming in through the window (which has effects on the webcam and greenscreen that I try to balance out by blocking half the window with the curtain and using a desk lamp on a second adjustable arm).

If only our computer could detect when I’m speaking and dial up the volume while I am quiet!

Audio Ducking

Well, it can. There is a technique audio engineers called “audio ducking”. It does the reverse: Whenever you speak into your microphone, it reduces the volume on another channel, to ensure it can’t go so loud you won’t be audible anymore. That’s basically the reverse of what we thought to do.

OBS also has this feature, however it is very nerdily named. It is hidden in its “Compressor” filter. Here’s how to use it for audio ducking in 3 simple steps:

Setting up the Compressor filter

1. Open up the Filters window for your desktop audio track

You can find it by looking for the entry for your desktop audio (or whatever audio track you want to reduce in volume whenever you speak), and click the little “gear” icon in its lower right corner.

That will bring up a popup menu, from which you can select “Filters” to show the filter window.

2. Add the Needed Filter

In that window, click the little “+” in the lower left and choose “Compressor” to add a “compressor” filter.

The filter will show the following UI to configure it. Note the popup labeled “Sidechain/Ducking Source”! We’re close!

3. Configure the Filter

The most important setting here is that you choose your microphone as the “Sidechain/Ducking Source”. This tells the compressor to reduce the game audio in response to input from that microphone.

Next we set the “Ratio” as high up as it can go (32:1). This is how strongly the game audio will be reduced. If you want to hear more of the game audio behind your speech, you can reduce this to 1:20 or whatever, but in general people wish it reduced even more strongly, so this is a good starting value.

If you have very loud background noises or speak very softly, you will also want to adjust the “Threshold” volume. This should be a dB number higher than any noise (so that your radiator coming on and producing a hum doesn’t cause game audio to be lowered), but should also be lower than the dB value the Audio Mixer in OBS shows when you speak normally, so your speech will actually trigger it.

We’ve also set the “Attack” to 1ms (the lowest value possible right now, 0 would be better) and “Release” to 1 second. This makes it so as soon as you start speaking, game audio will be reduced. But it will stay low for about 1 second even after, so if you are just shortly pausing in your sentence, game audio won’t come booming in.

Ignore the “Output Gain” slider. That’s basically a volume boost to game audio, but not needed for ducking.

Trying it Out

Click the button labeled “Close” to get rid of the Filters window and try it out. Play back some audio and start speaking. Looking at the level meters in OBS’s Audio Mixer, you should see the Desktop Audio meter noticeably reduce to ~⅓ of its volume while you speak, then come back to full volume when it’s done.

Congratulations! You can now be heard, as can be the NPCs in your game while you’re quiet.

Installing MPW on OS X

• Build the mpw tool according to the instructions in their Readme.md, basically:

  mkdir build
  cd build
  cmake ..
  make
  

• Get a copy of MPW for classic MacOS (their Acquiring MPW page page lists some places where you can still get it if you haven’t kept your original E.T.O. or CodeWarrior CDs).
• Create a folder ~/mpw.
• Copy the files from the verbatim folder in their repository into it (so you have e.g. a ~/mpw/Environment.text file, not ~/mpw/verbatim/Environment.text).
• Open the file Environment.text with a text editor and change the MPWVersion ?= 3.2 line to match whatever version your MPW Shell application shows if you choose Get Info on it in Finder.
• Open the Interfaces&Libraries folder from your copy of MPW, and copy the Interfaces, Libraries, DebuggingLibraries and RuntimeLibraries folders inside it to your ~/mpw folder (so you have e.g. a ~/mpw/Interfaces/CIncludes folder).
• open the MPW folder of your MPW distribution and copy the Tools folder from there to your ~/mpw folder (so you have e.g. a ~/mpw/Tools/AboutBox file).

Your MPW should now be ready.

Building the standard SillyBalls example that comes with MPW

Create a folder named mpw-sillyballs to hold your project (you can choose any name here, but that’s what I’ll call it going forward).

Obtain the C source code

Find the SillyBalls.c example. For MPW 3.5, it is at MPW/Examples/CExamples/SillyBalls.c. Copy it into a the mpw-sillyballs folder.

Creating a resource file

Every application on classic MacOS needs a few resources that describe the application and its UI. Those are usually defined in a resource file. You can create this resource file in a text description language named Rez. We’ll create a minimal resource file named SillyBalls.r that just tells the operating system about our application’s abilities:

#include <SysTypes.r>
#include <Types.r>

/* here is the quintessential MultiFinder friendliness device, the SIZE resource */

resource 'SIZE' (-1) {
	dontSaveScreen,
	acceptSuspendResumeEvents,
	enableOptionSwitch,
	canBackground,                  /* we can background; we don't currently, but our sleep value */
                                        /* guarantees we don't hog the Mac while we are in the background */
	multiFinderAware,               /* this says we do our own activate/deactivate; don't fake us out */
	backgroundAndForeground,        /* this is definitely not a background-only application! */
	dontGetFrontClicks,             /* change this if you want "do first click" behavior like the Finder */
	ignoreChildDiedEvents,          /* essentially, I'm not a debugger (sub-launching) */
	is32BitCompatible,              /* this app is safe to run in 32-bit address space */
	reserved,
	reserved,
	reserved,
	reserved,
	reserved,
	reserved,
	reserved,
	23 * 1024,        /* 23kb Preferred max. RAM */
	35 * 1024	  /* 35kb Minimal RAM limit */
};

Create the Makefile for building this app

# This should point to wherever you've built the 'mpw' tool from this repository:
MPW=~/Programming/mpw/build/bin/mpw

RINCLUDES=~/mpw/Interfaces/RIncludes

# 'SILB' is the unique "creator code" for this Silly Balls app, and used to associate icons
# with the app and its documents, and tell Finder to use this app to open a file. Make up
# your own unique 4-character code for your app here. All-lowercase codes are usually used
# by Apple, so use at least one uppercase letter.
LDFLAGS =-w -c 'SILB' -t APPL \
	-sn STDIO=Main -sn INTENV=Main -sn %A5Init=Main

PPC_LDFLAGS =-m main -w -c 'SILB' -t APPL

LIBRARIES={Libraries}Stubs.o \
	{Libraries}MacRuntime.o \
	{Libraries}IntEnv.o \
	{Libraries}Interface.o \
	{Libraries}ToolLibs.o \
	{CLibraries}StdCLib.o

PPC_LIBRARIES={SharedLibraries}InterfaceLib \
	{SharedLibraries}StdCLib \
	{PPCLibraries}StdCRuntime.o \
	{PPCLibraries}PPCCRuntime.o

TOOLBOXFLAGS=-d OLDROUTINENAMES=1 -typecheck relaxed

SOURCES=SillyBalls.c

OBJECTS=$(SOURCES:%.c=obj/%.68k.o)
PPC_OBJECTS=$(SOURCES:%.c=obj/%.ppc.o)

RFILES=SillyBalls.r
EXECUTABLE=SillyBalls

all: prepass bin/$(EXECUTABLE).ppc bin/$(EXECUTABLE).68k

prepass:
	mkdir -p obj bin

bin/$(EXECUTABLE).ppc: $(PPC_OBJECTS)
	$(MPW) PPCLink $(PPC_LDFLAGS) $(PPC_OBJECTS) $(PPC_LIBRARIES) -o $@; \
	Rez -rd $(RFILES) -o $@ -i $(RINCLUDES) -append

bin/$(EXECUTABLE).68k: $(OBJECTS)
	$(MPW) link $(LDFLAGS) $(OBJECTS) $(LIBRARIES) -o $@
	Rez -rd $(RFILES) -o $@ -i $(RINCLUDES) -append

obj/%.68k.o : %.c
	$(MPW) SC $(TOOLBOXFLAGS) $< -o $@

obj/%.ppc.o : %.c
	$(MPW) MrC $(TOOLBOXFLAGS) $< -o $@; \

clean:
	rm -rf bin obj

Building the app

Just type make all in your mpw-sillyballs directory. The Makefile will now create a bin/SillyBalls.68k and a bin/SillyBalls.ppc executable.

Integrating with CLion

Since we’re running on a modern OS, I thought I’d try if I could integrate the compiler with a modern IDE. I own CLion already and love its code navigation and refactoring features, so I thought I’d use CLion’s custom compiler support.

So as the CLion docs say, I created a compiler definition YAML file and used the little gear popup’s “Preferences…” menu item in the upper right of the CLion window to tell my project about this compiler definition file.

It gave the error “No compilation commands found.” One Stackoverflow post later, it was revealed that CLion’s Makefile parser is probably not smart enough to recognize $(MPW) SC as the same as mpw SC and the like. So I went and created a little shell script sc.sh to wrap the emulated compiler call as a single command:

#!/bin/zsh

# This script is needed so the CLion IDE will recognize the compiler and run it.

~/Programming/mpw/build/bin/mpw SC $@

And then updated the Makefile to call that instead of $(MPW) SC, and updated the YAML file to its final form:

compilers:
  - description: "MPW SC"
    match-sources: ".*\\.c"
    match-language: "C"
    match-compiler-exe: "(.*/)?sc.sh"
    code-insight-target-name: m68k
    include-dirs:
      - ${user-home}/mpw/Interfaces/CIncludes
    defines-text: "
#define __SC__ 0x0801
#define MPW_C 1
#define OLDROUTINENAMES 1
#define pascal
"

The important parts (besides using the shell script) here are:

1. match-sources so it knows this compiler deals with .c files
2. match-language tells CLion’s indexer (a version of clangd) what to parse these sources as.
3. code-insight-target-name – I was the least sure about this one. m68k is the usual abbreviation for the Motorola 68000 series of CPUs of early Macs, but I couldn’t find a list of target platforms clangd actually supports.
4. include-dirs tells the indexer where to find the system headers. This means that you can Command-click on WindowPtr in a source file and it will jump to its definition in MacWindows.h.
5. defines-text tells CLion to pretend some constants had been defined by the compiler. Most compilers define some constants that let you detect which compiler it is. But clangd is based on the clang compiler, so it doesn’t define the right ones for our custom SC compiler, so we have to manually define those that would usually be defined here.
   Apple’s ConditionalMacros.h header looks at these constants to set up some more standardized constants no matter what compiler you’re using, so this is a good place to find out what constants you need and what values they should have.
   For example, if you were setting up the PowerPC compiler MrC, you’d probably have to define __MRC__ to 0x0700 instead. I just picked the highest value that header had for that constant. I should probably actually run this compiler in the emulator and see what the actual value of my version is. I also decided to define away pascal, because it is a keyword that clang otherwise displays an error on. Ideally we’d define this to an unusual calling convention so clangd could possibly error if we pass a Pascal function through a mis-matched function pointer with C calling conventions, but I didn’t yet get around to doing all that. Also, I tried to define TYPE_BOOL to 1 to keep ConditionalMacros.h from re-defining true and false, but it just hard-codes that value for each compiler, so I couldn’t find a way to override it just for CLion’s clangd indexer.

In any event, this made CLion happy, and not only was I now able to jump to system headers using CLion’s standard navigation, it also now let me use the little “Hammer” icon to build my app with make all, and the Build > Clean menu item to run make clean.

Now to set up things for the C++ compiler too, and then I can get coding.

This is what is commonly called a variant.

C++ comes with its own variant class, but it is intended for storing completely distinct types. Given I do not really want to care what type a scripter used, and perform implicit conversions, I could actually implement this as a class hierarchy, with a common base class like:

class Value {
public:
	~Value() = default;
	
	int64_t GetAsInt64() const = 0;
	void SetAsInt64(int64_t) = 0;
	
	string GetAsString() const = 0;
	void SetAsString(const string&) = 0;
};

and subclasses are then like

class Int64Value : public Value {
public:
	Value(int64_t n = 0) : mValue(n) {}
	
	int64_t GetAsInt64() const { return mValue; }
	void SetAsInt64(int64_t n) { mValue = n; }
	
	string GetAsString() const { return to_string(mValue); }
	void SetAsString(const string& n) { mValue = atoll(n); }
	
protected:
	int64_t mValue;
};

Now the problem with this is that this provides a common interface for all types that lets us treat them the same, but we have to know what type a variable will be at compile-time. We still haven’t managed to make a variable change type. To do that, you’d have to use operator new: You would delete and new it under a new type to change its type. But that would be bad, as it would allocate a new block on the heap for each int/string you wish to use. Performance would be ridiculously slow. Ideally, we’d want these to be held in-line (or on the stack) like any other type.

Usually, you would use a union for that:

union ValueUnion {
	int64_t mInteger;
	string  mString;
};

But unions don’t like types with a constructor like string, because it doesn’t keep track of a union’s current type, so wouldn’t know whether it would have to call ~string() or not. Theoretically you’d use variant for that (but I’ll mention below why this doesn’t work here).

So what do we do? I didn’t know, until one day I remembered that C++ has what is called placement new. Placement new lets you provide the storage, and will then call an object’s constructor for you. It is intended for classes like vector, which allocates one large block for all elements, and then places objects inside the array one after the other. So I added the following class:

union VariantUnion {
	VariantUnion() {}
	~VariantUnion() {}
	Int64Value mInteger;
	StringValue mString;
};

class alignas(union VariantUnion) VariantValue : public Value {
public:
	VariantValue(int64_t n = 0) { new (mStorage) Int64Value(n); }
	VariantValue(const string& n) { new (mStorage) StringValue(n); }
	~VariantValue() { ((Value*)mStorage)->~Value(); }
	
	int64_t GetAsInt64() const { return ((Value*)mStorage)->GetAsInt64(); }
	void SetAsInt64(int64_t n) { ((Value*)mStorage)->SetAsInt64(n); }
	
	...

protected:
	uint8_t mStorage[sizeof(ValueUnion)];	
};

So basically its only job is to forward all calls to the underlying object. It will also create the underlying object using placement new (and destruct it again using placement delete, which looks like just calling the destructor directly). We have to provide the storage ourselves (which we do by making sure that mStorage is large enough to hold either of our possible types), but that is what we want, because we can just declare our storage in-line as a fixed-size array of bytes, and forego the extra allocation.

So how do we make it possible to change a type? We need to destroy the current Value subclass in mStorage and allocate a new one using placement new. I did that in my subclasses by implementing the setters for all other types:

class Int64Value : public Value {
public:
	...
	
	void SetAsString(const string& n) {
		((Value*)this)->~Value();
		new (this) StringVariantValue(n);
	}
	
	...
};

This way, if a variable is already an int64_t, it will just change Int64Value::mValue, but if it is another type, it will re-allocate the type in place.

I know this code is scary: You need to make sure that ValueUnion contains all your supported types, otherwise you might over-run your memory and cause hard-to-find bugs. You also need to make sure you use the proper alignment, because an array of uint8_t is usually aligned on 1-byte boundaries, which is invalid for e.g. an int64_t on many platforms. And since we’re overriding the alignment, you can’t have any other member variables in your VariantValue without thinking through whether that will mis-align mStorage. It also involves Int64Value destructing itself while its method is running and constructing a new object in its place. And finally, Int64Value makes assumptions about how large the storage its containing class has allocated for it is. That’s not proper encapsulation.

On the plus side, though, usage of this class is beautifully straightforward. You just call SetAsString() or GetAsString() and it will magically do the right thing, or throw an exception if it can’t convert.

So What’s Performance Like?

In a quick test, I used an array<int64_t> as a baseline, running a loop of 1’000’000 iterations with my programming language. That took 10ms.

Using the above approach, which of course replaces direct memory accesses with function calls and a bit of virtual dispatch overhead for each GetAsInt64() and SetAsInt64() call, doubled the runtime to 20 ms on my Mac, and to about 30ms on Windows.

Then I tried using C++’s variant:

inline string GetAsString() const {
	return std::visit([](auto&& arg) {
		using T = std::decay_t<decltype(arg)>;
		if constexpr (std::is_same_v<T, int64_t>) {
			return to_string(arg);
		} else if constexpr (std::is_same_v<T, string>) {
			return arg;
		} else {
			static_assert(always_false_v<T>, "non-exhaustive visitor!");
		}
	}, mValue);
}

inline void SetAsString(const string& n) {
	mValue = n;
}

...

variant<int64_t, string> mValue;

...

This took a whopping 100ms. Given that involved a lot of fancy new constructs like lambdas and generics, I tried going more old-school and finding the type via the variant::index() for comparison:

inline string GetString() const {
	switch(mValue.index()) {
		case 0:
			return to_string(get<int64_t>(mValue));
			break;
		case 1:
			return get<string>(mValue);
			break;
	}
}

This actually got us down to 60ms. But it also lost us all the compile-time type safety in favor of a runtime exception if someone adds a type in the middle of the variant<int64_t, string_>’s list of types, instead of at the end. It also does not raise any errors if we forget to implement a type like our pure virtual methods do. I also suspect that this will perform an extra type check on the assignment on every assignment, whereas our polymorphic approach knows when a type doesn’t change and will just go through virtual dispatch, which likely is better for caches.

So we have a factor 3 slowdown at worst for the polymorphic approach, and factor 6 to 10 slowdown for C++’s built-in variant. Plus, given variant assumes wholly independent types, the code for accessing a variant using a certain type (and performing appropriate conversion) is a lot cleaner using polymorphism.

So is C++’s Standard Variant Bad?

I wouldn’t make that blanket statement. I haven’t got much experience with the class yet, so I might just not be using the right call, and I have a very specific use case that doesn’t quite match what variant was made to support. All I can say is that I encourage you to not just stick variant into your core interpreter loop without comparing it to other approaches. :-p

First, what am I streaming, and what features do I want?

1. The currently stream PS4 and PC games. I want to do this with high quality, so I opted for a capture device with a separate streaming PC setup.
2. I want audio ducking. That is, I want game audio to be reduced in volume while I speak into the microphone, but want full game volume when I’m quiet. Too many streams have very low audio so it doesn’t conflict with their commentary, which makes it hard to follow the story.
3. I want to have overlays that show current chat messages and my channel logo, and notifications about new followers.
4. I want to have a bot running in the channel with which I or viewers can play sound effects.

Why not PS4 built-in streaming?

PS4 built-in streaming is really nice:

1. You just push a button on the controller and you get a menu from which to start/stop the stream.
2. It shows the chat onscreen at the right edge of the screen.
3. The PS4 has reserved capacities for streaming, so no stutter or slowdown, even without an extra PC and hardware capture card.
4. I can just plug in a USB headset and the mic will be used for commentary, and the headphones will play game audio without it being picked up by the headset mic.
5. Chat notifications and other private data is automatically blurred, and switching out of the game turns off stream video, so I don’t have to worry about accidentally showing my friends list, PSN ID or private messages containing sensitive data.

Sadly, it has a few downsides:

1. Text wrapping in the chat overlay is horrible. I think they just use Japanese-style character wrapping instead of breaking only at spaces between words.
2. The chat overlay doesn’t show all Twitch emotes, only an older set.
3. There is no way to call up Twitch’s web site to check how the stream sounds or whether there are compression artifacts without an extra PC.
4. No support for a bot. I still have to run a PC for the chat bot.
5. No game audio ducking.

The Setup

Basic setup

1. Elgato Game Capture HD
2. OBS
3. Elgato Sound Capture
4. Microsoft LifeChat LX-3000 headset (w. microphone)
5. Streaming PC for Game Capture software, bot.
6. Gaming PC resp. PS4 for the actual game (+ TFT Display)

I plug my headset into the streaming PC, and set up OBS so it records the audio from its microphone.

I plug the Elgato Game Capture HD (EGC for short) between the gaming PC and its display. The USB lead from the EGC goes into the streaming PC, which will be running OBS.

If you get a current EGC device, you can just turn on monitoring in OBS under “Advanced Audio Settings” to hear the game audio in the headset as it is being recorded.

Old capture devices with a delay

Given my EGC is the old model that had a delay, that would come confusingly late compared to what I see onscreen. So I use the “StereoMix” device built into Windows on the gaming PC to output audio not just to the display (so it goes into the EGC), but also out the line out port. This is a device that is disabled by default and has to be turned on in Windows’ old Sound Control Panel (by first showing inactive and disabled devices, and then enabling the StereoMix device). The audio is fed via a jack-plug-to-jack-plug cable and a Jack extension cable with in-wire volume controller into the microphone in port of the streaming PC. I then set that microphone in port to output through my headset in Sound Control Panel via “Listen to this Device”, while the streaming PC’s default audio is going through Elgato Sound Capture. This lets me feed all audio I want recorded (i.e. bot audio) into Sound Capture, which I can still hear in my headset, but what I don’t want recorded (the un-delayed audio from microphone in) only ends up in my headset, circumventing Sound Capture and therefore OBS.

For capturing the PS4, I use a little hardware dongle called an “HDMI Audio Extractor” to fulfill the same function. It gets plugged in between the PS4 and its display somewhere, just like the EGC. But again, that’s only needed if you have a capture device that has a delay, which Elgato’s new ones don’t have.

Ducking

OBS’s “Compressor” filter includes support for “sidechain ducking”. Which means you add a Compressor filter to your EGC track by clicking its little gear icon, set its “sidechain/ducking source” audio device to your microphone and it will go quieter when you speak into that microphone. I also increased its “release” duration to 500ms (which controls how quickly the audio will go back to full volume after you start speaking, the “attack”). My Ratio is 32:1, my threshold -35dB. You may want to play around a little with the ratio or threshold depending on how loud your microphone and game audio are.

Encoder settings

Since my internet connection’s upstream isn’t that good and I want good quality for my YouTube archive, I’ve set up the streaming PC to record using the GPU encoder at High quality 1080p with VBR 4000/5000 kbps using nvEnc. For streaming, I use the CPU encoder at fast quality with x264 at 720p and 1100 kbps CBR.

Since the CPU- and GPU-intensive game runs on the gaming PC, the streaming PC can afford to encode twice and to scale down 1080p to 720p for streaming with no ill effect on game performance. Since one encoder runs on the GPU and another on the CPU, both have ample processing power without one taking away from the other (If you don’t have an nVidia GPU, you can likely use Intel QSV instead of nvEnc).

Bot audio

Elgato Game Capture for Windows comes with a “virtual audio cable” application called Elgato Sound Capture. It has a few modes to run it in. I use its “Music” mode to take the audio the chatbot plays on the streaming PC and make OBS record it (Because EGC only includes the PS4/gaming PC audio).

To do that, I set up Sound Capture’s output device as the default system output device, then tell Sound Capture to play back through the headset. Then I set OBS to capture desktop audio from the Elgato Sound Capture device. That way, I can hear bot audio, as the Streamlabs Chatbot plays all sounds on the default audio output device, but it also gets recorded.

OTOH, any other audio I set up to directly play through the headset (like the un-delayed game audio for old capture devices above) is not recorded.

Other setup miscellanea

Both the PS4/gaming PC and streaming PC are plugged into wired internet, to avoid Wifi issues and get full Gigabit speeds for stream upload.

I also have a Blue Icicle XLR-to-USB adapter that I use with my XLR mic for better audio quality, but I prefer the headset, as it means I can turn my head to check out a noise or the clock and still remain audible. If I ever do webcam streams again (I have a Logitech C270 for that), I might forego the headset and use the mic on a separate microphone stand, and go back to the iPhone headset, which is less noticeable on cam, but I don’t want to use its microphone because I bump the mic with my chin too often.

My microphone stand is one of those full-height ones that you can stand on the floor, because table stands would pick up the noise and vibrations from me typing on the desk.

Disclaimer

The Elgato Game Capture HD was a gift from back when I worked at Elgato (I left in mid-2017). I used to work on the Mac version of Elgato Game Capture. That said, for capturing from the PS4, with overlays and all, a capture device is the only choice, so I think even if I was biased, I am not recommending anything I wouldn’t recommend otherwise.

C has one neat feature that can be (ab)used to work around many of its shortcomings: The C Preprocessor, which is basically a way to define instructions for copy-and-pasting bits of text together.

X-Macros use this feature to let you define a list, and then generate several bits of code based on that very same list.

You can do this because the preprocessor lets you remove macros using the #undef preprocessor command so you can define them a second time with a different expansion. Let’s do an example:

#define COLORS X(Red) \
               X(Green) \
               X(Blue)

// Define an enum:
#define X(name) COLOR_ ##name,

enum Color {
	COLORS
	COLOR_COUNT
};

#undef X

// Define a string table:
#define X(name) #name,

const char * gColorNames[COLOR_COUNT + 1] = {
	COLORS
	""
};

#undef X

After the preprocessor has run, that code will look like:

enum Color {
    COLOR_Red, COLOR_Green, COLOR_Blue,
    COLOR_COUNT
};

const char * gColorNames[COLOR_COUNT + 1] = {
    "Red", "Green", "Blue",
    ""
};

Allowing you to print an enum Color value like:

enum Color myColor = Green;
printf("myColor = %s\n", gColorNames[myColor]);

And get the printout:

myColor = Green

Since the initial examples of this technique named the macro to be replaced X() (like we did it above), the technique was named that as well, and it has stuck as a convention, although you could of course pick much more expressive and self-documenting names if you wanted.

Why would I use X-Macros?

X-Macros are very useful when you are dealing with static lists of things that need to be kept in sync. Be it two actual lists like above, or a list and a switch statement that needs to cover all its cases in a way that follows a simple pattern. The token-pasting operator ## and the stringify operator # are very handy in many such cases, to let you take the same data and use it as different data types.

Included X-Macros

One downside of classic X-Macros is that, given you can’t have line breaks in a macro, all your constants end up on the same line. The definition of COLORS above merely escapes the line breaks, which means they’re not part of the macro output, they just break the definition up over multiple lines to make it more readable. Worse, most IDEs will jump to the COLORS line in the enum above, not to the actual definition of the COLOR_Red entry, when you use their code navigation feature. That makes it harder to find documentation on the individual enum cases you might have written next to the individual X-macros.

One workaround to this is to not define a macro for the COLORS list, and instead write it into a separate file:

Colors_X.h

X(Red)
X(Green)
X(Blue)

and instead (ab)use #include to paste that header in twice:

// Define an enum:
#define X(name) COLOR_ ##name,

enum Color {
#include "Colors_X.h"
	COLOR_COUNT
};

#undef X

// Define a string table:
#define X(name) #name,

const char * gColorNames[COLOR_COUNT + 1] = {
#include "Colors_X.h"
	""
};

#undef X

Each X-Macro is now really on its own line, resulting in the preprocessed code:

enum Color {
    COLOR_Red,
    COLOR_Green,
    COLOR_Blue,
    COLOR_COUNT
};

const char * gColorNames[COLOR_COUNT + 1] = {
    "Red",
    "Green",
    "Blue",
    ""
};

And moreover, the compiler keeps track of line numbers in included files, and when you trigger code-navigation on a COLOR_Red identifier in your source code, it will now jump to the X(Red) line in Colors_X.h, as desired.

But of course the enum and strings array definitions look even less readable now, and you need a separate file for each and every enum.

Should I use X-Macros in my code?

In general, I would avoid using X-Macros. That I got an entire blog post out of the technique should show you that they are not obvious, and the caveats I gave above should show you that X-Macros have their own issues. That said, if you have a C codebase that consists of numerous static look-up tables that need to be kept in sync, X-Macros are likely the least horrible solution. If having out-of-sync tables can lead to hard-to-diagnose bugs, a little education to every new hire about X-Macros via a comment is a small price to pay. So sure, use them there if you can’t use statically declared structs instead.

After all, if you’re already forced to use C instead of a higher-level programming language, you probably have many constraints on you already, and X-Macros might actually lead to more readable and more maintainable code.