- Welcome to ZillaLib
- Games using ZillaLib
- Sample Code
- Tutorials
- ZillaLib Features
- License
- Setting Up a Project
- Platforms and Setup
- Asset File Handling
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.
- Game code implementation is 100% C/C++
- All platforms get compiled to natively, linked statically
- No touching of Java, Objective-C, Javascript, C# or anything required
- Exact same code that debugs on PC runs everywhere else
- Easy to set up, no dependencies
- Windows (32 and 64 bit)
- Android
- iOS (iPhone/iPad/iPod)
- WebAssembly
- Emscripten
- Chrome Portable Native Client
- Linux
- macOS
- Drawing of simple 2D geometry (lines, circles, polygons, etc)
- Surface texture loading (PNG/JPEG)
- Drawing of surfaces scaled/rotated
- Buffered batch rendering
- Repeated texture rendering
- Tiled textures for tile maps or animations
- Font rendering
- Bitmap fonts and TTF fonts
- Text alignment vertical/horizontal/baseline, automatic line breaks
- Particle system
- Custom vertex/fragment shader support
- Audio sample loading and playing (OGG)
- Music streaming and looping
- Hooks for custom processing
- Built in chip tune like synthesizer
- Samples with arbitrary playback speed
- Tiled textures for animation
- Particle system
- Transition manager for timer/event based animation
- Bone based physics for 2D ragdoll animations
- 2D Math library (Vectors, Rects, Rotating Bounding Boxes, etc.)
- Collision test functions for common interactions (Circle/Line/Boxes tests and sweeps)
- Easing functions
- Random Number Generators
- UDP based server/client system (based on ENET)
- Super light weight NAT punch (easily P2P connect, even from mobile to PC)
- HTTP requests for all platforms including POST data
- HTTP responses can be loaded as regular files (including textures/audio)
- Scene manager for splitting game parts
- Built in transition system for animating scene switch
- Event system for input, resizing
- Multitouch input support where available
- Mobile device motion sensors and joystick support
- Key/Value configuration storage for all platforms
- Thread support
- Open URL in default system browser
- Base64 encoding/decoding
- Data compression and checksum functions
- Custom easy to use XML and JSON handling
- Scene management with camera and light objects
- Material (shader) management system
- Many options for predefined materials but extendable with custom shader code
- Mesh file loaders (OBJ/PLY/Multi OBJ animation)
- Mesh generators (plane, box, sphere, ...)
- Shadow mapping
- 3D particle system
- Skeletal mesh with IK
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.