@database "DGEM"
@options "+g -i -s +z -t2 -d12"
@author "Rajah Lone"
@$VER: 1.2E
@subject "DGEM documentation"

@node "dgem_start" "DGEM: guide"

@image DGEM.IMG 1




                        @{"The labyrinth" LINK "dgem_general"}

                        @{"Legal" LINK "dgem_legal"}
                        @{"Installation and requirements" LINK "dgem_install"}
                        @{"Preferences" LINK "dgem_preferences"}

                        @{"History" LINK "dgem_versions"}
                        @{"Limitations" LINK "dgem_bogues"}
                        @{"Differencies" LINK "dgem_differencies"}

                        @{"Greetings" LINK "dgem_merci"}



 
@endnode

@node "dgem_general" "DGEM: presentation"
@image DRAGON.IMG 1


             Grey no more, Black and White once more.
             Hatred has risen again from the unbeing.
             Both of us know him well...
             Chaos has returned and stronger is his need of revenge.

          With great pains did I summoned you.
          You are now in the Labyrinth of the Avatars,
          where you must find the exit.
         Join me quickly at the entrance for our duty will not wait.

                  The Balance must stand

                            Lord Order


   DGEM is provided with an exemple of dungeon. Some dungeons and
   adventures will be proposed.

   @{0I}Feel free to become one of the dungeon masters, by creating a
   new labryinth with DGEM's DEDITOR@{0}
 
@endnode

@node "dgem_legal" "DGEM: legal"
@image DRAGON.IMG 1



             This game is a
             Renaissance product.





@image RENAISSA.IMG 40

           This game is a freeware coded by Rajah Lone,
           with the help of Daroou (dungeon building, character
           editing and bugreport) and Mateo (support).

      Copy and spread are granted by its use is restricted
      as follows:

   @{0B}You must have one of the original disks of
   Dungeon Master or Chaos Strikes Back.@{0}

  The original authors are:

   ú Directors: Doug BELL, Dennis WALKER and Mike NEWTON
   ú Graphists: Andy JAROS and Dave SIMON
   ú Producer: Wayne HOLDER

  DGEM is a game written @{0I}de novo@{0} with GFA Basic and
  uses the graphwork and sounds of the legendary game.

  DGEM uses legal system calls (pure AES and VDI) to run on
  modern Atari machines or emulators that can't run the original
  game. This program is not suited for old Atari machines.

  Please @{0B}note@{0} that we deny any responsability concerning
  the use of this program. Use it at your own risk.
 
@endnode

@node "dgem_install" "DGEM: installation and requirements"
@image DRAGON.IMG 1


              16 colors 640*400 pixels screen is the minimum required.

          A modern operating system such as MagiC or MiNT is strongly
          advised, with an optimized VDI like NVDI.

        The program uses the Falcon XBIOS Sound since the 0.12 version.
        Some drivers exists to add these XBIOS functions if you do not
        have this machine (see the @{"Sound" LINK "dgem_preferences3"} preferences)

    The game uses plenty of memory, moreover on high-colored screens.
    So if you have not enough space or if the game becomes slower, run
    it in 640*480 16 colors.

   Since the 0.20 version, you'll need a lot of memory:
   8 Mo (16 colors ) or 14 Mo (256 colors) is the minimum required.
   If you want to see all monsters in real colors, use the 256 color
   mode screen.

  Minimum requirements:
  STeem/Nostalgia/Hatari: TOS 2.06, VDI extended mode, 14 Mo
  Falcon/TT/clones: TOS 4.04 (MagiC advised), 256 colors, 14 Mo

  Recommended:
  MagiCPC/MagicMacX/Aranym/FireBee: 32 Mo and TTRAM
  Falcon/TT/clones: MagiC, NVDI, 14Mo or more, 256 colors or more

  On Aranym and fVDI with 16?/256c modes, you may encounter display
  problems, use TC32 bits screenmodes.

  You can install DGEM program and its data folder on every media
  that has enough space.

  DGEM can be launched from a non-writable media (CDROM) but you
  need to declare in a modern OS the HOME$ environment variable
  and configure in the preferences the folder for saved games.
  ie in MAGX.INF, #_ENV HOME=C:\GEMSYS\HOME\
  If not HOME$ declared, the DGEM.INF file is written in the
  DGEM.DAT\SYS\ folder.
  If not HOME$ declared and the media is not writable, the
  DGEM.INF file be located on the root of the C partition.

  ST-Guide installation is required if you want to call the
  documentation directly from the game. Make it as *.ACC or
  declare its path in the environment variable STGUIDE$.
  ie in MAGX.INF, #_ENV STGUIDE=C:\ST-GUIDE.ACX
 
