A guided tour of the Dreemchest Lua based game engine


As you may know from previous posts I am rather a big fan of Lua based game engines.  When I learned about a new one completely off my radar, I just had to check it out.  The game engine in question is Dreemchest.



As I mentioned earlier, Dreemchest is scripted using Lua.  Underneath Dreemchest is powered by a C++ core.  In terms of other Lua game engines, Dreemchest is probably most similar to Corona in scope.  It comes with a WYSIWYG editor and somewhat uniquely, enables you to use Flash to create your user interface.  Unlike Corona, you don’t need to authorize against and build on their servers, everything is done locally, I know some people really hate that about Corona and Gideros ( and more recently Loom ). Oh yeah, it’s also free(for now?).  Let’s jump in and take a look at Dreemchest.


First things first, you need to download Dreemchest, which you can do right here.  It is available for Windows and MacOS, although I have to admit, the MacOS version seems to be a lot less stable right now, so if you have a choice I would consider choosing the Windows version.  There is no installer, simply download the archive, extract it then run composer.  Dreemchest seems to be a Qt app, so I’m a bit shocked a Linux build isn’t available.  Then again, Linux is a fairly small sub-set of the population, so maybe that’s a down the road feature.


Meet Dreemchest Composer.


Dreemchest Composer in action


This is the WYSIWIG environment in action with the Animation sample loaded.  Currently there are over 20 samples available showing you how to perform various actions in Dreemchest.  As you can see from the Window above, it’s a pretty sparse environment, but most of the information you need is available.  Across the top is the toolbar you would use to configure and run your application.  Below the is the WYSIWYG editing area and below that is the output panel.  On your right hand side is the Property window, which is populated dynamically by your script objects, allowing you to view and configure values visually instead of in code.  Below that are your assets, that you can import, create then drag and drop into your scene.


The UI itself is incredibly customizable, every dialog can be detached, moved or closed, leaving you law things out exactly as you want.



Coding and documentation


So, where exactly do you do the coding?  If you have the Animation sample open, take a look at the assets panel and you will see a pair of script objects, App and Hero.



Double click one of these script files and it will open in the integrated text editor.


It’s a fairly barebones editor, but it does what you need including syntax highlighting, auto-completion and automatic indention.  It’s nice not having to switch apps to edit code.


The programming language itself is standard Lua 5.1, with an class inheritance system.  If you know Lua you will be immediately comfortable with Dreemchest.  If you press play or F5 to run your application, it runs directly inside Dreemchest:


As of right now, debugging options are quite light.  You can alter position, from portrait to landscape, simulate home button press and not much else.  Oddly enough, once the application is running, you see the options traditional debugging options, such as step in, step out and continue.  That said, I cant figure out how to add an actual breakpoint.  My guess is, this is a feature under active development.  I look forward to it too, as for now you would be limited with printing to the output window while debugging.  Build and load times are virtually non-existent, which is nice.


From a coding perspective, there is a pretty good amount of documentation, especially for such a young project.  As mentioned earlier, there are currently 20+ samples included with the download.  There are a series of tutorials available here as well as an API reference available here.  The API is quite straight forward, somewhat minimal, but still under developed.  Pretty much everything you need to create a 2D game is currently there, including graphics, tweening, audio and physics.  For physics, there is also an integrated shape editor which is rather convenient.  Still under development, new functionality is being added with each release.  This is critical though, as you don’t get source code, so you need all functionality needs to be in box.




Perhaps the most innovative feature of Dreemchest is the ability to embed and communicate with Flash objects for creating your UI layer.  You can included an SWF file just like you do any other graphic file.  The swf file can contain ActionScript2 code, and the two languages can communicate back and forth.  Here is a simple example from the SDK on working with a Flash animation, showing how you can load and communicate between the languages.  uiButtons is the swf file that has been added to the scene.

class "Main"( StageObjectContainer )    function Main:main()      -- Register necessary functions for Flash UI      UIManager.registerFunction( 'nativeSetPitch', function( value ) trace( 'Pitch set to: '..value ) end )                -- Attach to events dispatched from Flash UI      UIManager.attachListener( 'uiStop', self )      UIManager.attachListener( 'uiToggleMusic', self, 'onMusicToggle' )            local ui = uiButtons.new()      self:attach( ui )                -- Notify Flash UI by dispatching an event      UIManager.dispatchEvent( 'onRefresh', { version = 104, message = 'hi there!' } )  end        function Main:uiStop( e )      trace( 'Stop the music' )  end        function Main:onMusicToggle( e )      if e.pause then          trace( 'Pause music' )      else          trace( 'Continue music playback' )      end  end

This allows you to use the rich UI functionality of Flash/ActionScript for your UI layer, while performing game logic and rendering in Lua.


Building your application


When it comes to creating and deploying your application, that’s a pretty simple process.  Simply select the File->Export menu and select the platform.  You need to have a Mac to build iOS or OSX target.  You need to install the Android or iOS SDK and point Dreemchest at the proper directory before you can export to either platform.  The results of the build (an apk in the case of Android) are in the output subdirectory although I had to do a bit of searching to figure this out.






Dreemchest is certainly a young engine, but it has a great deal of potential.  I did experience crashes and a few UI glitches, although the newest release seems a great deal more stable.  I’m actually quite surprised by just how much it did improve in just a couple weeks, this bodes well for the future. This is certainly an engine worth keeping an eye on, especially if you like Lua and are targeting iOS or Android.  It may not be for everyone, if you need source code for example, Moai is a better fit.  But if you are looking for an all in one accessible toolkit, Dreemchest is a good pick.  Of course, it’s free too, so you’ve got nothing to lose by checking it out.


Scroll to Top