Add a dreambook

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