\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename sly.info
@settitle Sly
@c %**end of header
@copying
Copyright @copyright{} 2013, 2014  David Thompson @email{davet@@gnu.org}

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU
Free Documentation License''.

A copy of the license is also available from the Free Software
Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}.

@end quotation

The document was typeset with
@uref{http://www.texinfo.org/, GNU Texinfo}.

@end copying

@titlepage
@title Sly 0.1
@subtitle Using the Sly game engine
@author David Thompson
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@c Output the table of the contents at the beginning.
@contents

@ifnottex
@node Top
@top Sly

@insertcopying
@end ifnottex

@c Generate the nodes for this menu with `C-c C-u C-m'.
@menu
* Introduction::                About Sly.
* Installation::                Installing Sly.
* Getting Started::             Writing your first Sly program.
* API Reference::               Sly programming interface.
* Contributing::                Help improve Sly!
* Copying This Manual::         The license of this manual.
* Index::
@end menu

@c Update all node entries with `C-c C-u C-n'.
@c Insert new nodes with `C-c C-c n'.

@node Introduction
@chapter Introduction

Sly is a 2D/3D game engine written in the GNU Guile dialect of the
Scheme programming language.  With the help of Guile, Sly provides all
of the essential building blocks for making video games, such as:
window management, input event handling, rendering, linear algebra,
and powerful scripting capabilities.  Sly differentiates itself from
traditional game engines by providing a dynamic live coding
environment and a functional API.

For those unfamiliar with the term, ``live coding'' is the practice of
improvised interactive programming.  Sly provides a suitable
environment for live coding by leveraging Guile's cooperative REPL
server.  When used with a powerful editing tool such as Emacs (with
the fantastic Geiser extension), programmers may evaluate arbitrary
code and see the effects of their modifications in real time.  This
tight feedback loop allows for faster prototyping, greater
productivity, and most importantly, more fun.

Functional reactive programming (FRP) is a technique used to model
time-varying values with pure functions.  A pure function is a
function whose return value depends solely upon its arguments.  They
also produce no side-effects, such as calling 'set!' on a variable or
writing to a file on disk.  Sly encapsulates time-varying values in
``signals'', a high-level data structure for controlling the flow of
events.  Unlike imperative event callbacks, signals can easily be
composed to form new signals.  By modeling game state with pure
functions and immutable data, a game can be seen as a function of
time.  To play the game is to ``fold'' (accumulate a result) over
time.  Constructing a game this way allows for deterministic behavior
that is easier to reason about and test than the accumulation of
side-effects seen in traditional game engines.  The signal interface
is also declarative, meaning that the programmer describes @emph{what}
the state of the world should be like at any given time, rather than
@emph{how} to get there.

@node Installation
@chapter Installation

Sly is available for download from its website at
@url{sly.dthompson.us}.  This section describes the software
requirements of Sly, as well as how to install it.

The build procedure for Sly is the same as for GNU software packages,
and is not covered here.  Please see the files @file{README.org} and
@file{INSTALL.org} for additional details.

@menu
* Requirements::                Software needed to build and run Sly.
* Examples::                    Run example programs.
* Development Environment::     The ideal development environment.
@end menu

@node Requirements
@section Requirements

Sly depends on the following packages:

@itemize
@item @url{https://gnu.org/software/guile, GNU Guile}, version 2.0.11 or later;
@item @url{https://gnu.org/software/guile-opengl, GNU guile-opengl}, version 0.1 or later.
@item @url{https://dthompson.us/pages/software/guile-sdl2.html, guile-sdl2}, version 0.2.0 or later;
@end itemize

@node Examples
@section Examples

To test your Sly installation, try running some of the included
example programs.  Examples can be found in the
@file{share/sly/examples} directory, relative to the installation
prefix.

To run an example, invoke Guile with the relevant file, such as:
@code{guile simple.scm}.  If successful, a window with a sprite in the
center will open.

A more complex example can further test your installation and show off
what Sly can do.  Try running the ``2048'' example in
@file{share/sly/examples/2048} with @code{guile 2048.scm}.

@node Development Environment
@section Development Environment

The ideal tools to use for developing Sly applications are:

@itemize
@item @url{https://gnu.org/software/emacs, GNU Emacs}, version 24 or later
@item @url{http://mumble.net/~campbell/emacs/paredit/, Paredit}, version 23 or later
@item @url{http://nongnu.org/geiser/, Geiser}, version 0.6 or later;
@end itemize

See their respective home pages for installation and usage instructions.

@node Getting Started
@chapter Getting Started

@c @menu
@c * Open a window
@c * Draw a sprite
@c * Respond to user input
@c @end menu

@node API Reference
@chapter API Reference

@menu
* Booting::                     Opening a window and running the game loop.
* Math::                        Vectors, quaternions, matrices, etc.
* Time::                        Tick-tock.
* Scripting::                   Functional game object scripting.
* Input::                       Keyboard, mouse, and joystick input.
* Rendering::                   Drawing to the screen.
* Utilities::                   Miscellaneous conveniences.
@end menu

@include api/init.texi
@include api/math.texi
@include api/time.texi
@include api/scripting.texi
@include api/input.texi
@include api/rendering.texi
@include api/utils.texi

@node Contributing
@chapter Contributing

This project is a cooperative effort, and we need your help to make it
grow!  Please get in touch with us on @code{#sly} on the Freenode IRC
network.  We welcome ideas, bug reports, patches, and anything that
may be helpful to the project.

The git source code repository can be found at
@url{https://git.dthompson.us/sly.git}.

@node Copying This Manual
@appendix Copying This Manual

@menu
* GNU Free Documentation License::  License for copying this manual.
@end menu

@c Get fdl.texi from http://www.gnu.org/licenses/fdl.html
@node GNU Free Documentation License
@section GNU Free Documentation License
@include fdl.texi

@node Index
@unnumbered Index

@syncodeindex tp fn
@syncodeindex vr fn
@printindex fn

@bye

@c sly.texi ends here