Legacy:Package Naming

The Unreal Engine has certain pitfalls to do with the naming of packages...

Problem 1: name overlap

It has been noted many times, and complained about by experienced map collectors countless times, that mappers and modders need to observe some conventions when naming their creations. This is most important in regard to resource files such as .utx, .usx, etc.

This is the problem for those who are unaware. The Unreal engine (in all PC versions as far as I am aware) requires all package names (i.e. package file names) to be unique WITHOUT the extension. The extension is disregarded. This means that City.ut2, City.utx, and City.uax cannot coexist because the engine would try to treat them all as the same package and generate an error. A level is just another package by the way. You can MAKE all these and have them in your directories because the computer doesn't think they are different (since as files, they have different extensions), but if Unreal engine games try to use them there will be an error.

How could you get such packages? Well, either different people could have created different packages and given them the same first name but different extensions and you downloaded them or you the mapper/modder could have made different packages in various programs and given them the same first name but different extensions. i.e. You made a texture package and called it City and made a sound package and called it City.

For example:

DM-City.ut2

City.utx

OK, because the first names are different. "DM-" (or any other gametype moniker) is actually part of the package's name. This makes the two different: the engine sees these as "City" and "DM-City".

City.unr

City.utx

City.umx

CITY.uax

CiTy.usx

Wrong, because the package name without extension is the same. Upper and lower case do not matter. As far as the Unreal engine is concerned they are packages and must have unnique names since package extensions are irrelevant.

Finally there is the problem that many mappers and modders tend to gravitate towards the same names when making texture packages, etc. This additional problem means that different mappers might all decide to name their city based texture packages City.utx, for instance. Since neither files nor packages can have the same name and the same extension, without overwriting each other if put them in the same directory, you get this problem:

City.utx →>mapper A's city textures package

City.utx →>mapper B's city textures package

City.utx →>mapper C's city textures package

These files might be entirely different except for their names but they cannot be used together in the same Unreal based game install (remember this includes UT2003, etc.). Not only that they will overwrite each other just like ordinary files.

This has been a big problem in the past as everyone tries to use the same name for a package or map, whether it is City, Urban, Forest, or any other generic name. Some people have tried to combine packages with the same name but different contents, but since the indexing is extremely complicated and packages are not just zips or wads like other games, this rarely works. It is in no way recommended, since you can lose data!

The reason for this

As far as the Unreal engine is concerned (and I believe this is true across all PC versions) all packages are the same and must have unique names, regardless of extension.

The reason is that the internal format of all packages is the same no matter what the extension is. Any kind of data can go into any kind of package. The extensions and the practice of sorting packages is purely for the sake of us humans. Level packages, sound, music (.umx packages, not .ogg files), textures, etc. are all stored in packages in the same manner. This is what makes storing textures and stuff in your map's package using "MyLevel" possible.

i.e. a texture package could have sounds and static mesh info in it IF someone wanted to put them in. The extension .utx is merely a naming convention and the habit of putting only texture files in .utx packages is again, only a convention.

Another example are the .u packages. They contain compiles UnrealScript code, but usally also textures, sounds, meshes, etc., but the same things could be saved in the map's package via MyLevel. Don't confuse .uc files with .u packages, they are just plain ASCII text files with hopefully compilable UnrealScript code.

For an explantion beyond that you have to ask Tim Sweeney, father of the Unreal engine. :P

Problem 2: spaces, cases

Don't use spaces in package names, there is no useful reason why to use spaces in packages names anyway.

The reason not to use spaces is because a space needs to be escaped in many cases (on command line, and in HTTP requests). Using spaces will only make it more difficult for users of the package, HTTP redirect will simply fail (because the spaces are not escaped), on Linux is often fails too.

From UT version 447 and UT2003 version 2220 spaces in redirects will be replaced with the correct %20, but that's no excuse to use spaces.

Don't randomly mix cases, UNIX systems (and Mac) are case sensitive (yes Mac is too), Always use a logical mixed case name: "DM-SomeMap.ut2" (good) and not "dM-sOmEMap.Ut2" (bad), this is simply unreadable but can also causes problems because it invites people to rename it. Cases are mostly important for HTTP redirection because Unreal will use the same cases as used in the filename on the local server. So the filename has to have the exact same case as on the HTTP server.

Also during releases preserve the cases used in the filename. On UNIX systems you can have MyPackage.u and myPackage.u this will confuse Unreal. On UNIX systems Unreal will perform a case insensitive lookup for the requested file and the first result will be used.

Only use alphanumeric characters and '_', '-', '.' , don't use any other characters. Package names are not meant to look cool. Other characters often need to be escaped on UNIX systems and might not work for HTTP redirecting.

Proposed Naming Convention

