--------------------------------------------------------------------------------
-- |
-- Module      :  Terminal.Game
-- Copyright   :  © 2017-2019 Francesco Ariis
-- License     :  GPLv3 (see LICENSE file)
--
-- Maintainer  :  Francesco Ariis <fa-ml@ariis.it>
-- Stability   :  provisional
-- Portability :  portable
--
-- Machinery and utilities for 2D terminal games.
--
-- New? Start from 'Game'.
--
--------------------------------------------------------------------------------

-- Basic col-on-black ASCII terminal, operations.
-- Only module to be imported.

-- todo test that handlers are closed in case of errr [test]

-- xxx timer in contrib o altro modulo?
-- xxx qptain e jimreed, implement normal movement

module Terminal.Game ( -- * Running
                       FPS,
                       Event(..),
                       Game(..),
                       playGame,

                       -- * Game Logic
                       -- | Some convenient function dealing with
                       -- Timers ('Timed') and 'Animation's.
                       --
                       -- Usage of these is not mandatry: 'Game' is
                       -- parametrised over any state @s@, you are free
                       -- to implement game logic as you prefer.

                       -- ** Timers
                       Timed,
                       creaTimer, creaBoolTimer,
                       creaTimerLoop, creaBoolTimerLoop,
                       fetchFrame, isExpired,

                       -- ** Animations
                       Animation,
                       -- xxx elimina animation?
                       -- xxx o di certo Loop e ExpBehaviour
                       Loop(..), ExpBehaviour(..),
                       creaAnimation,
                       tick, reset,
                       fetchAniFrame, isAniExpired,
                       getFrames,

                       -- * Drawing
                       -- | To get to the gist of drawing, check the
                       -- documentation of '%'.

                       -- ** Plane
                       Plane,
                       Coords,
                       Row, Column,
                       Width, Height,
                       blankPlane,
                       stringPlane,
                       stringPlaneTrans,
                       makeTransparent,
                       makeOpaque,
                       paperPlane,
                       planeSize,

                       -- ** Draw
                       Draw,
                       (%), (#), (&),
                       mergePlanes,
                       cell, box, textBox,
                       Color(..), ColorIntensity(..),
                       color, bold, invert,

                       -- * Testing
                       testGame,
                       setupGame,
                       recordGame,
                       readRecord,
                       narrateGame,
                       errorPress

                       -- * Cross platform
                       -- $threaded
                     )
    where

import System.Console.ANSI
import Terminal.Game.Layer.Imperative
import Terminal.Game.Layer.Object
import Terminal.Game.Plane
import Terminal.Game.Draw
import Terminal.Game.Animation

-- $threaded
-- Good practices for cross-compatibility:
--
-- * choose game dimensions of no more than __24 rows__ and __80 columns__.
--   This ensures compatibility with the trickiest terminals (i.e. Win32
--   console);
--
-- * use __ASCII characters__ only. Again this is for Win32 console
--   compatibility, until
--   [this GHC bug](https://gitlab.haskell.org/ghc/ghc/issues/7593) gets
--   fixed;
--
-- * employ colour sparingly: as some users will play your game in a
--   light-background terminal and some in a dark one, choose only colours
--   that go well with either (blue, red, etc.);
--
-- * some terminals/multiplexers (i.e. tmux) do not make a distinction
--   between vivid/dull, do not base your game mechanics on that
--   difference.