GameLib is a collection of libraries for creating applications in Cakelisp.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

224 lines
9.8 KiB

#+title: GameLib
3 years ago
GameLib started as a library for making games, but became a collection of generally useful modules for desktop applications as well.
3 years ago
GameLib is written in [[][Cakelisp]].
3 years ago
* Setup
Clone the repository:
3 years ago
git clone
By default, GameLib does not include any 3rd-party dependencies. The dependencies will be downloaded to a folder ~Dependencies/~ as soon as you import their modules. This allows me to continue adding useful tools to GameLib without having it balloon into hour-long submodule downloading.
Build tests:
cd test/
This step will take a while the first time, because it builds Cakelisp, Ogre, SDL, and all the test programs. Subsequent executions will use the ~cakelisp_cache~ and will be much faster.
Note that changes to the 3rd-party dependencies will not automatically be detected.
** Building Ogre tests
You may need to follow the instructions in the /Asset pipeline/ section if you are failing during the ~Asset-Building~ stage. You may also comment out any ~VocalGame.cake~ lines in the build script to avoid building any assets.
** Setting up for your project
mkdir my-project
cd my-project
mkdir Dependencies
git submodule add Dependencies/cakelisp
git submodule add Dependencies/gamelib
Then, copy the following script (you get the idea - build cakelisp, then build your project):
# Build Cakelisp itself
echo "\n\nCakelisp\n\n"
./ || exit $?
cd ../..
echo "\n\nMy project\n\n"
$CAKELISP MyProject.cake || exit $?
You'll probably need the following search paths added to one of your ~.cake~ files:
#+BEGIN_SRC lisp
;; Cakelisp
(set-cakelisp-option cakelisp-src-dir "Dependencies/cakelisp/src")
(add-cakelisp-search-directory "Dependencies/cakelisp/runtime")
;; Gamelib
(add-cakelisp-search-directory "Dependencies/gamelib/src")
Refer to ~test/~ for project setup.
** Cleaning test
This shouldn't be necessary because ~test/~ is set up to not clone dependencies as submodules, but if you are testing the submodules feature, this script helps undo them.
** Platform setup
*** Ogre
You may need X11 headers to build on Ubuntu. You'll also need imagemagick and blender for the asset building:
sudo apt install libx11-xcb-dev imagemagick blender
There is a TODO to automatically install these.
* Module platform support
Modules don't necessarily support all platforms out of the box. If you are trying to use GameLib on one of these platforms, please let me know your results so I can update the table.
Here are the known compatibility results, where blank means untested/unknown:
| Module | Linux x86_64 | Linux Arm v7 | Windows x64 | macOS |
| Aubio.cake | Yes | Probably | | |
| AutoTest.cake | Yes | Yes | Yes | Yes |
| Config_ZigCompile.cake | Yes | | | |
| Config_ZigWindows.cake | Yes | | | |
| DataBundle.cake | Yes | Yes | Yes | |
| Dependencies.cake | Yes | Yes | Yes | |
| Dictionary.cake | Yes | Yes | Yes | Yes |
| DynamicArray.cake | Yes | Yes | Yes | Yes |
| FileSystem.cake | Yes | Yes | Yes | |
| FreeType.cake | Yes | | | |
| Image.cake | Yes | Yes | Yes | |
| ImGui.cake | Yes | No[1] | Yes | |
| ImGuiSDLOpenGL.cpp | Yes | No[1] | Yes | |
| Introspection.cake | Yes | Yes | Yes | Yes |
| Math.cake | Yes | Yes | Yes | Yes |
| Ogre.cake | Yes | | | |
| OgreInitialize.cake | Yes | | | |
| OpenGL.cake | Yes | No[1] | Yes | |
| ProfilerAutoInstrument.cake | Yes | Yes | Yes | Yes |
| ProfilerNull.cake | Yes | Yes | Yes | Yes |
| SDL.cake | Yes | | Yes | |
| STB.cake | Yes | Yes | Yes | Yes |
| TaskSystem.cake | Yes | | Yes | |
| TinyCCompiler.cake | Yes | | | |
| Tracy.cake | Yes | | | |
| WindowsHeader.cake | Yes[2] | Yes[2] | Yes | |
[1] These programs rely on hard-coded OpenGL versions. TODO: Make it automatically decide to use OpenGL ES when necessary.
[2] This works on Linux only when an appropriate cross-compiler is being used, e.g. ~Config_ZigWindows.cake~, or MinGW.
* Automatic downloading
The following modules will automatically download their dependencies if missing:
- Aubio.cake
- ZigCompile.cake[3]
- Dictionary.cake
- DynamicArray.cake
- FreeType.cake
- Image.cake
- ImGui.cake
- Math.cake
- Ogre.cake
- OgreInitialize.cake
- OpenGL.cake
- SDL.cake
- STB.cake
- TaskSystem.cake
- TinyCCompiler.cake
- Tracy.cake
[3] This uses curl to download a binary blob.
Unless otherwise specified, the download happens through ~git clone~ commands. You can stop downloading via editing ~src/Dependencies.cake~ to suppress the commands.
* Terms
GameLib is copyright (C) 2020 Macoy Madson ~<>~.
Licensed under ~GPL-3.0-or-later~.
Contact if you would like to negotiate an exception for your use-case.
* Ogre Asset pipeline
You should do it manually once to ensure your environment is properly configured, then refer to ~test/src/VocalGame.cake~ function ~process-3d-assets~ for how to automate it.
** Blender setup
- Install [[][Blender]]. I can confirm Blender 2.91 works.
- Copy ~blender2ogre~ to Blender plugins:
cp -r Dependencies/blender2ogre/io_ogre/ ~/.config/blender/2.91/
- Open Blender, then open Preferences (Edit->Preferences), and click Add-ons
- Search for "Ogre" and check the box to enable the OGRE Exporter
- Build Ogre, if you haven't already (run
- Set ~OGRETOOLS_XML_CONVERTER~ to where you built OgreMeshTool. You'll need to browse to ~gamelib/Dependencies/ogre-next/build/Debug/bin/OgreMeshTool_d~
You are now ready to export. Open your model or create one, then do ~File -> Export -> Ogre3D~. See the following section for settings.
** OGRE Export Settings
- Don't *export materials*. These are v1 materials as far as I know, which don't work with Ogre 2
- Don't *export scene*. I don't use these files
- Ensure *mesh export version* is set to ~v2~
- Don't *export selected* only
** Materials and Textures
The ~blender2ogre~ plugin doesn't do much to help with Ogre v2 materials.
For a textured mesh:
- UV unwrap mesh
- Create new image for texturing
- Add a new material and set the diffuse input to your new image. Name the material what you'd like it to be called in the game as well
- Paint the texture as desired
- In the Image Editor window, do ~Image -> Save As~ and save the image to a lossless format (I used PNG)
- Run the following to convert the image to (which will be a larger file, but will load /drastically/ faster):
convert assets/MyTexture.png data/Materials/Textures/
- Export the mesh. Because export materials doesn't do us any good yet, we only export the mesh to get the updated UV coordinates and material (name only)
- Create a ~.material~ text file like below:
hlms MyMaterial pbs
roughness 0.4
fresnel 1.33
// normal_map Rocks_Normal.tga
// roughness_map Rocks_Spec.tga
// specular_map Rocks_Diffuse.tga
- Finally, add the material to the ~Ogre::Item~:
This is only necessary if the mesh didn't already have the Material name set.
** Converting ~.mesh.xml~ to ~.mesh~
You shouldn't need to do this step if you set ~OGRETOOLS_XML_CONVERTER~, but in case blender2ogre didn't recognize it, here's how I worked around it:
cd Dependencies/ogre-next/build/Debug/bin
./OgreMeshTool_d -e -O puqs ../../../../../test/data/Models/Suzanne.mesh.xml
Run this after you've made an attempted export from the Blender OGRE plugin.
** Animations
- Rig your mesh as you would normally in Blender
- Open the Dope Sheet, and switch mode to Action Editor
- Use the New button to create an action. The name you use here will be the name needed for the code (the animation name)
- Create the action's keyframes
- Open the NLA editor, and click ~Push Down Action~ to create an NLA track. Blender2Ogre uses NLA tracks to determine which animations to export
You can repeat this for all the different actions you want for a given skeleton.
The name of the skeleton comes from the name of the Object which has the armature modifier's mesh. This may mean shared skeletons will be created in duplicate due to having different object mesh names.