New package format for upcoming 0.51.0 release (bye bye pk3)
Hi, upcoming 0.51.0 release will introduce a new package format to succeed to the good old pk3 one. Don't worry, it's just the same we already used…
TL;DR: .pk3 becomes .dpk
So, why the change ?
Over the years, Unvanquished improved a lot the good old pk3 format, adding version checking and dependency mechanism. The problem comes when you try to handle both the legacy pk3 and the pk3 plus addition formats. It's not only about the engine but also the editing chain, early patch for netradiant had to do ugly stuff like if pk3 format and game is unvanquished then do this if not unvanquished then do this and the more games want to use the Dæmon engine, the more ugly hardcoded exceptions would have to be made. That's not a good option, and these ugly workarounds even can't solve the issue of a Dæmon based games supporting both newer pk3 and legacy pk3, you see the point? Tools would have to do if pk3 format and game is Dæmon based and game is not Xonotic but it's not a legacy pk3 but perhaps it's an unvanquished game and I really don't know even the compiler itself would prefer to become a hermit to raise goats on a desert island.
So, we had to face the reality, our packages are not pk3 anymore, so the solution is simple: let's name them differently.
Let's welcome DPK
If you already published a map for Unvanquished the last years, you already use the DPK format: you just have to rename the pk3 extension to dpk extension and that's all.
You already know the naming scheme: map-<name>_<version>.dpk.
So just rename your map-castle_1.pk3 to map-castle_1.dpk and you're done!
Of course the uncompressed package directory is now using .dpkdir extension instead of the .pk3dir one, so you can rename your working directory this way: map-castle_src.dpkdir.
For more information about the DPK format (versioning, how to write a DEPS file to request other package to be loaded at map load etc.) you can see the DPK Format page on the Unvanquished wiki!
Redemption time
Well, I said you just have to rename your pk3 to dpk and that's all, by the way since no one DPK map is already used out there, it's the best time for you to fix naming or versioning issue. For example if you put a large version number and regret it, you can put a small one now: it's a fresh start for everyone of you.
Why do I say that? Basically many of us reproduced bad habits from tremulous, and also we were lacking solid building experience to discover and pick the best practices. During all these years I worked hard to build tools to assist the Unvanquished mapping process, and also patched a lot of others (including NetRadiant and Q3map2) so now I can tell you I discovered I made myself a lot of mistake in the past and I would invite you to not do them yourself. For example I versioned myself some early packages using the trem version number which is greater than the src version number I use in repositories, it means the released packages have priority over the work-in-progress one, that's painful!
So basically, it's a very good idea to reserve src version number for your work-in progress source package (for example: map-castle_src.dpkdir), it's a very good to reserver the test version number for your ready-to-test directory package with compressed assets etc (for example: map-castle_test.dpkdir). Using these version numbers is good because the Urcheon tool I wrote is able to handle them on an complete automated way. Urcheon is a tool that allows you to completely build entire libraries of packages (including maps and texture sets) handling the whole map compilation, asset compression and package compression process, and Urcheon is able to write the final package version number for you just reading your repository labels.
That's why for example using a _v2 version number is not good for you, you can, nothing will enforce you to not do it, it's a valid version number, but it can bite you hard in the future in the most unexpectable way. For example it means your previously released map-castle_v2.dpk package will have priority over your map-castle_src.dpkdir source package containing your upcoming v3 and radiant will loads the wrong assets. Also, if you want to use the Urcheon tool to handle your assets repositories and build your map and have it writing the version number automatically, you'll had to create a vv3 label to get your package automatically versionned map-castle_v3.dpk.
Like many other tools, Urcheon looks for v prefixed git labels as version numbers. And if someone wants to write another tool to do the same thing Urcheon does, he will probably does the same because that's a very good practice very commonly used in many development tools. That's also why version numbers like a1, b2 and r1 are not very good. They are very correct and will not bite you hard in your back, they are smaller than both src and _test version numbers, but it's will just makes you using ugly version labels in your git repositories: va1, vb2 and vr1.
Well, it would probably be a good idea to enforce the starts with a number rule but I'm not that strong: you're currently free to do things that will annoy you one day. Basically it also means the build tools can't distinguish the valued and the v0.1 git labels, first one will produce a package named map-castle_alued.dpk and second one will produce a package named map-castle_0.1.dpk which looks weird, and with a always starts with a number rule the tools would be able to discriminate those and ignore the valued[/u] label to pick another label formed the v### way in history.
Basically, if you really want to flag your package as alpha or beta or things like that it's better for you to put the letter at the end of your version number, more like a flag or a tag than a version number: map-castle_0.1a.dpk, map-castle_0.2b.dpk, and map-castle_1.0.dpk. No one will enforce you to do things the other way, but doing this looks to be the very best practice to not get bad and unpleasant surprises later.
Examples and suggestions
This is a list of official and contrib maps I know, and what can be a best version (you're free to do whatever you want though):
Official maps (I can do the job for you at 0.51.0 release time)
map-antaresa04+1.pk3 → map-antares_0.4a.dpk
map-chasm_b2.pk3 → map-chasm_0.2b.dpk
map-forlornb1.pk3 → map-forlorn_0.1b.dpk
map-parpax_d05.pk3 → map-parpax_0.5d.dpk
map-perseusb5a+1.pk3 → map-perseus_0.5b.dpk
map-plat23_b13+1.pk3 → map-plat23_0.13b.dpk
map-spacetracks_1.0+1.pk3 → map-spacetracks_1.0.dpk
map-station15_1.0+2.pk3 → map-station15_1.0.dpk
map-thunderb3+2.pk3 → map-thunder_0.3b.dpk
map-vega_b4.pk3 → map-vega_0.4b.dpk
map-yocto_b2c+1.pk3 → map-yocto_0.2b.dpk
You can of course suggest other versions number you prefer, for example you can ask to rename map-chasm_b2.pk3 to map-chasm_2.dpk or map-chasm_2.0b.dpk, or to rename map-plat23_b13+1.pk3 to map-plat23_1.3b.dpk or map-plat23_13.dpk or map-plat23_13.0b.dpk or… tell us what you prefer and what you want.
Preview map (I can do the job for you at 0.51.0 release time)
map-freeway_1.0 → map-freeway_1.0.dpk
Maps I maintain (I will do the job myself)
map-arachnid2r1.2+55d0babe.pk3 → map-arachnid2_1.2.dpk
map-atcshd_r1.2+55d0babe.pk3 → map-atcshd_1.2.dpk
map-karithr1.2+55d0babe.pk3 → map-karith_1.2.dpk
map-nexus6_r1.2+55d0babe.pk3 → map-nexus6_1.2.dpk
map-niveusr1.2+55d0babe.pk3 → map-niveus_1.2.dpk
map-transit_r1.2+55d0babe.pk3 → map-transit_1.2.dpk
map-tremorr1.2+55d0babe.pk3 → map-tremor_1.2.dpk
map-uncreation_r1.2+55d0babe.pk3 → map-uncreation_1.2.dpk
map-rsmse_0+unv-a37-illwieckz+2.pk3 → map-rsmse_0.1.dpk
map-terminus_b22.pk3 → map-terminus_0.2b.dpk
Maps from various contributors (I can do it for you if you're OK)
map-combat-t3_1.3.pk3 → map-combat-t3_1.3.dpk
map-ctcs_1.1.pk3 → map-ctcs_1.1.dpk
map-fortification_1.1.pk3 → map-fortification_1.1.dpk
map-hangar28b1.pk3 → map-hangar28_0.1b.dpk
map-mms-stahl_v01.pk3 → map-mms-stahl_0.1.dpk
map-jotav2.0.pk3 → map-jota_2.0.dpk
map-usstremor_v1.0.pk3 → map-usstremor_1.0.dpk
map-stalkyard_b4.pk3 → map-stalkyard_0.4b.dpk
The same way you can ask for another version, like renaming map-hangar28_b1.pk3 to map-hangar28_1.dpk or map-hangar28_1.0b.dpk for example.
Let's rock!
Ping @Ingar, @Viech, @SuperTanker, @Pevel, @EmperorJack, @tvezet, @Matth, @FreeSlave etc.
Just remind that renaming .pk3 will work and will be enough, but do notice that if you want to change something you've did in the past to make something better instead, it's time !
Note that if you want and if you give me permission, I can not only rename your maps package for you but also optimise them (recompress them using crunch, building missing navmeshes if needed etc.). That's a special question for @Matth since in the past you already asked me to make navmeshes for you: do you allow me to optimize and/or complete your previously released maps?
It would be very cool to have all your contrib maps properly renamed at 0.51.0 release time.
Let's rock, and let's pave the way to Unvanquished 0.51.0!
Fig 1. People react to Unvanquished 0.51.0 rumor