Admin Resource: The Custom Campaign


(Susefreak) #1

Custom Campaign Creation

A big issue in ETQW is to get “custom content” working. Escpecially on the server side. It’s not a case of dump the files and put them in a certain directory. This is only a part of the equation. There is something extra to it, wich I hope I can make clear in this file.

§1: Prerequisites

There are only a few tools you need:
[I]Windows, Linux, OSX, BSD, Solaris, Minix:
A zip client (7-zip, Win-zip, etc.)
Text-editor (Notepad++, Nano, Vim, Emacs, xcode, etc.)
ETQW (How obvious)
ETQW Server client (optional, just for testing and easy capturing of hashed values)

  • A basic knowledge of the idTech4 engine specifically ETQW
    This is all you need.[/I]

The zip client is needed for packaging or unpacking the .pk4 files.

§2: Let’s get on with it

Making a custom campaign might sound challenging but it certainly isn’t. After you’ve seen it it’s just like a walk in the park. There are a lot of mistakes that you can make, some that you only may notice when you’ve already tried to run the game.

The pk4 with the content for your custom campaign is nothing but a zip file with directories and files.

Starting off I suggest making a directory tree that is the same as this:

[B][I]	-- $root of custom campaign$
	    |-- addon.conf							(§3)
	    |-- def
	    |   `-- campaigns
	    |       `-- $name-of-your-custom-campaign$.def		(§4)
	    |-- script
	         `-- map.script						(§5)[/I][/B]

This tree shows what the file names are and where you need to put them.
The presented lay-out is essential for a working custom campaign.

§3: addon.conf

This file is essential. In this file you put the map file names you want to use. Not only the human readable file names, but also the engine readable file names.

You might be thinking “engine readable file-names???!?!” Yes, in order to make the engine understand what to load, it hashes the files in the ETQW directory. How do you know what hashes are made for which map? Simple just check link underneath, it has all the available hashes for most custom maps out there:
http://www.bravehardt.com/TAW/Quake_Wars/Susefreak/Public_Files/checksums.txt

Now it might be that you have a new custom map, that is not available over there, you can also check your console.log located in your ETQW directory. In that log you see the game engine perform the hashing and checking the files.

In order to make the game read the you need to define what to load. Underneath is an example of a custom campaign’s addon.def.

//====-begin of example-==========================================

addonDef {
// maps
//	"0x9fdd62e9" 	// arcis_a1
	"0xa5b0b6c7" 	// arcis_a2	

//	"0x8b634e7f" 	// atw3_b2
//	"0x290b0ed"  	// atw3_b3	
	"0xbeb782e8" 	// atw3_b4

//	"0x4790a6ad" 	// andes_a2
//	"0xd2756032" 	// andes_a2_1 hotfix
//	"0x6d09d77"  	// andes_a3
//	"0x8739ba48" 	// andes_a4_1
	"0xac5a69"   		// andes_b1

//Mega-textures
	"0x1796c6c1"		// arcis_a2_mega1
	"0xd6fbd3bd"		// atw3_b4_mega1

}

campaignMetaData campaign_example {
    "pretty_name"       "^4Example ^2Campaign"
    "server_shot_thumb" "levelshots/campaigns/thumbs/pacific.tga"
    "show_in_browser"   "1"
}

//==========================================-end of example-====

As you can see there are only 3 maps included in here. For documentation reasons in this file the are the older version of the maps included, yet as you can see also commented out to avoid conflicts on the server and client.

Below those maps you see related mega textures. These files are also needed. You can run without these if you want, but there is a downside to it not including these files in the addon.def, that is that the game engine will reload itself when the map changes, which means that players will need to rejoin the server once the next map is loaded. Hence the earlier stated issue that the corresponding megatexture files are also included. Once included the game engine loads the megatextures when the campaign is loaded.

At the end of the file you see the campaignMetaData. This part of the file tells the engine how to present the campaign to the end user in the ui and console.

The pretty name as you can see understand colour codes, so you can give your future campaigns the colours of your likings. With the servershot you can show an image that you want to loading screen for the end user. I suggest using images from the base ETQW in order to not complicate things even more for you or end-users. (I always use pacific, since I know this one works). The show in browser option allows end users to load the custom campaign using the UI. If not the user only can load it using the command line. Always keep this on, for everyone’s comfort.

In this example I’ve only made 1 campaign. There can be alot more

Base_ETQW only supports 3 maps on each loading screen, but ETQW:PRO and QWTA support up to 12 maps on the loading screen of the campaign.

§4: $name-of-your-custom-campaign$.def

This is just a reminder for your file. It can be a generic name, but for troubleshooting it is suggested that you use an easy and corresponding name. Something like ilovesheep.def or headache.def will do. It is up to your creativity.

//====-begin of example-==========================================

campaignDef campaign_example {
   map "maps/arcis"
   map "maps/andes"
   map "maps/atw3"

    data {
        "mtr_backdrop" "levelshots/campaigns/pacific"
    }
}

//==========================================-end of example-====

The obvious stuff is posted again. The campaignDef, as the abreviation says defines the campaign. This needs to correspond with the campaignMetaData in the addon.conf for obvious reasons.

Next up is the rotation of the maps. First Arctic Assault is used, then andes and last but not least ATW3. These paths come from the map.pk4 it self. Just unzip a map.pk4 and open it’s corresponding addon.conf, in the line mapMetaData line you see that most maps come from maps, but there are some deviations on this rule like TEVallhalla, which requires “maps/TEVallhalla/TEVallhalla”. Yet as a rule of thumb it’s “maps/”.

Then there is the data, this also has to be corresponding with the file in addon.conf, yet must not be the same path, since in the addon.conf a thumb in loaded, while this should not load a thumb.

§5: map.script

Every map has some scripts for the gameplay, which we also need to load on the campaign. A simple link to the file will do, but this can also be used to run complementary scripts. This will not be covered in this main segment, but is available in Appendix A.

//====-begin of example-==========================================
// Optional - for megatexture load on server start
// Delete/comment out the following, unless you have the required mega2 packs!
#include "script/mega/arcis_mega.script"
#include "script/mega/atw3_mega.script"
#include "script/mega/disobj_mega.script"

// Required, if you want to avoid restarts on map changes

#include "script/maps/arcis.script"
#include "script/maps/atw3.script"
#include "script/maps/andes.script"

//==========================================-end of example-====

The scripts you need to run for the gameplay need to be included, as well as the mega-textures. These are required to avoid map changes.

Yet again the question is, how do I know the path for the script? Well that’s also pretty easy, take a look at the unzip corresponding map file but this navigate to the script directory and open map.script. (make sure the correct file is opened :P)

§6: Now what?

Go back to the root of your custom campaign, so you see
*def-dir
*script-dir
*addon.conf

Now create a zip file with the prefix zzz_ and place the above mentioned files in there.
Name the zip to your preference, but with the prefix zzz_ and rename the extenstion to .pk4 instead of .zip.

(Note: Campaigns don’t need the zzz_ prefix, but this is done to keep track of the custom campaigns!)

Tip: On operating systems with a bash-shell just run this command in the root of your custom campaign dir:

[I]test@test$ zip -r zzz_example.pk4 *[/I]

Take your freshly created file and place it in the mod you want to run your custom campaign in. So if it’s qwta, place it in qwta, etc…

Also make sure you have the corresponding maps in your /base direcory.

Launch a server and spawn the server on a normal campaign, then switch it over to the custom one. (This should always be done, when loading a custom campaign, even on already launched servers)

§7:Troubleshooting

If for some reason you get a reason. Look at your server’s console.log, it will spit out an error and this enables you to backtrace the possible mistake that took place.

Appendix A: Pimping your custom campaign

Now that you’ve made a custom campaign wouldn’t it be nice to have a cool load screen?
That’s possible, there are some requirements to the image you can use though.
Basically the image needs to be a tga file without an alpha channel and needs to match in the power of two: so 128x128 512x512 and so on. I personally suggest using a file with a resolution of 1024x1024 just because that looks nicer.
Also make sure the images are in the corresponding directories (see below)
Again start of with this directory tree.

[B]	-- $root of custom campaign$
	    |-- addon.conf							
	    |-- def
	    |   `-- campaigns
	    |       `-- $name-of-your-custom-campaign$.def		
	    |-- script
	    |     `-- map.script						
	    |-- levelshots
	    |   `-- campaigns
	    |       |-- custom.tga
	    |       `-- thumbs
	    |           `-- custom.tga
	    |-- materials
	         `-- custom.mtr[/B]


