Creating a course
Creating a custom golf course may at first appear daunting, but is in fact reasonably easy to understand once the process is broken down into stages. This guide will attempt to describe those stages to aid in what is hopefully a fun and rewarding experience creating custom content for VGA Golf. The only software required is Blender (although other 3D software will work), and the current version of the mod kit, available in the repository or on itch.io.
A course is made up of one or more holes, and is described to the game through a configuration file. The configuration file is detailed later in this guide, and also has its own document describing the format in the mod kit directory, named course_format.md. Making a hole for a course is composed of several steps.
- Creating the geometry. That is the 3D mesh that makes up the terrain seen in the game.
- Masking the geometry with collision data. This controls how the ball will interact with different parts of the hole.
- Assigning materials to the geometry. Each different terrain type requires its own material, that not only defines how it appears in game, but how the game engine assigns the collision mask.
- Sculpting the landscape. This optional step allows crafting the rolling terrain which appears around the edge of the hole.
- Baking the terrain texture. This texture (described in the
course_format.mddocument in the mod kit) is used to place in-game generated vegetation, and describe the height map for the surrounding landscape. - Placing game data. Each hole needs to have data describing the tee and pin positions, as well as optionally any prop models placed for decoration.
- Exporting and converting the data from Blender and importing it into the game. This is handled by the software included in the mod kit
While these steps are entirely possible in other software, the mod kit also includes some template files and scripts which are intended to speed up the hole creation process, and to which this guide will frequently refer.
The first time you create a hole you'll need to take a few steps to prepare Blender for the rest of this guide. However these only need to be done once. The most obvious step, if you haven't done so already, is install Blender. It's available to download from blender.org, as well as on Steam, if you prefer. Once it is running there are a couple of useful add-ons that can be enabled, which help creating a hole. Go to file->preferences then select add-ons. The first is included with Blender and can be found by typing palette in the search box. In the results below check the box next to Import Palettes.
This enables importing Photoshop .ase palettes and Krita .kpl palette files into Blender. As creating a collision mask for a hole requires painting parts of the geometry specific colours then it is very convenient to be able to import palettes of these colours into your project. The palette files themselves are included as part of the mod kit, named collision_colours.ase and collision_colours.kpl.
With the preferences still open click the install button and browse to the mod kit directory. In there is a file named prop-export.py which enables exporting the hole data from Blender directly to the hole configuration file used by the game. Select this to install it and enable the export option (by clicking the check box in the lower pane) in Blender. This is optional, of course, the configuration file is a text document which can be created manually (and described in full by course_format.md in the mod kit directory), but using this add-on can speed up creation time significantly.
If you are new to Blender then it will also be worth taking the time to learn a few basic commands. This guide is not a Blender tutorial, although there are plenty out there, such as those by Grant Abbitt on YouTube. When creating a hole it's worth knowing basic commands such as switching between Object and Edit mode, switching between Vertex, Edge and Face selection mode, and learning how to Grab, Rotate and Scale geometry. It maybe also be worth looking into tools like the knife tool, basic sculpting, and basic UV editing. If you feel you have a good handle on these topics, then read on!
As stated, this guide is not meant as a Blender tutorial. It'll not cover mesh editing specifics, but rather try to explain some of the rules necessary for the creation of hole geometry. The mod kit contains a Blender file named hole_template.blend which has many basic properties required by the game already set up. You can open this file (in Blender 2.9 and above) then save it as a new one to prevent accidentally modifying the template. The first rule of hole geometry is never talk about hole geometry is that it should fit in an area of 320 Blender units in the X direction and 200 in the Y direction. A unit in Blender is translated to one metre in game units. When looking down from the top view 0,0 (the origin) should be in the bottom left hand corner of the model. The template file has an Image Object which is already sized and placed to these dimensions. In the Image Object properties you can select an image from your hard drive to display, which can be useful if you have 2D designs for your course. With an image loaded it is quite simple to model your geometry around your design.
When creating the geometry consider that the hole needs at least some Fairway type terrain and a Green on which to place the pin. It is also usually preferable to surround the hole in Scrub type terrain, which the game will use to mark the ball 'out of bounds' if it goes off-course. Note that the green area of the hole shouldn't be much larger than about 5-6 units in radius, else this will lead to long and tedious putts on the part of the player. In the template project there is a circular shape object named green diameter which can be used to gauge the size of the green area in the hole model, if you prefer.
Another helper included in the template file is a plane named water. This indicates the water level in the game, and should not be moved. Changing this plane will not affect the in-game water in any way, it is included in the Blender file so that you can see where the water may intersect your geometry. Modifying the size or position of the water plane will probably only cause incorrect results! If the plane appears to be in the way when modelling in Blender then it can be hidden using the layer view in the top-right window, by clicking the eye icon next to the water plane. If you do accidentally move the water plane then by default it is placed at -0.2 units on the Z axis, so moving it back to this position should fix it.
VGA Golf reads collision data from the hole model by looking at the vertex colours of the mesh faces. Each terrain type has a specific colour as follows:
- RGB (05,05,05) or (0.020, 0.020, 0.020) normalised: Rough
- RGB (15,15,15) or (0.059, 0.059, 0.059) normalised: Fairway
- RGB (25,25,25) or (0.098, 0.098, 0.098) normalised: Green
- RGB (35,35,35) or (0.137, 0.137, 0.137) normalised: Bunker
- RGB (45,45,45) or (0.176, 0.176, 0.176) normalised: Water
- RGB (55,55,55) or (0.216, 0.216, 0.216) normalised: Scrub
- RGB (65,65,65) or (0.255, 0.255, 0.255) normalised: Stone
To simplify things a bit you can import a palette of these colours directly into Blender. If you don't have palette import enabled, see Setting Up (above) for how to do this. Then go to file->import->ase (or kpl) palette. Browse to the mod kit directory and click on the collision_colours palette file. Then, when in Edit mode, select the faces you want to paint, for example the faces of the Green, then switch from Edit mode to Vertex Paint mode. Rather than paint directly on the mesh, you can use the face mask button
to make sure the colour is only applied to the selected faces. On the right open the palette panel, and select the collision colours pallete from the name drop down. Here a new swatch of grey colours should appear. Unfortunately Blender loses the name for individual colours on import, however they should be ordered as they are listed above.
Selecting the third grey square will set the active colour to that of the Green terrain collision. Press ctrl+k and the active colour will then be applied to the selected faces. Switch back to Edit mode, select the next set of faces for the next terrain (for example, the Fairway) then repeat the process. Make sure you do this for all face in the model. If you set the material preview to flat shaded with vertex colours you will be able to see the different terrain areas:
For each terrain type on the hole geometry, VGA Golf requires a specific material. To this end the hole_template file includes a set of materials which are already prepared with terrain name, default textures (although they can be changed to anything you like), as well as being configured in advanced for the terrain texture baking step, below. It's probably most practical to assign materials when in the UV Editing workspace in Blender, as it also offers instant feedback and quick iteration on an UV mapping which might be required. To assign a material select the geometry faces in the mesh edit window, click on the materials tab, highlight the appropriate material in the list then click Assign. If the viewport shading is set to Texture then the edit window will immediately update with the new material.
It is important that each terrain type has its own material assigned as the game engine uses the materials to split the mesh when it's loaded, before it then examines the vertex colour to decide which type of collision should be applied. Once materials are assigned the geometry steps for creating a hole are complete.