Custom Gobblegum Tutorial

Game Asset Reversing | Releases

func_vehicle:

Demo Video


Introduction
This tutorial will teach you how to create a custom Gobblegum (internally referred to as BGB), complete with an image, model, and custom effects.

Creating custom Gobblegums is a lengthy process, so be prepared to do quite a bit of work. This can be done either as a mod, or as a part of a map. You'll almost certainly want to use the map method as it doesn't need a mod to function, so players downloading your map won't need to find the mod for the map to work, but I've included steps for both for completeness. Skip over sections marked as 'MOD ONLY' if you are using the map method, and vice versa.

You'll need to use my custom Gobblegum machine if you want to dispense the Gobblegum (don't worry, it's better than the original anyway). If you haven't already got it, you'll learn more later in this tutorial.

Download this pack, which contains (almost) everything you'll need to create your custom Gobblegum and have it work on your map. The steps in this tutorial will refer to files in the corresponding folder of the zip.

This has taken a lot of researching to do, so there might be some errors in this tutorial. Let me know if you have any issues.

Step 0(Preplanning)
The first thing you need to do is think of what your Gobblegum is going to do. Changing its internal name, activation type, etc. later is not easy, so make sure you know what you want to call it and what you want it to do now. For this tutorial, I'll create a round-based (blue) Gobblegum with internal name func_vehicle, to keep it simple to understand. Just replace func_vehicle with your_gobblegum_name (lowercase, underscores as spaces) whenever you see it.

Step 1(Logo)
One of the most important assets you need to create is the Gobblegum logo. Open the Step 1 folder in the zip, which contains the background circle for the four types of Gobblegum. Open the background in an image editor and create a new layer on top of the background. Use pure white (255, 255, 255) to create the logo inside the coloured area. Once you're finished, save it in your image editor's format to preserve layers in case you want to edit it later. Then save it as a png, called i_mtl_p7_zm_bgb_icon_func_vehicle_c.png.

Step 2(HUD icon)
Another asset we need to create is the Gobblegum HUD icon. Open the Step 2 folder, which contains existing HUD icons for every colour and rarity combination. Open the image that matches the colour and rarity combination that you want in an image editor and create a new layer. Add the logo png you created in the last step to this new layer, and use your editor's tools to remove the white around the logo. Position your logo so that it perfectly covers the existing logo, while keeping the white outline. Create a third layer on top, and either use one of my premade 'magic layers' to make the logo look like it is shaded or create your own. To make your own magic layer, make a circular selection that matches the size of the logo area, and then use large, soft brushes of pure black or pure white at about 8-32/256 transparency. Then just try to recreate the shading effect.

At this point, you should compare your HUD icon to one of the base icons I have provided, to make sure they look similar enough. I've found you might need to boost the saturation on the logo layer to get the look to match up. Once you're done, save this twice, once in your editor's format and again as a png called t7_hud_zm_bgb_func_vehicle.png.

Step 3(APE 1)
Firstly, move your two created pngs to a suitable game folder. Personally, I used Call of Duty Black Ops III\texture_assets\custom_bgb. If you don't use this folder, you're going to have to change a lot of file paths.
While you're here, also move all the textures in the Step 3 textures folder to this location.

Now we need to set things up in APE. Drag the GDTs found in the Step 3 GDTs folder to Call of Duty Black Ops III\source_data.
You need to locate the zm_bgb_func_vehicle GDT in APE, and rename all instances of func_vehicle with your_gobblegum_name, including the GDT name itself and the assets names and properties.

We also need to quickly change some model textures. You need to open the XMODEL_EXPORT files in a text editor and scroll to the bottom. You'll see some filenames. Replace 'func_vehicle' in the lower pair with your_gobblegum_name, and the upper pair line with one of the following lines depending on colour and rarity:

Classic
MATERIAL 0 "mtl_p7_zm_bgb_regular_blue" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_regular_blue_c.png"
MATERIAL 0 "mtl_p7_zm_bgb_regular_green" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_regular_green_c.png"
MATERIAL 0 "mtl_p7_zm_bgb_regular_orange" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_regular_orange_c.png"
MATERIAL 0 "mtl_p7_zm_bgb_regular_purple" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_regular_purple_c.png"

Mega
MATERIAL 0 "mtl_p7_zm_bgb_mega_blue" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_mega_blue_c.png"
MATERIAL 0 "mtl_p7_zm_bgb_mega_green" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_mega_green_c.png"
MATERIAL 0 "mtl_p7_zm_bgb_mega_orange" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_mega_orange_c.png"
MATERIAL 0 "mtl_p7_zm_bgb_mega_purple" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_mega_purple_c.png"

Rare Mega
MATERIAL 0 "mtl_p7_zm_bgb_rare_mega_blue" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_rare_mega_blue_c.png"
MATERIAL 0 "mtl_p7_zm_bgb_rare_mega_green" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_rare_mega_green_c.png"
MATERIAL 0 "mtl_p7_zm_bgb_rare_mega_orange" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_rare_mega_orange_c.png"
MATERIAL 0 "mtl_p7_zm_bgb_rare_mega_purple" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_rare_mega_purple_c.png"

Ultra-rare Mega
MATERIAL 0 "mtl_p7_zm_bgb_urm_blue" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_urm_blue_c.png"
MATERIAL 0 "mtl_p7_zm_bgb_urm_green" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_urm_green_c.png"
MATERIAL 0 "mtl_p7_zm_bgb_urm_orange" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_urm_orange_c.png"
MATERIAL 0 "mtl_p7_zm_bgb_urm_purple" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_urm_purple_c.png"

