# 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
