FunGEn 0.4 → 0.4.1

raw patch · 15 files changed

+251/−149 lines, 15 filesPVP: major bump suggested

API removals or changes: PVP suggests a major version bump

API changes (from Hackage documentation)

Files

• FunGEn.cabal +1/−1
• Graphics/UI/Fungen.hs +51/−14
• Graphics/UI/Fungen/Display.hs +4/−1
• Graphics/UI/Fungen/Game.hs +96/−85
• Graphics/UI/Fungen/Init.hs +20/−2
• Graphics/UI/Fungen/Input.hs +6/−5
• Graphics/UI/Fungen/Loader.hs +4/−3
• Graphics/UI/Fungen/Map.hs +26/−20
• Graphics/UI/Fungen/Objects.hs +24/−13
• Graphics/UI/Fungen/Text.hs +6/−3
• Graphics/UI/Fungen/Timer.hs +4/−0
• Graphics/UI/Fungen/Types.hs +1/−0
• Graphics/UI/Fungen/Util.hs +3/−2
• Graphics/UI/GLUT/Input.hs +1/−0
• README.md +4/−0

@@ -1,5 +1,5 @@ name:               FunGEn
-version:            0.4
+version:            0.4.1
 copyright:          (C) 2002 Andre Furtado <awbf@cin.ufpe.br>
 license:            BSD3
 license-file:       LICENSE

