Löve2d utils: livecode & vector

These are two small lua utilities that I wrote myself, which I find extremely useful when I’m writing games with Löve2D.  I guess you could call them “libraries”.  I think that they could be useful to other developers, so I’ve decided to share them via Github.  Each one of them is a single lua file that you can include in your project, and they are independent from each other.


This introduces a class called “Vector”, which I use for 2d vector math.  It has a bunch of basic functions like modulus, angle, vector operations (sum, product with scalar, dot product), and some other convenience functions (round, angle with another vector).  Note: all angles are in radians.

It’s briefly documented on the README file, and you can also take a look at the unit tests included.  The library is licensed under the zlib license.



This addresses the problem of tweaking values in a game.  The standard workflow with Löve2D is write some code, run the game, find something that needs to be changed, stop the game, change the number in the code, and launch again.  What this library offers is a faster cycle by loading changes in the code live while it’s running.  This way, once your game is running, you can just tweak values in the source and as soon as the file is saved, the changes are applied.  This can be specially powerful when the changes you’re making in the source affect the game in parts that are not shown at the beginning.  For example, if you were tweaking the values of some boss enemy at the end of a given level, having to restart the game every time you made one such change and reach the boss could take a while.

What this script does is to replace the standard Löve2D main loop, adding the possibility to “watch” changes in the source code while the application is running.  It does by modifying the function love.filesystem.load(): when you load files using that (as opposed to lua’s “require”), livecode starts tracking them internally and reloading them when they change in the filesystem.  It must be said, though, that this is not a perfect solution for all cases: it’s very dependant on the way you use global and local variables within your program.  For example, if you have an update function for a given entity which depends on some new variable that is initiallized when this entity is created, it can happen that already existing instances of such entity do not have said variable, and thus update will fail with them.  In that case, you can restart the game with F5 (which is a shortcut to call love.load() ), and that should fix this.  Moreover, a file that gets re-loaded by livecode is expected to overwrite the global variables/functions, and only them.  So, if you’re defining functions as methods of instances that are created during an explicit call to load, chances are that those functions will not be automatically overwritten (again, depends on your coding style), again you need to reload the game with F5.  Another possible problem is if you’re defining global variables outside of load: these will be overwritten each time you change something.

Fixing issues like that would require a more “intelligent” version of the library that is capable to parse your code, understand it, and decide where to apply changes, making several assumptions in the process that could potentially be wrong.  Not only that, but it would probably require to force a particular coding style upon you in order to make these assumptions valid.  That would be way out of the scope of this library, and I think it’s important how it works internally in order to figure out how to use it effectively and to understand where its limitations come from.  For that, there is a bit of explanation in the included readme file, as well as in the header of the souce code.

One feature that I included and I find extremely useful is that the game doesn’t need to be restarted when there is an error.  The game window shows the error message, on a black background, and subsequent calls to update/draw are skipped until the files change, which means that potentially you have fixed the issue; then the game continues executing from that point.  The black background is intentional, in order to distinguish it from standard errors happening at the Löve2D level (blue background), which means that the game is not able to recover from the error and has to be closed.

I use this for development only.  Once you want to distribute your games, I recomend that you remove the reference to this file.  Livecode does not require any changes in your source code at all, including it is only one line: “require ‘livecode'”.  All files loaded through love.filesystem.load() afterwards will be watched.  There are also a few more advanced features available (for example, watching resource files and calling a user-defined function when they are changed, and the possibility to define a callback function that will be called every time changes are reloaded), but even in its most basic use it’s already quite useful.

Also released under zlib license.

This entry was posted in Löve2d, Misc. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s