Map naming and versioning

[illwieckz]

Hi, I’m porting some maps from Tremulous but I don't want to do mistakes.

1. Versioning

Unvanquished allows us to versionize pk3, which is a good thing. So we have for example:

Code: Select all

map-plat23_b13+1.pk3
map-spacetracks_1.0+1.pk3
map-station15_1.0.pk3

Is a future map-plat23_1.0.pk3 will supersede map-plat23_b13+1.pk3, unless b13+1 > 1.0 on a “sort” side ?

Some maps from Tremulous were previously versioned trem, for exemple : map-orion_trem+2.pk3.
So, when I updated them, I just increased the number, for example map-orion_trem+3.pk3, keeping the trem part since trem is a very high “number”.

The problem is here: if someone wants to update them, he must keep this “high number”.

So, for maps that already have this versioning, it's too late since some servers and players already uses it, but what to do for other maps? For example I have fixed right now another map. Which version I must give? “trem” is not a good Idea, imagine if the mapper wants to update it in the future, he will be forced to use the silly versioning I used before him (and will be angry against me).

I must use a version the mapper can update after I ported his map.

2. Naming

On the other hand, I like the _trem versioning because it shows if the map is the tremulous version or an Unvanquished map, for example see map-spacetracks-r1_trem+1.pk3 tremulous map and the updated official map-spacetracks_1.0+1.pk3. It's nice.

What do you think about using a trem- prefix while naming maps from Tremulous?

For example, the map map-vega-beta1.pk3 from tremulous can be named map-trem-vega_b1.pk3, and in server list, called trem-vega, so the user knows he is voting for a trem map.

If the mapper wants to update it officially for Unvanquished, the new one will be named map-vega_1.0.pk3 for example, so there will be no conflict between the map I ported, and the map he improves, even if the version number of the ported map is higher than the version number of his official release for Unvanquished.

For example, I will be able to rename map-meep_trem.pk3 to map-trem-meep_b2+1.pk3, (map name: trem-meep), so I can reset the versioning with a meaning one, without conflicting with the _trem versioning. What do you think about it?

3. Defining good practices

The idea is to define good practices now to prevent future mess, before more people try to port and create unofficial maps for Unvanquished.

[illwieckz]

3. Versioning example from another project

As an example of nomenclature, we can look how the guys from the GoldenEye:Source project does this (which is good):

• ge_basement.bsp

• ge_basement_classic.bsp

• ge_complex.bsp

• ge_complex_classic.bsp

Four official maps, two “themes”, two “versions” per theme, one “release” per version:

• Same GoldenEye theme “Basement”, the version from Nintendo 64 (_classic) for nostalgia (all was redone, but models, textures etc. looks exactly the same), and the revamped one (new models, new textures…)
• Same GoldenEye theme “Complex”, the version from Nintendo 64 (_classic) for nostalgia, and the revamped one.

• ge_train_cy.bsp

• pd_felicity.bsp

• pd_ravine.bsp

On unofficial GoldenEye map “Train” by CY, and two maps ported from PerfectDark:Source.

Because the source engine does not use pk3, they can't have pk3 versioning, so it can end this way (which is bad):

• ge_temple_classic.bsp

• ge_temple_mk_a6.bsp

The officially released classic GoldenEye “Temple” map, and an alpha6 release by Mookie.

It's the same problem we had with Tremulous, when we had “map-metro-b1.pk3” shipping “Metro-b1.bsp” and “map-metro-b1-2.pk3” shipping “Metro-b1-2.bsp”.

That's why you created pk3 versioning, which is a good idea.

There is two kind of versions

But in fact there is two versioning, the release (alpha4, beta3, release1, release2fix4…) and the version (classic, trem). You can have ATCS version tremulous release 5, and ATCS version HD release 2. You can have Spacetracks version Tremulous release 1, and Spacetracks version Unvanquished release 1. All these versions can be playable and people is able to want to play one of these versions, but no one wants to play an older release.

That's why for example people created “atcs”, “atcshd” and “atcs_dege”, no one must supersede others. If “atcs” and “atcs-onice” have different gameplay, “atcs”, “atcshd” and “atcs_edge” are exactly the same map with the same gameplay, but with revamped assets. They are not different releases of the same map, they are different version of the map, so this versions must be visible on name, to be able to choose them, and to prevent superseding.

