GameLib

• Setup
  • Building Ogre tests
  • Setting up for your project
  • Cleaning test
  • Platform setup
    • Ogre
    • SDL2
• Module platform support
• Automatic downloading
• Terms
• Ogre Asset pipeline
  • Blender setup
  • OGRE Export Settings
  • Materials and Textures
  • Converting .mesh.xml to .mesh
  • Animations

GameLib started as a library for making games, but became a collection of generally useful modules for desktop applications as well.

GameLib is written in Cakelisp.

Setup

Please see cakelisp/doc/Tutorial_ProjectSetup.org for a step-by-step tutorial on how to set up a project to use Cakelisp and GameLib. Shorter instructions follow here.

Clone the repository:

git clone https://macoy.me/code/macoy/gamelib.git

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/
  ./Build.sh

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 https://macoy.me/code/macoy/cakelisp/ Dependencies/cakelisp
  git submodule add https://macoy.me/code/macoy/gamelib/ Dependencies/gamelib

Then, copy the following script (you get the idea - build cakelisp, then build your project):

#!/bin/sh

CAKELISP_DIR=Dependencies/cakelisp

# Build Cakelisp itself
echo "\n\nCakelisp\n\n"
cd $CAKELISP_DIR
./Build.sh || exit $?

cd ../..

CAKELISP=./Dependencies/cakelisp/bin/cakelisp

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:

  ;; 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

  ./test/RemoveSubmodules.sh

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.

SDL2

On Ubuntu/Debian:

  sudo apt install automake autotools-dev libtool libegl1-mesa-dev

You may need to add libwayland-dev, but I'm not sure.

Testing wayland support:

  pkg-config --exists 'wayland-client >= 1.18' wayland-scanner wayland-egl wayland-cursor egl 'xkbcommon >= 0.5.0'
  echo $?

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
Allocator.cake	Yes	Yes	Yes	Yes
Aubio.cake	Yes
AutoTest.cake	Yes	Yes	Yes	Yes
AutoUpdate.cake	Yes		Yes
AutoUpdateApplication.cake	Yes		Yes
Compression.cake	Yes		Yes
Config_ZigCompile.cake	Yes
Config_ZigWindows.cake	Yes
Cryptography.cake	Yes		Yes
Curl.cake	Yes		Yes
DataBundle.cake	Yes	Yes	Yes
Dependencies.cake	Yes	Yes	Yes
Dictionary.cake	Yes	Yes	Yes	Yes
DynamicArray.cake	Yes	Yes	Yes	Yes
FileDialog.cake	Yes	Yes	Yes
FileSystem.cake	Yes	Yes	Yes
FreeType.cake	Yes		Yes
Hash.cake	Yes	Yes	Yes	Yes
HashStringTable.cake	Yes	Yes	Yes	Yes
Image.cake	Yes	Yes	Yes
ImGui.cake	Yes	No[1]	Yes
ImGuiSDLOpenGL.cpp	Yes	No[1]	Yes
Introspection.cake	Yes	Yes	Yes	Yes
KeyManagement.cake	Yes	Yes	Yes	Yes
Licenses.cake	Yes	Yes	Yes	Yes
Math.cake	Yes	Yes	Yes	Yes
Network.cake	Yes	Yes	Yes
Noise.cake	Yes	Yes	Yes	Yes
Ogre.cake	Yes
OgreInitialize.cake	Yes
Oniguruma.cake	Yes		Yes
OpenGL.cake	Yes	No[1]	Yes
OpenSSL.cake	Yes
ProfilerAutoInstrument.cake	Yes	Yes	Yes	Yes
ProfilerNull.cake	Yes	Yes	Yes	Yes
Protocol.cake	Yes	Yes	Yes	Yes
Raylib.cake	Yes
RemoteCommands.cake	Yes	Yes	Yes	Yes
SDL.cake	Yes		Yes
STB.cake	Yes	Yes	Yes	Yes
TaskSystem.cake	Yes		Yes
TinyCCompiler.cake	Yes		Yes
Tracy.cake	Yes
VersionedData.cake	Yes	Yes	Yes	Yes
WindowsHeader.cake	Yes[2]	Yes[2]	Yes
XML.cake	Yes	Yes	Yes	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

• Compression.cake

• Cryptography.cake

• Curl.cake

• ZigCompile.cake[3]

• Dictionary.cake

• DynamicArray.cake

• FreeType.cake

• Image.cake

• ImGui.cake

• Math.cake

• Noise.cake

• Ogre.cake

• OgreInitialize.cake

• Oniguruma.cake

• OpenGL.cake

• OpenSSL.cake

• Raylib.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 <macoy@macoy.me>.

Licensed under GPL-3.0-or-later.

Contact macoy@macoy.me 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 BuildDependencies_Debug.sh)

• 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 .dds (which will be a larger file, but will load drastically faster):

    convert assets/MyTexture.png data/Materials/Textures/MyTexture.dds

• 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
  
        diffuse_map		MyTexture.dds
        // normal_map		Rocks_Normal.tga
        // roughness_map	Rocks_Spec.tga
        // specular_map	Rocks_Diffuse.tga
    }

• Finally, add the material to the Ogre::Item:

   item->setDatablock("MyMaterial");

  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.