Merge pull request #15 from keera-studios/zuriHac2018

Merging and readjustment of repo after ZuriHac2018

Author: chriz-zeller

README.md

@@ -15,6 +15,6 @@ or select a section below:
 * [Books](http://github.com/keera-studios/haskell-game-programming/wiki/Books)
 
 
-Please, donate to this project using flatter: [![Flattr this awesome project](http://api.flattr.com/button/flattr-badge-large.png)](https://flattr.com/submit/auto?user_id=ivanperez-keera&url=https://github.com/keera-studios/haskell-game-programming&title=HaskellGameProgramming&language=&tags=github&category=software) 
+Please, donate to this project using flatter: [![Flattr this awesome project](http://api.flattr.com/button/flattr-badge-large.png)](https://flattr.com/submit/auto?user_id=ivanperez-keera&url=https://github.com/keera-studios/haskell-game-programming&title=HaskellGameProgramming&language=&tags=github&category=software)
 
 If you would like to use another donation method, please get in touch with Keera Studios.

examples/board-game-scaffold/ChangeLog.md

@@ -0,0 +1,5 @@
+# Revision history for keera-board-game-scaffold
+
+## 0.1.0.0  -- 2018-06-04
+
+* First version. Released on an unsuspecting world.

examples/board-game-scaffold/LICENSE

@@ -0,0 +1,70 @@
+# keera-board-game-scaffold
+
+This is a Haskell board game scaffold.
+
+Table of Contents:
+  * [Installation](#installation)
+  * [Documentation](#documentation)
+  * [Related projects](#related-projects)
+  * [Curious?](#curious)
+
+## Installation
+
+For installing the game you need the following packages:
+   * [GHC](https://www.haskell.org/ghc/)
+   * [command-line interface for cabal](https://github.com/haskell/cabal/tree/master/cabal-install)
+   * SDL2, SDL2-gfx
+
+On debian/ubuntu, you can install them with:
+
+   ```
+   $ sudo apt-get install ghc cabal-install
+   $ sudo apt-get install libsdl2-dev libsdl2-gfx-dev
+   ```
+I recommend using a [cabal sandbox](https://www.haskell.org/cabal/users-guide/installing-packages.html#developing-with-sandboxes) for installing the game.
+
+Here are the instructions:
+
+```
+$ git clone https://github.com/keera-studios/haskell-game-programming
+$ cd examples/game-board-scaffold
+$ cabal update
+$ cabal sandbox init
+$ cabal install --only-dependencies
+$ cabal run
+```
+
+If any of these instructions do not work for you, please let me know via [issue](https://github.com/keera-studios/haskell-game-programming/issues) or [mail](chriz@keera.co.uk).
+
+## Documentation
+
+To try and make things as clear as possible, the code includes as much haddock
+documentation and comments as we could reasonably fit. You can compile
+those with:
+
+```
+$ git clone https://github.com/keera-studios/haskell-game-programming
+$ cd examples/game-board-scaffold
+$ cabal update
+$ cabal sandbox init
+$ cabal install --only-dependencies
+$ cabal configure && cabal haddock --executables --internal
+```
+
+## Related projects
+  * [Magic Cookies](https://github.com/keera-studios/magic-cookies), a commercial FRP game written in Haskell using Yampa that's available on iTunes and Google Play.
+  * [Haskanoid](https://github.com/ivanperez-haskell/haskanoid) a Haskell breakout game implemented using the Functional Reactive Programming library Yampa.
+  * [Pang a Lambda](https://github.com/keera-studios/games-pang-a-lambda) a Haskell game implemented using the Functional Reactive Programming library Yampa.
+
+## Curious?
+
+It seems that I catched your attention. If so let's get in contact ([issue](https://github.com/keera-studios/haskell-game-programming/issues) or [mail](chriz@keera.co.uk))! Some (but none exclusive) examples: Are you interested in ...
+  * ... improving this game? Like:
+    * Improving the documentation.
+    * Improving the code.
+    * Adding new features.
+    * ... ?
+  * ... using this Haskell game for educational or other purposes?
+  * ... letting me know what you think about this Haskell game?
+  * ... writing your own Haskell game?
+  * ...?

examples/board-game-scaffold/README.md

@@ -0,0 +1,2 @@
+import Distribution.Simple
+main = defaultMain

examples/board-game-scaffold/Setup.hs

@@ -0,0 +1,112 @@
+# Introduction to the Basic Game Structure Used by Keera Studios Ltd
+Work in progress by Christina Zeller
+
+## Goal of this document:
+- We (Keera Studios) want to introduce (parts of) our recent basic game structure.
+- Using this basic game structure as a skeleton in mind shall help you to easier and faster find your way in our games.
+- Besides, if you are developing your own games, it might help you to structure your games.
+
+## Reading advices and content of this document:
+- [Warning](#warning)
+  - Obviously everybody should read warnings.
+    Here you find some limitations of the document.
+- [Game Structure](#game-structure---the-modules)
+  - If you want to know about our game structure, this is the place to look.
+- [Why is a basic game structure helpful?](#why-is-a-basic-game-structure-helpful)
+  - If you wonder whether you should know something about game structures, here you find some reasons why we think it is helpful.
+- [Curious?](#curious)
+  - If you want to get involved or use our material, take a look at this section.
+
+## Warning
+- This document describes parts of a theoretical (ideal) game structure. We are working hard to reach it, however sometimes reality clashes with theory. Our solution is either to work harder to get closer to the ideal or sometimes we are figuring out that our ideal is not ideal and we adapt the game structure.
+- So don't be surprised if not all our games show the complete basic game structure or if in the future we change our mind and state another. That's called development.
+
+## Game Structure - The Modules
+- Basically all our games have the following modules.
+- However, sometimes module names vary slightly. That's because we haven't found a consent regarding several names yet. Hopefully, this will become more stable someday in the near future.
+- Therefore, if you have any suggestions to improve names or the structure, let us know!
+
+```
+  Game
+      ----> Main
+      ----> Constants
+      ----> UserInput
+      ----> DeviceOutput
+      ----> InputOutputMatcher
+      ----> Play
+      ----> State
+      ----> Objects
+      ----> Levels
+```
+
+```
+-------------------------------------------------------------------------------
+
+                                                     Constants
+Main
+  |
+  |___ init:
+  |     UserInput
+  |     DeviceOutput
+  |
+  |___ game loop:
+       sense         (UserInput)    ---\  Input      / State (of Game)
+       process input (Play) ------------> Output--->   Levels
+       create output (DeviceOutput) ---/  Matcher    \ Objects
+
+-------------------------------------------------------------------------------
+```
+
+### Main.hs
+- Catch and print exceptions.
+- Create handler for initializing input and output and allocate resources.
+- Start the game loop. That is, sense input, process input, create output.
+
+### Constants
+Define magic numbers at one place with one name.
+
+### DeviceOutput.hs
+Handle output related  aspects, that is
+ - Initialize device output related aspects like a rendering context, runtime context, window and sound.
+ - Render (visual and audio).
+
+### UserInput.hs
+Provide controller for storing and recognizing user input.
+
+### InputOutputMatcher
+Match the user input with the displayed screen.
+
+### State.hs
+Provide the structure for game states.
+
+###  Play.hs
+Provide the game logic/flow.
+
+###  Objects.hs
+All objects of the game with specific properties and functions.
+
+###  Levels.hs
+Define every level with its characteristics.
+
+## Why is a basic game structure helpful?
+- The game structure helps to find your way in our games even if you are not familiar with the implementation details.
+- If you handle many games you can change things in all games at the same time.
+- Skeletons reduce needed brain capacity for maintenance.
+  - It helps you to start to write your first game.
+  - You can reuse code or outsource parts that are always handled in the same way.
+  - Once well known, you can focus on the game specific parts not on the technical and maybe boring parts that need to be done in every game.
+- Introducing new features will hopefully result in only minor changes of your game structure.
+- ...
+
+## Curious?
+
+It seems that I caught your attention. If so let's get in contact ([issue](https://github.com/keera-studios/haskell-game-programming/issues) or [mail](chriz@keera.co.uk))! Some (but none exclusive) examples: Are you interested in ...
+  * ... improving this document? Like:
+    * Improving spelling and grammar.
+    * Improving the comprehensibility of the document.
+    * Improving the structure of the document.
+    * ... ?
+  * ... using this source for educational or other purpose?
+  * ... letting me know what you think about this document?
+  * ... writing your own Haskell game?
+  * ...?

examples/board-game-scaffold/docs/game-structure.md

@@ -0,0 +1,174 @@
+# ZuriHac 2018 --- Game Programming --- Some Tasks
+by Christina Zeller
+
+- This document gives an unsorted overview of suggested tasks in Haskell game programming.
+- The unsorted tasks vary in complexity. Don't get (too) frustrated but ask me for hints.
+
+Table of Contents:
+  * [Hands on tasks (playing with the code)](#hands-on-tasks-playing-with-the-code)
+  * [Hands on tasks (createing a board game)](#hands-on-tasks-creating-a-board-game)
+  * [Exploring the game structure](#exploring-the-game-structure)
+  * [Haskanoid: SDL FRP (Yampa) Wiimote](#haskanoid-sdl1-sdl2-frp-yampa-wiimote)
+  * [Confused?](#confused)
+
+## Hands on tasks (playing with the [code](https://github.com/keera-studios/haskell-game-programming/tree/zuriHac2018/examples/board-game-scaffold/src))
+### Constants
+- Change the title of the window.
+- Change the default screen size.
+- Change the screen margin.
+### Levels
+- Change the background colour.
+- Change the fields colour.
+- Change the number of fields of a grid.
+- Change the shape of the grid.
+- Add a new level.
+- Add a level solved definition for each level.
+- Add a maximal number of moves in a level.
+### GameState
+- Add a field to count moves.
+- Add a pause game state.
+### DeviceOutput
+- Do not render/display empty fields.
+- Do render/display empty fields as small filled pies or ellipses.
+- Draw fields as triangles.
+- Add rendering/displaying of a level solved status.
+- Add rendering/displaying of a paused game status.
+- Add a button (rectangle, circle, ...) next to the game board.
+- Add the level number next to the game board.
+- Render images/assets instead of circles/triangles/rectangles ([one source of free assets](http://www.kenney.nl/)).
+- Add audio.
+### UserInput
+- Close the window if the close button of a window was clicked.
+- Handle/Store a keyboard pressed key 'P' event.
+### InputOutputMatch
+- Add a function to check whether the background was clicked.
+- Add a function to check whether a specific area was clicked (e.g., a restart button).
+### Objects
+- Add a new field kind.
+### GameLogic
+- Change the allowed moves.
+- Change the result of a move.
+- Count the number of moves.
+- Restart the level if the background or a button on the screen was clicked.
+- Add a level solved behaviour.
+- Add a pause game behaviour.
+- React on a keyboard pressed key 'P' event with changing to the paused game status.
+
+## Hands on tasks (creating a board game)
+- Reimplement an existing board game (4 in a line, solitaire, find the pairs, Mensch \"argere dich nicht, ...).
+- Create your own board game (maybe using the [board game scaffold](https://github.com/keera-studios/haskell-game-programming/tree/zuriHac2018/examples/board-game-scaffold)) with your own logic and rules.
+
+## Exploring the game structure
+- Create the haddock documentation (see [README](https://github.com/keera-studios/haskell-game-programming/blob/zuriHac2018/examples/board-game-scaffold/README.md)) and get an overview of the game.
+- Where do you expect:
+  - The handling of mouse and key board events?
+  - The definition of the game board and its elements in general?
+  - The definition of a solved game board?
+  - The handling of the game flow?
+  - The rendering of a game board?
+  - The background colour?
+  - The colour of fields of the board?
+  - The logical board size?
+  - The board size used for rendering?
+  - The definition of a valid move?
+  - The result of a move?
+  - The detection of clicked fields?
+- Read about our [basic game structure](https://github.com/keera-studios/haskell-game-programming/blob/zuriHac2018/examples/board-game-scaffold/docs/game-structure.md). Why you should read it? The document will tell you.
+- Take a look at the following import examples. Can you associate them with the specific modules of the [game](https://github.com/keera-studios/haskell-game-programming/tree/zuriHac2018/examples/board-game-scaffold/src)?
+  - Example 1:
+
+```haskell
+-- External imports
+import           Control.Monad   (void)
+import           Data.Int        (Int16, Int32)
+import           Data.List       (transpose)
+import qualified Data.Text       as T (pack)
+import           Foreign.C.Types (CInt (CInt))
+import           SDL             (InitFlag (InitVideo), Renderer, V2 (V2),
+                                  V4 (V4), Window, createSoftwareRenderer,
+                                  createWindow, defaultWindow, getWindowSurface,
+                                  getWindowSurface, initialize, showWindow,
+                                  surfaceFillRect, updateWindowSurface,
+                                  windowInitialSize)
+import           SDL.Primitive   (fillCircle)
+
+-- Internal imports
+import Constants (Color, caption, defaultBG, screenMarginWH, screenWH)
+import GameState (GameState, GameStatus (LevelPlaying), gameGrid, gameInfo,
+                  gameLevel, gameStatus)
+import Levels    (LevelSpec, background, fieldColor, levels)
+import Objects   (Field, Grid, fieldId, findPosition)
+```
+
+  - Example 2:
+
+```haskell
+-- External imports
+
+-- Internal imports
+import GameState        (GameState, GameStatus (LevelPlaying), gameGrid,
+                         gameInfo, gameStatus)
+import InputOutputMatch (clickedFields)
+import Objects          (Field, FieldKind (Empty, Tile), Grid, fieldKind,
+                         swapFields)
+import UserInput        (Controller, controllerDragPoss)
+```
+
+  - Example 3:
+
+```haskell
+-- External imports
+import Data.Ix (inRange)
+
+-- Internal imports
+import DeviceOutput (absFieldsPositions, calcFieldSize)
+import Objects      (Field, Grid)
+```
+
+  - Example 4:
+
+```haskell
+-- External imports
+import Data.Ix   (inRange)
+import Data.List (find)
+
+-- Internal imports
+import DeviceOutput (ScreenPosition, gridFieldSize, gridFieldsAbsPositions)
+import Objects      (Field, Grid)
+```
+
+  - Example 5:
+
+```haskell
+-- External imports
+
+-- Internal imports
+import DeviceOutput (RenderingCtx, initializeGUI, render)
+import GameLogic    (gameLogic)
+import GameState    (GameState, defaultState)
+import UserInput    (Controller, defaultController, updateController)
+```
+
+  - Example 6:
+
+```haskell
+-- External imports
+import Data.Int (Int32)
+import SDL      (EventPayload (MouseButtonEvent, MouseMotionEvent),
+                 InputMotion (Pressed, Released), Point (P), V2 (V2),
+                 eventPayload, mouseButtonEventMotion, mouseMotionEventPos,
+                 pollEvent)
+
+-- Internal imports
+```
+
+- Create a list for commonly used variables and abbreviations in the code. If you see irregularities you are very welcome to fix them.
+- What makes it easy or hard to understand the code? If you want try to fix it and/or give us feedback regarding the difficulty of understanding our documents and our code.
+- Compare the board game scaffold with the game structure of [haskanoid](https://github.com/ivanperez-keera/haskanoid) and/or [Pang a Lambda](https://github.com/keera-studios/games-pang-a-lambda).
+- Structure [raindrops](https://github.com/keera-studios/haskell-game-programming/tree/master/examples/raindrops) using our [basic game structure](https://github.com/keera-studios/haskell-game-programming/blob/zuriHac2018/examples/board-game-scaffold/docs/game-structure.md).
+
+## Haskanoid: SDL1 SDL2 FRP (Yampa) Wiimote
+- Take a look at the [issues](https://github.com/ivanperez-keera/haskanoid/issues) that we added and tagged with ZuriHac2018 of [haskanoid](https://github.com/ivanperez-keera/haskanoid) our breakout game in Haskell. It uses functional reactive programming, can be played with various input devices (mouse, wiimote, ...) and can be compiled with SDL1 or SDL2.
+
+## Confused?
+Don't panic! Let's talk and find a solution. ;-)