That's, why, if you created a pk3 versioning system, I think we must use it for release versions only.

4. Suggestion

Why not use this nomenclature (and invite contributors to use it):

Official maps:

• map-plat23_b13.pk3

• map-plat23_b13+1.pk3

  • plat23.bsp

• map-spacetracks_1.0+1.pk3

  • spacetracks.bsp

• map-station15_1.0.pk3

  • station15.bsp

Maps ported from Tremulous (official or unofficial Tremulous maps, don't care, they are all unofficial Unvanquished maps):

• map-trem-meep_b2+1.pk3

• map-trem-meep_b2+2.pk3

  • trem-meep.bsp

• map-trem-atcshd_1.pk3

  • trem-atcshd.bsp

And for unnofficial Unvanquished map from community members:

• map-contrib-mapname_a1.pk3

• map-contrib-mapname_b2+3.pk3

  • contrib-mapname.bsp

And if someday in the future, the “contrib” map or the “trem” map becomes an official Unvanquished map, just drop the “trem-” or “contrib-” prefix. By definition, official team takes care of official Unvanquished maps, so, if there is both “contrib-mapname” and “mapname” available, people knows the “mapname” is the latest.

Also, we can just merge “trem-” and “contrib-” prefixes and use “contrib-” prefix for all non official-maps (from Tremulous or not):

• map-contrib-meep_b2+1.pk3

• map-contrib-meep_b2+2.pk3

  • contrib-meep.bsp

• map-contrib-atcshd_1.pk3

  • contrib-atcshd.bsp

What do you think about it?

[Viech]

I'll just respond to your first post for now since I started my reply earlier today.

Is a future map-plat23_1.0.pk3 will supersede map-plat23_b13+1.pk3, unless b13+1 > 1.0 on a “sort” side ?

According to the debian versioning scheme we use, letters should be greater/newer than numbers, which is why I'd recommend r01 (for "Release") for the final version of maps that used a or b before. Whether a letter/revision or floating point version (or anything else) is used is up to the mapper, which is why we use the +n standard to make updates (or, to prevent clashes when more people are likely to make updates +year-month-day-time-name. You can find the official versioning guidelines here.

Some maps from Tremulous were previously versioned trem, for exemple : map-orion_trem+2.pk3.
So, when I updated them, I just increased the number, for example map-orion_trem+3.pk3, keeping the trem part since trem is a very high “number”.

That (using _trem) was actually a bad idea as it interfers greatly with the author's versioning scheme. A + notation should've been used. I'll discuss its format at the end of my reply.

So, for maps that already have this versioning, it's too late since some servers and players already uses it

True in theory but I'd rather refer to our alpha status and give even existing maps a proper version. The client would load the same map as is loaded on the server anyway, only for a local game it may be that an outdated map is loaded.

What do you think about using a trem- prefix while naming maps from Tremulous? … For example, the map map-vega-beta1.pk3 from tremulous can be named map-trem-vega_b1.pk3, and in server list, called trem-vega, so the user knows he is voting for a trem map.

Just to be precise, the prefix must be map-, the engine expects it that way. Using map-trem- as a prefix works, technically, but it means that "trem-" is part of the map name. This is neither true nor the standard and it also requires you to rename the BSP and other files and folders to match. The "trem" (or "unv") bit should be part of the version, not of the map name!

If the mapper wants to update it officially for Unvanquished, the new one will be named map-vega_1.0.pk3 for example, so there will be no conflict between the map I ported, and the map he improves, even if the version number of the ported map is higher than the version number of his official release for Unvanquished.

If the mapper updates the map, they would choose a higher base version anyway or just increment the version extension. This in comination with us using a + notation as explained below makes sure that "the version number of the ported map" can never be higher than "the version number of [their] official release for Unvanquished".

The idea is to define good practices now to prevent future mess, before more people try to port and create unofficial maps for Unvanquished.

+1

OK, so let's get to my versioning proposal, which should be in line with our official guidelines.

First of all, I think as the map version is an Unvanquished-specific version, the version string shouldn't include "trem" but "unv". It is also clear that we should not touch the author's (base) version but release an update to that version via a + notation. Let's say the original map is map-vega_1.0.pk3, then we now have that the new version should be of the form map-vega_1.0+…unv….pk3.

So let's talk about that suffix. We could go with a simple iterator, e.g. unv1, but that has some drawbacks. For example, you don't know how old the release is (and whether it is likely to be outdated) and, secondly, this only works if you have a single porter, which may not be the case in the future. My proposal for the prefix is unv-unvversion-portername. This is a tad less precise as the date/time format we use for development packages but it's easy to read and will show you in an instant how old the port is, which is important given that every Unvanquished release may break with the old map requirements. Including the name of the porter ensures that two people can make a port for the same Unvanquished version independently. For the name of the porter, to go in line with the other guidelines, only lowerspace letters and numbers are allowed and it should be shortened for long user names. The Unvanquished version should be of the form a27 for Alpha releases (0.27.x, the x is only used for hotfixes that won't break the map format) and b01 for Beta releases. (Note that I plan to use b01 as the version for the first beta release we make as we can't really increase the first 0 in 0.xx.x.)

To put this together, if you're working on a port that would work with the current Unvanquished version of let's say 0.30.1, you would turn map-vega_1.0.pk3 into map-vega_1.0+unv-a30-illwieckz.pk3. You wouldn't need to update the a30 when Unvanquished 0.31.0 is released since that string is just a measurement of the age of the port, measured in Unvanquished releases. If you want to make a new release for the same Unvanquished release, you would append a simple iterator: map-vega_1.0+unv-a30-illwieckz+1.pk3.

So, that's my proposal. In addition to being relatively short compared to the date/time/author format we use for development packs, it means that a server admin could either decide to only ship the ports of a specific porter or, in case they don't have a preference, they'd always use the latest port which is a good default behaviour.

[Viech]

Mildly related, if you're making a port, you should probably read this thread in full.

[illwieckz]

According to the debian versioning scheme we use, letters should be greater/newer than numbers, which is why I'd recommend r01 (for "Release") for the final version of maps that used a or b before.

Sounds very good to me (but we must re-number without delay maps that have a trem version since t > r).

Whether a letter/revision or floating point version (or anything else) is used is up to the mapper, which is why we use the +n standard to make updates.

I found the +n nice.

(or, to prevent clashes when more people are likely to make updates +year-month-day-time-name)

I find the +year-month-day-time-name over complicated (for example for my photos I use yearmonthday-time, it's more compact and as usable), but the point is no to have something perfect but to have a standard that every one respect, so it's not a problem for me. :-)

That (using _trem) was actually a bad idea as it interfers greatly with the author's versioning scheme.

Yes, it was very bad, that's why I wrote this topic before I release more maps with this very bad number !

Just to be precise, the prefix must be map-, the engine expects it that way. Using map-trem- as a prefix works, technically, but it means that "trem-" is part of the map name.

This what I said. The ideas was to prefix maps (not pk3), so for example the players do: “/callvote map trem-meep”.

This is neither true nor the standard and it also requires you to rename the BSP and other files and folders to match.

This is not a problem at all, in fact I already have to rename 90% of the BSP and other files and folders to match since all map names from tremulous contains version numbers etc.

For example I already done things like that:

Code: Select all

atcszalpha-b2.bsp  →  atcszalpha.bsp
bluedragon2_b3.bsp →  bluedragon.bsp
cruz-b6.bsp        →  cruz.bsp
eden-b3.bsp        →  eden.bsp
gamma_core-final   →  gamma-core.bsp
gloom2beta2.bsp    →  gloom2.bsp
meep_b2.bsp        →  meep.bsp
methane-beta1.bsp  →  methane.bsp
Metro-b1-2.bsp     →  metro.bsp
procyon-r1.bsp     →  procyon.bsp
pulse_102.bsp      →  pulse.bsp
UTCS.bsp           →  utcs.bsp
veddak-final.bsp   →  veddak.bsp
vega-beta1.bsp     →  vega.bsp
wrecktify_b2.bsp   →  wrecktify.bsp

Also, for each map (even these ones with good bsp name) I must move levelshots/mapname.ext to meta/mapname/mapname.ext, move scripts/mapname.arena to meta/mapname/mapname.arena, then I must create minimap minimaps/mapname.webp and a minimaps/mapname.minimap, then I must create navmeshes, and for some maps, fix the “Entities” lump inside the BSP, so renaming BSP is NOT a problem at all, it's a very minor part in the porting procedure.

OK, so let's get to my versioning proposal, which should be in line with our official guidelines.

First of all, I think as the map version is an Unvanquished-specific version, the version string shouldn't include "trem" but "unv". It is also clear that we should not touch the author's (base) version but release an update to that version via a + notation. Let's say the original map is map-vega_1.0.pk3, then we now have that the new version should be of the form map-vega_1.0+…unv….pk3.

OK.

My proposal for the prefix is unv-unvversion-portername. This is a tad less precise as the date/time format we use for development packages but it's easy to read […]. Including the name of the porter ensures that two people can make a port for the same Unvanquished version independently. For the name of the porter, to go in line with the other guidelines, only lowerspace letters and numbers are allowed and it should be shortened for long user names. The Unvanquished version should be of the form a27 for Alpha releases (0.27.x, the x is only used for hotfixes that won't break the map format) and b01 for Beta releases. (Note that I plan to use b01 as the version for the first beta release we make as we can't really increase the first 0 in 0.xx.x.)

Sounds good to me. Why not use a tilde prefix for username like in ubuntu PPA versionning? For example: map-vega_b1.unv-a36_illwieckz.pk3.

New question: is “map-vega_b1” < “map-vega_b10”?

If you want to make a new release for the same Unvanquished release, you would append a simple iterator: map-vega_1.0+unv-a30-illwieckz+1.pk3.

Seems OK for me.

I'm sorry I didn't respond earlier, I think your second post doesn't quite match the guidelines/concepts we have so far :<
map name and version should be strictly seperated. I'm fine with allowing map votes to specify a version but just voting the map basename should always launch the latest release, no matter who ported etc.

In fact a same map can have multiple release, and multiple variations. In this case, the issue is just to have another name (since it's another map), but when the variation is only ”the map as it appeared on tremulous before”, a standard suffix could be a good idea, but this point is very very very minor now, with all your elucidations. :p

So, for maps that already have this versioning, it's too late since some servers and players already uses it

True in theory but I'd rather refer to our alpha status and give even existing maps a proper version. The client would load the same map as is loaded on the server anyway, only for a local game it may be that an outdated map is loaded.

OK.

I hope spudwebb will be ok with that, since he is hosting some map I ported with bad version numbers.

It's time to do things right!

[Viech]

Sounds good to me. Why not use a tilde prefix for username like in ubuntu PPA versionning? For example: map-vega_b1.unv-a36_illwieckz.pk3.

We shouldn't use ~ like that because the versioning scheme we use treats it as a special character: It allows you to order any number of versions before an existing or target version: r01₁ < r01₂ < r01 < r01+1 < r01+2. Re-read the official versioning guidelines for more examples on this.

About the +: We've been using it to make updates to a package with an existing version string that we don't want to touch, which is exactly what we should do with old maps. Furthermore, we use ~ only as explained in the paragraph above and we use - (which is, semantically, not any different from +) as a general seperator. The choice fell on - because _ is reserved for the engine and may never be used in a version or package name string while . (which behaves just like + and -) looks bad given that it's also a file extension seperator.

New question: is “map-vega_b1” < “map-vega_b10”?

Yes. Still we should use b01…b99 because not every sorting algorithm in the world behaves the same as our engine and it's unpleasant if some website or file browser orders our packages differently.

About the file renaming: I don't think the (tedious) process is the problem here. I'm against the map-trem-… scheme because we just established the standard to strictly split map name and version, which this proposal would soften again. The "trem"/"unv" bit is part of the version and it has nothing to do with the map name at all. In that light, any "convenience" side effect when it comes to votes and such would be a terrible hack. What we need instead is the possibility to vote for or load as part of the rotation a specific version of a map, which is a currently missing feature. (Also, I personally don't find it convenient to specify a certain version/manifestation of a map by hand everytime I start a vote; I want to be able to vote a map by name without keeping in mind whether it was ported by the original author or somebody else, which would ultimately be the distinction between map-trem-nano and map-nano…)

[illwieckz]

The dot was a mistake, I wanted to write a “+”. :p

So, if if I understood everything, the next ported map I will release will be “map-vega_b1+unv-a36-illwieckz.pk3”. :p

[Viech]

Looks good to me!