Custom Golf Balls
This guide covers creating and adding your own golf balls to the golf game (VGA Golf). Golf balls can be chosen by the player during avatar creation, and can be shared between clients so that they appear in network games.
Custom balls can be created in any 3D software which supports exporting to glTF, and in this guide we'll use the free software Blender. To create custom balls you'll also need the game engine model importer, which can be built from source in editor directory of the crogine repository, or binaries for Windows can be downloaded in the mod-kit from the itch.io page. The mod-kit also contains a Blender project with a ball model template.
The ball model geometry is very simple, and also needs very little detail. If you're not using Blender then it is important to note that the measurement units should be set to metres, and that the diametre of the ball is 0.042 units - ie 42mm across.
Note also that the origin of the ball is at the bottom of the geometry, not the centre.
Golf balls do not currently support texturing - instead their colour can be modified by using their vertex properties. In Blender this is done with vertex painting.
You are of course not limited to 'ball' shapes - although be aware of how little detail will show up in game. For example it is possble to make something a little more fanciful:
Once the geometry is complete you will need to export it from your 3D software as a glTF binary which has an extension of *.glb. When exporting make sure that you export only the selected geometry (and that the ball is selected), and that you include the vertex colour properties. UVs can be omitted as they will be ignored, and will make the final file slightly bigger if included. In Blender the export settings look like this:
Note that any coordinate system that you use should be converted so that the Y axis is up. Save the glTF file to somewhere on your hard drive.
Once the model is exported it needs to be converted to a file that crogine / VGA Golf can read. This is done with the model converter program, included either as part of the mod-kit download, or can be built from source in the editor directory of this repository.
The very first time you run the editor you will need to set the working directory so that it knows where the assets of the golf game are. This can be done from View->Options then clicking Browse in the new window which appears. Browse to the directory where the golf game is installed, which contains the assets directory.
With that done (it only needs to be done once) you can now import the glTF binary by clicking File->Import Model.
A new window will appear listing all of the models found in the glTF file. It will most likely have the same name as the model you exported from the 3D software, in this case 'Sphere'. If your modelling software uses sRGB colour space (the default in Blender) make sure to also check Convert Vertex Colourspace which will re-adjust the vertex colours to linear RGB, used by the game engine.
If all goes well a grey preview of the model will load into the main window. On the panel on the left make sure the Model tab is selected, which will display information about the imported data. If something went wrong further information is printed at the bottom of the editor window, or can be viewed in detail by opening console window by pressing F1. Make sure the vertex attributes section includes colour. If this is missing go back and make sure the vertex colour data is properly being exported to the glTF file.
Once you are happy that the model imported correctly, click the Convert button. If this is not the first time you have imported this particular model, and you wish to preserve the existing material, you can check Export Model Only. This will make sure to only overwrite the model data leaving the material data intact. Browse to the golf/assets/golf/models/ directory and save the file with a suitable name.
The model will re-open on success and, if you are not using an existing material, will be coloured magenta. In the left hand pane click the Material tab. Make sure the Shader Type is set to Unlit, the diffuse colour is white, and that Use Vertex Colours is checked. The preview window should update to show the correct colours.
Click File->Save to save the updated material, then close the importer.
Finally, for the game to be able to see the new ball, we need to create a ball definition file. This is merely a text file which you can create in any plain-text editor, that contains some meta-data about the model. Open your favourite editor, such as notepad++, sublime text or whichever you prefer and create a new blank file. You can copy and paste the following into it, and modify it to suit your needs:
ball
{
model = "assets/golf/models/my_ball_model.cmt" //path to the ball model file
tint = 0.23, 0.44, 0.288, 1 //this is the tint colour of the ball as it is seen from a distance. Omitting this will use a white colour.
uid = 45 //this must be unique. UIDs will be ignored if a ball file has already been loaded with the given UID
}
The tint colour is in normalised (0 - 1) values, as used by Blender and OpenGL. To convert an 8-bit colour simply divide the value for each channel by 255. For example 100 / 255 = 0.392. Note that the 4th value MUST be 1, ie have an alpha value with no transparency. Ball models are synchronised across network games via their UIDs. If a ball has no matching UID on a client, then the default ball model is loaded. This can usually be left blank as the first time a ball is loaded VGA Golf will generate a UID for you. You must share your ball definition and model files with all clients should you want other players to be able to see them. Save the definition file to the golf/assets/golf/balls/ directory with the extension *.ball. Run the golf game, and if you were successful the new ball will appear in the player customisation menu!
If you create any of your own balls, please share them either on Twitter or on the VGA Golf page as I would love to see them!