qtMUD

NOTE: This essay was written as a development log, which means that, among other issues, code blocks and examples may be incomplete, missing, or wrong.

It's been a while since I've touched my MUD engine: two and a half years, I think.

In the meantime, I haven't done any computer programming, but I feel like I've learned a lot about computer programming. One thing I've learned is that there exists a way of writing software called literate programming, which is a way of writing a piece of software by writing documentation for people first, with chunks of code embedded in. (Most code has some documentation inside it, but with lots living in another place.) Check out "Literate programming" on Wikipedia for more information.

This seemed like it would be useful thing for qtMUD, which I intend to "be the non-programmer's introduction to creating and running a MUD."

Since implementing the paradigm for the project would require a rewrite, I figured I would use the opportunity to take stock of the rest of my implementation - down to the language I was using. Python has, I think, never been in practice what I hoped it would be in theory, especially when it comes to being easy for non-developers to work with. (Without ending up in "dependency hell.")

I'm not interested in explaining, right now, why I made the choice, because I feel it would invite unwanted bickering, but I've decided to use Crystal as qtMUD's main programming language. Crystal is a compiled object-oriented statically-typed programming language - different in a lot of ways from Python, but I feel it's quite similar in the ways that matter. Ahh, nope, I said I wouldn't explain it.

Moving on.

It might sound like re-implementing a game engine, even one for something a simple as a MUD, is a big undertaking. Luckily, I've never made it very far in implementing my vision for qtMUD, so what I have isn't that well-developed.

Right now, qtMUD establishes a few features and ways of doing things - enough that I was able to make a functional multiplayer persistent card game with it. Here's a brief rundown:

qtMUD has services, subscriptions, and things. When the game is running, it ticks every service, and parses any events that were subscribed to be executed that tick. The game world is made up of things, which have qualities that represent their in-game attributes, such as a room's contents or a player-character's experience.

If you're familiar with game engines, you'll recognize most of that as pretty standard, even if I don't use the common terminology. So there's no confusion, though, I'm going to break that down into a bit more detail, by talking about how the engine starts and runs, and what happens when a player logs in.

When the Admin starts their qtMUD server, it goes through three stages: loading, starting, and running.

When the server is loading, it looks what optional features are set to be enabled, what MUD libraries to load, and what services to load.

qtMUD is meant to let you just use what you need, so a lot of basic features are "optional," like colored text output (useless if you're converting your engine's output to audio, for example, and at least in Python, required a dependency.)

MUD libraries are collections of new features, usually representing complete game worlds. For example, Fyreside was a test MUD library I wrote for the Python qtMUD.

Services are what some programmers might call "daemons," they're persistent objects that handle persistent engine information. The talker - the thing that handles in-game communication between players - is one service. The socket server that users connect to is another.

After the MUD engine has looked at all those, it begins the process of loading them:

1. For each MUD library,
   1. add its services to the list it has already prepared
   2. and add its enabled optional features to the list it has already prepared.
2. Once that's done, it tries to load each service:
   1. Most services have subscribers, which are functions that will be triggered when a matching event is scheduled. (More on that shortly.) These subscribers are added to a list.
   2. Some services have their own tick function, which is added to a list. (More on that shortly, as well.)
   3. Services often have their own variables and stuff to configure; that's usually done at this point, too.
3. Once the services are loaded, the enabled optional services are. What this means depends on the service, but it might mean replacing a subscription with a different one.

So, at the end of the loading process, the MUD engine has a list of services that need to be ticked, and a list of subscribers that will trigger when a relevant event is scheduled. Past this point, the optional features aren't dealt with anymore.

The next step of the engine's get-going process is to start, which sends a call to services that will tick. This often does different things - in the case of the MUD socket service, it binds the ports and sets up the server.

The final step of the process is to run, which does two things:

• It maintains the game tick, which is a loop that, over and over until its told to stop, calls the tick() function in every loaded service, and calls every subscription for which there is an event scheduled. Subscriptions are functions that "happen" the tick after an event related to them are scheduled. For example, a user sending a message through the talker service causes an event to be scheduled, that says basically, "for everyone listening to that channel, show them the message." The next tick, everyone gets shown the message.

The game engine ticks until it's told to stop, at which point it shutdowns the services and exits.