@@ -1,10 +1,13 @@-{- | This is the main module of FunGEN - Functional Game Engine.
+{- |
+This is the main module of FunGEN (Functional Game Engine), which re-exports the rest.
 -}
 {- 
 
 FunGEN - Functional Game Engine
-http://www.cin.ufpe.br/~haskell/fungen
-Copyright (C) 2002  Andre Furtado <awbf@cin.ufpe.br>
+http://joyful.com/fungen
+Copyright (C)
+2002  Andre Furtado <awbf@cin.ufpe.br>
+2008, 2011-2013 Simon Michael <simon@joyful.com>
 
 This code is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ -13,17 +16,51 @@ -}
 
 module Graphics.UI.Fungen (
-   module Graphics.UI.Fungen.Types,
-   module Graphics.UI.Fungen.Util,
-   module Graphics.UI.Fungen.Loader,
-   module Graphics.UI.Fungen.Objects,
-   module Graphics.UI.Fungen.Map,
-   module Graphics.UI.Fungen.Game,
-   module Graphics.UI.Fungen.Display,
-   module Graphics.UI.Fungen.Input,
-   module Graphics.UI.Fungen.Timer,
-   module Graphics.UI.Fungen.Text,
-   module Graphics.UI.Fungen.Init
+
+  -- * Execution
+  -- | Starting and stopping a game.
+  module Graphics.UI.Fungen.Init,
+
+  -- * Types
+  -- | Some basic types.
+  module Graphics.UI.Fungen.Types,
+
+  -- * Images
+  -- | Loading BMP image files.
+  module Graphics.UI.Fungen.Loader,
+
+  -- * Text
+  -- | Printing text on the screen.
+  module Graphics.UI.Fungen.Text,
+
+  -- * Tile Maps
+  -- | Tile maps (backgrounds).
+  module Graphics.UI.Fungen.Map,
+
+  -- * Objects
+  -- | Game objects (sprites).
+  module Graphics.UI.Fungen.Objects,
+
+  -- * Input
+  -- | User input from mouse and keyboard.
+  module Graphics.UI.Fungen.Input,
+
+  -- * Timing
+  -- | Timing control.
+  module Graphics.UI.Fungen.Timer,
+
+  -- * Game
+  -- | Game management and various game utilities.
+  module Graphics.UI.Fungen.Game,
+
+  -- * Display
+  -- | Rendering the game window.
+  module Graphics.UI.Fungen.Display,
+
+  -- * Util
+  -- | Miscellaneous utilities.
+  module Graphics.UI.Fungen.Util
+
 ) where      
 
 import Graphics.UI.Fungen.Types

@@ -1,3 +1,4 @@+{-# OPTIONS_HADDOCK hide #-}
 {- | This FunGEn module renders the game window.
 -}
 {- 
@@ -21,7 +22,9 @@ import Graphics.Rendering.OpenGL
 import Graphics.UI.GLUT
 
--- | Given a fungen Game and IOGame, generate an opengl display handler.
+-- | Given a fungen Game and IOGame step action, generate a GLUT
+-- display callback that steps the game and renders its resulting
+-- state. 'Graphics.UI.Fungen.funInit' runs this automatically.
 display :: Game t s u v -> IOGame t s u v () -> DisplayCallback
 display g gameCycle = do 
         clear [ColorBuffer]

@@ -1,3 +1,4 @@+{-# OPTIONS_HADDOCK hide #-}
 {- | 
 This FunGEn module contains some important game routines.
 -}
@@ -15,45 +16,57 @@ 
 
 module Graphics.UI.Fungen.Game (
-        Game, IOGame, runIOGame, runIOGameM, liftIOtoIOGame, liftIOtoIOGame',
-        getGameState, setGameState,
-        getGameFlags, setGameFlags,
-        enableGameFlags, disableGameFlags,
-        enableMapDrawing, disableMapDrawing,
-        enableObjectsDrawing, disableObjectsDrawing,
-        enableObjectsMoving, disableObjectsMoving,
-        getObjectManagers, setObjectManagers,
-        getGameAttribute, setGameAttribute,
-        createGame, funExit,
-        drawMap, clearScreen, getTileFromIndex, getTileFromWindowPosition, setCurrentMapIndex,
-        drawAllObjects, drawObject, moveAllObjects, destroyObjects, destroyObject,
-        getObjectsFromGroup, addObjectsToGroup, addObjectsToNewGroup, findObjectManager,findObject,
-        getObjectName, getObjectGroupName, getObjectAsleep, getObjectSize,
-        getObjectPosition, getObjectSpeed, getObjectAttribute,
-        setObjectPosition, setObjectAsleep, setObjectSpeed, setObjectCurrentPicture, setObjectAttribute,
-        replaceObject,
-        reverseXSpeed, reverseYSpeed,
-        objectsCollision, objectsFutureCollision,
-        objectListObjectCollision, objectListObjectFutureCollision,
-        objectTopMapCollision, objectBottomMapCollision, objectRightMapCollision, objectLeftMapCollision,
-        pointsObjectCollision, pointsObjectListCollision,
-        objectTopMapFutureCollision, objectBottomMapFutureCollision, objectRightMapFutureCollision, objectLeftMapFutureCollision,
-        printOnPrompt, printOnScreen, printText, randomFloat, randomInt, randomDouble,
-        showFPS,
-        wait
+  Game, IOGame,
+  -- ** creating
+  createGame, 
+  -- ** IO utilities
+  runIOGame, runIOGameM, liftIOtoIOGame, liftIOtoIOGame',
+  -- ** game state
+  getGameState, setGameState,
+  getGameAttribute, setGameAttribute,
+  -- ** game flags
+  getGameFlags, setGameFlags,
+  enableGameFlags, disableGameFlags,
+  enableMapDrawing, disableMapDrawing,
+  enableObjectsDrawing, disableObjectsDrawing,
+  enableObjectsMoving, disableObjectsMoving,
+  -- ** map operations
+  drawMap, clearScreen, getTileFromIndex, getTileFromWindowPosition, setCurrentMapIndex,
+  -- ** object operations
+  getObjectManagers, setObjectManagers,
+  drawAllObjects, drawObject, moveAllObjects, destroyObjects, destroyObject,
+  getObjectsFromGroup, addObjectsToGroup, addObjectsToNewGroup, findObjectManager,findObject,
+  getObjectName, getObjectGroupName, getObjectAsleep, getObjectSize,
+  getObjectPosition, getObjectSpeed, getObjectAttribute,
+  setObjectPosition, setObjectAsleep, setObjectSpeed, setObjectCurrentPicture, setObjectAttribute,
+  replaceObject,
+  reverseXSpeed, reverseYSpeed,
+  -- ** collision detection
+  objectsCollision, objectsFutureCollision,
+  objectListObjectCollision, objectListObjectFutureCollision,
+  objectTopMapCollision, objectBottomMapCollision, objectRightMapCollision, objectLeftMapCollision,
+  pointsObjectCollision, pointsObjectListCollision,
+  objectTopMapFutureCollision, objectBottomMapFutureCollision, objectRightMapFutureCollision, objectLeftMapFutureCollision,
+  -- ** text operations
+  printOnPrompt, printOnScreen, printText,
+  -- ** random numbers
+  randomFloat, randomInt, randomDouble,
+  -- ** utilities
+  showFPS,
+  wait
 ) where
 
 import Graphics.UI.Fungen.Types
 import Graphics.UI.Fungen.Util
 import Graphics.UI.Fungen.Loader
 import Graphics.UI.Fungen.Text
+import Graphics.UI.Fungen.Timer
 import Graphics.UI.Fungen.Map
 import Graphics.UI.Fungen.Objects
 import Graphics.Rendering.OpenGL
 import Graphics.Rendering.OpenGL.GLU
 import Graphics.UI.GLUT
 import Control.Monad
-import System.Exit
 import Data.IORef
 import Text.Printf
 
@@ -78,8 +91,7 @@ --
 -- * v - /V/icinity (map tile) attribute type.
 -- 
--- A Game consists of the following attributes, accessible via the
--- accessor functions below:
+-- Internally, a Game consists of:
 --
 -- * @gameMap       :: IORef (GameMap v)         -- a map (background)@
 --
@@ -114,12 +126,16 @@ 	fpsInfo       :: IORef (Int,Int,Float)  -- only for debugging
 	}
 
--- | A game action (IOGame) has the type @IOGame t s u v a@, where t, s, u and v
--- are as for Game and a is the type returned by each action of the game
--- (such as the Int for "IO Int").  The name IOGame was chosen to remind
--- that each action deals with a Game, but an IO operation can also be
--- performed between game actions (such as the reading of a file or
--- printing something in the prompt).
+-- | IOGame is the monad in which game actions run. An IOGame action
+-- takes a Game (with type parameters @t s u v@), performs some IO,
+-- and returns an updated Game along with a result value (@a@):
+--
+-- @newtype IOGame t s u v a = IOG (Game  t s u v -> IO (Game t s u v,a))@
+--
+-- The name IOGame was chosen to remind that each action deals with a
+-- Game, but an IO operation can also be performed between game
+-- actions (such as the reading of a file or printing something in the
+-- prompt).
 newtype IOGame t s u v a = IOG (Game  t s u v -> IO (Game t s u v,a))
 
 -- | Game flags: mapDrawing, objectsDrawing, objectsMoving
@@ -250,7 +266,7 @@             fpsInfo 	  = gFPS
             })
 
--- loads all of the pictures used in the game
+-- | loads all of the pictures used in the game
 loadPictures :: [(FilePath,InvList)] -> IO [TextureObject]
 loadPictures pathsAndInvLists = do
         bmps <- loadBitmapList (map pathAndInv2color3List pathsAndInvLists)
@@ -258,17 +274,11 @@         texStuff texBmList bmps
         return texBmList
 
----------------------------------
--- ending the game
----------------------------------
-funExit :: IOGame t s u v ()
-funExit = liftIOtoIOGame' exitWith ExitSuccess
-
 ----------------------------------
 -- map routines
 ----------------------------------
 
--- draws the background map
+-- | draws the background map
 drawMap :: IOGame t s u v ()
 drawMap = do
     m <- getMap
@@ -276,7 +286,7 @@     (_,(winWidth, winHeight),_) <- getWindowConfig
     liftIOtoIOGame $ drawGameMap m (fromIntegral winWidth, fromIntegral winHeight) p
 
--- returns a mapTile, given its pixel position (x,y) in the screen
+-- | returns a mapTile, given its pixel position (x,y) in the screen
 getTileFromWindowPosition :: (GLdouble,GLdouble) -> IOGame t s u v (Tile v)
 getTileFromWindowPosition (preX,preY) = do
        m <- getMap
@@ -290,7 +300,7 @@                         else getTileFromIndex (fromEnum (y/tileXsize),fromEnum (x/tileYsize)) -- (x,y) window orientation is different than index (x,y)!
             else error "Game.getTileFromWindowPosition error: game map is not a tile map!"
 
--- returns a mapTile, given its index (x,y) in the tile map
+-- | returns a mapTile, given its index (x,y) in the tile map
 getTileFromIndex :: (Int,Int) -> IOGame t s u v (Tile v)
 getTileFromIndex (x,y) = do
         m <- getMap
@@ -302,11 +312,11 @@                         else error ("Game.getTileFromIndex error: tile index " ++ (show (x,y)) ++ " out of map range!")
             else error "Game.getTileFromIndex error: game map is not a tile map!"
 
--- paint the whole screen with a specified RGB color
+-- | paint the whole screen with a specified RGB color
 clearScreen :: GLclampf -> GLclampf -> GLclampf -> IOGame t s u v ()
 clearScreen r g b = liftIOtoIOGame $ clearGameScreen r g b
 
--- set the current map for a MultiMap
+-- | set the current map for a MultiMap
 setCurrentMapIndex :: Int -> IOGame t s u v ()
 setCurrentMapIndex i = do
         m <- getRealMap
@@ -358,7 +368,7 @@ -- objects routines
 ----------------------------------
 
--- draws all visible objects
+-- | draws all visible objects
 drawAllObjects :: IOGame t s u v ()
 drawAllObjects = do
     o <- getObjectManagers
@@ -366,26 +376,26 @@     p <- getPictureList
     liftIOtoIOGame $ drawGameObjects o q p
 
--- draw one object
+-- | draw one object
 drawObject :: GameObject s -> IOGame t s u v ()
 drawObject o = do
     q <- getQuadric
     p <- getPictureList
     liftIOtoIOGame $ drawGameObject o q p
 
--- changes objects position according to its speed
+-- | changes objects position according to its speed
 moveAllObjects :: IOGame t s u v ()
 moveAllObjects = do
     m <- getObjectManagers
     let newManagers = moveGameObjects m
     setObjectManagers newManagers
 
--- destroys objects from the game
+-- | destroys objects from the game
 destroyObjects :: [(GameObject s)] -> IOGame t s u v ()
 destroyObjects [] = return ()
 destroyObjects (o:os) = destroyObject o >> destroyObjects os
 
--- destroys an object from the game
+-- | destroys an object from the game
 destroyObject :: GameObject s -> IOGame t s u v ()
 destroyObject obj = do
     m <- getObjectManagers
@@ -394,13 +404,13 @@     let newManagers = destroyGameObject objName mngName m
     setObjectManagers newManagers
 
--- returns the list of all objects from the group whose name is given
+-- | returns the list of all objects from the group whose name is given
 getObjectsFromGroup :: String -> IOGame t s u v [(GameObject s)]
 getObjectsFromGroup mngName = do
         mng <- findObjectManager mngName
         return (getObjectManagerObjects mng)
 
--- adds an object to a previously created group
+-- | adds an object to a previously created group
 addObjectsToGroup :: [(GameObject s)] -> String -> IOGame t s u v ()
 addObjectsToGroup objs managerName = do
 	manager <- findObjectManager managerName
@@ -408,96 +418,96 @@ 	let newManagers = addObjectsToManager objs managerName managers 
 	setObjectManagers newManagers
 
--- adds an object to a new group
+-- | adds an object to a new group
 addObjectsToNewGroup :: [(GameObject s)] -> String -> IOGame t s u v ()
 addObjectsToNewGroup objs newMngName = do
 	let newManager = objectGroup newMngName objs
 	managers <- getObjectManagers
 	setObjectManagers (newManager:managers)
 
--- returns an object manager of the game, given its name (internal use)
+-- | returns an object manager of the game, given its name (internal use)
 findObjectManager :: String -> IOGame t s u v (ObjectManager s)
 findObjectManager mngName = do
     objectManagers <- getObjectManagers
     return (searchObjectManager mngName objectManagers)
     
--- returns an object of the game, given its name and is object manager name
+-- | returns an object of the game, given its name and is object manager name
 findObject :: String -> String -> IOGame t s u v (GameObject s)
 findObject objName mngName = do
     objectManagers <- getObjectManagers
     let m = searchObjectManager mngName objectManagers
     return (searchGameObject objName m)
 
--- there is no need to search through the managers, because the name of an object is
+-- | there is no need to search through the managers, because the name of an object is
 -- never modified so the result of this function will always be safe.
 getObjectName :: GameObject s -> IOGame t s u v String
 getObjectName o = return (getGameObjectName o)
 
--- because an object can have its group (manager) name modified, it is necessary
+-- | because an object can have its group (manager) name modified, it is necessary
 -- to search through the managers to find it, otherwise this functions won't be safe.
 getObjectGroupName :: GameObject s -> IOGame t s u v String
 getObjectGroupName o = do managers <- getObjectManagers
                           let obj = findObjectFromId o managers
                           return (getGameObjectManagerName obj)
 
--- because an object can have its sleeping status modified, it is necessary
+-- | because an object can have its sleeping status modified, it is necessary
 -- to search through the managers to find it, otherwise this functions won't be safe.
 getObjectAsleep :: GameObject s -> IOGame t s u v Bool
 getObjectAsleep o = do managers <- getObjectManagers
                        let obj = findObjectFromId o managers
                        return (getGameObjectAsleep obj)
 
--- because an object can have its size modified, it is necessary
+-- | because an object can have its size modified, it is necessary
 -- to search through the managers to find it, otherwise this functions won't be safe.
 getObjectSize :: GameObject s -> IOGame t s u v (GLdouble,GLdouble)
 getObjectSize o = do managers <- getObjectManagers
                      let obj = findObjectFromId o managers
                      return (getGameObjectSize obj)
 
--- because an object can have its position modified, it is necessary
+-- | because an object can have its position modified, it is necessary
 -- to search through the managers to find it, otherwise this functions won't be safe.
 getObjectPosition :: GameObject s -> IOGame t s u v (GLdouble,GLdouble)
 getObjectPosition o = do managers <- getObjectManagers
                          let obj = findObjectFromId o managers
                          return (getGameObjectPosition obj)
 
--- because an object can have its speed modified, it is necessary
+-- | because an object can have its speed modified, it is necessary
 -- to search through the managers to find it, otherwise this functions won't be safe.
 getObjectSpeed :: GameObject s -> IOGame t s u v (GLdouble,GLdouble)
 getObjectSpeed o = do managers <- getObjectManagers
                       let obj = findObjectFromId o managers
                       return (getGameObjectSpeed obj)
 
--- because an object can have its attribute modified, it is necessary
+-- | because an object can have its attribute modified, it is necessary
 -- to search through the managers to find it, otherwise this functions won't be safe.
 getObjectAttribute :: GameObject s -> IOGame t s u v s
 getObjectAttribute o = do managers <- getObjectManagers
                           let obj = findObjectFromId o managers
                           return (getGameObjectAttribute obj)
 
--- changes the sleeping status of an object, given its new status
+-- | changes the sleeping status of an object, given its new status
 setObjectAsleep :: Bool -> GameObject s -> IOGame t s u v ()
 setObjectAsleep asleep obj = replaceObject obj (updateObjectAsleep asleep)
 
--- changes the position of an object, given its new position
+-- | changes the position of an object, given its new position
 setObjectPosition :: (GLdouble,GLdouble) -> GameObject s -> IOGame t s u v ()
 setObjectPosition pos obj = replaceObject obj (updateObjectPosition pos)
 
--- changes the speed of an object, given its new speed
+-- | changes the speed of an object, given its new speed
 setObjectSpeed :: (GLdouble,GLdouble) -> GameObject s -> IOGame t s u v ()
 setObjectSpeed speed obj = replaceObject obj (updateObjectSpeed speed)
 
--- changes the current picture of a multitextured object
+-- | changes the current picture of a multitextured object
 setObjectCurrentPicture :: Int -> GameObject s -> IOGame t s u v ()
 setObjectCurrentPicture n obj = do
 	picList <- getPictureList
 	replaceObject obj (updateObjectPicture n ((length picList) - 1))
 
--- changes the attribute of an object, given its new attribute
+-- | changes the attribute of an object, given its new attribute
 setObjectAttribute :: s -> GameObject s -> IOGame t s u v ()
 setObjectAttribute a obj = replaceObject obj (updateObjectAttribute a)
 
--- replaces an object by a new one, given the old object and the function that must be applied to it.
+-- | replaces an object by a new one, given the old object and the function that must be applied to it.
 replaceObject :: GameObject s -> (GameObject s -> GameObject s) -> IOGame t s u v ()
 replaceObject obj f = do
     managerName <- getObjectGroupName obj
@@ -518,7 +528,7 @@ -- collision routines
 -----------------------
 
--- checks the collision between an object and the top of the map
+-- | checks the collision between an object and the top of the map
 objectTopMapCollision :: GameObject s -> IOGame t s u v Bool
 objectTopMapCollision o = do
     asleep <- getObjectAsleep o
@@ -530,7 +540,7 @@                 let (_,mY) = getMapSize m
                 return (pY + (sY/2) > (realToFrac mY))
 
--- checks the collision between an object and the top of the map in the next game cicle
+-- | checks the collision between an object and the top of the map in the next game cicle
 objectTopMapFutureCollision :: GameObject s -> IOGame t s u v Bool
 objectTopMapFutureCollision o = do
     asleep <- getObjectAsleep o
@@ -543,7 +553,7 @@                 let (_,mY) = getMapSize m
                 return (pY + (sY/2) + vY > (realToFrac mY))
 
--- checks the collision between an object and the bottom of the map
+-- | checks the collision between an object and the bottom of the map
 objectBottomMapCollision :: GameObject s -> IOGame t s u v Bool
 objectBottomMapCollision o = do
     asleep <- getObjectAsleep o
@@ -553,7 +563,7 @@                 (_,sY) <- getObjectSize o
                 return (pY - (sY/2) < 0)
 
--- checks the collision between an object and the bottom of the map in the next game cicle
+-- | checks the collision between an object and the bottom of the map in the next game cicle
 objectBottomMapFutureCollision :: GameObject s -> IOGame t s u v Bool
 objectBottomMapFutureCollision o = do
     asleep <- getObjectAsleep o
@@ -564,7 +574,7 @@                 (_,vY) <- getObjectSpeed o
                 return (pY - (sY/2) + vY < 0)
 
--- checks the collision between an object and the right side of the map
+-- | checks the collision between an object and the right side of the map
 objectRightMapCollision :: GameObject s -> IOGame t s u v Bool
 objectRightMapCollision o = do
     asleep <- getObjectAsleep o
@@ -576,7 +586,7 @@                 let (mX,_) = getMapSize m
                 return (pX + (sX/2) > (realToFrac mX))
 
--- checks the collision between an object and the right side of the map in the next game cicle
+-- | checks the collision between an object and the right side of the map in the next game cicle
 objectRightMapFutureCollision :: GameObject s -> IOGame t s u v Bool
 objectRightMapFutureCollision o = do
     asleep <- getObjectAsleep o
@@ -589,7 +599,7 @@                 let (mX,_) = getMapSize m
                 return (pX + (sX/2) + vX > (realToFrac mX))
 
--- checks the collision between an object and the left side of the map
+-- | checks the collision between an object and the left side of the map
 objectLeftMapCollision :: GameObject s -> IOGame t s u v Bool
 objectLeftMapCollision o = do
     asleep <- getObjectAsleep o
@@ -599,7 +609,7 @@                 (sX,_) <- getObjectSize o
                 return (pX - (sX/2) < 0)
 
--- checks the collision between an object and the left side of the map in the next game cicle
+-- | checks the collision between an object and the left side of the map in the next game cicle
 objectLeftMapFutureCollision :: GameObject s -> IOGame t s u v Bool
 objectLeftMapFutureCollision o = do
     asleep <- getObjectAsleep o
@@ -610,7 +620,7 @@                 (vX,_) <- getObjectSpeed o
                 return (pX - (sX/2) + vX < 0)
 
--- checks the collision between two objects
+-- | checks the collision between two objects
 objectsCollision :: GameObject s -> GameObject s -> IOGame t s u v Bool
 objectsCollision o1 o2 = do
     asleep1 <- getObjectAsleep o1
@@ -634,7 +644,7 @@                               
                          return ((bX1 < aX2) && (aX1 < bX2) && (bY1 < aY2) && (aY1 < bY2))
 
--- checks the collision between two objects in the next game cicle
+-- | checks the collision between two objects in the next game cicle
 objectsFutureCollision :: GameObject s -> GameObject s -> IOGame t s u v Bool
 objectsFutureCollision o1 o2 = do
     asleep1 <- getObjectAsleep o1
@@ -705,17 +715,17 @@ -----------------------------------------------
 --              TEXT ROUTINES                --
 -----------------------------------------------
--- prints a string in the prompt
+-- | prints a string in the prompt
 printOnPrompt :: Show a => a -> IOGame t s u v ()
 printOnPrompt a = liftIOtoIOGame' print a
 
--- prints a string in the current window
+-- | prints a string in the current window
 printOnScreen :: String -> BitmapFont -> (GLdouble,GLdouble) -> GLclampf -> GLclampf -> GLclampf -> IOGame t s u v ()
 printOnScreen text font pos r g b = do
         t <- getTextList
         setTextList ([(text,font,pos,r,g,b)] ++ t)
 
--- internal use of the engine
+-- | internal use of the engine
 printText :: IOGame t s u v ()
 printText = do
         t <- getTextList
@@ -738,7 +748,7 @@ --           DEBUGGING ROUTINES              --
 -----------------------------------------------
 
--- shows the frame rate (or frame per seconds) 
+-- | shows the frame rate (or frame per seconds) 
 showFPS :: BitmapFont -> (GLdouble,GLdouble) -> GLclampf -> GLclampf -> GLclampf -> IOGame t s u v ()
 showFPS font pos r g b = do
 	(framei,timebasei,fps) <- getFpsInfo
@@ -751,10 +761,11 @@ 		else setFpsInfo ((framei + 1),timebasei,fps)
 	printOnScreen (printf "%.1f" fps) font pos r g b
 
--- get the elapsed time of the game
+-- | get the elapsed time of the game
 getElapsedTime :: IOGame t s u v Int
 getElapsedTime = liftIOtoIOGame $ get elapsedTime
 
+-- | delay for N  seconds while continuing essential game functions
 wait :: Int -> IOGame t s u v ()
 wait delay = do
 	printText 				    -- force text messages to be printed (is not working properly!)

@@ -1,3 +1,4 @@+{-# OPTIONS_HADDOCK hide #-}
 {- | 
 This FunGEn module contains the initialization procedures.
 -}
@@ -15,6 +16,7 @@ 
 module Graphics.UI.Fungen.Init (
         funInit
+        ,funExit
 )where
 
 import Graphics.UI.Fungen.Types
@@ -27,8 +29,19 @@ import Graphics.UI.Fungen.Timer
 import Graphics.Rendering.OpenGL
 import Graphics.UI.GLUT
+import System.Exit
 
-funInit :: WindowConfig -> GameMap v -> [(ObjectManager s)] -> u -> t -> [InputBinding t s u v] -> IOGame t s u v () -> RefreshType -> FilePictureList -> IO ()
+-- | Build a FunGEn game and start it running.
+funInit :: WindowConfig           -- ^ main window config
+        -> GameMap v              -- ^ background tile map
+        -> [(ObjectManager s)]    -- ^ object (sprite) groups
+        -> u                      -- ^ initial game state
+        -> t                      -- ^ initial game attribute
+        -> [InputBinding t s u v] -- ^ input bindings
+        -> IOGame t s u v ()      -- ^ step action
+        -> RefreshType            -- ^ timing type
+        -> FilePictureList        -- ^ image files to load
+        -> IO ()
 funInit winConfig@((px,py),(sx,sy),t) userMap objectGroups gState gAttrib i gameCicle r picList = do
         initialize "FunGen app" []
         createWindow t -- (return ()) [ Double, RGBA ]
@@ -52,4 +65,9 @@         loadIdentity
         ortho 0.0 (fromIntegral sx) 0.0 (fromIntegral sy) (-1.0) 1.0
         matrixMode $= Modelview 0
-        loadIdentity+        loadIdentity
+
+-- | Exit the program successfully.
+funExit :: IOGame t s u v ()
+funExit = liftIOtoIOGame' exitWith ExitSuccess
+

@@ -1,3 +1,4 @@+{-# OPTIONS_HADDOCK hide #-}
 {- | 
 This FunGEn module controls the user input (mouse, keyboard, joystick...)
 -}
@@ -15,7 +16,7 @@ 
 module Graphics.UI.Fungen.Input (
         InputBinding, InputHandler,
-        Key(..), KeyEvent(..), SpecialKey(..), MouseButton(..), Modifiers(..), Position(..),
+        KeyEvent(..), Key(..), SpecialKey(..), MouseButton(..), Modifiers(..), Position(..),
         funBinding
 ) where
 
@@ -23,10 +24,10 @@ import Graphics.UI.GLUT
 import Graphics.UI.GLUT.Input (KeyEvent(..), KeyBinder, StillDownHandler, initGLUTInput)
 
--- | A FunGEn input handler (which we use instead of GLUTInput's) is
--- an IOGame (game action) that takes two extra arguments: the current
--- keyboard modifiers state, and the current mouse position. (For a StillDown
--- event, these will be the original state and position from the Press event.)
+-- | A FunGEn input handler is like an IOGame (game action) that takes
+-- two extra arguments: the current keyboard modifiers state, and the
+-- current mouse position. (For a StillDown event, these will be the
+-- original state and position from the Press event.)
 type InputHandler t s u v = Modifiers -> Position -> IOGame t s u v ()
 
 -- | A mapping from an input event to an input handler.

@@ -1,3 +1,4 @@+{-# OPTIONS_HADDOCK hide #-}
 {- | 
 This FunGEn module loads [bmp] files.
 -}
@@ -15,7 +16,7 @@ 
 module Graphics.UI.Fungen.Loader (
         loadBitmap, loadBitmapList, FilePictureList
-)where
+) where
 
 import Graphics.Rendering.OpenGL
 import System.IO
@@ -30,7 +31,7 @@ type BmpList = [(GLubyte, GLubyte, GLubyte, GLubyte)]
 type FilePictureList = [(FilePath,InvList)]
 
---loads a bitmap from a file
+-- | Loads a bitmap from a file.
 loadBitmap :: FilePath -> Maybe ColorList3 -> IO AwbfBitmap
 loadBitmap bmName invList = do
         bmFile <- openBinaryFile bmName (ReadMode)
@@ -40,7 +41,7 @@         hClose bmFile
         return (bmW,bmH,bmData)
 
- -- loads n bitmaps from n files        
+-- | Loads n bitmaps from n files.
 loadBitmapList :: [(FilePath, Maybe ColorList3)] -> IO [AwbfBitmap]
 loadBitmapList bmps = do
         bmList <- loadBmListAux bmps []

@@ -1,3 +1,4 @@+{-# OPTIONS_HADDOCK hide #-}
 {- | 
 This FunGEn module contains the map (game background) routines.
 -}
@@ -14,15 +15,18 @@ -}
 
 module Graphics.UI.Fungen.Map (
-        GameMap,
-        Tile, TileMatrix,
-        getTilePictureIndex, getTileBlocked, getTileMoveCost, getTileSpecialAttribute,
-        colorMap, textureMap, tileMap, multiMap,
-        getMapSize,
-        isTileMap, getTileMapTileMatrix, getTileMapScroll, getTileMapSize, getTileMapTileSize,
-        getCurrentMap, updateCurrentMap, updateCurrentIndex, isMultiMap,
-        drawGameMap, clearGameScreen
-)where
+  GameMap, Tile, TileMatrix,
+  -- ** creating
+  colorMap, textureMap, tileMap, multiMap,
+  -- ** map attributes
+  isTileMap, isMultiMap, getMapSize, getTileMapTileMatrix, getTileMapScroll, getTileMapSize, getTileMapTileSize,
+  -- ** map tiles
+  getTilePictureIndex, getTileBlocked, getTileMoveCost, getTileSpecialAttribute,
+  -- ** setting the current map
+  getCurrentMap, updateCurrentMap, updateCurrentIndex,
+  -- ** drawing
+  drawGameMap, clearGameScreen,
+) where
 
 import Graphics.UI.Fungen.Types
 import Graphics.UI.Fungen.Util
@@ -46,7 +50,7 @@ getMapSize (MultiMap _ _) = error "Map.getMapSize error: getMapSize cannot be applied with MultiMaps!"
 
 ----------------------------
--- special TileMap routines
+-- * special TileMap routines
 ----------------------------
 
 isTileMap ::  GameMap t -> Bool
@@ -71,7 +75,7 @@ 
 
 ------------------------------
--- get routines for a Tile
+-- * get routines for a Tile
 ------------------------------
 
 getTilePictureIndex :: Tile t -> Int
@@ -88,7 +92,7 @@ 
 
 -------------------------------
--- get routines for a MultiMap
+-- * get routines for a MultiMap
 -------------------------------
 
 getCurrentMap :: GameMap t -> GameMap t
@@ -115,25 +119,25 @@ updateCurrentIndex _ _ = error "Map.updateCurrentIndex error: the game map is not a MultiMap!"
 
 -----------------------------
--- creation of maps
+-- * creation of maps
 -----------------------------
 
--- creates a PreColorMap
+-- | creates a PreColorMap
 colorMap :: GLclampf -> GLclampf -> GLclampf -> GLdouble -> GLdouble -> GameMap t
 colorMap r g b sX sY = ColorMap (Color4 r g b 1.0) (sX,sY)
 
--- creates a PreTextureMap
+-- | creates a PreTextureMap
 textureMap :: Int -> GLdouble -> GLdouble -> GLdouble -> GLdouble -> GameMap t
 textureMap texId tX tY sX sY = TextureMap texId (tX,tY) (0,0) (0,0) (sX,sY)
 
--- creates a PreTileMap, cheking if the tileMatrix given is valid and automatically defining the map size
+-- | creates a PreTileMap, cheking if the tileMatrix given is valid and automatically defining the map size
 tileMap :: TileMatrix t -> GLdouble -> GLdouble -> GameMap t
 tileMap matrix tX tY | matrixOk matrix = TileMap matrix (tX,tY) (0,0) (0,0) (sX,sY)
                      | otherwise = error "Map.tileMap error: each line of your TileMap must have the same number of tiles!"
                    where sX = ((fromIntegral.length.head) matrix) * tX
                          sY = ((fromIntegral.length) matrix) * tY
 
--- creates a multimap
+-- | creates a multimap
 multiMap :: [(GameMap t)] -> Int -> GameMap t
 multiMap [] _ = error "Map.multiMap  error: the MultiMap map list should not be empty!"
 multiMap mapList currentMap | (currentMap >= (length mapList)) = error "Map.multiMap error: map index out of range!"
@@ -146,7 +150,7 @@ mapListContainsMultiMap (a:as) | (isMultiMap a) = True
 			       | otherwise = mapListContainsMultiMap as
 
--- cheks if the tile matrix is a square matrix
+-- checks if the tile matrix is a square matrix
 matrixOk :: TileMatrix t -> Bool
 matrixOk [] = False
 matrixOk (m:ms) = matrixOkAux (length m) ms
@@ -158,14 +162,16 @@ 
 
 ----------------------------------------
---       MAP DRAWING ROUTINES         --
+-- * map drawing
 ----------------------------------------
+
+-- | clear the screen
 clearGameScreen :: GLclampf -> GLclampf -> GLclampf -> IO ()
 clearGameScreen r g b = do
         clearColor $= (Color4 r g b 1.0)
         clear [ColorBuffer]
 
--- draws the background map
+-- | draw the background map
 drawGameMap :: GameMap t -> Point2D -> [TextureObject] -> IO ()
 drawGameMap (ColorMap c _) _ _ = do
         clearColor $= c

@@ -1,3 +1,4 @@+{-# OPTIONS_HADDOCK hide #-}
 {- | 
 This module contains the FunGEn objects procedures
 -}
@@ -13,19 +14,29 @@ -}
 
 module Graphics.UI.Fungen.Objects (
-    GameObject,
-    getGameObjectId, getGameObjectName, getGameObjectManagerName, getGameObjectAsleep, getGameObjectPosition, getGameObjectSize, getGameObjectSpeed, getGameObjectAttribute,
-    getObjectManagerName, getObjectManagerCounter , getObjectManagerObjects,
-    ObjectPicture(..), Primitive(..),
-    FillMode (..),
-    object, drawGameObjects, drawGameObject,
-    objectGroup, ObjectManager,
-    findObjectFromId, searchObjectManager, searchGameObject,
-    updateObject, updateObjectAsleep, updateObjectSize, updateObjectPosition,
-    updateObjectSpeed, updateObjectAttribute, updateObjectPicture,
-    addObjectsToManager,
-    moveGameObjects,
-    destroyGameObject
+  ObjectManager,
+  GameObject,
+  ObjectPicture(..), Primitive(..),
+  FillMode (..),
+  -- ** creating
+  object,
+  -- ** object attributes
+  getGameObjectId, getGameObjectName, getGameObjectManagerName, getGameObjectAsleep,
+  getGameObjectPosition, getGameObjectSize, getGameObjectSpeed, getGameObjectAttribute,
+  -- ** updating
+  updateObject, updateObjectAsleep, updateObjectSize, updateObjectPosition,
+  updateObjectSpeed, updateObjectAttribute, updateObjectPicture,
+  -- ** drawing
+  drawGameObjects, drawGameObject,
+  -- ** moving
+  moveGameObjects,
+  -- ** destroying
+  destroyGameObject,
+  -- ** groups of objects
+  objectGroup, addObjectsToManager,
+  getObjectManagerName, getObjectManagerCounter , getObjectManagerObjects,
+  -- ** searching
+  findObjectFromId, searchObjectManager, searchGameObject,
 ) where
 
 import Graphics.UI.Fungen.Types

@@ -1,3 +1,4 @@+{-# OPTIONS_HADDOCK hide #-}
 {- | 
 This FunGEn module contains some functions to print text on the screen.
 Fonts supported: Bitmap9By15, Bitmap8By13, BitmapTimesRoman10, BitmapTimesRoman24
@@ -16,17 +17,19 @@ -}
 
 module Graphics.UI.Fungen.Text (
-	Text,
 	BitmapFont(..),
+	Text,
 	putGameText
 ) where
 
 import Graphics.UI.GLUT
+import Graphics.UI.Fungen.Types
 import Graphics.Rendering.OpenGL
 
-type Text = (String,BitmapFont,(GLdouble,GLdouble),GLclampf,GLclampf,GLclampf)
+-- | String to be printed, font, screen position, color RGB.
+type Text = (String,BitmapFont,Point2D,GLclampf,GLclampf,GLclampf)
 
--- string to be printed, type of font, screen position, color RGB
+-- | Display these texts on screen.
 putGameText :: [Text] -> IO ()
 putGameText [] = return ()
 putGameText ((text,font,(x,y),r,g,b):ts) = do

@@ -1,3 +1,4 @@+{-# OPTIONS_HADDOCK hide #-}
 {- | 
 This FunGEn module controls timing (how time-based functions will behave).
 -}
@@ -21,14 +22,17 @@ import Graphics.UI.GLUT
 import Graphics.UI.GLUT.Input
 
+-- | Used by 'Graphics.UI.Fungen.funInit' to configure the main loop's timing strategy.
 data RefreshType
         = Idle
         | Timer Int
 
+-- | Change the current timing strategy.
 setRefresh :: RefreshType -> StillDownHandler -> IO ()
 setRefresh Idle stillDown = idleCallback $= Just (stillDown >> postRedisplay Nothing)
 setRefresh (Timer t) stillDown = addTimerCallback t (timer stillDown t)
 
+-- | Generate a GLUT timer callback.
 timer :: StillDownHandler -> Int -> TimerCallback
 timer stillDown t = do
         stillDown

@@ -1,3 +1,4 @@+{-# OPTIONS_HADDOCK hide #-}
 {- | This FunGEn module contains the FunGEN basic types. 
 -}
 {- 

@@ -1,3 +1,4 @@+{-# OPTIONS_HADDOCK hide #-}
 {- | 
 This FunGEn module contains some auxiliary functions.
 -}
@@ -99,7 +100,7 @@ dropGLsizei n (_:xs) | n>0  = dropGLsizei (n-1) xs
 dropGLsizei _ _ = error "Util.dropGLsizei error: negative argument"
 
--- to be used when no invisibility must be added when loading a file
+-- | to be used when no invisibility must be added when loading a file
 addNoInvisibility :: [FilePath] -> [(FilePath, Maybe ColorList3)]
 addNoInvisibility [] = []
 addNoInvisibility (a:as) = (a, Nothing):(addNoInvisibility as)
@@ -120,7 +121,7 @@ matrixToList [] = []
 matrixToList (a:as) = a ++ (matrixToList as)
 
--- return the max indexes of a matrix (assumed that its lines have the same length)
+-- | return the max indexes of a matrix (assumed that its lines have the same length)
 matrixSize ::  [[a]] -> (Int,Int)
 matrixSize [] = (0,0)
 matrixSize m@(a:_) = ((length m) - 1,(length a) - 1)

@@ -1,3 +1,4 @@+-- {-# OPTIONS_HADDOCK hide #-}
 {- |
 GLUT-based keyboard/mouse handling.
 

@@ -71,6 +71,10 @@  ## Release notes +### 0.4.1 (2013/08/06)++* reorganised and exposed more haddocks+ ### 0.4 (2013/08/05)  * a new hakyll-based website, incorporating the old site