From 8c2fbeae53cbfcf80e7b524bc922626df1ed327f Mon Sep 17 00:00:00 2001
From: Abhinav Sarkar <abhinav.sarkar@gmail.com>
Date: Thu, 21 Nov 2013 22:04:24 +0530
Subject: [PATCH] Added readme

---
 README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8db9896
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+# Gravity Pong
+
+Gravity Pong is the famous [Pong][pong] game with a twist, written in [ClojureScript][cljs] using the 
+[core.async][coreasync] library.
+
+Along with the usual Pong ball and the paddles on both sides of the screen, there is also a mass at 
+the center of the screen which exerts a gravitational force on the ball causing it to change its path
+from a usual straight line to a curve. And the user can control the gravitational force using the 
+keyboard to shape the ball's path as they want! It can be played [here][demo] (only works on 
+Google Chrome for now).
+
+## Programming Details
+It is written in the [Flow-based Programming][fbprog] paradigm where calculations of ball's position, 
+velocity etc are done by separate modular components running in their own threads of computation 
+(in this case, core.async go processes). These components are connected using signals (implemented 
+using core.async channels) to form a network - like an electronic circuit - to build the complete game.
+
+The very [lose coupling][coupling] (data coupling) caused by this modular design allows one to add 
+new components in the network without changing other parts of it. In fact, this was first developed 
+as a usual Pong game and gravitation was added only as an afterthought, with very minimal changes
+to the existing code.
+
+Here is how the network of components interconnected with signals looks like:
+
+<pre>
+                                      +-d-----------+--------------------------+
+                                      v             |                          |
+ keyboard +-e-> sampler +---k---> paddle-postnr +-d-+   +-> gravitation +--+   |
+                  ^                                 |   p                  a   |
+                  t                                 |   |                  |   |
+                  |                                 |   |                  |   |
+                  +-------+          +-p----------+-|---+                  |   d
+                          |          |  +-a-------|-|------+---------------+   |
+                          |          v  v         | |      |                   v
+  browser +-b--> ticker +-+--t--> ball-postnr +-p-+-|------|------------p-> renderer
+                    ^     |             ^         | |      |                  ^  ^
+                    |     |       +-----|---------+ |      |                  |  |
+                    s     |       |     l     +--d--+      |                  s  t
+                    |     |       |   +-+-----|-------+    |                  |  |
+                    |     |       p   l   +-a-|-------|----+                  |  |
+                    |     |       v   v   v   v  +-l--+                       |  |
+                    |     +---t-> collision-detr                              |  |
+                    |     |             ^        +-s--+-----------------------+  |
+                    |     |             s             |                          |
+                    +-----|-------------+-------------+                          |
+                          |                                                      |
+                          +------------------------------------------------------+
+</pre>
+
+Signals     
+
+ - *b*: ticks from browser
+ - *t*: game ticks        
+ - *e*: keyboard events   
+ - *k*: keydowns          
+ - *p*: ball position     
+ - *l*: ball velocity     
+ - *a*: ball acceleration 
+ - *d*: paddle positions  
+ - *s*: game state        
+
+Components
+
+ - *keyboard*: keyboard for user input
+ - *browser*: browser
+ - *ticker*: generates game ticks from browser ticks
+ - *sampler*: samples input signal based on a sampling signal
+ - *paddle-postnr*: paddle positioner, calculates the position of paddles
+ - *ball-postnr*: ball positioner, calculates the position of the ball
+ - *collision-detr*: collision detector, detects collision of the ball with the paddles and the 
+                       walls, also calculates the velocity of the ball
+ - *gravitation*: calculates the acceleration of the ball due to gravitation
+ - *renderer*: renders the game on screen
+
+ This project was written as an experiment to play with the core.async library and can serve as
+ a medium sized example project for the same. The main source can be found [here][src].
+
+[pong]: https://en.wikipedia.org/wiki/Pong
+[cljs]: https://github.com/clojure/clojurescript
+[coreasync]: https://github.com/clojure/core.async
+[demo]: http://abhinavsarkar.net/frpong
+[fbprog]: https://en.wikipedia.org/wiki/Flow-based_programming
+[coupling]: https://en.wikipedia.org/wiki/Coupling_(computer_programming)
+[src]: https://github.com/abhin4v/frpong/blob/master/src/cljs/frpong/core.cljs
\ No newline at end of file