Whimsical
MATERIAL 0 "mtl_p7_zm_bgb_whim_blue" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_whim_blue_c.png"
MATERIAL 0 "mtl_p7_zm_bgb_whim_green" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_whim_green_c.png"
MATERIAL 0 "mtl_p7_zm_bgb_whim_orange" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_whim_orange_c.png"
MATERIAL 0 "mtl_p7_zm_bgb_whim_purple" "Phong" "color:..\_images\i_mtl_p7_zm_bgb_whim_purple_c.png"

Once you've made the changes, use Export2Bin to turn them into XMODEL_BINs. Then move these bins to a suitable folder, this time I used Call of Duty Black Ops III\model_export\custom_bgb. Then, change LOD0 in both models in APE to the corresponding XMODEL_BIN.

A sign that you have done this correctly is the models (p7_zm_bgb_func_vehicle, p7_zm_bgb_func_vehicle_ui) will look correct in the 3D preview (use alt and drag left mouse to rotate the model). Don't worry about the camo (mtl_zmb_t7_camo_bgb_func_vehicle_i), that will still look untextured even if you have changed the color map property.

We need to do some more stuff in APE in the next step, so keep it open.

Step 4(APE 2)
Now we need to modify the camo list. You've already moved the required GDT (zm_bgb_shared) to the correct folder in the previous step. Find it in APE, and modify camo_t7_zmb_bgb_ship. Scroll down to Camo Type 64. This is the first available slot that we can add our Gobblegum, and this is the slot which the example uses. Each camo slot has two materials, and they each have a 'base material', and a 'replace with' property. Don't change the base materials. For Material 1, you want to change the 'replace with' value to the material used by a Gobblegum with the same type and rarity as yours. For example, because my Gobblegum will be round-based with a Mega rarity appearance, I will choose this material to be the same as Board Games, and thus will put 'mtl_zmb_t7_camo_bgb_board_games' as Material 1's replace with value.

Material 2 should be your camo material ie. mtl_zmb_t7_camo_bgb_func_vehicle_i.

You can ignore the 'Asset doesn't exist' warnings, it will work in game just fine.

The slot you choose is important, because it maps to a Camo Index which we will need later. Unfortunately, Treyarch has kind of fucked with this table internally, so it doesn't exactly work like you think it would. Camo Type 64 - 71 work, and they map to Camo Index 61 - 68 (just take 3 away to get index). Camo Type 72 - 75 don't work as already existing Gobblegums take up their respective indices for some reason. If you need more than 8 slots, move to the second file, camo_t7_zmb_bgb_base76.
Camo Type 76 and higher seem to map to one less in the Camo Index (ie. Camo Type 76 -> Camo Index 75).

Step 5(Modifying existing scripts)
To get our Gobblegum to work in game, we will eventually need to 'register' it. The register function definitions are not included in bgb gsc or csc skeletons by default, so we need to add them. Open Call of Duty Black Ops III\share\raw\scripts\zm\_zm_bgb.gsc in a text editor. Below the last line, add

function register(name, limit_type, limit, enable_func, disable_func, validation_func, activation_func) {}

function register(name, limit_type) {}

bubblegum

bubblegum_consumable

zmui_bgb_func_vehicle

zm_bgb_func_vehicle

t7_hud_zm_bgb_func_vehicle

zmui_bgb_func_vehicle_desc

equippedbubblegumpack

func_vehicle:

Step 8 (Coding the Gobblegum's effects)
This is the fun step! It's finally time to make your Gobblegum do something. Copy the files in Step 8 to Call of Duty Black Ops III\usermaps\your_map_name\scripts\zm\bgbs (or corresponding mod folder). Once you've renamed these files, open them in a text editor. In __init__(), we 'register' the Gobblegum. Here's what the parameters do:

Parameter 1 is your Gobblegum's internal name.
Parameter 2 is activation method. (rounds, time, event, or activated).
Parameters 3+ are only used in GSC.
Parameter 3 is the 'use limit'. For rounds, this is 'full rounds' (ie. 0 means till end of current round). For time, it's the time in seconds. For activated, it's the number of times it can be activated. For event, completely skip this parameter.
Parameters 4 and 5 are the enable / disable functions. Enable is called on receiving the BGB, and disable is called when the BGB is swapped or expires.
Parameters 6 and 7 are the validation / activation functions. These are only used on 'activated' (purple) Gobblegums.
The validation function should return true or false depending on whether the user should be able to activate the Gobblegum. The basic cases (drinking perk, downed, etc) are already taken care of, so you don't need to worry about them. An example of when you would need this is with a gum like In Plain Sight, where you don't want it to be activated again while the first use is still active.
The activation function is called when the bubble blowing animation is finished. Don't forget a

self endon("disconnect");

self thread bgb::run_timer(10);

self bgb::set_timer(3, 5);

self bgb::do_one_shot_use();

zm_bgb_func_vehicle

TRUE

FALSE

#using scripts\zm\bgbs\_zm_bgb_func_vehicle;

#using scripts\zm\bgbs\_zm_bgb_func_vehicle;

main()

LuiLoad( "ui.uieditor.menus.hud.t7hud_zm_custom" );
LuiLoad( "ui.uieditor.widgets.hud.zm_ammowidget.zmammo_bbgummeterwidget_fix" );
LuiLoad( "ui.uieditor.widgets.mphudwidgets.cursorhint_image_fix" );
LuiLoad( "ui.uieditor.widgets.hud.zm_cursorhint.zmcursorhint_fix" );

GreenDonut:

This is insane. Thank you for this and being extremely specific with the instructions. Much appreciated!