This will only cover the parts that are added or altered.
Starting of again with the addon.confg:

//====-begin of example-==========================================

addonDef {
// maps
//	"0x9fdd62e9" 	// arcis_a1
	"0xa5b0b6c7" 	// arcis_a2	

//	"0x8b634e7f" 	// atw3_b2
//	"0x290b0ed"  	// atw3_b3	
	"0xbeb782e8" 	// atw3_b4

//	"0x4790a6ad" 	// andes_a2
//	"0xd2756032" 	// andes_a2_1 hotfix
//	"0x6d09d77"  	// andes_a3
//	"0x8739ba48" 	// andes_a4_1
	"0xac5a69"   		// andes_b1

//Mega-textures
	"0x1796c6c1"		// arcis_a2_mega1
	"0xd6fbd3bd"		// atw3_b4_mega1

}

campaignMetaData campaign_example {
    "pretty_name"       "^4Example ^2Campaign"
    "server_shot_thumb" "levelshots/campaigns/thumbs/custom.tga"
    "show_in_browser"   "1"
}

//==========================================-end of example-====

Now as you can see the filename for the image changed from pacific.tga to custom.tga. That’s the image we want to use for the ingame server browser. So far nothing too difficult here.

Next the campaign.def:

//====-begin of example-==========================================

