The core game runtime of Habitat: backend API, frontend web client
Bump to 0.1.15
Update install script; no need to compile anymore
Update stale domain name references


browse  log 



You can also use your local clone with git send-email.


a top-down browser-based MMORPG for humans and computers

#Table of contents

#What is Habitat?

Habitat is a browser-based MMORPG (massive multiplayer online role-playing game). It uses a top-down perspective, like the original Zelda games. The player travels through the game world, defeating enemies and becoming gradually more powerful.

#The pantheon

The world of Habitat is overseen by an indeterminate number of powerful beings, including:

  • System - The system entity. The glue that binds the game together. It's like the Force: the invisible, but not entirely impersonal, essence that exists between all things. It's the only entity that doesn't exist in the database -- its attributes are static and immutable. It is everywhere and nowhere.
  • Eternity - A closed doorway to the time beyond time. It sits at the heart of nothingness, at the center of the mind of the System.
  • Evil - The fundamental force of evil in the game world. All of the major and minor realms of Hell exist within its mind. It lies in repose at the foot of Eternity.
  • Maker - A manifestation of the personality of the System. It strives to maximize the amount of different personalities in the universe. To this end, it creates locations and experiences that aim to attract new players to the game. In this way, the System, whose blood runs through every entity, can vicariously experience as many distinct situations as possible. The Maker roams the universe, as its work requires, and wears many faces.
  • 602494 - A creature of chaos. It strives to tear down and destroy all created objects. Little is known about it.
  • ma'at - A force of justice in the universe. Along with its servants, it investigates instances of misbehavior and punishes the offenders accordingly by sending them to the appropriate Hell realm.
  • Seratora, the Gladiator - God of combat. She oversees the Combat Heaven dimension, where players can compete with each other in PvP scenarios.
  • The Tribunes - a family of ancient and powerful demons. They brought themselves into this world through the mind of Evil. In ages immemorial, Maker ensnared them and bound them to various subdimensions of Hell, where they now rule. Their exact number is unknown, and they strive always to escape. The most dangerous of the Tribunes are Agrippa, Tullus, Fausta, Aulus, Spuria, Caeso, Opiter, Vopisca, Mettia, and Sertor.
  • Witches and Warlocks - Agents of Maker. They are dispatched far and wide throughout the universe on missions to further Maker's aims. They take the form of humans wearing various types of sunhats. If you find yourself speaking to an entity with a sunhat, it's a good chance you're talking to a Witch or Warlock.


The universe of Habitat is broken up into distinct realms, or planes of existence. Each realm is centered at its respective origin point [0, 0], and extends infinitely in all directions. There are a handful of "well-known" realms that always exist, such as:

  • Intro - the first shared realm that new players will visit. It has weak enemies and easier starting quests tailored to low-level characters.
  • Datacenter - this is the virtual world where all of the machines running the Habitat universe are stored. It's possible to actually interact with the real-life servers that are hosting the game world through their Datacenter representations.
  • Taranasuca - the home plane of Maker's witches and wizards.

There are also realms that fall into broad categories (Heavens, Hells), eg:

  • Porn Hell - an infernal dimension where demons compete to bump, twerk and grind your soul into oblivion. Any player characters that exhibit profane (nude or lewd) behavior is banished to this dimension by ma'at until their penance is complete.
  • Garbage Hell - players are sent here if they are caught littering elsewhere in the game world.
  • Profanity Hell - players can be temporarily banished to this realm for using profane language in realms that do not permit it.
  • Combat Heaven - a realm dedicated to player-versus-player combat.
  • Loot Heaven - a plane of infinite loot, like Aladdin's cave. Players that find themselves in Loot Heaven may claim a single item of their choosing, but only one; and then they are sent back to wherever they were taken from.
  • Healing heaven - any player entering Healing Heaven is immediately restored to full health.

In Habitat, a mind is like a room: you can open the door and walk inside. You can stash items there. In this sense, an entity's mind functions like its inventory. Any items given to an entity are deposited near the origin point of its mind. But minds are also a kind of "home base" for entities: a safe haven where they can retreat in order to rest up. Most importantly, minds are realms, which means that they are just as much a part of the physical game world as anywhere else. In fact, all gameplay within the universe of Habitat takes place within someone's mind; it's just a question of which entity's mind is serving as your current plane of being at a given time.

This means that every entity is always situated within a nested set of minds, like matryoshka dolls, beginning with the entity's current plane of existence, and extending outward until we reach an entity that is located within its own mind.

Some entities do not really exist, except as the vessel for the realm that lives within their mind. Like a Gaia spirit of sorts.


