diff --git a/DREAMBOOK.md b/DREAMBOOK.md new file mode 100644 index 0000000..c2850aa --- /dev/null +++ b/DREAMBOOK.md @@ -0,0 +1,258 @@ +# dreambook + +a living document. the vision, the philosophy, the wild ideas. not a spec. +come back here when you need to remember why this matters. + + +## why text + +text is not a limitation. it is the medium. + +david jacobson at brandeis studied this: narrow bandwidth doesn't impoverish +experience, it enriches imagination. when you read "a torch flickers against +wet stone walls" your brain builds a cathedral. VR hands you someone else's +cathedral. text worlds are collaborative hallucinations between the author +and the reader. + +the MOO community proved this for decades. LambdaMOO, MediaMOO, PMC-MOO - +people formed real relationships, built real communities, lived real social +lives through nothing but text on a terminal. presence isn't about polygons. +presence is about engagement, attention, the feeling that you are *there* and +that what happens *matters*. + +we honor telnet. the protocol is the interface. ANSI color, cursor control, +alternate screen buffer - these are our tools. a person with a terminal +emulator gets the full experience. no browser required. no client download. +`telnet mud.example.com 6789` and you're in. + + +## the world + +not rooms. terrain. + +the world is a large 2D grid of tiles. each tile is a terrain type - grass, +mountain, water, forest, sand, whatever the planet calls for. the player +sees a viewport into this grid, always centered on themselves. move east +and the viewport shifts east. you are always @. + +``` +...........~~...... +...^^^^....~~...... +....^^^^..~~....... +.........@.~~...... +............~~..... +.............~~.... +``` + +you're standing between a mountain range and a river. + +``` +....^^^^..~~....... +....^^^^...~~...... +.........@..~~..... +.............~~.... +..............~~... +...............~~.. +``` + +you walked south-east. the mountains are scrolling off the top of the +viewport, river's closer. @ never moved on screen. the world moved. + +**terrain types:** + +- `.` grass/ground - the default, walkable, the base canvas +- `^` mountains - impassable, you walk around them +- `~` water - rivers, lakes, oceans. shallow water (light blue) you can + wade through. deep water (dark blue) you can't cross without a boat or + ability. you get wet crossing shallow water. that matters (cold, weight, + combat penalty, whatever the system wants). +- `T` trees/forest - walkable but slower, provides cover +- more terrain types per world/planet. different planets use different + palettes. earth is green and blue. a desert planet is yellow and brown. + same concept, different colors. + +**entities on the map:** + +- `@` you, always centered +- `*` other players or mobs. you see a * to the north-east, that's + something alive. could be a player, could be a mob. you won't know until + you get closer or use a skill/scouter/scan. if multiple entities share + a tile the display could show count or just *. + +the viewport size comes from NAWS - we know the terminal dimensions. a +small terminal gets a smaller window into the world. a big terminal sees +more terrain. the map can sit above the status line or beside a description +panel, adapting to available space. + +**movement is tile-based.** cardinal directions (n/s/e/w) and diagonals +(ne/nw/se/sw). each step is one tile. movement speed could vary by terrain +(forest is slower, roads are faster). the map redraws on every move. + +**the world data** lives in files - YAML, TOML, or even plain text grids. +version controlled, human-editable. a world is a set of maps (earth surface, +caves, interiors, other planets). runtime state (where players are, mob +positions, dropped items) lives in memory. the world definition is the +source of truth; instances are ephemeral. + +rooms still exist conceptually - when you enter a building or cave, you +transition from the overworld grid into an interior space. that could be +its own small grid or a classic room-with-exits. the overworld is terrain, +interiors are rooms. both work. + + +## combat + +inspired by a DBZ MUD. timing-based, not turn-based. not twitch either - +there are windows. you read what's happening and respond. + +**attacking:** +- punch right/left [target] +- roundhouse [target] +- (more moves to discover/earn) + +**defending:** +- dodge right/left +- duck +- jump +- parry high/low + +you see your opponent telegraph: + +``` +jake pulls back his right fist +``` + +that means parry high or dodge left. but not instantly - there's a timing +window. too early and you whiff, too late and you eat it. commands have +cooldowns. you can't just spam parry. + +**power level** is your health AND your damage multiplier. damage is a +percentage function of PL. this creates natural scaling - fights between +equals are long and tense, fights against weaker mobs are fast. + +**stamina** governs action economy. empty your stamina and you pass out, +vulnerable. resource management matters. + +**progression** has diminishing returns. killing a mob at your PL gives ~10% +gain. killing something far below you gives almost nothing. you have to push +into harder territory. no grinding weak mobs forever. + +the combat engine is a state machine per encounter, driven by the game loop +tick. input is queued, processed each tick, timing windows checked, hits +resolved, output sent. the framework supports tweaking all these numbers - +timing windows, damage curves, stamina costs, XP formulas. + + +## session modes + +a player's session has a mode stack. each mode filters what events reach +the player and what commands are available. + +- **normal mode**: you see everything - room events, chat, people walking by, + weather, ambient messages. full MUD experience. + +- **combat mode**: combat output dominates. you still see urgent things + (someone attacking you, system messages) but casual chatter and room + ambience get suppressed or buffered for after the fight. + +- **editor mode**: full isolation. you're writing something - a room + description, a letter, a piece of IF. the world keeps going but none of + it scrolls through your editor. when you exit, you get a summary of what + you missed. this is critical for telnet - without mode filtering, world + output would destroy whatever you're composing. + +- **IF mode**: you've entered an interactive fiction game within the MUD. + you're in a sub-world with its own rooms, puzzles, inventory. other + players see "jared is playing The Caves of Doubt in the arcade." fully + isolated from main world noise. + +modes can stack. you could be in an IF game and enter combat within it. + + +## interactive fiction as content + +the MUD can host IF games. a room in the world could be a portal to one. +players enter and they're in a self-contained adventure - puzzles, keys, +locked doors, inventory, the whole classic IF toolkit. + +IF games could be defined in data files, same as the main world but with +puzzle/trigger extensions. or - and this is the MOO dream - players could +*create* IF games from within the MUD. builder commands, an in-world editor +(editor mode!), test it, publish it. other players play through your +creation. + +user-created content is the MOO ethos. LambdaMOO's power was that players +built the world. not just decorating - *programming*. we don't need a full +in-world programming language (MOO's approach has tradeoffs), but we do need +a world-building DSL that's powerful enough to express puzzles, triggers, +conditional descriptions, state machines. + +the DSL should be writable in the in-MUD editor. plain text, easy to learn, +easy to share. someone with a telnet client and curiosity should be able to +create a small adventure. + + +## presence and community + +from the MOO research: + +- **presence comes from engagement, not fidelity.** you don't need graphics + to feel like you're somewhere. you need things to care about. + +- **identity is constructed through language.** your description, your emotes, + your speech patterns, your name - these are your body in a text world. + +- **community forms through shared space and shared creation.** people who + build together bond. the MOO wizards learned this. the builders learned + this. give people tools to shape the world and they'll make it home. + +- **authority shapes culture.** who can build? who can program? who moderates? + these aren't just admin decisions, they define what kind of community grows. + lean toward trust and openness. + +- **the mask enables authenticity.** jacobson's paradox: removing physical + cues doesn't remove identity, it lets people construct identity more + deliberately. text worlds let people be who they want to be. that's not + deception, it's freedom. + + +## technical north stars + +- **telnetlib3 is the transport.** it handles telnet protocol, option + negotiation, GMCP, MSDP, NAWS. we use it as a dependency, contribute + upstream. we already improved CHARSET/MTTS fallback - that's the + relationship. users who give back. + +- **async everything.** the game loop is an asyncio task alongside the telnet + server. no threads, no blocking. player input → queue → tick → output. + +- **world data in files, state in memory, persistence in SQLite.** world + definitions are version controlled YAML/TOML. everything loads into memory + at startup. player accounts and progress persist to SQLite. no external + database server. + +- **the game loop is tick-based.** 10 ticks/second or whatever feels right. + each tick: drain input queues, update combat, run mob AI, flush output. + timing-based combat requires a real clock. + +- **simple > clever.** always. readability > performance. the codebase should + be approachable. someone should be able to read server.py and understand + how connections work in five minutes. + + +## things to explore later + +- GMCP for rich client data (Mudlet, Blightmud can use structured data + alongside raw telnet text - maps, gauges, inventory panels) +- MSDP for real-time variable updates (HP bars, stamina, PL) +- MCCP for compression (big rooms, lots of text) +- alternate screen buffer for map/combat split views +- sound via MSP (mud sound protocol) or links +- inter-MUD communication (IMC2, I3?) +- AI-driven NPCs that actually converse +- procedural world generation from templates +- seasons, weather, time of day affecting descriptions +- crafting systems +- housing / player-built rooms in the persistent world +- a web client that's just a terminal emulator (xterm.js) pointing at the + telnet port - honor the protocol even in the browser