ao-mud is a spellbook of well-commented atomic bash scripts that each do one thing. we are building semantic building blocks for an autonomously-evolving digital spellcasting language.

deicidus e844e4ad5e added more cool software		2 years ago
spells	read-magic and look follow symbolic links	2 years ago
tutorials	added service manager and tutorials	2 years ago
README.md	added more cool software	2 years ago
install	mud renamed to install	2 years ago
style_guide.md	added list of potential suite inclusions and style guide	2 years ago

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

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.
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:".
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.

Potential Suite Inclusions

This is a list of projects that (as far as we can tell so far) follow free software principles and do something interesting or useful in terms of 1) doing basic computer functions on a UNIX system; 2) making basic computer tasks easier to do or teaching people about UNIX; 3) cryptography: or onboarding people to cryptography and privacy best practices for personal communications; or 4) decentralization: peer-to-peer infrastructure or 5) GUIs for helping people to self-organize politically or organize themselves or their community's information in a post-colonial way; 6) self-host content in an increasingly integrated way; or 7) form ad-hoc mesh networks.

The first projects that will be integrated are: tor, bitcoin, lightning, and SimpleX (in that order). After that, the next features and tools added to the suite will be chosen by popular demand, in close collaboration with specific partner communities.

We are very open to new suggests or critiques or existing items on this list. This is just a public place to collect research on the best free software and non-commercial open-source projects, so that they can be integrated into the ao-bash suite for easy, replicable installation and use by an increasingly large user base.

Similar software is grouped together under one bullet. This list does not represent an endorsement; it represents the state of current research for potential endorsement.

Basic Computer Tasks

SimpleX Chat is encrypted chat with no logins at all

backups - BorgBackup

Timeshift for Linux is an application that provides functionality similar to the System Restore feature in Windows and the Time Machine tool in Mac OS
Notational Velocity is an impressive-looking notes-taking app that attempts to optimize the notes-taking interface in ways similar to ao-3.

UNIX Convenience & Education

Umbrel is a beautiful personal server OS for self-hosting
GNU Guix is a package manager based on Nix's package manager
The New Adventure Shell turns your shell into an adventure game.
BashCrawl is an interactive bash tutorial.
- Terminus is apparently a web-based game like this
- The Command Line Murders looks very fun
- BashVenture looks like a good tutorial game worth trying out
trouble-maker is a command-line app that will cause problems on your system so you can practice troubleshooting them.

Cryptography & Cryptocurrency

tor
SimpleX chat
bitcoin and lightning (clightning implementation)

Dark Crystal social key management allows your friends to back up your keys
Tribler is a tor-onion-routing-like bittorrent client

Decentralized Hosting Infrastructure

Zion is a bitcoin social network / bitcoin layer three.
Matrix-CRDT allows you to use Matrix as the backend for local-first applications.
- Aphrodite is meant to make local software easy to make (project not usable yet)
- @localfirst/auth enables decentralized yet local-first auth using a "conflict-free replicated state container based on a signature chain".
- Solid is a specification for decentralized data storage.
- The Local-First SDK is new and not working yet but I like the philosophy.
PouchDB is a JavaScript that syncs unproblematically.
slskd is a self-hosted web-based client for the soulseek p2p network.
EarthStar is a low-to-the-ground distributed storage protocol
CODA Protocol allows truly decentralized computation (not usable yet) (CCP GitHub)
IPFS is a capable platform and addressing system for distributing responsibility for self-hosting a file on a case-by-case basis.
IPS is the main alternative to tor.

AO GUI for community forum and decision making in a way immanent to the UNIX operating system.

Crabgrass is a p2p social networking software
Dual Power App is a new attempt to create a platform co-op for black communities
Lemmy and Ramble are quality reddit alternatives.
Syndie is an app to syndicate data that can access I2P, Tor, and Freenet (stalled since 2016)
freedit is "the safest and lightest forum, powered by rust"
webmentions (standard)
ActivityPub (standard)

Self-Hosting Content

youtube-dl can download archival copies of videos from YouTube and most other video websites.
- Horahora - YouTube alternative - locally archive, browse, and share videos from nearly any site.
- PeerTube is another alternative that includes plugins and monetization options
Mail-in-a-Box is an easy-to-deplay mail server in a box
Immich is a self-hosted Google Photos replacement
prose.sh is a blog platform for hackers
Etherpad for shared text editing
Cryptpad is a self-hosted Google Drive alternative that works great

Ad-Hoc & Mesh Networking

tuntox "forwards TCP connections over the Tox protocol, which allows low-latency access to distant machines behind NAT you can't control or with a dynamic IP address."

Reticulum, a prepper version of the internet
nostr is Notes and Other Stuff Transmitted by Relays
- awesome-nostr is a list of nostr-related software
- nostrgram is a Telegram clone written in plain JavaScript.
- ArcadeCity has a nostr app
- Lightning.Pub is an LND-based nostr lightning thing
- bija is a Flask-based nostr client
- StackerStan is a good example of a nostr-based AO-like wiki thing (but written in Go)
- Nodestr is a nostr relay implementation in Node.js
- Nvote is a nostr-powered reddit clone
- more-speech is a desktop Nostr client

Miscellaneous

Project Cambria translates your data with lenses
DeepL translator (non-Google)
Hypothes.is is an open-source, standards-based web annotations solution!
DALLE2-pytorch
Podman is a drop-in replacement for Docker that doesn't require a background service.
CardConjurer is a site and apparently open-source repo to make printable Magic card templates. Art assets in this repo I think.
Penpot is a prototyping/diagramming tool
Bootstrap is a nice set of generic icons and other mobile-first web elements for quickly prototyping a project
Whonix for securite hosting; NixOS for reliable environment reproduction.