@endnode

@node "dgem_preferences" "DGEM: preferences"
@image DRAGON.IMG 1





               @{"Paths" LINK "dgem_preferences1"}
               @{"Display" LINK "dgem_preferences2"}
               @{"Sound" LINK "dgem_preferences3"}
               @{"Misc" LINK "dgem_preferences4"}
               @{"Console" LINK "dgem_preferences5"}






 
@endnode

@node "dgem_preferences1" "DGEM: paths preferences"
@image DRAGON.IMG 1




            @{0U}Saved games path@{0}
              The software will write saved games in this folder.

            @{0U}Other maze@{0}
              Filename *.DGM created with Deditor.
              A customized dungeon can be loaded from another location than
              DGEM.DAT\DATAS\ and other name than MAZE.DGM.
              The program need to be restarted for the changes to be effective.
              Do not forget to save the preferences.

            @{0U}Use a cache for converted images files@{0}
              This option is set by default. At first start, saves the cache
              after images loading and convertion. 
              Next start, if found and corresponding to the screen pixel format
              and bitplane number, the software will load the DIMAGES.nnn and
              DIMAGES.IDX instead of loading and converting (for a long time)
              the original DGX images files. If the screen format is the same.
              This speed up program start up.

            @{0U}Cache path@{0}
              The software will write there the converted images.
 
@endnode

@node "dgem_preferences2" "DGEM: display preferences"
@image DRAGON.IMG 1




            @{0U}Use a desk background@{0}
              The software will install its own desk background.
              Can be nicer in the 16/256 colors modes and under
              a multitasking environement.

            @{0U}Window view size@{0}
              A zoom can be applied on the view window.
              This option uses some enhancements appeared with
              NVDI (see NVDI4 docs). Unfortunatly, it's slow and
              does not work with graphics cards and some NVDI
              versions.
              If a Pixels packed format (ie 'chunky' mode) is detected,
              then a built-in zoom is proposed for 16c, 256c, TC16 and
              TC32 screenmodes.

            @{0U}Windows without tile bar@{0}
              The title bar of some windows are masqued to gain
              space on screen. Can be nicer. These windows must be
              joined to the 'view' one to be moved.

            @{0U}Use Offscreen VDI functions@{0} (need restart)
              If available ("EdDI" cookie) and set, opens an offscreen VDI
              bitmap and uses this handle. May speed up animations on some
              configurations such as Milan+NVDI. 
              Carefull, it may also slow display on standard machines.
              Due to some bugs, text display uses the on-screen VDI handle.
              
            @{0U}Allocates in Video RAM@{0} (need restart)
              If available (Radeon card on PCI, SuperVidel), this option is
              unhidden and set on to use ct60_vmalloc(). This relocates
              graphics datas in Video RAM to speed up animations.
              It this options appears disabled, the VRAM allocation has failed.
      
            You cannot yet use these display options together.           
 
@endnode

@node "dgem_preferences3" "DGEM: sound preferences"
@image DRAGON.IMG 1




            @{0U}Enable (Falcon compatible) sound@{0}
              The software will use the XBIOS sound routines
              appeared with the Falcon TOS. If you want to enable
              the sound on other computer than a Falcon, you may
              install for:

              ú Atari STE or TT, or an Atari emulator which
                supports DMA Sound, then use Thomas Huth's XSound
                (put the XSND_DMA.PRG in the AUTO folder, see in
                the GOODIES folder of DGEM archive).

              ú Milan: use the MilanBlaster driver (commercial)

              ú Hades: use GSXB from Assemsoft (freeware)

              ú Aranym: use zmagxsnd.prg and use correct audio parameters 
                in Aranym config file
             
              Note: under MiNT with Memory Protection mode, set the
              program header flag to 'Super' or 'Global' for the DMA sounds
              to be played without crash.

            @{0U}Maximum volume@{0}
              The software will attenuate sound output.
              Can be more convenient if you uses others sounds
              programs but the stereo sounds effects will be less
              noticable.
 
