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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 README (limited to 'README') 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. -- cgit v1.2.3