A book about LÖVE, Games and Lua.
Switch branches/tags
Clone or download
Latest commit 2a1d9d6 Jul 10, 2017


LÖVE for Newbies

A book about LÖVE, Games and Lua. Join%20Chat
View the rendered book with examples at love2d-community.github.io/love2d-book.

The collaborative book will be divided into three main units:

  1. A walkthrough to building a small prototype and introducing the user to the LÖVE framework,

  2. A more realistic revamp of the built prototype to create a "full" game, and lastly

  3. An area of examples and snippets containing best and known practices in game development.

The book s written using a generator called Asciidoctor.
Quick Reference: http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

We have extended the AsciiDoctor syntax with livecode blocks and block macros. There also are some other additions, you can use them like this:

livecode::test[] (1)

livecode::test[name=test2] (2)

[livecode,example] (3)
function love.draw()
    love.graphics.setColor( 255, 255, 0, 255 )
    love.graphics.rectangle( "fill", 10, 10, 100, 100 )

code_example::world1/05_better-steering/rotation[] (4)
code_example::world1/05_better-steering/rotation[exclude="lib/*,maps/*",include="**/*.lua,**/*.txt"] (5)

wiki:love.graphics.setColor[] (6)
wiki:love.graphics[the graphics module] (7)
  1. loads love2D-book-code/test directory

  2. load love2D-book/code/test directory. It’s name is test2 so it doesn’t conflict with the first.

  3. runs the code below it; has the name of "example"

  4. shows all .lua files from the specified directory, except those in lib/

  5. shows all .lua and .txt files from the specified directory, except those in lib/ and maps/

  6. links to the wiki page for love.graphics.setColor and formats the link accordingly

  7. links to the wiki page for love.graphics using the text the graphics



You will need ruby and bundler to be installed for rendering the book.

With ruby set up, you can install bundler like so:

$ gem install bundle

then install the dependencies:

$ bundle install


To render the ebook and pdf you can run render.sh:

$ ./render.sh

but the preferred way to work on the project is by running Guard:

$ bundle exec guard

this will automatically render the HTML ebook as you change the files. You can use any LiveReload extension in a browser to have it automaically refresh as you modify the book.


Whenever a significant portion of the book has changed and is ready for release, stage the files on master and run release.sh. Make sure that book/code is at the correct revision and staged before releasing.

Style Guidelines

  • The three chapters are called Worlds and each section is a Level

  • At the end of every Level, remind the reader about what he has learned in this chapter

  • Use examples and concrete language wherever possible.

  • Programming is all about abstraction, and examples help make this a lighter and more enjoyable read

  • Make everything interesting to read about and motivate the reader to keep on learning

  • Be clear and direct when talking something new. Keep it simple, stupid!

  • Every Level ends with additional exercises that the reader can choose to try

  • Give “Pro Tips” and “Watch out!”-notices where fitting (Admonitions)

  • Use informal language and short text to show new content

  • Keep lines shorter than 125 characters (soft rule, better have a slightly longer line than wrap two words)

  • One sentence per line

  • If sentences need to be wrapped due to length, try to wrap at a comma to keep the source readable

  • Use the code repository for examples that readers may want to try out or modify, use inline livecode for minor changes and demos

  • Style lists with *, don’t end items with .

  • Use wiki block macros when discussing LÖVE functions and concepts (wiki:love.graphics.print[print] → wiki:love.graphics.print[print])

  • Use backticks when mentioning Lua values ("string""string")

  • Link to sections you reference (<<world1-2, last Level>>lastLevel)

  • Show relevant portions of source code before livecode displays, use callouts (<1>) to discuss source code

Thank you for helping create this :)