@endnode

@node "dgem_preferences4" "DGEM: miscellaneous preferences"
@image DRAGON.IMG 1




            @{0U}Confirm alerts@{0} (not yet implemented)
              advised for beginners.

            @{0U}Freeze keyboard buffer when moving@{0}
              If you have a very fast Atari, better enable
              this function when moving with the keyboard
              cursor pad.

            @{0U}Using PC keyboard@{0}
              The keyboard cursor pad for the moves of the
              party is Atari by default. If you have a PC keyboard
              (for Milan or Hades), enable this option may help.

@image CURSORS.IMG 20
            Moves:



@image CUR_ATAR.IMG 20
            Atari:



@image CUR_PC.IMG 20
            PC:               (The keyboard arrows are also working)



@image CUR_NUM.IMG 20
            NumPad:




 
@endnode

@node "dgem_preferences5" "DGEM: console preferences"
@image DRAGON.IMG 1




            @{0U}Buffer@{0} (applied at next launch)
              Select the number of lines that the software will
              keep in memory.

            @{0U}Height@{0} (applied at next launch)
              Select the number of lines that the software will
              display in the console window.

            @{0U}Enable debug logging@{0}
              Debugging message will be displayed in the console
              window. For coding purposes: you should not need it ;-)

              Special keys for debug mode:
              "s" to display statistics on the sofware memory manager
 
@endnode