All of the non-player characters in the game world speak a distinct language among themselves. This language is called sananife, (sȯ-nə-'nē-fā, 0x5a9a91fe) which is also the word for beingdom — the collective group of all beings in the game. Human-controlled players need to learn to understand sananife before they can communicate verbally within the game. This is true even for communication strictly between player characters: if you want to communicate within the game world, you must speak sananife.

Sananife is a pretty basic language in terms of mechanics. It uses an alphabet of 16 characters, corresponding to the 16 possible digits in hexadecimal representation: abcdefghinorstuw

hex: 0 1 2 3 4 5 6 7 8 9 A B C D E F
character: o i r w u s g t h n a b c d e f

We can then combine these characters in pairs to form the 55 morae -- the fundamental building blocks of the sananife language. Each mora must consist of a consonant (bcdfghnrstw) followed by a vowel (aeiou).

  • Valid: su, fa, wo.
  • Invalid: us.

This yields the following mora table:

b c d f g h n r s t w
a ba ca da fa ga ha na ra sa ta wa
e be ce de fe ge he ne re se te we
i bi ci di fi gi hi ni ri si ti wi
o bo co do fo go ho no ro so to wo
u bu cu du fu gu hu nu ru su tu wu

From here, we can start to combine morae to create distinct words. For instance, sa + na. The word sa, by itself, is the base form of the verb meaning to be. na is a marker mora, which is normally used to indicate the subject of a sentence. However, when affixed to the end of a verb, it transforms that verb into a noun (similiar to adding -ification in english). sana, the combined word, is the sananife word for being (any sentient entity within the game world). Similarly, the mora ni, by itself, is used to signal a positive tone. fe, by itself is a marker mora used to indicate numbers. Combining ni + fe gives us nife, the sananife word for all or every. Adding -nife as a suffix to another noun is akin to adding -dom in english (eg, videogame-dom): it signifies the abstract existence of all the instances of that noun. So sananife, all together, means something close to beingdom, which is akin to humanity but also extends to non-human characters in the game world.


There are two principal dialects of sananife, as spoken by entities within the game world. The first is what's called "new" sananife, or sananife ninu (literally good sananife). It consists only of the characters abcdefghinorstuw, plus any necessary whitespace or punctuation. And, while sananife is fundamentally case insensitive, new sananife tends to capitalize the beginnings of sentences, as well as proper nouns, to make things easier for human readers.

However, there's also "old" sananife (sananife gorabafe), which is a bit closer to the actual byte representation that gets sent over the wire. Unlike sananife ninu, old sananife does not do human readers the favor of substituting the alphabetical digits oirwusgthn for the hexadecimal digits 0-9. Nor does it clean up the raw hexadecimal values for punctuation and whitespace. The words sananife gorabafe are written in old sananife as 5a9a91fe00602abafe. Note the 00 marker after the 91fe: that's how spaces are encoded. The punctuation marks are also assigned values starting with 0: (. = 0a, ? = 0e, ! = 01, etc). This makes it pretty easy to programmatically determine where words are located in a sananife string, because the mora are not allowed to start with a number.

language -
ninu Na sananifena disa be tibe no nugocino!
gorabafe 9a005a9a91fe9a00d15a00be0071be0090009460c19001
english Literally: Sananife is you now! Colloquially: You're a part of Habitat now!

"Friendly" entities in the game world tend to speak sananife ninu, although they also understand sananife gorabafe. However, the demons and their offspring, as well as other primordial entities at the farther reaches of the game universe — they only speak gorabafe. (It would be quite creepy to be exploring some far-flung realm, when suddenly you find yourself surrounded by a group of ancient menhirs, all chanting at you in raw, incomprehensible hexadecimal.)

As a player gradually becomes more powerful within the game world, and they spend more time listening to sananife being spoken around them, their skill level with the language will increase. This will allow their game client to perform inline translation of any incoming sananife messages into the user's preferred language. A higher language skill also allows players to compose their own messages in sananife from human-language input. However, gorabafe is much harder to translate than ninu, and requires a higher skill level.


Sananife is extremely easy to pronounce, once you know how each vowel should sound:

vowel pronunciation
a ah (as in "call")
e ay (as in "rage")
i ee (as in "free")
o oh (as in "grow")
u oo (as in "true")

When pronouncing a word with multiple syllables, the accent should always fall on the next to last syllable; e.g., sananife is pronounced``sah nah NEE fay`.

Also, the morae ce and ci are pronounced with a hard K sound ("kay" and "key").


Visually, Habitat is pretty primitive. It's essentially just a bunch of boxes moving around, interacting with each other and with the terrain behind them. That framework acts as a blank canvas; the entities of the game world are free to draw upon that canvas.

#Game mechanics

The game mechanics for Habitat are relatively simple. It's a two-dimensional top-down universe, meaning that there is no force of gravity to worry about. All gameplay occurs in real-time; it is not turn-based.


Entities interact with the game world via spells. Spells are the fundamental units of change within the game. They change the state of the universe in specific ways. For instance, there's the MOVE spell, which allows an entity to move up, down, left or right within its current plane. Or the FIND spell, which allows an entity to search for other nearby entities matching a certain description.

You can think of spells like kernel syscalls: small, fundamental actions that you can take to mutate the system. Those spells may be wrapped up in more complex invocations, but underneath the covers it's just a series of the basic spells being cast. For instance, an entity may have an ability that creates a fireball and also restores some health to it. Those would be different syscalls.


Each entity has a certain amount of available health. When the entity takes damage, it is deducted from their current health. If the entity runs out of health, they are banished back into their own mind. This is akin to "dying" and being reborn.


Energy within Habitat is broken up into nine distinct elemental bands: death, earth, fire, life, light, metal, shadow, water, and the void. Each entity can choose which element force it wishes to align with. There are different pros/cons to each.


Aside from entities, the fabric of the game world itself is modifiable. Entities can use the PROJECT spell to change the background texture within their current plane of being. This background texture is important, because the pixels used in it affect the elemental alignment of the corresponding game area. Lots of black pixels means excess void energy in that area of the world; lots of red pixels means an abundance of fire energy; and so on. Entities can be conferred with special powers when they stand in areas dominated by their respective elemental alignment. Conversely, bad things can happen to entities that stand within the power of rival element types.

#What makes Habitat special?

Okay, well, so what? What makes Habitat different from other games out there? I think these are the three main things:

  • Spells as a fundamental building block - Because the only way to mutate the game world is by casting one of the basic spells, we can actually create a full specification for more complex changes that need to occur. Those changes can be recorded and replayed later, spell-by-spell, in order to reproduce the same effects. It also means that there are no "god" entities, in the sense that they can operate outside the rules of the system. There is nothing special about the power wielded by the game's strongest dieties, other than the time it takes to acquire that power. In theory, any player character could also acquire it.
  • Self-referential control plane - Obviously there is a lot of plumbing that keeps a game like Habitat running. Servers, deploys, databases, restarts, different long-lived processes of various kinds. All of them are physically manifest within the Habitat universe. The Datacenter realm houses in-game representations of all the registered server processes used to host the game. It also houses the Database, which can even be reset from within the game itself (albeit with incredible difficulty). As a general rule, things should be configurable from within the game itself, rather than needing to rely on a privileged side-channel tool.
  • A fully-specified language - The fact that entities within Habitat use a custom language for communication means that certain classes of problems are (in theory) easier to combat. Content moderation, abuse prevention, spam, that kind of thing. Sananife, the language, reduces the surface area of what's expressible within the game, similar to other online games where you can only interact with nearby players via generic emotes. However, there are other downstream benefits to using a closed-loop language that I'm only beginning to dip into. Namely, it's a lot easier to perform sentiment analysis on the input text, and then use that to mutate the mental model that certain AI-powered entities have of the game world.

#Setting up a dev environment

I currently build and run Habitat directly on Ubuntu 20. That's the only supported environment right now, although I'd be very surprised if it didn't work across Debian in general. For running on a non-native Linux machine, I recommend just wrapping it in a VM. I don't currently have any wrappers checked into VC for virtualization (Docker etc, Terraform) but I am planning to add in the future. Note that those will not be located in this repo, which only includes the core Habitat process runtime.

git clone git@git.sr.ht:~habitat/core
cd habitat
npm install

This will prompt you to allow the installation of a habitat script on your system, which isn't required, but makes certain system management stuff a bit easier. It exposes the following subcommands:

subcommand description
start Starts the local runtime server.
stop Stops the runtime server.
restart About what you'd expect.
tail Tail the runtime server.
reset Reset all data currently resident in the runtime. Requires confirmation.
watch Watch for local file changes and recompiles the source files.
#Starting the server

Once you run habitat start to bring up the local runtime server, you should then be able to access the game via: https://www.habitat.dev/login

The default user credentials are:

  • Username: username
  • Password: password

#Tech stack

The tech stack for Habitat is pretty basic. Essentially all domain code is written in Typescript. There are different kinds of servers responsible for different things, but they all run within the same parent daemon (called the "runtime daemon"). That daemon process reads the list of desired services (workloads) from the ~/.habitat/services.json file when it starts up, and starts those services accordingly. So that means we can throw all the necessary services in that file for development, but then on production boxes the file can specify only a single desired workload.

Most game data is stored in MySQL tables. Redis is used for storing sessions as well as a pubsub broker for messages within the game world.

#Architecture overview

Habitat uses a relatively simple network architecture -- much simpler than most MMORPG's out there. This is possible due to the fact that the game does not use central authoritative gameservers. Instead, it uses an "edges-only" topology where clients connect to the nearest edge server, and those edge servers have full authority to modify the production game databases as they see fit. When a client (ie, someone's browser) creates a socket connection to one of the edge servers, that server then creates a thin game client of its own to match. It will amass a view of the universe at the player's location and use that to determine whether the player's browser is sending it valid information or not.

You're probably wondering: if there's no centralized server, then how do we control all the non-player characters (NPC's) that populate the game world? Excellent question. Some entities (read: more important ones) are controlled via separate client processes. Essentially these are separate hosts that connect to the edge servers, exactly like browser clients do, and then use heuristics and goals to determine what actions the NPC entities should take.

However, there are more entities crawling around the world of Habitat than would probably be feasible to control directly in this manner. So the edge servers also use some slight of hand to control basic entities in the immediate vicinity of the player.