campaignDef campaign_example {
   map "maps/arcis"
   map "maps/andes"
   map "maps/atw3"

    data {
        "mtr_backdrop" "levelshots/campaigns/custom"
    }
}

//==========================================-end of example-====

Same story, yet now it’s just levelshots/campaigns/custom rather then pacific.

Moving on to a new file: custom.mtr
Basically this file is needed to get a image to show up on the big load screen when you join the server, where you usually see the map of the continent.

//====-begin of example-==========================================

	material levelshots/campaigns/qcon {
		 sort gui
		{
			vertexColor
			map nopicmip clamp	"levelshots/campaigns/custom.tga"
		}
	}
//==========================================-end of example-====

Basically this file defines that this image should be loaded on the load of your campaign and makes it show up ingame.
You will know that you messed up when you only see a black image.

Now that should be it, zip it, rename it, put it on the server and and enjoy your campaign!

Credits:
I would like to thank:

Scrupus
RR02D02
Hannes
Azuvector
Mxyzptik
Timestar
Geppy
and everybody else who created custom content for ETQW and to all the players who help keeping it alive.

//==================================================-end-====

Document created by Susefreak (susefreak@gmail.com)
File can be distrubuted under the Creative Commons Share Alike license. (cc by-sa)
More info on: http://creativecommons.org/licenses/by-sa/3.0/legalcode

URL to the .rtf file: http://www.bravehardt.com/TAW/Quake_Wars/Susefreak/Public_Files/Custom_Campaign_creation.rtf

Also for the people using notepad++ for their cfg’s/game editting: A User Defined Language File: http://bravehardt.com/TAW/Quake_Wars/SmokeScreen/resources/notepad++/userDefineLang.xml


(Scrupus) #2

Nice guide, thanks for writing it! :smiley:

Would maybe look better if you use BB code for the code examples.

