Adding chapters to your mod

Chapters are used to split single-player mods down into manageable chunks. They give your story more structure and allow players to jump into the game half-way through if they so desire. They can also be used to control which background maps/images are displayed.

Adding chapters to your mod is a little complicated, because you need to modify a number of files in order to add new chapters.

Scripts

Registering a chapter

Create <mod>\cfg\chapter1.cfg. This will create a chapter, and contains the console commands that the game will run when it is started. Typically just:

map <first map of the chapter>

Do this for all your chapters.

Localising names

Create (or open, if it exists already) <mod>\resource\<mod>_english.txt (or _french, _japanese, etc). This is your mod's localisation file, where you write the unicode titles for your chapters.

Yours should look something like this:

lang
{
	Language "English"
	Tokens
	{
		modname_Chapter1_Title	"Chapter 1 title"
	}
}

If there are existing tokens in the file, don't remove them. Just add yours somewhere.

 Note: Localization files must be saved in the UCS-2 Little Endian format. In Notepad's "Save As..." dialogue this is called "Unicode".

 Note: Wrap any keys or values with whitespace in "quote marks".

Fixing on-screen titles

<mod>\scripts\titles.txt defines what appears on-screen when a new chapter starts.

Find the "chapter titles" section and modify it like so:

//CHAPTER TITLES

$fadein 0.01
$holdtime 3.5
$position -1 0.58

CHAPTER1_TITLE
{
#YourModName_Chapter1_Title
}

This file should be saved as normal ANSI.

Images

Thumbnails

You need to create thumbnails for each of your chapters. They should be in <mod>\materials\vgui\chapters\ and named chapter1, chapter2, chapter3 etc.

 Note: The images displayed in the new game dialogue are 152x86. Since texture dimensions must both be a power of two, your VTFs will be 256x128 with a border to the right and bottom.

 Note: Since these are UI textures, they should be compiled without mipmaps and with level of detail disabled. The VTEX commands for this are nomip and nolod.

Your material should look something like this:

"UnlitGeneric"
{
  "$baseTexture" "VGUI/chapters/chapter1"
  "$vertexalpha" 1
}

Backgrounds

<mod>\scripts\chapterbackgrounds.txt ties background maps and images to chapters. A background will not be used until the chapter it is associated with has been unlocked (see next section).

Here is what it might look like:

chapters
{
	1	"my_background01"
	2	"my_background02"
	3	"my_background03"
}

Each value should be the name of a map in <mod>\maps\ (unless you don't want background maps at all) and a material in <mod>\materials\console\. It's okay to omit a chapter.

See Menu Background Map for more details.

Maps

Unlocking chapters

By default, all chapters except the first start off locked. Unfortunately, Valve's not-terribly-good method of unlocking requires your maps to have the same names as theirs!

You can overcome this issue by starting your mod off with all chapters unlocked (edit the sv_unlockedchapters line in <mod>\cfg\config.cfg), or by changing your mod's programming. Hacking it within maps is not recommended.

Equipping players

Players who start a new game at a chapter half-way through your mod will drop into the world without any items. To equip them with the weapons and other goodies they are supposed to have, use a logic_auto's OnNewGame output to spawn a point_template.

The map list

This is not necessary but is used to easily find the names of maps without quitting and relaunching the game.
Create <mod>\maplist.txt and list of maps that your mod will use. For example:

Map1
Map2