From a user perspective, when you connect to the socket server with a MUD client, the game asks you some questions to suss out if you have an existing user account, and creates a new thing, a collection of qualities and their states. For example, all user things have an account ID quality.

The qualities of a thing define how different services and events will affect it. Some things are very simple, like a basic user account, but on a server with a large MUD library loaded, user accounts might have dozens of qualities.

Developers of MUD libraries will mostly fall into two tiers: those who create content for the library, creating new things with sets of qualities, like a collection of Room things that make up a small village, and those who make new types of things, new qualities, and the services and subscriptions that rely on them.

But that division is meant to occur because of one's interests, not necessarily technical difficulty.

Knowing that background, I'll explain what stuff the qtMUD engine had as implemented in Python:

• a MUD socket service that was how users could connect
• a Talker service that let users talk to each other, or showed server messages to all users.
• a "colored output" optional feature.
• a Client thing with qualities relating to the MUD socket service and Talker service.

There might have been other features, but that's what I can remember offhand, and what was well-tested.

Which honestly, shouldn't be that hard to reimplement in any language. What's going to be trickier is organizing it in a way that makes more sense for a literate programming paradigm.

NOTE: This essay was written as a development log, which means that, among other issues, code blocks and examples may be incomplete, missing, or wrong.

Last time I wrote about how I was planning to re-write qtMUD from Python3 to Crystal, and then I explained how the engine had worked. I pointedly didn't explain why I'm switching to Crystal, specifically, and I also glossed over the fact I don't really know Crystal. At all. And I haven't really touched a programming language in 3 years, since the last time I tinkered with qtMUD.

After I wrote that devlog, I went off and read the Crystal Reference, pretty much from beginning to end. I skimmed past stuff that I could tell might be useful down the line, but wouldn't be necessary to get started, because it was nothing I used in Python, even though I knew the features existed.

I'm pretty sure I want to design qtMUD to work as what Crystal calls a shard, or "package of Crystal code made to be shared-with and used-by other projects." See "Writing Shards" in Crystal Reference for more information.

That documentation says I need a working installation of Crystal, which I have, a working installation of Git, which I have, and a GitHub account, which I have but would prefer not to use - I've been preferring Drew DeVault's Sourcehut set of services, so would want to use a repo hosted at git.sr.ht/~emsenn.

The instructions, past the requirements, begin with creating a project. Crystal has a command for initializing one, but since I'm doing this program literately, I'm going to instead create sections in my main qtMUD document (probably what this devlog entry is a part of,) and write source code blocks to be tangled out - extracted.

Here's what I know I need:

• shard.yml, which defines the project for when I'm ready to distribute it. It is in the "Configure" subsection of the "Operations" section.
• src/qtmud.cr, which will be the implementation of qtMUD in the Crystal programming language. It is in the "qtMUD Source" section.
• spec/qtmud_spec.cr, which will be the specification of qtMUD, against which the implementation is written, and is also written in Crystal. It is in the "qtMUD Specification" section.

There's two other sections I've made to accompany those:

• "Install from Org-mode", under "Install" in the "Operations" section. It has a shell script for deleting the currently build directory and remaking the layout. Simple, but effective. Then I run org-babel-tangle to re-tangle the source code.
• "Test All", under "Test", also under "Operations". This is another shell script, that runs crystal spec (and runs it through a temporary file, because just running the command didn't get me the output in my Org-mode file. Hacky, but effective.

This gives me a development flow that could definitely be better if I was better at Org-mode, but:

1. Run (Ctrl-c, Ctrl-c in Emacs) the script in "Install from Org-mode" to delete the old version and make the necessary new directories.
2. Do org-babel-tangle in Emacs anywhere in the qtMUD file.
3. Run the script in "Test All".

This lets me know what specifications, if any, I've failed to implement.

Which gives me a pretty good base for starting to write the specifications and assertions! (Turns out I don't need Git installed or a GitHub account yet, at all.)

NOTE: This essay was written as a development log, which means that, among other issues, code blocks and examples may be incomplete, missing, or wrong.

Last time I wrote about bootstrapping a Crystal project with Org-mode, which got me to the point where I'm ready to start laying out the engine specifications I laid out in my first devlog.