@database "PacMania"
@options "+g -i -s +z -t2 -d12"
@author "Rajah Lone"
@$VER: 1.0 (01-12-2025)
@subject "PacMania documentation"

@node "pacmania_start" "PacMania: guide"

@image pacman.img 1

                          
                          
                          
                          
                           
                      Just another Pac-Man game,
                          for Atari GEM environment.
  
  
  
  


 @{"Generalities" LINK "pacmania_general"}, @{"Requirements" LINK "pacmania_install"} and @{"Legal" LINK "pacmania_legal"} 
 
 @{"Controls" LINK "pacmania_use"} and @{"Preferences" LINK "pacmania_preferences"}

 @{"History" LINK "pacmania_versions"} and @{"Greetings" LINK "pacmania_greets"} 
  
@endnode

@node "pacmania_general" "PacMania: generalities"

 This game is originally developped and edited by NAMCO for Arcade systems.
  
 Here is a GEM port rewritten in GFA Basic (GBE) on Apollo V4SA with EmuTOS,
 with originals graphics and sounds.
 
 Intro sequences are not planned, nor level pre-selection.
   
 This is for fun and study. Monetizing on these works is forbidden.
  
 @{0B}Credits:@{0}
 - NAMCO
 - https://www.spriters-ressources.com - graphics: SonicFan32, Tocf, Mister Man 
 - https://github.com/stuart73/UnityPacmania - some datas, analysis and sounds
 - https://pacman.fandom.com/wiki/Pac-Mania - analysis
 - https://strategywiki.org/wiki/Pac-Mania - analysis
 - me - GFA code
  
@endnode

@node "pacmania_legal" "PacMania: legals"

 This software is freeware. Its sources are provided for general knowlegde in
 the same archive. Adaptations and upgrades without the agreement of the author
 are permited. Monetizing on this work is forbidden.
 
 I deny any responsability of the usage of this software.
  
@endnode

@node "pacmania_install" "PacMania: requirements"

 @{0B}Mandatory:@{0}
 - screenmode: since 320*400px with 256 colors
 - RAM: 4MB
 - hard disk space: 12MB (more if you use cache)
  
 @{0B}Strongly recommended:@{0}
 - NVDI
 - TT-RAM
 - High-End Atari machine such as V4SA, FireBee, Falcon+060, Milan, Aranym...
 - XBIOS sound routines (Falcon compatible) for sounds effects

 If display is slow, use 256 colors screenmode instead of launching the game
 in True Color screenmode.
 
@endnode

@node "pacmania_use" "PacMania: controls"

 @{0B}Keyboard:@{0}
 - Arrows keys: moves
 - Shift keys: jump
 - Esc key: enable or disable pause
 - Control+N: new game
 - Control+I: about window
 - Control+P: preferences window
 - Control+Q: quit program
 - Control+H: highscores window
 - Help: open this guide
 
 @{0B}Joystick and JoyPad:@{0}
 - Stick: moves (no diagonals) 
 - Fire: jump
 
@endnode

@node "pacmania_preferences" "PacMania: preferences"

   @{"Cache" LINK "pacmania_preferences1"}
   @{"Display" LINK "pacmania_preferences2"}
   @{"Sound" LINK "pacmania_preferences3"}
   @{"Controls" LINK "pacmania_preferences4"}
   @{"Highscores" LINK "pacmania_preferences5"}
   @{"Miscellaenous" LINK "pacmania_preferences6"}
   @{"Debug" LINK "pacmania_preferences7"}
  
@endnode

@node "pacmania_preferences1" "PacMania: preferences - cache"

 @{0U}Use cache for converted images to screen format@{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 XIMAGES.nnn and
  XIMAGES.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}Image cache@{0}
  The software will write the converted images in this folder.
  
@endnode

@node "pacmania_preferences2" "PacMania: preferences - display"

 @{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}Main window 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 not available, a built-in function can zoom for True Color screens.

 @{0U}Hide mouse cursor if game windows ontop@{0}
  Mouse cursor may be not needed ingame, and its flickering may be annoying.
  Cursor is shown if game is paused.

 @{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.     
   
@endnode

@node "pacmania_preferences3" "PacMania: preferences - sound"

 @{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.
 
 @{0U}SNDH music@{0}
  Music is played if sounds are disabled.
  Need a Yamaha PSG or compatible. 
  This feature is disabled on ColdFire setup.  
  
@endnode

@node "pacmania_preferences4" "PacMania: preferences - controls"

 @{0U}Keyboard@{0}
  Use it or not for in-game.
  
 @{0U}Joystick 1@{0}
  Fire button is equal to right mouse click so in multitasking mode, point
  the mouse cursor on the program window to avoid other application or desk
  action.

 @{0U}Joypad A@{0}
  If you have STE Joypad ports (Jagpads ports).
  
@endnode

@node "pacmania_preferences5" "PacMania: preferences - scores"

 @{0U}Local highscore@{0}
  The highest highscore is saved in a file in $HOME folder.
  It's specific to the current levels/maps id. If you change it, then
  the local highscore is reset.
    
 @{0U}Share highscore online@{0}
  Highscore is sent to a WebService @ptonthat.fr, 
  where the score is compared with other gamers'.
    
  If activated, the highscores list is automaticaly downloaded.
  If not, then use the update button to load it.
     
  You must use a nickname and location. 
  A STinG or compatible TCP/IP layer is needed. 
  MiNTNet is used but GlueSTik must be there for the resolver function.
  
@endnode

@node "pacmania_preferences6" "PacMania: preferences - miscellaneous"

 @{0U}Confirm alerts@{0}
  Advised for beginners.

 @{0U}Slow down@{0}
  This value corresponds to an small pause in milliseconds added between
  screen refreshes. Inscrease this if game is too quick.
  Aranym needs 1 or 2 ms to tame the main timer.
  Value should be 0 ms, computation is done (Daroou's trick) to adapt main
  timer with display delays.
  
@endnode

@node "pacmania_preferences7" "PacMania: preferences - debug"

 @{0U}Use log file@{0}
  Enable this if you encounter sprite display or whatever problems.
     
 @{0U}Log file@{0}
  The traces will be written in this file, mainly errors while loading
  the datas at program start.
  Under MiNT, set to u:/ram/pacmania.log by default.
  
 @{0U}Calculate framerate@{0}
  Compute average framerate, and write it to log when "O" key is pressed.
  Wait some time in the scene to count significant amount of frames before
  write output. Remind that computing this may slow the display.
  Scenes: out of game, ingame, game paused.
  
@endnode

@node "pacmania_versions" "PacMania: history"
 
 @{0B}1.0 @{0} (01-12-2025) 
 - add: basic AI for ghosts.
 - add: fine tuning for levels, according to websites game analysis.
 - add: local score and online highscores.
 - add: hub (lifes, fruits collection, score, messages).

 @{0B}WIP 20250105@{0}
 - add: pacman and ghosts interactions.
 - add: deaths sequences, eyes state and ghost regeneration in nest.
 - add: regular, green, pink power pills and fruits/bonus.
 - add: bonus and catches gains.

 @{0B}WIP 20241225@{0}
 - First release as preview: only eat pellets, run through levels,
   no interaction with ghosts, no bonus, no scores, no music.
 
@endnode

@node "pacmania_greets" "PacMania: greetings"

  Thanks to:
  - The Atari V4SA and Apollo Team.
  - Jean-Marc Stocklausen aka Daroou
  - Lonny Pursell (GFA Basic and GBE)
 
@endnode
