项目作者: HearthSim

项目描述 :
Python deserialization library for Unity3D Asset format
高级语言: Python
项目地址: git://github.com/HearthSim/UnityPack.git
创建时间: 2016-01-03T06:55:10Z
项目社区:https://github.com/HearthSim/UnityPack

开源协议:MIT License

下载


UnityPack

Build Status

A library to deserialize Unity3D Assets and AssetBundles files (*.unity3d).

Dependencies

How Unity packs assets

Most extractors for Unity3D files (such as Disunity)
deal with the format as a “file store”, treating it as one would treat a zip. This is
not how the format actually works.

Unity files are binary-packed, serialized collections of Unity3D classes. To this end,
they are much closer to a json file containing arrays of objects.

Some of those classes have fields which contain raw data, such as Texture2D’s image data
field or TextAsset’s m_Script field. Using this, files can be “extracted” from the asset
bundles by using their m_Name and an appropriate extension. But doing so leaves out all
the “unextractable” classes which one might want to deal with.

Usage

To open an asset, or asset bundle, with unitypack:

  1. import unitypack
  2. with open("example.unity3d", "rb") as f:
  3. bundle = unitypack.load(f)
  4. for asset in bundle.assets:
  5. print("%s: %s:: %i objects" % (bundle, asset, len(asset.objects)))

The objects field on every Asset is a dictionary of path_id keys to ObjectInfo
values. The path_id is a unique 64-bit signed int which represents the object instance.
The ObjectInfo class is a lazy lookup for the data on that object.

Thus, if you want to actually extract the data:

  1. for id, object in asset.objects.items():
  2. # Let's say we only want TextAsset objects
  3. if object.type == "TextAsset":
  4. # We avoid reading the data, unless it's a TextAsset
  5. data = object.read()
  6. # The resulting `data` is a unitypack.engine.TextAsset instance
  7. print("Asset name:", data.name)
  8. print("Contents:", repr(data.script))

Not all base Unity3D classes are implemented. If a class is unimplemented, or a custom class
(eg. a non-Unity class) is encountered, the resulting data is a dict of the fields instead.
The same dict of fields can be found in the _obj attribute of the instance, otherwise.

Included tools

Included are two scripts which use unitypack for some common operations:

Asset extraction

unityextract can extract common types of data from assets and asset bundles, much like Disunity.
By default, it will extract all known extractable types:

  • AudioClip objects will be converted back to their original format. Note that recent Unity3D
    versions pack these as FSB files, so python-fsb5
    is required to convert them back.
  • Texture2D objects will be converted to png files. Not all Texture2D formats are supported.
    Pillow version >= 3.4 is required for this.
    decrunch is required for DXT1Crunched / DXT5Crunched.
  • Mesh objects (3D objects) will be pickled. Pull requests implementing a .obj converter are
    welcome and wanted.
  • TextAsset objects will be extracted as plain text, to .txt files
  • Shader objects work essentially the same way as TextAsset objects, but will be extracted to
    .cg files.

Filters for individual formats are available. Run unityextract --help for the full list.

YAML conversion

unity2yaml can convert AssetBundles to YAML output. YAML is more appropriate than JSON
due to the recursive, pointer-heavy and class-heavy nature of the Unity3D format.

When run with the --strip argument, extractable data will be stripped out. This can make the
resulting YAML output far less heavy, as binary data will otherwise be converted to Base64 which
can result in extremely large text output.

Here is a stripped example of the movies0.unity3d file from Hearthstone, which contains only
two objects (a MovieTexture cinematic and a corresponding AudioClip):

  1. !unitypack:AudioClip
  2. m_BitsPerSample: 16
  3. m_Channels: 0
  4. m_CompressionFormat: 0
  5. m_Frequency: 0
  6. m_IsTrackerFormat: false
  7. m_Legacy3D: false
  8. m_Length: 0.0
  9. m_LoadInBackground: false
  10. m_LoadType: 0
  11. m_Name: Cinematic audio
  12. m_PreloadAudioData: true
  13. m_Resource: !unitypack:StreamedResource {m_Offset: 0, m_Size: 0, m_Source: ''}
  14. m_SubsoundIndex: 0
  15. m_AssetBundleName: ''
  16. m_Container:
  17. - first: final/data/movies/cinematic.unity3d
  18. second:
  19. asset: !PPtr [0, -4923783912342650895]
  20. preloadIndex: 0
  21. preloadSize: 2
  22. m_Dependencies: []
  23. m_IsStreamedSceneAssetBundle: false
  24. m_MainAsset: {asset: null, preloadIndex: 0, preloadSize: 0}
  25. m_Name: ''
  26. m_PreloadTable:
  27. - !PPtr [0, -6966092991433622133]
  28. - !PPtr [0, -4923783912342650895]
  29. m_RuntimeCompatibility: 1
  30. !unitypack:stripped:MovieTexture
  31. m_AudioClip: !PPtr [0, -6966092991433622133]
  32. m_ColorSpace: 1
  33. m_Loop: false
  34. m_MovieData: <stripped>
  35. m_Name: Cinematic

Stripped classes will be prefixed with unitypack:stripped:.

License

python-unitypack is licensed under the terms of the MIT license.
The full license text is available in the LICENSE file.

Community

python-unitypack is a HearthSim project. All development
happens on our IRC channel #hearthsim on Freenode.

Contributions are welcome. Make sure to read through the CONTRIBUTING.md first.