From fe677bd06a3646f92c9b3b5111260191272b19e6 Mon Sep 17 00:00:00 2001 From: David Thompson Date: Fri, 5 Jun 2015 21:06:57 -0400 Subject: Restructure README. --- README | 214 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.org | 214 ------------------------------------------------------------- 2 files changed, 214 insertions(+), 214 deletions(-) create mode 100644 README delete mode 100644 README.org 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. diff --git a/README.org b/README.org deleted file mode 100644 index 6a7a0b5..0000000 --- a/README.org +++ /dev/null @@ -1,214 +0,0 @@ -* Sly - The Living, Breathing Game Engine - - 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 functional 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 - - GNU GPL v3+ - - See =COPYING= for the full license text. -- cgit v1.2.3