ao-mud/README.md

ao-mud

ao-mud is a project to make the terminal easier for novice users by narrativizing it as a Multi-User Dungeon, or M.U.D.

Principles:

• story first - make the world make sense, and that will tell us what to code
• playtest-driven development - try to use it, fail fast and iterate; it has to be fun
• POSIX-compatible scripts - maximally compatible across platforms and weird nested environments
• immanence - the game is here, a meaningful virtual space in the terminal
• immediacy - the game is everywhere, not a separate mode
• pedagogy - collecting best practices and making them easy to use, learn, remember, and teach/share in well-commented bash scripts
• sharpen the saw - gradually improving the architecture of the tech stack
• smarter conventions - we can evolve the terminal and make it easier to teach by migrating to higher-order semantics (new words)
• semantic evolution - we can evolve bash from a pidgin to a creole with rigorously one-function apps plus a recursive parser

Architecture

ao-mud is also ao-bash, an attempt to immanentize the AO to the terminal for a native un-AO experience that requires no database.

Some architectural guidelines:

• Make many small, atomic scripts that are almost as atomic as possible
• The smallest logical size is a semantic unit: (e.g., read-magic handles both reading all attributes or one named attribute, could abstract read-all-magic and read-all-magic but it's semantically parsimonious to combine them)
• Make each script work either sourced or executed by using the BASH_SOURCE idiom (will be included after conversion to POSIX)

The Beginning of Your AO Adventure...

What is the Autonomous Organization, what does it mean? This mystery drives your quest.

We all sense something is wrong with the world. We all want to ask the same question.

The AO is the answer to this question.

Along the way, you will learn to use the Unix terminal, and you will gain special terminal upgrades. Most people don't believe that UI upgrades can be game-changing, but with cybernetics and a little magic, anything is possible.

Three Paths of Knowledge

On your AO adventure, there are three different tutorials which gradually unlock the powers of the terminal. Choose your class wisely:

• Sorcerer: The Path of Sorcery is the path of casual power. Sorcerers learn how to wield powerful spells early on, but they don't know how they work. Sorcerers trade words and understanding and remember this knowledge in their memory.

• Wizard: The Path of Wizardry is a path of careful learning. Wizards start by learning the true names of bash commands, and learn to assemble spells gradually. Wizards trade spells on pages (bash scripts) and save them in their spellbook (spells folder).

• Alchemist: The Path of Art is an oral tradition. Find a bash alchemist who can teach you the elements and the ways of alchemy.

Loading Saved Games

ao-mud contains unlockable menus and terminal shortcuts that make using the terminal easier and more fun. To skip ahead and turn some of these features on without unlocking them in tutorial mode, you can use a Save Code that you received from an earlier playthrough. To use a Save Code, open the AO main menu, select "Load Saved Game", enter your Save Code, and press Enter.

Folder Structure

The structure of this project right now is simple. There is a spells folder containing spells you can cast. This folder has a subfolder called cantrips, which contains tiny spells that are used to compose larger spells that aren't meant to be used on their own.

Conventions

1. As a naming convention, spells that use hypens (-) in their name instead of spaces are set up to be run as scripts in the terminal (even if they are cantrips that will merely inform you not to do so). Spells that include a function that is not accessible by executing the script in the terminal are named with underscores (_) in their names. Open these (or any) spells in a text editor to see what they contain.

2. Terminal commands that simply output a single value should output the bare value by default. A --verbose or -v flag should be included on all such functions to include a description field such as "Cursor X:".

3. Cantrips should be so atomic so as to include a single value, if possible. This reduces parsing that must be done by those using the cantrip.

How to Cast a Spell

To cast a spell, cd into the spells directory. Then, the first time you cast the spell, chmod +x spellname. Then ./spellname to cast.

How to Begin

To access the mud main menu, run chmod +x mud and then ./mud in this directory.

A tutorial is coming soon. For now, explore the ./spells directory. Try reading or running the rosetta-stone script or the jump script.