summaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
Diffstat (limited to 'README')
-rw-r--r--README214
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.