Making hypertext adventures

2024-11-20

Hello there!

In my previous post about text games, I wrote in detail how I made text adventures in C. What I like about C is that it helps me write simple programs and it doesn't need plenty of documentation to be understood.

But command-line adventures aren't perfect:

These days, everyone and their toaster has a web browser*, so there is a simple and widely available alternative to command-line text games: hypertext games.

*Well, almost every device today, and not all devices past or future. The web isn't eternal. But then, how can your text game survive the end of the world? I'll have to discuss it in a future post. EDIT: as promised, game longevity has been discussed!

What is a hypertext game?

Pages linking one another. A bit like gamebooks, and now a common interactive fiction format. In short, it's the web 1.0 (or even the web 0.9) but as a game.

Disclaimer: I will keep it simple here. No Javascript or server-side logic. Only text and links. I recommend a text browser called Lynx as a baseline. It is the oldest web browser still maintained today, after 32 years of watching other ones rise and fall. Pretty wild when you think about it. You can do a more elaborate game on top of that if you want, see Progressive enhancement for more info on the topic.

Because of the limitations above, those games will be stateless. No fancy state tracking like HP, XP, money, inventory, or morality alignment. Only the current page (and I guess a built-in save system in the form of tabs and bookmarks). You may wonder, is this really still a game? Yes. Thanks for asking the question.

Now, let's dive in and make our own pocket of playable cyberspace!

Today's example:
Fourmidable

As an example, I'll use Fourmidable, a game I've already made with some friends. In short:

As an ant queen, you have to solve many challenges in the colony: resource exploitation, trading, war and peace.

Despite what the description suggests, this isn't a stat-heavy game. It's more like a choose-your-own-adventure.

The current game is made in Twine. It's a good engine for interactive fiction, and I recommend it for non-developers. But with it, Fourmidable needs Javascript and takes half a megabyte even though by word count it is not a dominating Dostoievsky doorstopper.

And to be honest, I think I can improve the writing a bit, at least for the English version. However, this post is firstly about the technical side of things, not the writing side.

I found two ways to organize a hypertext game:

The naive route:
one node per page

In the simplest form, you write a HTML file, add a link to it, save it, and save another HTML file at the link's target. Rinse and repeat for however many nodes (files) and choices (links) you want.

A "lexia" is a more formal term for "node", but I rarely use it (in fact I just came across it!).

Advantage:

Disadvantage: you have A LOT of pages at the end.

The single page route:
one CSS line

Fortunately, there is a way to make it all fit in one web page.

Here is a tiny sample game. Start or reset prototype

A concerned farmer ant approaches your throne.

Yer majesty! Not much was harvested this year. Tis only september, but our winter supplies have begun to decrease!

Your explorers could hunt on the Dark Lands, where the black ants live, at the risk of being spotted by your enemies.

Also among your denizens is told that the giants' fortress has legendary amounts of food, but taking too much from them would ruin the entire colony.

You will send hunter ants to the Dark Lands, in the hope of not getting caught by the enemy.

To be continued. Back

You prepare an expedition to the giants' house.

To be continued. Back

You wait. You decide that the problem isn't an emergency just yet, and move to the next point of today's agenda.

To be continued. Back

To show only one paragraph at a time, I use the URL's fragment (the "#" thing), and one CSS rule: 

element:not(:target) { display: none }

Then you just need to write your story fragments in elements that have an ID, and the links point to "#" + your target ID.

Advantages:

(Minor) disadvantages:

You can also do a hybrid of the two, if you don't like having one humongous file nor thousands of tiny files. You can also generate the tiny files from one big file + a script. The big file could even be a state machine transition table in CSV format.

And now for some limits to keep in mind for both techniques.

Story issues

This is stateless. For Fourmidable, this is problematic, because each day you make decisions on several topics (defense, food supply, exploration), and those topics are interlinked. You only know the consequences the following day, with some common states in between.

What if I flattened the story, one topic at a time? So, first you have food problems, then if you don't starve you have defense problems, then if you don't start a war you move on to the next problem.

The problem, in Fourmidable's case, is that it feels much less like a political simulator.

I guess you could fix it with parallel state machines and politely asking the player to keep more than one tab open. Smaller state machines will begin and end like secondary quests, there's even some potential for password systems.

UX issues

Beyond the structure of nodes, you have to make some more choices.

Inline links, or links at the bottom? When I adapted Fourmidable for a word-limited game jam, I chose inline links because that means fewer words. But in retrospect, it doesn't really feel like choices, more like adjacent resources, so back to bottom links we go. If you want an in-game wiki, it might be wise to separate the two types of links.

Also, as I wrote this blog, I discovered the Gemini protocol, which only allows full-line links. In our modern attention economy full of information overload, that might actually be the best option.

Fancy improvements

Even with only simple HTML, you can write a separate wiki to show off the worldbuilding. Story pages point to wiki pages when needed. Some things to keep in mind:

Among other improvements, if every node in your story has one obvious link (like "next"), you can give it the autofocus attribute. Then the player only needs to press Enter to follow that link. Keyboard users will thank you a lot.

A quick word on progressive enhancement. It's great, and IMO better than graceful degradation (the opposite method). But sometimes it's okay to raise the bar if you game really looks like shit in pure HTML. You can't run it everywhere after all. Or can you?

I really need to write a post about game longevity sometime.

Conclusion

Phew, I think my blog posts are getting larger.

On that, see you on the next one!

…

Bonus:
New plot idea for Fourmidable

As you wake up from your cocoon, ready for a new life, an ancient tablet of instructions faces you. Nobody else is in sight in the colony.

Greetings,
I am the Forminister.
This here is a top secret training program meant for you, fellow ant, to determine if you are worthy of the one droplet of royal gel that will turn you into a princess and allow you to start a colony.

You see, after a terrible incident, we lost all our princess ants.
Years have passed, the royal chambers have gathered dark red dust, cloaked by darkness, rising into the stale air for every step one makes near it.

The chambers' vast emptiness is only compensated by the ever-growing Web of pheromones housing this program.
Note to self: clean it a bit.

Only workers remain, and carefully guarded princes awaiting for the rightful winner to claim her title.

I am only a regent, a facilitator in the saving of our colony.

You will meet many workers, from the humble farmer, to the boastful soldier, and the industrious builder, and even some agents from outside the colony.

Web?

Until a very short while ago, ant communication was, to be polite, quite primitive.

It was only by studying the spiders' webs, that one prodigious worker of ours got the brilliant idea of impregnating it with pheromones, thus structuring information in new and revolutionary ways.

It wasn't me, your servitor is far from having these qualities. I may not be a good creator, but it is said that I am among the best maintainers, and I can only imagine that is why I am in charge of the program.

Wiki?

This site, as I like to call it, is part of the Web of pheromones.

Compared to our training program, (nicknamed the Story by some incompetent slackers), this wiki has a much more... encyclopedic layout.

You cannot edit it, for every candidate to the program, past or future, must have equal chances.

Farmer's blog:

Endgame Farmer's blog:

Soldier's intranet

Halt there! Prove your knowledge before proceeding. You detain, or we retain. Me captain. (list of password-protected pages)

Builder's website: work in progress. Of course it's not finished.

Aphids' social network

Black Ants' alternative internet