The following is a proposed naming convention based on the system I (Githianki) use. It might seem a bit akward but it works very well when trying to sort through hundreds of files. It allows anyone to easily see what files are related to which map or mod. That, in my opinion, makes it worth any slight awkwardness.

maps

maptype-mapname.unr or maptype-mapname.ut2

or mapname.unr or mapname.ut2 for Single Player

where maptype is DM or CTF, etc. and

where mapname is unique among all package and map names.

For example: DM-SuperMap.unr or SuperMap.ut2

for other resource packages

mapname_extension.extension or

modname_extension.extension

where extension is the three letter extension for the resource type and

where mapname MATCHES EXACTLY the mapname of the map the resource is related to or

where modname is EXACTLY the same for a related set of files and is unique among all modnames

For example:

DM-SuperMap.unr or DM-SuperMap.ut2

SuperMap_utx.utx

SuperMap_usx.usx

SuperMap_umx.umx or

LarryMod_utx_01.utx

LarryMod_utx_02.utx

LarryMod_usx.usx

This allows all packages related to SuperMap to be searched for (across directories) and be unique with regard to each other, since even when the extension is stripped the resource type remains part of the package name. Note LarryMod has two texture packages and added a numerical extension to make sure the names were unique yet still could be found easily by searching for LarryMod.

Mapper/Modmaker Makercode Extension System

There has also been a makercode proposal that would allow each mapper or mod maker/team to identify its content. It could be incorporated as follows:

makercode_mapname_extension.extension or

makercode_modname_extension.extension

where makercode is a three or four capital letter code that a content maker chooses for him or herself and always uses and

where extension is the three letter extension for the resource type and

where mapname MATCHES EXACTLY the mapname of the map the resource is related to or

where modname is EXACTLY the same for a related set of files and is unique among all modnames

For example:

CTF-SuperMap.unr or CTF-SuperMap.ut2

JOE_SuperMap_utx.utx

JOE_SuperMap_usx.usx

JOE_SuperMap_umx.umx

JOE is the three letter code for stuff made by JOE. There might also be JOE_City_utx.utx which JOE uses for all her maps. With this scheme BOB_City_utx.utx will never conflict.

A mod example might be:

MCTF-SuperMap.unr or MCTF-SuperMap.ut2

TMMK_MultiCTF_utx_01.utx

TMMK_MultiCTF_utx_02.utx

TMMK_MultiCTF_usx.usx

TMMK_MultiCTF_umx.umx

MCTF is the gametype code for MultiCTF maps. MultiCTF is the name of the mod which is used on all MultiCTF packages. TMMK stands for Team ModMaker who made this (fictional) mod. As you can see they have two texture packages and added numerical extensions to the package names to track their files.

Conclusion

As you can see, this system allows for neat organization and prevents package name conflicts between all the various mappers and modders out there, without everyone having to come up with tons of different names for files that are related. Since three letters might not be enough for makercodes people or teams could use four, as in the last example.

The key thing about any system is that people be consitent and use it. Some folks might wish to be more descriptive about what a package contains than JOE_BlowMap_utx.utx. That is fine as long as the makercode is unique and used. Say JOE_grassytextures_utx.utx, instead of the map or mod name. This is fine. Remember the system is designed to help avoid conflict with others (makercodes) and help organize your own efforts (extensions in the package name) only. It isn't a rule or law but I think everyone will benefit if we all stick as close to it as possible.

-Githianki-

P.S.> This system can be used for any Unreal engined game. Simply use the appropriate extensions for the maps for that game and any others which are appropriate to that game.

Related Topics

• Package Extension Catalog

---

Discussion

Mysterial:Packages that are named the same without the extension DO NOT cause an error IF the only time those packages are used is in DynamicLoadObject() calls. Not sure why that is, and it certainly isn't a reason for ignoring package naming issues, but I thought it was a quirk of the engine worth mentioning.

Wormbo: The engine will search the [Core.System] Paths for matching package files. Once a package file is found, the engine first tries to load a .DLL (Windows) or .SO (Linux/Mac) from the System directory with the same name as the package and then loads the first package file found. As several people have noticed already, the DLL loading is done using Windows' LoadLibrary() function, which goes through all the operating system search paths. This is neither a real performance problem (after the first request the file system cache will speed things up) nor a security issue (UT2004 properly specifies an absolute path name so only DLLs from the game's System directory can be loaded), so it's nothing to worry about.

A note to Joeyz and {DDG}Vaptor: If you guys think this is a performance problem then please give us some hard numbers. Keep in mind that logginbg all those file system accesses are a big performance hit already, so make sure you gather your numbers without running FileMon, if possible. You were asked for those numbers several times already but still fail to deliver them. Instead you spread information and imply unproven facts to... well, I don't really know what you are trying to achieve by posting all this several times, always in a way which implies that there are serious problems.