tf2pcfm - TF2 particle merger modifier

Heads-up: this program is very barebones. It's a WIP.

No binaries. Compile yourself. It was only tested on Linux. Crashes may happen. No support given. You have been warned.
https://git.pevhs.ch/tf2pcfm.git

This tool offers the possibility to modify and merge particles from different PCF files together. It was made specifically for Team Fortress 2 and so will not work with any other DMX files (at least if they have not the same header). It can come in handy if you would like to use different particle mods that are incompatible with each other because they modify the same PCF files. (DMX and PCF are used interchangeably here, PCF just means that the DMX tree contains particle data.)

Notice: Unless you really know what you are doing, I advise against using files outputted by this program as the basis to build other particle mods, for the following reasons:

Particles may not appear in the particle editor (probably because they aren't referenced in the root element).
To avoid name collision, elements and attributes have a randomized suffix added to their name.
This program cannot detect if particles are orphaned, so unused particles are still written in the output. (This might get partly fixed when I implement functions to remove objects.)

As this is a "homemade" program, there are risks that the files it is outputting contain errors, even if the particles seem to work fine in-game.

To know the names of the particle(s) you want to replace, refer to these links (they aren't up to date, you might need to do some research on your own):

You should also open the particles in the particle editor to better see what you want to edit.

Limitations

This program only works with binary PCF files containing this header: . It will refuse to run otherwise. Since this is the binary version used by TF2, it shouldn't be an issue, but if it is, you can try to convert your file with dmxconvert to the keyvalues2 (ascii) format, then back to binary. (If TF2's dmxconvert doesn't work, you can try the one included with Source Filmmaker.)

Usage

For example, if someone wanted to merge the particles of the Dragon's Fury from this mod with the rest of the flamethrower particles from this other mod, it could be done like so:

Invoke the program with ./tf2pcfm script, where script is a text file containing these lines:

load to_mod.pcf
load from_mod.pcf
override_content "1:particleSystemDefinitions/projectile_fireball"\
                 "0:particleSystemDefinitions/projectile_fireball"
override_content "1:particleSystemDefinitions/projectile_fireball_pyrovision"\
                 "0:particleSystemDefinitions/projectile_fireball_pyrovision"
override_content "1:particleSystemDefinitions/projectile_fireball_crit_red"\
                 "0:particleSystemDefinitions/projectile_fireball_crit_red"
override_content "1:particleSystemDefinitions/projectile_fireball_crit_blue"\
                 "0:particleSystemDefinitions/projectile_fireball_crit_blue"
override_content "1:particleSystemDefinitions/muzzle_dragons_fury"\
                 "0:particleSystemDefinitions/muzzle_dragons_fury"
write 0 new_mod.pcf

These commands will copy over to the first loaded tree the trail and fireball effects of the Dragon's Fury from the second tree, then write the first tree to the specified filename. As you can see, backslashes can be used to separate long commands over multiple lines.

The downside of this tool is that depending on the particle one wants to merge, it can take some time to set everything up. The upside, however, is that the script can be executed at will, so if one of the PCF file gets updated you can just run it again to benefit from the new changes.

You need to be a bit familiar with how DMX files work to use this tool, but I guess that if you're willing to open TF2 with the -tools option and maybe convert your files with dmxconvert in keyvalues2 format, you should be able to understand how it works.

Commands

They are:

load file

load a PCF file.

override_content id:path id:path

copy the content of an element to another, overriding the latter's content. An element is defined by its tree's id followed by its path. id is the index of the loaded PCF file, starting at 0.

change_value id:path value

change the value of an attribute. As of 2024-06-27, only the following attributes are supported: int, float, bool, color, vector2/3/4. value is the new value whose format changes depending on the type:

Type	Description	Example
int	number	2
float	number, decimals allowed	2.44
bool	0 or 1	1
color	R G B A, from 0 to 255	255 200 65 255
vector2/3/4	a series of 2, 3 or 4 floats, respectively	(vec3) 2 3.44 5.04

The program will throw an error if the value does not correspond to the target attribute's type.

write id file

Output the loaded DMX tree defined by id to the given file. If file is a hyphen (-), the tree will be printed to stdout.

Information on the DMX format I've gathered in the making of this program can be found here.

Script examples

load particles/explosion.pcf
load particles/cinefx.pcf
override_content "1:particleSystemDefinitions/hightower_explosion"\
                 "0:particleSystemDefinitions/ExplosionCore_Wall_Jumper"
override_content "1:particleSystemDefinitions/hightower_explosion"\
                 "0:particleSystemDefinitions/ExplosionCore_MidAir_Jumper"

load particles/impact_fx.pcf
load particles/level_fx.pcf
override_content "1:particleSystemDefinitions/nucleus_core_steady"\
                 "0:particleSystemDefinitions/impact_wood"