An object-oriented framework for the LÖVE game engine. No longer being worked. See README for details.
Lua Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

No Longer in Development!

Grace is no longer in development. I made the mistake trying to create a massive framework, to help me make games in LÖVE, but the process just bogged me down in the end. The framework has become so huge, that I have trouble working on it, and sometimes even comprehending it.

The path I've taken is just to take the core ideas out of Grace, simplify them and strip them down to my needs, and make a little game out of it. Since then, I've actually made some progress.

Grace will most likely return, but completely rethought, and all the previous work, which has just ended up in a mess, will be scrapped.

So there you have it. And for the record, below is the previous README:


Grace is an object-oriented framework for the LÖVE game engine, written in Lua. The aim of the framework is to provide a lot of object-oriented organisation to help games not so easily become a mess. A number of useful utilities and other things are included, such as a tweening system, functions for maths, colors, data, etc.

Currently the framework has reached Alpha 4. It's features are not complete, and a lot of testing remains to be done. If you would like to help test it and find bugs, please do, and report what you find in the issue tracker. Any code contributions are also very welcome.

There is no documentation for the framework at the moment, outside of the code, as it is still in an early stage of development. However, most functions and classes are documented through comments above them in the code, so it shouldn't be too hard to work it out.


  • Organisation through the use of Worlds, Entities, Layers, and Tags.
  • Drawing and updating callbacks for Worlds and Entities.
  • Physics support in Worlds and PhysicalEntities.
  • A Camera class.
  • An Input module, which provides many aids in handling input and input abstraction.
  • A few classes to help with data structure (these will be expanded).
  • A tweening system.
  • Many utility functions for maths, colors, data, easing, and more.
  • Time scaling.
  • And much more to be added...


Here's a quick overview of how the framework works. You control the game as a whole through the normal love callbacks, such as love.update, love.draw, and so on.

The next layer is Worlds, which might be called States in other frameworks/engines. You might have your game entirely in one world, but you'll most likely use more. You might have one for a Menu and one for each game mode (e.g. Campaign, Arcade, and Multiplayer). You might even have one for each level.

Every in-game object from a crate to an explosion, from a starship to a GUI button, is going to be an Entity. Usually, you will subclass the Entity class to define certain behaviour, and then create one or more instances of it. If you need support for the physics system you should use PhysicalEntity.

Entities can be positioned on Layers, which determine the drawing order. Layers can have depth, which means determines when entities are drawn.

Entities can be organised by Tags, which simply have a name. These Tags can be used in functions, such as the collision functions to identify a group of entities (all the entities tagged with that tag).

Finally, the preferable way to manage input is through Input class. This provides many useful things related input, included checking for all keys or mouse buttons, and proper mouse calculations (if you're using a Camera).

Hopefully that gives you a quick overview of how it works.


Grace is licensed under the zlib/libpng license. See LICENSE.txt or the Open Source Initiative page.


This library is based quite heavily on FlashPunk, an awesome Flash game engine. I have used it for inspiration on the framework's structure, and I've used some of it's code too. Thanks to Chevy Ray for creating FlashPunk!

Thanks to kikito who has developed middleclass and middleclass-extras, which this framework uses. He has also created PÄSSION, which I have used a bit for inspiration, especially on the Camera class. And finally, thanks goes to his advice on handling audio, which was implemented in the audio module.

Thanks to bartbes for creating AnAL which provided some help in the creation of the SpriteMap class.

Thanks to as3ds, an ActionScript 3 library full of data structures, for inspiration on the creation of the coming data structures (in the data module).

Finally, thanks to LuaBit for filling the gap of bitwise operators in Lua.

middleclass, middleclass-extras, and LuaBit are contained in the thirdParty folder.


At the current point the master branch is used as the development area (this will change when a stable version is released). If you want the files for specific release, please select the release by using tags. Other branches are topic branches for development for things that aren't ready to be included, but aren't going to be just thrown away.