Welcome to Mage Against Generic Enchantment!

===========================
  ABOUT
===========================

Mage Against Generic Enchantment was written in seven days, as part of
the Seven Day Roguelike Challenge.

    You were a mage enrolled in the prestigious MAGE academy.  This academy's
    recursive acronym is Mage Against Generic Enchantment.  The founding
    principle is a rejection of boring magic that can be tamed by orthogonal
    rules.  Each spell should have its own unique charm unrelated to
    other magic.

    It didn't take long to discover the academy was a scam.  The same
    boring rules underlie their magic as the rest of the multiverse, except
    they've hidden the connections behind thick layers of obfuscation.

    Escape is not so easy, however, for they've placed the academy on the
    top of a tall tower.  The lower levels are all inhabited by monsters
    that make short work of students that try to leave without a gate spell.

===========================
  HOW TO START
===========================

If you are a windows user, run it from windows/mage.exe.

If you are a linux user, run it from linux/mage.sh.
You may need to install SDL.

If you are a source diver, go into the src directory.
Look for BUILD.TXT files to try and guide you, there is one under
each of the porting subdirectories.

===========================
  HOW TO PLAY
===========================

Mage Against Generic Enchantment is at its core a very traditional
roguelike.  Players of Nethack will find themselves at home.

A key difference is that an earnest effort has been made to make it
playable with no visual component.  See how far you can make it
without turning on the map!

(If you give up, [O]ptions and select [d]isplay map)

===========================
  DEFINITIONS
===========================

Large rooms are 5x5.  Small rooms are 2x2.  Short hallways are 5x2 and
long hallways are 8x2.  Elbows are L shaped rooms with the directions
telling which way the arms of the L face.  They are 5 on each side.

Fireballs, clouds, and other bursts are 3x3 unless described as large,
then they would be 5x5.

===========================
  CUSTOMIZING 
===========================

If you don't like the default font, you can change it!

Go to the windows directory and replace terminal.png with another font
compatible with The Doryen Library.

The text to speach on Windows runs off the built-in library.  You can
change the voice using the Windows speach settings.  Fine grain
control can be had by editing the mage.cfg file.  You can also disable
attempting to connect to the Windows TTS service entirely in the .cfg
file - this may be necessary when Microsoft breaks this service some
day.

On Linux, pipe the output of the program to your favorite speach
synthesizer.  espeak and festival are options I know
./mage.sh | espeak
./mage.sh | festival --tts
but I don't know of something that will properly be pre-empted by the
console stream commands.

On Windows console output is lost by default - you can attach a
console via the mage.cfg if your display tech needs one.

===========================
  GAME DESIGN MESSAGE
===========================

An essential part of my own definition of Roguelikes is that they are
grid-based tactical combat games.  But does the grid have to be
displayed for it to be a roguelike?

Decades ago, on USENET, I first encountered blind players of
roguelikes.  While roguelikes are very visual in nature (being
top-down grid-based tactical combat simulators), they also were quite
accessible.  Console output can be queried in a discrete manner.
Usually messages were always displayed in the same location for a
screen reader to report.  They are also turn-based, allowing time to
inspect the map.

Since then roguelikes have moved in another direction.  We run libtcod
to gain 24-bit colour, which also makes the screen impenetrable short
of OCR.  The message window atrophies, replaced instead by on-screen
effects.  Complicated control schemes are pared down to just a few
commands.  You can see this development in my own 7DRLs.

In my case, ironically, the reason for the change has been to increase
accessibility.  New users are distressed by a wall of keyboard
commands.  They don't read the messages, or inspect details, but
instead expect relevant information to be bubbled to them.  I don't
need to be told "You hit the rat" if I can see a flash of red on the
rat.   Menus are built contextually and are navigated with arrow keys.
This is all part of the WIMP philosophy - a philosophy strongly tied
around a tight feedback loop between the user and the computer.

Consider selecting something from a menu.  Mousing to it is done by
hand-eye coordination, requiring constant monitoring of how the mouse
is moving while moving it.  Keyboard navigation is little better - you
rarely think "down 5 times", instead you hit down repeatedly until the
desired item is highlighted.  How is this to be navigated without
sight?

Two obvious approaches are braile and text-to-speech synthesis.  While
both of these can make long form text like this document accessible,
they are much less useful for tight feedback loops.  The other
approach is to rethink the problem to remove the feedback loop.  This
is what voice mail systems do.  They do not ask you to select next and
previous options until you get to the one you want.  They expect a
direct choice of the final option from 1-9.  And note that very
swiftly we start hitting 7 to delete the message.

So, back to this game...

I set as a goal a roguelike that could be played without visual feedback.
I am not about to acquire a braile reader or improve my listening skills,
however, so the ansatz I used is that if it can be played with the
message stream alone I would consider it a success.  Since I want it to
be a roguelike (if I just wanted a TTY only game, I could look to
MUDs) I also decided to make a very traditional one.  I also
wanted it to be a good roguelike irrespective of this approach.
Ideally, the excercise will result in a better roguelike than if it
was not taken.

Central to this approach is the Display Map Option.  This lets me both
debug if what I'm describing is what is happening, but also ensure
you can toggle between the worlds.

I learned in this process that my message output had atrophied a fair
bit.  There was a lot of important information not making it to the
console.  I also had to try and balance the information overload of
reading the screen.  A lot is happening on the map in a roguelike.

Interestingly, this also caused me to re-implement a lot of Nethack's UI
decisions.  Having keys assigned for inventory items becomes essential
when menus are expensive to render.  Likewise, verb-first lets the
inventory be pared making shorter menus than noun-first interfaces.
This results in an explosion of commands and I found myself heading to
the Nethack pages to make sure my hotkey choices were somewhat close.
Nethack has long been ridiculed for its long command list.  But while
researching text-to-speech, I came across Microsoft's Narrator
shortcut list:

https://support.microsoft.com/en-us/windows/appendix-b-narrator-keyboard-commands-and-touch-gestures-8bdab3f4-b3e9-4554-7f28-8b15bd37410a

I count over 200 table entries there.  Using the full keyboard just
makes sense once you discard the feedback loop.  The idea is to maximize
information from the user in each input event.  If we discard the
rapid-scan of the visual system, we can't keep asking the user "Are we
there yet?" but need to work at higher chunks.

Thanks to Microsoft's work on accessiblity, I was also able to
integrate with their SAPI TTS system.  This proved its own excitement
as getting TTS to sensibly render text is... interesting.
Ironically it is likely I've failed to handle IME properly.

So, did this make for a better game?

I believe it did.  Even if you play with the map on, Mage Against
Generic Enchantment is a better game than if I had not done this
exercise.  I don't just mean that the messages are better rendered.
But going back to the Nethack-style UX I feel improves the game.  I
had been very careful in the menu-system of my previous roguelikes to
preserve hotkeys for all actions.  I'd also carefully [C]all them out.
But they were unused, leaving us in a noun->verb world of a tight
dialog with the system.  While this may be necessary on a phone with
no discrete input, the keyboard is capable of so much more.  And if we
are not forced into it, we will lazily regress to arrow-ing our way
around the interface rather than playing the game.

I hope it at least makes you think; and is enjoyable even if you have
to turn the map on.

===========================
  CREDITS
===========================

This is a Seven Day Roguelike.  It was written in a 168 hour time
frame.  Hopefully it doesn't feel like that was the case, however.

Mage Against Generic Enchantments is written by Jeff Lait and uses The
Doryen Library for graphical output.  

You can contact Jeff Lait at: jmlait [snail] gmail [dot] com.

===========================
  FINAL IMPORTANT NOTE
===========================

Have fun!