@node "dgem_versions" "DGEM: history"
@image DRAGON.IMG 1



           @{0B}0.10@{0} First release, working has been made in
           preparation and during the Very Important Party 2 at
           Lyon (July 2000). Implementation of walls, stairs, pits
           and an exit for this minos-like game.

       @{0B}0.12@{0} (March 2001) Spatial sound routines (Falcon
       compatible), first walls and floor items (alcoves and
       decoration), hidden pits, second wall texture.
       Iconification and desk background.
       Fixed a crash on TT in singleTOS mode.

     @{0B}0.14@{0} (January 2002) Hard disk friendly new file format for
     the images, zoom mode (NVDI Atari required), PC keyboard managment.
     New items for walls and floor : doors, switches, pads,
     teleporters, wall inscriptions and some mechanisms to
     handle all these devices.

  @{0B}0.16@{0} (April 2003)
   ú image cache for fast reloading
   ú memory manager for images (much less Malloc calls, should
     crash a bit less on old systems, though TOS 2.06 640*400*16c
     is the minimum required)
   ú use of TT-RAM if possible (experimental)
   ú quicker display and sparing of memory (masks are only one
     bitplane now)
   ú extended preferences window with new options
   ú console window for message and debug purposes
   ú party summary and character sheets windows
   ú delay and multiple actions in mecanisms, wall items can be
     held on every faces of the wall tile.
   ú new wall items: keyholes, coinholes, gemholes, torch holder,
                     spy eye, fountains, character mirrors
   ú objects: everything from DM, CSB and TQ, but only manipulation
              is possible now.
              Are working: chest, scrolls, compass (in hand), keys,
              coins, gems, mirror, magnifier
   ú characters in party: at this time, works only as 'containors'
                          for objects. Their eyes are functional.

   @{0B}0.18@{0} (April 2005, Jaguar Connexion 2K5 release)
   ú on characters: eating, drinking, sleeping, homeostatis, death,
                    ressurection, weight carried, experience gain,
                    damages, resistance, selecting the leader,
                    fatigue, poisonned state, etc.
   ú with objects: most are usable now, some can modify characters
                   parameters, some can be used in hand, some are
                   with charges... For example, the lockpicks may
                   work on some weak keyholes, the rope permits to
                   climb down into a pit, some doors can be broken
                   by sword, torch burning...
   ú magic: all that is not thrown (ie fireball or dispell)
            2 new incantations for zo potion and alcohol.
            try the 'see through wall' or 'magic footprints' ;)
   ú action: with objects or nothing (with associated sounds), all
             is possible except throwing (magic or object) and shooting.
             try the fluxcage of the powered firestaff.

   @{0B}0.20@{0} (December 2005, Xmas)
   ú all the monsters
   ú floor items: monsters generator, blocking tile
   ú hand to hand fighting

   Carefull, since this version, the program needs more memory.
   8 Mo under 16 colors mode, 14 Mo under 256 colors mode.
   Under 16 colors mode, some monsters appear with false colors
   Minimum requirements:
   STeem/Nostalgia/Hatari: TOS 2.06, VDI extended mode, 14 Mo
   Falcon/TT/clones: TOS 4.04 (MagiC advised), 256 colors, 14 Mo

   @{0B}1.0@{0} (December 2006)
   ú missiles: thrown objects, spells casting, etherical effects
   ú last remaining spells
   ú Chaos' death
   ú wall items: amalgam, exit, dagger thrower, fireball or venom generators
   ú trigger for alcoves: activates something if put/remove precise object.
   ú some bugfixes

   @{0B}1.0B@{0} (January 2007)
   ú more ergonomic methode to change characters positions
   ú fixes:
     - crash if poison cloud was on a monster
     - cast spells and object disappeared under the stairs
     - characters bones disappeared under the stairs
     - bad redraw of characters positions after loading a saved game
     - bad text in console after new game or load a saved game
     - walking did not consume stamina
     - memory corruption after deleting an automatic job ('boots of speed' on
       the first character)
   Thanks to Jean-Luc CECCOLI
       
   @{0B}1.0C@{0} (March 2008)
   ú compatible with MiNT memory protection mode
     
   @{0B}1.0D@{0} (November 2012)
   - add: the sleep button can also be used to wake up (the party is wake up
          with a firm clic on main window)
   - fix: BubbleGEM support is removed (no use, and caused crash with MiNT)
   - fix: some code cleaning on deleting automatic jobs
   - fix: mouse cursor could disappear after modification of character position
          in the party
   - fix: crash when trying to play a DMA sound under MiNT with Memory 
          Protection. DGEM.PRG is now released with 'Super' in its program
          header to allow DMA sound xbios call.
   Thanks to Jo Even.
      
   @{0B}1.1@{0} (December 2012)
   - new: compiled with Lonny Pursell's GFA Library, with 68000 and ColdFire
          targets.
   - fix: wider and separated console windows, because some AES are not easy
          with small windows.
   - add: built-in zoom *2 or *3 in TC16 and TC32 modes, if the VDI does not
          propose them. 
   - fix: cleaned code ($F%, variables will not return as float#).
   - fix: rewrite of load and save preferences file.

   @{0B}1.1B@{0} (June 2013)
   - add: pause mode (Esc key, menu entry or iconification) (thanks JFL).
   - add: can use other maze files in preferences.
   - fix: cosmetic fixes for 3D ressource display under XaAES and MyAES.
   - fix: party sheet window arrows and mouse clicks with XaAES.
   - fix: display in iconified window under MyAES.
   - chg: display cursor with graf_mouse(M_ON/M_OFF) instead of v_hide/show_c
   - fix: in clear/freeze keyboard buffer function (thanks Daroou).
   - fix: general MU_TIMER delay is lowered by tasks and display delay (thanks Daroou).

   @{0B}1.1C@{0} (August 2013)
   - fix: general MU_TIMER delay was not correctly lowered.
   - fix: used sounds evenif not allowed (sound locked by another application).
   Thanks Daroou.

   @{0B}1.1D@{0} (March 2014)
   - fix: possible crash at start when reading the preferences file.
   - fix: cookie detection use Ssystem() if possible.

   @{0B}1.2@{0} (January 2016)
   - chg: image cache is set on by default and configuration is easier.
   - fix: color problem, was not right black around some monsters in TC16
          and TC32 screenmodes.
   - add: display option, if "EdDI" cookie available, can use an offscreen
          VDI handle. In most cases, slows display, but may speed up
          display animations with some machines such as Milan+NVDI.
   - add: display option, if available (Radeon on PCI or SuperVidel), uses
          ct60_malloc() to relocate graphics in Video RAM to speed up
          animations.
   - chg: some cleaning in the preferences panels.
   - fix: test for correct CPU 68K or Coldfire.
   Thanks calimero, shoggoth, Lonny PURSELL, Jean-Marc STOCKLAUSEN,
   and Guillaume TELLO.

   @{0B}1.2B@{0} (May 2018)
   - fix: a cache file could be empty if memory block was eactly 24000*nb_plan&.
          This happened in 16 colors screenmode, some of the raster loaded from
          the cache were corrupted.

   @{0B}1.2C@{0} (May 2018)
   - fix: workstation format value (interleaved-planes, pixel packed = chunky)
          is tested for the cache validation.
   - add: built-in zoom also available
          for 16 and 256 colors pixels packed screenmodes.

   @{0B}1.2D@{0} (May 2024)
   - fix: alert for 640x400 screenmode minimum needed (then continue).
   - fix: preferences windows is width reduced.
   - fix: add "u:" and convert slashes for $HOME value written in un*x format.
   - chg: use of clean revamped EXIST() instead of old Fopen() trick.
   - fix: wrong test of _SND (wrong bit 1, right bit 5) for XBIOS Falcon sound.

   @{0B}1.2E@{0} (December 2024)
   - fix: inappropriate Mfree()s while loading TGX rasters containors and sounds.
          could display bad images and/or play crashy sounds.
 
@endnode

@node "dgem_bogues" "DGEM: limits and issues"
@image DRAGON.IMG 1


            ú Requires the "EdDI" cookie to display on graphic cards.
              Falcon and new machines such as Milan have this by nature.
              If you have a graphic card with an old operating system,
              you'll need NVDI.

 
 
 
     ú Many Memory Allocation via GEMDOS calls: old TOS and ST emulators
       won't appreciate. TOS 2.06 seems to be the minimum required.
 
     ú some VDI does not implement all modes for rasters copies in some
     screen rezolutions. Noticed on Aranym + fVDI driver in 256 colors mode.
     Use True Color mode instead.
 
@endnode

@node "dgem_merci" "DGEM: greetings"
@image DRAGON.IMG 1



               Special dedicace to:

               - LemonBubble who made this come true
                 (Thanks for the Ultimate Ripper).

               - Daroou
                 (Comrad in arms, unfortunately lost in the labyrinth)


           Greetings to Claude ATTARD for learning me GEM.

      Best regards to STrider/MJJ, razaac/Supremacy, Helloý FroST and
      all the Sector1, JaceSTK, FanFan, Fabounio, BouB and MoMo
      of the megamighty PoPsY Team, ERS, andertal, CosmosH, Sygne030,
      Cooper, boMinz, Skweek, PMdata, Jagware team, K-L, Amigars,
      Speedy67, DrBio, StAn, MrBelett, RayXamber, Rix...
 
@endnode

@node "dgem_differencies" "DGEM: differencies with the original game"
@image DRAGON.IMG 1



               Dungeon Master changes the color palette twice while displaying
               So there's more than 16 colors on the screen. Some colors are
               used for monsters. Enlightenment or endarkment are also possible
               without using a mask.

             Under GEM environment, it is forbidden to change colors like
             this. So some monsters will appear with false colors in 16
             colors screen mode. And the dungeon will be always enlightened.
             Lighten or darken spells are ineffective. Torches can burn but
             only for pleasure, not for light.

          The correct colors are displayed when you use 256 or more screen
          mode. Carefull: this will use more memory to load the images.

        Moreover, to be friendly with multitasking environment, some work
        with images are already done. The original game unpacks, resizes,
        darkens, mirrors while playing. This could not be while other
        programs run, so all the images are loaded in memory. This explains
        why DGEM uses a lot of RAM.

     Using several windows, your AES (GEM part that controls the mouse cursor)
     should be updated (AES >= 3.40), so that you do not have to top a window
     to access its contents.

     Designed for relatively 'modern' Atari computers, and assuming there's
     enough RAM, all is located in memory. No stage limitation: monsters
     can fall into a pit and live, you can have all type of monsters, of
     doors, of items on the same level.
 
@endnode
