ZillaLib is a 2D and 3D game creation framework that runs on pretty much every open platform out there. Windows, Linux, macOS, Android, iOS and on the web.
It's a sleek C++ library that compiles to all platforms with zero change in the game code. Truly write once, run everywhere. Of course it is still possible to deviate parts easily where needed. For instance for touchscreen inputs.
The library itself compiles quickly, has zero external dependencies, and links statically adding only around 250kb to the binary size of the game. Still it comes with plenty of features.
See Games.md for a list. These can be played directly in the web browser or downloaded, and come with full source code under the same license as ZillaLib.
See the ZillaLibSamples repository for short and easy to understand sample code for almost all features.
See the tutorials listing on the ZillaLib website.
Here's a list of features provided by the ZillaLib.
ZillaLib is available under the zlib license.
First download this project from GitHub with the 'Download ZIP' button or by cloning the repository.
The library itself compiles automatically with the first project being built, so lets start right away!
By far the easiest way to get started is to use the interactive ZillaLib Project Generator tool which is available online or offline.
Just enter a project name and select the target project files to generate.
If you have placed ZillaLib in a directory named dfferent than "ZillaLib" or if you want to place your game project in a directory that is not next to ZillaLib's, you have to specify the relative path in the field 'Path to ZillaLib'. For instance, if you have ZillaLib in "D:\dev\libs\ZillaLib-master" and you plan to put your game project in "D:\dev\proj\MySuperGame", then specify "../../libs/ZillaLib-master" as the path to ZillaLib. Always specify the relative path. It makes it easy to build various platforms and even from different virtual machines in the same place.
When finished, click "Generate and Save Project Archive (ZIP)" and everything will automagically be prepared for you. Extract the project files in the planned location. There's even some sample code included to start up right away. Check the specific platform from the list below on how to set it up and how to actually get your project up and running.
Compiling and debugging is done with Visual Studio. All versions are supported (VC6 until VS2019). If you don't have it installed yet, you can download Visual Studio Community Edition here. Make sure "Visual C++" is selected during the installation. Optionally you can also install "Windows XP Support for C++" under the features/packages list.
Once installed, open your GameProject-vs.sln solution file. On your first start-up, it should have your game project selected as the start up project in the Solution Explorer (project name is bold). It should also default to the build configuration "Debug" and the build platform "Win32" on the top of the Visual Studio window. This is fine for now, you can just build and run the sample code with the menu function "Debug / Start Without Debugging".
XP support is enabled for VS2013 and older as it does not require any optional packages to be installed. If you use VS2015 or newer and want your output executable files to run on Windows XP, you need to activate the correct toolset by copying 'ZillaLib-vs.props.sample' to 'ZillaLib-vs.props', edit the file and remove the comment tags around <UseXPToolset>1</UseXPToolset>.
See README.md under Android for how to setup and build for Android.
See README.md under ZillaLib-iOS.xcodeproj for how to setup and build for iOS.
See README.md under WebAssembly for how to setup and build for WebAssembly.
This platform is deprecated, WebAssembly should be used instead.
See README.md under Emscripten for how to setup and build for Emscripten.
This platform is deprecated, WebAssembly should be used instead.
See README.md under NACL for how to setup and build for Native Client.
See README.md under Linux for how to setup and build for Linux.
See README.md under ZillaLib-OSX.xcodeproj for how to setup and build for macOS.
ZillaLib has various modes of packaging asset files with the game depending mainly on the target platform, but also on build configuration (debug or release) and on the project settings.
Files are loaded through the ZL_File class. ZL_File can reference actual files on the file system, data in memory, or files inside containers. Containers themselves are a ZL_File, too. When loading files, paths are given relative from the game project directory and are written with forward slashes.
There is a global file container ZL_File::DefaultReadFileContainer which will be used automatically for reading files. Depending on the platform and build configuration, this default container will be automatically set on startup. Generally similar platform types have similar asset handling.
Debug builds always load asset files directly. It is recommended to call the LoadReleaseDesktopDataBundle method at the beginning of Load of your ZL_Application subclass. LoadReleaseDesktopDataBundle takes an optional file name as parameter. It should name a zip-file (does not need a .zip ending) which will be used as the default read file container in release builds.
Alternatively, if your project was set-up with the 'Embed Assets in Binary' option, the optional parameter can be left empty. In that case, the executable binary of the game itself will be loaded as default container. A project with that option enabled will automatically package all assets during the release build process into the output binary just for that.
LoadReleaseDesktopDataBundle does nothing on debug builds as well as non-desktop builds, so it does not need a platform check with if or #if.
Mobile app packages have a fixed way of packaging and loading files. Therefore all build configurations behave the same and no separate actions are required. On Android, the applications APK package is being loaded as the default read file container on startup. On iOS applications are installed and extracted by the operating system so files can be loaded with no file container.
The build process for web targets packages all assets into a single file for distribution. A ZIP file named GAME_Files.dat on NACL and a GAME_Files.js named file for Emscripten.
If your project was set-up with the 'Embed Assets in Binary' option, the asset file will be merged into the main game executable file so distribution becomes a single file.
Because there is no traditional file access on the web, the entire asset file will be loaded into memory on startup and ZL_File instances then read from that memory.