Restructure README.

1 files changed, 214 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..3167c82
--- /dev/null
+++ b/README
@@ -0,0 +1,214 @@
+-*- mode: org -*-
+
+Sly is a free software game engine written in [[https://gnu.org/software/guile][Guile Scheme]].  It
+provides an abstraction layer above SDL and OpenGL for common game
+programming requirements such as:
+
+- Animation
+- Shaders
+- Sprites
+- Tilesets
+- Scene graph
+- Keyboard/mouse/joystick input
+- Scripting
+
+Sly differentiates itself from most other game engines by encouraging
+[[http://toplap.org/about/][live coding]] and emphasizing [[http://elm-lang.org/learn/What-is-FRP.elm][functional reactive programming]].
+
+* Inspiration
+
+  Every programming language should have a fun, easy to use game
+  library.  Guile is no exception.  Sly draws its inspiration from
+  easy-to-use libraries/engines such as [[http://love2d.org/][LÖVE]], [[http://pygame.org/][Pygame]], and [[http://pyglet.org/][Pyglet]].
+  Sly's reactive nature is heavily inspired by the [[http://elm-lang.org/][Elm]] programming
+  language.
+
+* Example
+
+  Here is the simplest Sly application (so far).
+
+  #+BEGIN_SRC scheme
+    (use-modules (sly game)
+                 (sly window)
+                 (sly math vector)
+                 (sly render camera)
+                 (sly render model)
+                 (sly render sprite))
+
+    (define scene
+      (model-move (vector2 320 240) (load-sprite "gnu.png")))
+
+    (define camera (orthographic-camera 640 480))
+
+    (add-hook! draw-hook (lambda _ (draw-model scene camera)))
+
+    (with-window (make-window #:title "Hello, world!")
+      (start-game-loop))
+  #+END_SRC
+
+* Features
+
+** The Game Loop
+
+   Sly's game loop doesn't tie drawing and updating
+   together. Instead, updates happen on a fixed timestep (60 ticks
+   per second by default) while drawing happens as many times as
+   possible. A framerate indepedent loop mitigates slow down that the
+   user might experience when updating the game takes longer than
+   drawing a frame at the desired rate. Instead of slowing to a
+   crawl, some frames are dropped and the loop tries to catch up on
+   updates. Additionally, a fixed timestep allows for a deterministic
+   simulation, unlike a variable timestep.
+
+   To start up the game loop, simply call =(start-game-loop)=. It's a
+   good idea to set up the game window prior to starting the loop via
+   the =with-window= form.
+
+   #+BEGIN_SRC scheme
+     (with-window (make-window #:title "Best Game Ever"
+                               #:resolution #(640 480))
+       (start-game-loop))
+   #+END_SRC
+
+** Functional Reactive Programming
+
+   Game state is a function of time.  The player's score, the current
+   stage, an enemy's hit points, etc. all change in response to
+   events that happen at discrete points in time.  Typically, this
+   means that a number of callback procedures are registered to
+   respond to events which mutate the relevant data structures.
+   However, this approach, while simple and effective, comes at the
+   price of readability, comprehension, and expression.  Instead of
+   explicitly mutating data and entering "callback hell", Sly
+   abstracts and formalizes the process using a functional reactive
+   programming style.
+
+   In Sly, time-varying values are called "signals", and they are
+   defined in a declarative and functional manner.  Rather than
+   describing the process of mutation procedurally, one describes the
+   relationship between signals instead.  Signal relationships are
+   described in a functional style using =signal-map=, =signal-fold=,
+   =signal-filter=, and others.
+
+   Example:
+   #+BEGIN_SRC scheme
+     (define-signal position
+       (signal-fold v+ (vector2 320 240)
+                    (signal-map (lambda (v) (v* v 4))
+                                (signal-sample 1 key-arrows))))
+   #+END_SRC
+
+   This signal describes a relationship between the arrow keys on the
+   keyboard and the position of the player.  =signal-sample= is used
+   to trigger a signal update upon every game tick that provides the
+   current state of the arrow keys.  =key-arrows= is a vector that
+   maps to the current state of the arrow keys, allowing for 8
+   directional movement.  This vector is then scaled 4x to make the
+   player move faster.  Finally, the scaled vector is added to the
+   previous player position via =signal-fold=.  The player's position
+   is at (320, 240) initially.  As you can see, there are no
+   callbacks and explicit mutation needed.  Those details have been
+   abstracted away, freeing the programmer to focus on more important
+   things.
+
+   As an added bonus, signals adapt to changes in their environment
+   when defined using the =define-signal= form.  This means that a
+   signal can be re-defined at the REPL and other dependent signals
+   will take notice and re-evaluate themselves automagically.
+
+** REPL Driven Development
+
+  Guile's read-eval-print-loop allows you to develop your game while
+  it is running!  This allows you to see in real-time what your
+  changes do to the game without having to kill, recompile, and
+  restart the program every time a change is made.
+
+  Sly integrates Guile's [[https://gnu.org/software/guile/manual/html_node/Cooperative-REPL-Servers.html][cooperative REPL server]] into the game loop.
+  To activate this feature, import the =(sly repl)= module and call
+  =(start-sly-repl)=.  To connect to the REPL server, use the [[http://www.nongnu.org/geiser/][Geiser]]
+  extension for GNU Emacs.
+
+  *Geiser*
+
+  #+BEGIN_SRC fundamental
+   M-x connect-to-guile
+  #+END_SRC
+
+  Use the default host and port settings when prompted.
+
+* Building
+
+  Sly uses the typical GNU build system. First run =autogen.sh= and
+  then do the usual incantations.
+
+  #+BEGIN_SRC sh
+    ./autogen.sh
+    ./configure
+    make
+    sudo make install
+  #+END_SRC
+
+  See =INSTALL.org= for more detailed installation instructions.
+
+* Developing
+
+  Users of GNU Guix can quickly create a development environment by
+  running:
+
+  #+BEGIN_SRC sh
+    guix environment -l package.scm
+  #+END_SRC
+
+* Running Examples
+
+  To run an example when Sly has been installed:
+
+  #+BEGIN_SRC sh
+    cd examples
+    guile simple.scm
+  #+END_SRC
+
+  To run an example without installing Sly (useful when developing):
+
+  #+BEGIN_SRC sh
+    cd examples
+    ../pre-inst-env guile simple.scm
+  #+END_SRC
+
+  To quit an example:
+  - Close the window
+  - Press the =ESCAPE= key
+
+* Using the Sandbox
+
+  If you want to quickly create a Sly environment and start
+  experimenting, run =./pre-inst-env sandbox=.  It will import many
+  useful modules, start a REPL server, open a window, and start the
+  game loop.  Simply connect to the REPL server and start hacking!
+
+* Platforms
+
+  Sly supports GNU/Linux currently. OS X support is in the works, but
+  there are problems with guile-sdl. See
+  https://github.com/davexunit/guile-2d/issues/2 for more details.
+
+* Dependencies
+
+  - GNU Guile >= 2.0.11
+  - [[http://www.gnu.org/software/guile-opengl/][guile-opengl]] >= 0.1.0
+  - [[https://www.gnu.org/software/guile-sdl/index.html][guile-sdl]] >= 0.5.0
+  - SDL 1.2
+  - FreeImage >= 3.0
+  - GNU Scientific Library (GSL)
+
+* Community
+
+  For help and general discussion, join the =#sly= IRC channel on
+  irc.freenode.net.
+
+* License
+
+   Sly is licensed under the GNU General Public License version 3 or
+   later.
+
+   See =COPYING= for the full license text.