/me vote for sticky thread, so we can add other campaign tricks and solutions here :slight_smile:


(light_sh4v0r) #3

Nice, that should be helpful!


(Susefreak) #4

Quick update: A fun extra campaign
A campaign that yo can load and add a new vehicle in during the gameplay: A bicycle (courtesy of Luddens Desir)
http://www.bravehardt.com/TAW/Quake_...zz_bicycle.pk4
Just place it in the known game directory and load the bicycle campaign.
You should be a able to spawn a bicycle using spawn vehicle_bicycle


(Susefreak) #5

QWTA vehicles on some maps

Hey folks, new update.

QWTA introduced new vehicles to the game, the jupiter and the abaddon.:stroggbanana:
Now to get the fullest out of them they have been placed in some maps. TAW is already using these.

Implementation: Use you normal campaign file and go into the root of it. Create a dir called maps.
In the dir you place the .entities files for the maps you want to use the vehicles on, like sewer.entites. The can be found in the same subdirectory, but then just from pak007.pk4.

Look throught the .entities files for the exact changes and see how they are build up.
Enjoy.
Area22
Canyon
Island
Outskirts
Refinery
Sewer
Slipgate
Valley

To get the exact positions, go ingame and drop the console and type:
getviewpos The first 3 values are only relevant.
The rotation is based on Euler Angles Theorem for the people interested, easiest way is to nick it from existing vehicles, but if you’d like you can do the math :eek:

People can also use if for other vehicles too, or player spawns, the whole shebang

And here’s a complete campaign to run with:
The campaign:infiltrator:
Put it in the qwta dir and load the qwtavehicles campaign.

Have fun.


(DrFunkenstein) #6

I tried to create a custom campaign with stock maps but it doesn’t show up in the admin tab when I connect to a local dedicated server.

I’d appreciate it if anyone could have a look at it and tell me what’s wrong with it (it’s probably something very stupid!). You can find the custom campaign in the attachment to this post and I had to chang the extension to zip so I could upload it. It’s a pk4 file on my local system.

Thanks in advance.

Dr. Funkenstein

P.S. Wanted to delete the attachment, but I have no idea how…


(Runeforce) #7

I have an idea, but not sure that it will work. At least you can try it out, see if it does any difference.

In your Addon.conf, instead of:

campaignMetaData custom_africa

write

campaignMetaData campaign_customafrica

Same with your def file. Instead of writing

campaignDef custom_africa

write

campaignDef campaign_customafrica

(DrFunkenstein) #8

Thank you for your suggestions, I’ll try those and post my results with those changes.

Dr. Funkenstein


(DrFunkenstein) #9

Sorry for taking so long to reply but I finally figured out what was wrong with the custom campaigns I created: I wasn’t consistent in naming them. The names in addon.conf weren’t the same as the names in the def file.

I knew it would be something stupid, it always is :mad: .

Thanks for the tutorial and the suggestions, Runeforce, and credits should go to Donnovan as well. He was kind enough to create a custom campaign for OCB some time ago and I used that as a basis. Mistakes in my original attempt were mine alone.

I’m glad it’s working now and here’s the correct version of the custom campaigns I created as a zip file.

zzz_stockmaps_remix.zip (2.26 KB)

The thing I did was:

  • remove the 3 stock maps I don’t like at all (Outskirts, Quarry, Ark);
  • create 3 campaigns instead of 4 with the 9 remaining maps to keep the format of the Vanilla game;
  • tucked Salvage to the tail of the North America campaign because I think it’s one of the best maps and I definitely didn’t want to lose that one.

Africa and Pacific didn’t change, the order for North America is Valley, Area22 and Salvage.

It’s the maps people are used to in the format people are used to with a bit of rearranging. I hope I can convince PV or Villa to give this a try.

Dr. Funkenstein


(Kl3ppy) #10

I’ll help you with villa :slight_smile:

Anyways, thanks fo having a look at this, I’m really looking forward to play the new NA campaign :slight_smile: