{"id":13658616,"url":"https://github.com/HearthSim/UnityPack","last_synced_at":"2025-04-24T11:32:19.175Z","repository":{"id":45136025,"uuid":"48937139","full_name":"HearthSim/UnityPack","owner":"HearthSim","description":"Python deserialization library for Unity3D Asset format","archived":false,"fork":false,"pushed_at":"2022-01-06T00:35:07.000Z","size":332,"stargazers_count":737,"open_issues_count":48,"forks_count":152,"subscribers_count":61,"default_branch":"master","last_synced_at":"2025-04-08T11:12:38.603Z","etag":null,"topics":["disunity","python","unity","unity3d","unity3d-format"],"latest_commit_sha":null,"homepage":"https://hearthsim.info/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HearthSim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-03T06:55:10.000Z","updated_at":"2025-04-06T11:13:39.000Z","dependencies_parsed_at":"2022-08-22T06:00:31.794Z","dependency_job_id":null,"html_url":"https://github.com/HearthSim/UnityPack","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HearthSim%2FUnityPack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HearthSim%2FUnityPack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HearthSim%2FUnityPack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HearthSim%2FUnityPack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HearthSim","download_url":"https://codeload.github.com/HearthSim/UnityPack/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250618470,"owners_count":21460102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["disunity","python","unity","unity3d","unity3d-format"],"created_at":"2024-08-02T05:01:01.151Z","updated_at":"2025-04-24T11:32:18.458Z","avatar_url":"https://github.com/HearthSim.png","language":"Python","readme":"# UnityPack\n[![Build Status](https://api.travis-ci.org/HearthSim/UnityPack.svg?branch=master)](https://travis-ci.org/HearthSim/UnityPack)\n\nA library to deserialize Unity3D Assets and AssetBundles files (*.unity3d).\n\n## Dependencies\n\n* [python-lz4](https://github.com/python-lz4/python-lz4) (For UnityFS-compressed files)\n\n\n## How Unity packs assets\n\nMost extractors for Unity3D files (such as [Disunity](https://github.com/ata4/disunity))\ndeal with the format as a \"file store\", treating it as one would treat a zip. This is\nnot how the format actually works.\n\nUnity files are binary-packed, serialized collections of Unity3D classes. To this end,\nthey are much closer to a json file containing arrays of objects.\n\nSome of those classes have fields which contain raw data, such as Texture2D's `image data`\nfield or TextAsset's `m_Script` field. Using this, files can be \"extracted\" from the asset\nbundles by using their `m_Name` and an appropriate extension. But doing so leaves out all\nthe \"unextractable\" classes which one might want to deal with.\n\n\n## Usage\n\nTo open an asset, or asset bundle, with unitypack:\n\n```py\nimport unitypack\n\nwith open(\"example.unity3d\", \"rb\") as f:\n\tbundle = unitypack.load(f)\n\n\tfor asset in bundle.assets:\n\t\tprint(\"%s: %s:: %i objects\" % (bundle, asset, len(asset.objects)))\n```\n\nThe `objects` field on every `Asset` is a dictionary of `path_id` keys to `ObjectInfo`\nvalues. The `path_id` is a unique 64-bit signed int which represents the object instance.\nThe `ObjectInfo` class is a lazy lookup for the data on that object.\n\nThus, if you want to actually extract the data:\n\n```py\nfor id, object in asset.objects.items():\n\t# Let's say we only want TextAsset objects\n\tif object.type == \"TextAsset\":\n\t\t# We avoid reading the data, unless it's a TextAsset\n\t\tdata = object.read()\n\t\t# The resulting `data` is a unitypack.engine.TextAsset instance\n\t\tprint(\"Asset name:\", data.name)\n\t\tprint(\"Contents:\", repr(data.script))\n```\n\nNot all base Unity3D classes are implemented. If a class is unimplemented, or a custom class\n(eg. a non-Unity class) is encountered, the resulting data is a dict of the fields instead.\nThe same dict of fields can be found in the `_obj` attribute of the instance, otherwise.\n\n\n## Included tools\n\nIncluded are two scripts which use unitypack for some common operations:\n\n\n### Asset extraction\n\n`unityextract` can extract common types of data from assets and asset bundles, much like Disunity.\nBy default, it will extract all known extractable types:\n\n* `AudioClip` objects will be converted back to their original format. Note that recent Unity3D\n  versions pack these as FSB files, so [python-fsb5](https://github.com/hearthsim/python-fsb5)\n  is required to convert them back.\n* `Texture2D` objects will be converted to png files. Not all Texture2D formats are supported.\n  [Pillow](https://github.com/python-pillow/Pillow) version \u003e= 3.4 is required for this.\n  [decrunch](https://github.com/HearthSim/decrunch) is required for DXT1Crunched / DXT5Crunched.\n* `Mesh` objects (3D objects) will be pickled. Pull requests implementing a .obj converter are\n  welcome and wanted.\n* `TextAsset` objects will be extracted as plain text, to .txt files\n* `Shader` objects work essentially the same way as TextAsset objects, but will be extracted to\n  .cg files.\n\nFilters for individual formats are available. Run `unityextract --help` for the full list.\n\n\n### YAML conversion\n\n`unity2yaml` can convert AssetBundles to YAML output. YAML is more appropriate than JSON\ndue to the recursive, pointer-heavy and class-heavy nature of the Unity3D format.\n\nWhen run with the `--strip` argument, extractable data will be stripped out. This can make the\nresulting YAML output far less heavy, as binary data will otherwise be converted to Base64 which\ncan result in extremely large text output.\n\nHere is a stripped example of the `movies0.unity3d` file from Hearthstone, which contains only\ntwo objects (a MovieTexture cinematic and a corresponding AudioClip):\n\n```yaml\n!unitypack:AudioClip\nm_BitsPerSample: 16\nm_Channels: 0\nm_CompressionFormat: 0\nm_Frequency: 0\nm_IsTrackerFormat: false\nm_Legacy3D: false\nm_Length: 0.0\nm_LoadInBackground: false\nm_LoadType: 0\nm_Name: Cinematic audio\nm_PreloadAudioData: true\nm_Resource: !unitypack:StreamedResource {m_Offset: 0, m_Size: 0, m_Source: ''}\nm_SubsoundIndex: 0\n\nm_AssetBundleName: ''\nm_Container:\n- first: final/data/movies/cinematic.unity3d\n  second:\n    asset: !PPtr [0, -4923783912342650895]\n    preloadIndex: 0\n    preloadSize: 2\nm_Dependencies: []\nm_IsStreamedSceneAssetBundle: false\nm_MainAsset: {asset: null, preloadIndex: 0, preloadSize: 0}\nm_Name: ''\nm_PreloadTable:\n- !PPtr [0, -6966092991433622133]\n- !PPtr [0, -4923783912342650895]\nm_RuntimeCompatibility: 1\n\n!unitypack:stripped:MovieTexture\nm_AudioClip: !PPtr [0, -6966092991433622133]\nm_ColorSpace: 1\nm_Loop: false\nm_MovieData: \u003cstripped\u003e\nm_Name: Cinematic\n```\n\nStripped classes will be prefixed with `unitypack:stripped:`.\n\n\n## License\n\npython-unitypack is licensed under the terms of the MIT license.\nThe full license text is available in the `LICENSE` file.\n\n\n## Community\n\npython-unitypack is a [HearthSim](http://hearthsim.info) project. All development\nhappens on our IRC channel `#hearthsim` on [Freenode](https://freenode.net).\n\nContributions are welcome. Make sure to read through the `CONTRIBUTING.md` first.\n","funding_links":[],"categories":["Open Source Repositories","Python","Asset Bundle","Open Source Packages"],"sub_categories":["Utilities"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHearthSim%2FUnityPack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHearthSim%2FUnityPack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHearthSim%2FUnityPack/lists"}