Yampa

Domain-specific language embedded in Haskell for programming hybrid (mixed discrete-time and continuous-time) systems. Yampa is based on the concepts of Functional Reactive Programming (FRP) and is structured using arrow combinators.

Installation

Yampa is available on hackage: http://hackage.haskell.org/package/Yampa.

$ cabal sandbox init         # Optional. Useful to isolate projects.
$ cabal update
$ cabal install Yampa

Examples

Getting Yampa to run is trivial. FRP is about values that change over time. In Yampa, a system is defined by a signal function (SF), which determines how the varying input and the varying output relate. For example:

{-# LANGUAGE Arrows #-}
import FRP.Yampa

signalFunction :: SF Double Double
signalFunction = proc x -> do
  y <- integral -< x
  t <- time     -< ()
  returnA -< y / t

This signal function says that the output signal is the integral y of the input signal x, divided by the time t. The above syntax uses a Haskell extension called Arrows. If you are unhappy using arrow syntax, you can also write that code using applicative style and/or arrow combinators:

signalFunction1 :: SF Double Double
signalFunction1 = (/) <$> integral <*> time

signalFunction2 :: SF Double Double
signalFunction2 = (integral &&& time) >>^ (/)

All three are equivalent, and it's a matter of which one you like best. To run this example, we need to provide the inputs, the times, and consume the output:

firstSample :: IO Double   -- sample at time zero
firstSample =
  return 1.0  -- time == 0, input == 1.0

nextSamples :: Bool -> IO (Double, Maybe Double)
nextSamples _ =
  return (0.1, Just 1.0) -- time delta == 0.1s, input == 1.0

output :: Bool -> Double -> IO Bool
output _ x = do
  print x     -- print the output
  return False -- just continue forever

This is a trivial example, since the integral of the constant function 1.0 over time, divided by the time, is always 1.0! Nevertheless, we are now ready to run!

ghci> reactimate firstSample nextSamples output signalFunction
1.0
1.0
1.0
1.0
1.0
1.0
...

There is a directory with examples, which includes two basic SDL examples and one with using a Nintendo Wii Remote. You can install them with:

$ cabal sandbox init         # Optional, but recommended
$ cabal update
$ cabal install Yampa -fexamples

There are many programs written in Yampa:

• Haskanoid: a game that uses SDL multimedia, wiimote and kinect. It's cross platform and works in desktop, mobile, and web (compiled with GHCJS).
• Space invaders.
• Frag: a 3D first person shooting game.
• Peoplemon: a role playing game.
• Yampa-2048: an implementation of the game 2048 using Yampa and Gloss.
• MandelbrotYampa: a "hello world" using SDL2, Yampa and OpenGL.
• Haskelloids: a reproduction of the Atari 1979 classic "Asteroids"

A more comprehensive list can be obtained using the reverse dependency finder (http://packdeps.haskellers.com/reverse/Yampa), but only programs uploaded to hackage are listed.

Haskanoid, SDL cross-platform arkanoid.	Peoplemon, a role playing game	Yampa2048, a gloss board game

Use in production

• Keera Studios is using it for several Haskell games for Android and iOS including a game currently available on iTunes and Google Play. See:
  • http://facebook.com/keerastudios
  • https://itunes.apple.com/us/app/magic-cookies/id1244709871
  • https://play.google.com/store/apps/details?id=uk.co.keera.games.magiccookies

Backends

Yampa is backend agnostic, you can ultimately connect it to any backend you want. Existing backends include:

• SDL
• SDL2
• OpenGL / GLUT
• WX (see wxHaskell)
• HTML Canvas via JS Dom (for an example, see haskanoid's GHCJS branch)
• HTML5 Canvas via blank-canvas (see yampa-canvas)
• Gloss (see yampa-gloss)
• Diagrams (see diagrams example)
• Keera Hails (reactive programming framework with GTK, WX, Qt, Android, iOS and HTML support).

Testing

Yampa comes with a sophisticated testing library that allows you to use QuickCheck to test your games, and use a time-travel debugger. These features are described in the paper Testing and Debugging Functional Reactive Programming.

You can find the additional projects at:

• yampa-test
• Haskell Titan

Documentation and tutorials

The distribution of Yampa comes with substantial haddock documentation, which you can build using haddock or just read online. To build a local copy, do:

$ cabal unpack Yampa ## Or git clone this-repo
$ cd Yampa-*
$ cabal init
$ cabal install --only-dependencies
$ cabal configure && cabal haddock --internal

Documentation is also available online: https://wiki.haskell.org/Yampa

Papers and technical reports

• Extensible and Robust Functional Reactive Programming (Ivan Perez; 2017)

• Testing and Debugging Functional Reactive Programming (Ivan Perez and Henrik Nilsson; 2017)

• Functional Reactive Programming, Refactored (Ivan Perez, Manuel Bärenz, and Henrik Nilsson; 2016)

• Safe Functional Reactive Programming through Dependent Types (Neil Sculthorpe and Henrik Nilsson; 2009)

• Push-Pull Functional Reactive Programming (Conal Elliott; 2009)

• Switched-on Yampa: Declarative Programming of Modular Synthesizers (George Giorgidze and Henrik Nilsson; 2008)

• Demo-outline: Switched-on Yampa: Programming Modular Synthesizers in Haskell (George Giorgidze and Henrik Nilsson; 2007)

• Dynamic Optimization for Functional Reactive Programming using Generalized Algebraic Data Types (Henrik Nilsson; 2005)

• The Yampa Arcade (Antony Courtney, Henrik Nilsson, and John Peterson; 2003)

• Arrows, Robots, and Functional Reactive Programming (Paul Hudak, Antony Courtney, Henrik Nilsson, and John Peterson; 2002)

• Functional Reactive Programming, Continued (Henrik Nilsson, Antony Courtney, and John Peterson; 2002)

• Genuinely Functional User Interfaces (Antony Courtney and Conal Elliott; 2001)

• See also:

  • Collection of Yampa diagrams
  • Henrik Nilsson's publications
  • Ivan Perez's publications
  • First Year PhD Report (Ivan Perez, 2014), chapter 3 includes a review of FRP and outlines some existing issues.

Related projects

• yampa-sdl2: Yampa and SDL2 made easy.
• Haskell-OpenGL-Tutorial same as here: Visually attractive mandelbrot implementation.
• graphui: Attempt to implement Graphui.
• hamball: 3D, LAN FPS game of hamster balls flying around and shooting lasers written in Haskell.
• yampa-glfw: GLFW backend.
• Spaceinvaders: Re-write of the classic space invaders.
• Haskanoid: Arkanoid clone in SDL with wiimote and kinect support that works on windows, linux, Mac, Android, and Web.
• Magic Cookies: iOS/Android haskell puzzle game.
• Pang-a-lambda: 2D arcade game inspired by the classic super-pang.
• yampa-canvas: Backend to blank-canvas / HTML5 Canvas.
• yampa-gloss: Gloss backend.
• diagrams example: Demonstration of Yampa with Diagrams.
• Keera Hails: Backend for reactive framework with GTK, WX, Qt, Android, iOS and HTML support.
• YampaSynth: Software synthesizer.
• Frag: 3D first person shooter.
• cuboid: 3D puzzle game with GLUT.
• Haskelloids: Reproduction of the Atari 1979 classic "Asteroids".
• YFrob: Yampa-based library for programming robots.
• YampaShooter: Top-down team based networked tank game.
• LaneWars: Top-down MOBA game with online multiplayer.
• Functional Reactive Virtual Reality: a fork of Yampa with extensions for VR.
• Dunai: An FRP implementation inspired by Yampa that extends SFs with a monad.
• Bearriver: API-compatible Yampa replacement built on top of dunai using Monadic Stream Functions.
• The Bearriver Arcade: A couple of arcade games made using bearriver.

Help and collaboration

You can collaborate at least in three ways:

• File an issue (https://github.com/ivanperez-keera/Yampa/issues).

• Write documentation (send a link and/or a pull request).

• Research: we are constantly trying to improve Yampa. We'd be glad to have collaborators. If you are working on this, please, let us know.

  (Interactivity and FRP is the main topic of my (ongoing) work and research, so I'll keep working on this for some time. -- Ivan Perez)

Authors

• Henrik Nilsson
• Antony Courtney

Maintainer

• Ivan Perez