Absolute beginners guide to sending clients pk3s

The full title of this tutorial should be “Absolute beginners guide to getting FTE clients to automatically download the files they need, while allowing older (non-CSQC compatible) clients to connect without crashing”. Or “How to make a modern Quake engine (CSQC, shaders, particles, iqms etc ) compatible with older clients, so that they can also connect”.

Traditionally. by using precache_ functions, and making sure the files are on your server, Quake clients automatically download the files below.

LIST ONE: Files which Quake clients can automatically download from Quake servers
1. models (*.mdl) / precache_model()
2. iqms (*iqm) / precache_model()
3. the iqm’s image files (*tga, *.png, *.jpg) / precache_pic()
4. particle scripts (*.cfg)  /particleeffectnum()
5. images (*tga, *.png, *.jpg) /precache_pic()
6. maps (*.bsp)/ automacically downloaded when connecting
7. csprogs.dat/ automacically downloaded when connecting
8. sounds (*.wav) / precache_sound()
9. charset / precache_pic()
10. skyboxes (image files)/precache_pic()

But not all files can be sent in this way. Here’s a list of files which (normally) have to be manually downloaded by players:

LIST TWO: Files which Quake clients CANNOT automatically download from Quake servers
1. real time lighting files (*.rtlights)
2.  *.lit files
3.  *.lux files
4. shaders (*.cfg)
5. glsl file (*.glsl)
6. default.cfg
7. qwprogs.dat // only needed for single player games

Normally these files (ie both the above lists) are ALL included in one zip (which also contains the client), and are automatically extracted into the right directories when unzipping. But what if your game runs on a (dedicated) multiplayer server which regularly updates content?

OVERVIEW:
The method described here is to zip the files into a pk3, upload the pk3 to the server, reference one of the files contained in the pk3 (ie in the qc), and this makes the server send this pk3 to connecting players… and BOOM – they get ALL the files. Here’s the details:

THE METHOD
Step 1. make a new folder to represent your game’s root folder, lets call it ‘root2’

Step 2. make subdirectories in root2, to imitate/match up with/mirror the directories in your mod folder, in which the files you need players to have are situated. eg, if the files you need to send are currently situated in

c:/Quake/your_mod_name/particles
c:/Quake/your_mod_name/scripts
c:/Quake/your_mod_name/textures
c:/Quake/your_mod_name/lits

.. then root2 should contain those folders as well, eg:

c:/root2/particles
c:/root2/scripts
c:/root2/textures
c:/root2/lits

Step 3. Put a copy of all your required files in their corresponding directory in the root2 folder. Make sure you include any textures your reference in your shaders, or in any qc script embedded in functions such as shaderforname().

Step 4. go into c:/root2, select everything, and zip it, lets name the file ‘my_package’. Note: just to be crystal clear, you selected everything IN root2, NOT root2 itself. ie there is no root2 folder in my_package.pk3. ie. the contents of my_package.pk3 are:

/particles
/scripts
/textures
/lits

Step 5. Change the extension from ‘zip’ to ‘pk3’, so the file is now called ‘my_package.pk3’

Step 6. Upload my_package.pk3 to your server and put it in: Quake/modname

Step 7. The QuakeC part
Ideally, the names of all of the files in my_package.pk3 are NEW, ie no files with the same names are (nor have EVER BEEN) on the server. Pick one of these new files, let’s say it’s called “scripts/elvis.cfg”. In the qc run the following code when someone connects, eg somewhere in ClientConnect():

whichpack(“scripts/elvis.cfg”); // whichpack makes the server search for the file “scripts/elvis.cfg”, and returns a string, which is the name of the pk3 in which “scripts/elvis.cfg” is contained.

HOW IT WORKS
When a client connects, whichpack(“scripts/elvis.cfg”); will run, and the server will automatically tell the client that the ‘returned package’ (in this case “my_package.pk3”) should be pre-downloaded and used. This will force clients (specifically FTE clients) to download my_package.pk3 (if they don’t already have it) from the server.

Q1: What if the pk3 is massive, and I need to update one line on one script? Do I have to remake the whole thing, and players have to redownload it just because one line in one tiny file has changed?
A: If that’s the case, then don’t use one BIG pk3 for ‘regularly updated’ files, make a special tiny pk3’s which only have (tiny) scripts. Remember to give the updated versions new (unique!) names eg if you update “scripts/elvis.cfg”, name the update “scripts/elvis2.cfg”. Similarly, zip it into a new pk3 called eg “my_package2.pk3”)

Q2: How can I confirm that the server knows that the files are in the pk3?
A: flocate scripts/elvis.mdl

Q3: I followed these instructions, but the particles aren’t running!
A: You need to change maps, though when testing, I had to restart my client to get it to run the particle script in the pk3.

[TO DO: What if there is a conflict between a (eg) shader in foo.pk3 and foo3.pk3 ie one w the same name?]

Leave a Reply

 

 

 

You can use these HTML tags

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

Notify me of followup comments via e-mail. You can also subscribe without commenting.