UDN
Search public documentation:

UnrealPackages
日本語訳
中国翻译
한국어

Interested in the Unreal Engine?
Visit the Unreal Technology site.

Looking for jobs and company info?
Check out the Epic games site.

Questions about support via UDN?
Contact the UDN Staff

Unreal Packages

Document Summary: An overview of packages and asset representation in the Unreal Engine.

Document Changelog: Created by Warren Marshall. Maintained by Richard Nalezynski?.

Introduction

The Unreal Engine concept of a package is a file which contains blobs of binary data that can be manipulated and accessed via the Unreal Engine.

Content packages contain various types of game assets. These assets include textures, static meshes, skeletal meshes, physics assets, UI Scenes and more! Anything that can be added to the game engine can put into a package. Using the Content Browser in UnrealEd, you can import assets into your packages, move assets around, rename assets, and save the resulting packages back out again.

Levels are represented as a special kind of package. Levels don't generally contain assets. Instead, they contains references to assets that are inside of package files. This allows the sharing of assets across many levels and allows an artist to change the asset one time in the package file and all the levels that reference it will be automatically updated. It is possible to embed assets directly into your level file; but that practice is generally frowned upon since it bloats your level file size and eliminates the possiblity of that asset being shared with other levels. Levels also make heavy use of Actors that are defined in UnrealScript classes.

UnrealScript classes are compiled into unique packages, as well. UnrealScript packages may also contain references to content and level packages.

Package Types

Packages can have different extensions but they are all the same format internally. The Unreal Engine does care what is in the package and doesn't contain any special case handling for specific extensions. However, there is a general convention that most licensees follow:

Extension Contains
U Compiled UnrealScript code. These are generated by the UCC compiler and shouldn't contain any assets; only references.
UDK The default extension for levels; contains Actors defined in compiled script packages and assets stored in content packages.
UPK The generic extension for content that indicates a collection of assets.

Licensees may register unique level extensions at the Licensee File Extensions? page.

Groups

Packages can contain multiple tiers of groups within them. Think of them as subdirectories in a directory structure on your hard drive. These are used entirely for the humans trying to make sense of the package contents; the engine doesn't care if you use them or not.

Unreal supports multi-level grouping structure; but, while you can go as deep as you want with it, it is generally recommended to stay to 3 or 4 levels deep at the most. Otherwise, it just gets too unwieldy trying to use the content browser package tree. Below is an example of multiple groups being used to organize armor assets:

CB_Packages.PNG

The package in this case is Pickups (which would be pickups.upk on the hard drive). Inside of that packages are many groups which are being used to organize the assets inside of it. For example, in case of the selected item, the path to get to the specific asset would be Pickups.Armor.Materials. This is analogous to accessing your hard drive (i.e. "c:\pickups\armor\materials"). Each group can contain assets, just like any directory can contain files.

Naming

When naming your assets and packages, it is strongly recommended that you use unique names for them all. Naming multiple things the same will sometimes lead to the engine not being able to resolve exactly what you want to load/reference and finding the wrong one. This leads to obscure problems and can be a debugging nightmare.

Just avoid the problem altogether and name your assets/packages uniquely. Having said that, your group names can be whatever you want them to be. They don't need to be unique as they are never referenced or searched for directly.

Organization

Content packages are typically stored in the Content directory of your build. They may contain subdirectories that represent various types of content such as Textures or UI Scenes. Again, this is only for human readability and maintenance.

Level packages are stored in the Maps directory of your build.

Compiled UnrealScript packages are stored in the Scripts directory of your build.

See the Asset Pipeline page for more information on naming and organization of packages.

Limitations

There is no limit to how many assets can appear in a package file, but there is a limit of 2GB on the overall package size. Going beyond that limit will cause the package to not load on certain platforms. If the package is approaching even half of that size, it might be wise to abstract out various parts into smaller packages.

Management

Additionally, packages may become large if they contain various types of content that is being worked on by different team members. This can create very large file copies that are stored for each revision in source control. To avoid these problems, consider a strategy where you scan the set of packages that you have and identify which ones are bigger than 200-300 megs. Take those large packages and split them up. This can help a lot in terms of disk usage.

Cooking will do a lot of the work of "combining" all of the data needed into the seek-free packages. Additionally, it is pretty easy to just combine packages back into larger ones later on in the dev cycle, when there is less content iteration. To do this, simply rename the asset from one package to another. This will create a redirector object that points to the new location. You can not delete the old (empty) package until you have run the FixupRedirects commandlet to remap all the references to old content locations to point to the new location.

Loading

Native packages are loaded so that any data defined in the packages that affect the native C++ classes (through defaultproperties) are used when running the code. There are classes defined in C++ and script, and they need to always be in sync.

Package loading is a very complex system which most licensees never actually need to deal with on a low level.

Exports are objects that exist in a package.

Imports are references to objects in other packages.

So, if you have a material MatX in package A, and it references TexY in package A and TexZ in package B, you'd have:

Package A:
        Exports:
                MatX
                TexY
        Imports:
                B.TexZ

Package B:
        Exports:
                TexZ

The editor loads the native script packages, packages listed in the EditPackages and PackagesToBeFullyLoadedAtStartup keys in the configuration file, and all of their references.

When you load a package (editor or game), it will load objects from other packages to resolve all references. It will not load all the objects in the packages that are referenced. It loads the minimum needed from other packages.

In the editor, packages listed in gray in the Content Browser are only partially loaded because they are loaded as a result of loading other packages. You can right-click on a package to fully load it. The content directory of your game will be automatically scanned for packages each time you start the editor. Any package found will show up in the package tree of the Content Browser.

You can also load external packages (packages not found within the search path of the engine) by clicking on the folder icon in the lower left of the Content Browser. However, it is strongly recommended that you do not reference any assets from external packages in levels or other packages as these assets wont be found when running the game or commandlets.