Pölygamy is a small LÖVE framework.

Currently, a state and a keyboard modules are available, and a timer module is in the works. Each module can be used in isolation, but they are designed to be complementary.



  • allows to bind keys to callbacks in a declarative fashion,
  • supports multiple, switchable configurations
  • supports configuration (single) inheritance.
  • supports useful ranges ([f-j] is expanded to f, g, h, j) and other patterns inspired by the Lua patterns library.
  • allows to treat the keyboard as a key matrix (full support for US qwerty keyboards only at the moment, but the common subset of qwerty, azerty and qwertz can be used universally (sorry, dvorak users))
  • is freindly with both imperative and OO coding styles.


  • allows to design each game state as if it were a full LÖVE app (custom update and draw callbacks),
  • supports state transitions (through before( from, to, ... ) and after( from, to, ... ) callbacks)

See this forum post for the latest version and the (extensive) documentation.

Here's an dummy app written with Pölygamy:

love.filesystem.load("library/Polygamy/init.lua")("library/Polygamy/") -- must be outside the load callback.
                                                -- since it creates a custom love.run loop
local state, goto, pkeyboard = Polygamy.state, Polygamy.state.goto, Polygamy.keyboard   -- for convenience
-- load your ressources, initialize your code... then : 
title = state( "Title Screen" )
function title.before() pkeyboard.use( "title" ); print"menu" end
function title.update(dt)  --[[ your title update callback ]] end
function title.draw()      --[[ draw your fine title here  ]] end
pkeyboard( "title" ):setConfig( "pressed", {
	[{" ", "return"}] = function() goto("In Game")       end,
	escape            = function() love.event.push('q') end,
	[Polygamy.default] = print
ingame = state( "In Game" )
function ingame.before( from, to, ... )
	if from == "Title Screen" then --[[Game.state.reset()]] end
	pkeyboard.use( to ) -- to == "In game" in this case
	print "In Game"
function ingame.update( dt ) --[[ instill life in your game world ]] end
function ingame.draw()   --[[ and render it in its full glory ]] end
function ingame.after( from, to, ... )
	if to == "Pause Screen" then
		-- dim the screen, take a screenshot
pkeyboard("In Game"):setConfig("pressed", {
	[" %arrows "] = { held = function(key,_,_,dt) Hero:move(key,dt); end },
	[" "]  = function() Hero:shoot()           end,
	escape = function() goto( "Title Screen" ) end,
	p      = function() goto( "Pause Screen" ) end
pause = state( "Pause Screen" )
function pause.before() pkeyboard.use( "pause" ); print"Pause" end
function pause.update(dt) end -- if you don't define it, the previous callback remains active.
function pause.draw() --[[ display "Paused" on top of the screenshot.]] end
pkeyboard( "pause" ):setConfig( "pressed", {
	escape = function() goto( "Title Screen" ) end,
	p      = function() goto( "In Game" )      end
-- then get the ball rolling :-)
function love.load() 
    goto("Title Screen")