{"id":15805285,"url":"https://github.com/k0lb3/unitypy","last_synced_at":"2025-05-13T23:08:20.527Z","repository":{"id":35045502,"uuid":"198518141","full_name":"K0lb3/UnityPy","owner":"K0lb3","description":"UnityPy is python module that makes it possible to extract/unpack and edit Unity assets","archived":false,"fork":false,"pushed_at":"2025-05-02T15:41:12.000Z","size":31830,"stargazers_count":1006,"open_issues_count":13,"forks_count":142,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-05-02T16:44:21.309Z","etag":null,"topics":["assetstudio","data-mining","python","python3","unity","unity-asset","unity-asset-extractor","unitypack"],"latest_commit_sha":null,"homepage":"","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/K0lb3.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"K0lb3"}},"created_at":"2019-07-23T22:36:09.000Z","updated_at":"2025-05-02T15:41:17.000Z","dependencies_parsed_at":"2024-03-25T15:17:01.677Z","dependency_job_id":"70f7880b-f8dc-4850-81f5-4034ea9e2a9b","html_url":"https://github.com/K0lb3/UnityPy","commit_stats":{"total_commits":426,"total_committers":33,"mean_commits":"12.909090909090908","dds":0.3380281690140845,"last_synced_commit":"1a6d5dcc536696ecfd5a141cccdb8686abc5ab0e"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/K0lb3%2FUnityPy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/K0lb3%2FUnityPy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/K0lb3%2FUnityPy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/K0lb3%2FUnityPy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/K0lb3","download_url":"https://codeload.github.com/K0lb3/UnityPy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254041618,"owners_count":22004744,"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":["assetstudio","data-mining","python","python3","unity","unity-asset","unity-asset-extractor","unitypack"],"created_at":"2024-10-05T02:07:15.357Z","updated_at":"2025-05-13T23:08:15.514Z","avatar_url":"https://github.com/K0lb3.png","language":"Python","readme":"# UnityPy\n\n[![Discord server invite](https://discordapp.com/api/guilds/603359898507673630/embed.png)](https://discord.gg/C6txv7M)\n[![PyPI supported Python versions](https://img.shields.io/pypi/pyversions/UnityPy.svg)](https://pypi.python.org/pypi/UnityPy)\n[![Win/Mac/Linux](https://img.shields.io/badge/platform-windows%20%7C%20macos%20%7C%20linux-informational)]()\n[![MIT](https://img.shields.io/github/license/K0lb3/UnityPy)](https://github.com/K0lb3/UnityPy/blob/master/LICENSE)\n![Test](https://github.com/K0lb3/UnityPy/workflows/Test/badge.svg)\n\nA Unity asset extractor for Python based on [AssetStudio](https://github.com/Perfare/AssetStudio).\n\nNext to extraction, UnityPy also supports editing Unity assets.\nVia the typetree structure all objects types can be edited.\n```py\n# modification via dict:\n    raw_dict = obj.read_typetree()\n    # modify raw dict\n    obj.save_typetree(raw_dict)\n# modification via parsed class\n    instance = obj.read()\n    # modify instance\n    obj.save(instance)\n```\n\nIf you need advice or if you want to talk about (game) data-mining,\nfeel free to join the [UnityPy Discord](https://discord.gg/C6txv7M).\n\nIf you're using UnityPy a commercial project,\na donation to a charitable cause or a sponsorship of this project is expected.\n\n**As UnityPy is still in active development breaking changes can happen.**\nThose changes are usually limited to minor versions (x.y) and not to patch versions (x.y.z).\nSo in case that you don't want to actively maintain your project,\nmake sure to make a note of the used UnityPy version in your README or add a check in your code.\ne.g.\n\n```python\nif UnityPy.__version__ != '1.9.6':\n    raise ImportError(\"Invalid UnityPy version detected. Please use version 1.9.6\")\n```\n\n1. [Installation](#installation)\n2. [Example](#example)\n3. [Important Classes](#important-classes)\n4. [Important Object Types](#important-object-types)\n5. [Custom Fileystem](#custom-filesystem)\n6. [Credits](#credits)\n\n## Installation\n\n**Python 3.7.0 or higher is required**\n\nvia pypi\n\n```cmd\npip install UnityPy\n```\n\nfrom source\n\n```cmd\ngit clone https://github.com/K0lb3/UnityPy.git\ncd UnityPy\npython -m pip install .\n```\n\n### Notes\n\n#### Windows\n\nVisual C++ Redistributable is required for the brotli dependency.\nIn case a new(ish) Python version is used, it can happen that the C-dependencies of UnityPy might not be precompiled for this version.\nIn such cases the user either has to report this as issue or follow the steps of [this issue](https://github.com/K0lb3/UnityPy/issues/223) to compile it oneself.\nAnother option for the user is downgrading Python to the latest version supported by UnityPy. For this see the python version badge at the top of the README.\n\n### Crash without warning/error\n\nThe C-implementation of the typetree reader can directly crash python.\nIn case this happens, the usage of the C-typetree reader can be disabled by adding these two lines to your main file.\n\n```python\nfrom UnityPy.helpers import TypeTreeHelper\nTypeTreeHelper.read_typetree_boost = False\n```\n\n## Example\n\nThe following is a simple example.\n\n```python\nimport os\nimport UnityPy\n\ndef unpack_all_assets(source_folder : str, destination_folder : str):\n    # iterate over all files in source folder\n    for root, dirs, files in os.walk(source_folder):\n        for file_name in files:\n            # generate file_path\n            file_path = os.path.join(root, file_name)\n            # load that file via UnityPy.load\n            env = UnityPy.load(file_path)\n\n            # iterate over internal objects\n            for obj in env.objects:\n                # process specific object types\n                if obj.type.name in [\"Texture2D\", \"Sprite\"]:\n                    # parse the object data\n                    data = obj.read()\n\n                    # create destination path\n                    dest = os.path.join(destination_folder, data.name)\n\n                    # make sure that the extension is correct\n                    # you probably only want to do so with images/textures\n                    dest, ext = os.path.splitext(dest)\n                    dest = dest + \".png\"\n\n                    img = data.image\n                    img.save(dest)\n\n            # alternative way which keeps the original path\n            for path,obj in env.container.items():\n                if obj.type.name in [\"Texture2D\", \"Sprite\"]:\n                    data = obj.read()\n                    # create dest based on original path\n                    dest = os.path.join(destination_folder, *path.split(\"/\"))\n                    # make sure that the dir of that path exists\n                    os.makedirs(os.path.dirname(dest), exist_ok = True)\n                    # correct extension\n                    dest, ext = os.path.splitext(dest)\n                    dest = dest + \".png\"\n                    data.image.save(dest)\n```\n\nYou probably have to read [Important Classes](#important-classes)\nand [Important Object Types](#important-object-types) to understand how it works.\n\nPeople with slightly advanced python skills should look at [UnityPy/tools/extractor.py](UnityPy/tools/extractor.py) for a more advanced example.\nIt can also be used as a general template or as an importable tool.\n\n### Setting the decryption key for Unity CN's AssetBundle encryption\n\nThe chinese version of Unity has its own inbuild option to encrypt AssetBundles/BundleFiles. As it's a feature of Unity itself, and not a game specific protection, it is included in UnityPy as well.\nTo enable encryption simply use `UnityPy.set_assetbundle_decrypt_key(key)`, with key being the value that the game that loads the budles passes to `AssetBundle.SetAssetBundleDecryptKey`.\n\n## Important Classes\n\n### [Environment](UnityPy/environment.py)\n\nEnvironment loads and parses the given files.\nIt can be initialized via:\n\n-   a file path - apk files can be loaded as well\n-   a folder path - loads all files in that folder (bad idea for folders with a lot of files)\n-   a stream - e.g., io.BytesIO, file stream,...\n-   a bytes object - will be loaded into a stream\n\nUnityPy can detect if the file is a WebFile, BundleFile, Asset, or APK.\n\nThe unpacked assets will be loaded into `.files`, a dict consisting of `asset-name : asset`.\n\nAll objects of the loaded assets can be easily accessed via `.objects`,\nwhich itself is a simple recursive iterator.\n\n```python\nimport io\nimport UnityPy\n\n# all of the following would work\nsrc = \"file_path\"\nsrc = b\"bytes\"\nsrc = io.BytesIO(b\"Streamable\")\n\nenv = UnityPy.load(src)\n\nfor obj in env.objects:\n    ...\n\n# saving an edited file\n    # apply modifications to the objects\n    # don't forget to use data.save()\n    ...\nwith open(dst, \"wb\") as f:\n    f.write(env.file.save())\n```\n\n### [Asset](UnityPy/files/SerializedFile.py)\n\nAssets are a container that contains multiple objects.\nOne of these objects can be an AssetBundle, which contains a file path for some of the objects in the same asset.\n\nAll objects can be found in the `.objects` dict - `{ID : object}`.\n\nThe objects with a file path can be found in the `.container` dict - `{path : object}`.\n\n### [Object](UnityPy/files/ObjectReader.py)\n\nObjects contain the _actual_ files, e.g., textures, text files, meshes, settings, ...\n\nTo acquire the actual data of an object it has to be read first. This happens via the `.read()` function. This isn't done automatically to save time because only a small part of the objects are of interest. Serialized objects can be set with raw data using `.set_raw_data(data)` or modified with `.save()` function, if supported.\n\n## Important Object Types\n\nAll object types can be found in [UnityPy/classes](UnityPy/classes/).\n\n### [Texture2D](UnityPy/classes/Texture2D.py)\n\n-   `.m_Name`\n-   `.image` converts the texture into a `PIL.Image`\n-   `.m_Width` - texture width (int)\n-   `.m_Height` - texture height (int)\n\n**Export**\n\n```python\nfrom PIL import Image\nfor obj in env.objects:\n    if obj.type.name == \"Texture2D\":\n        # export texture\n        data = obj.read()\n        path = os.path.join(export_dir, f\"{data.m_Name}.png\")\n        data.image.save(path)\n        # edit texture\n        fp = os.path.join(replace_dir, f\"{data.m_Name}.png\")\n        pil_img = Image.open(fp)\n        data.image = pil_img\n        data.save()\n```\n\n### [Sprite](UnityPy/classes/Sprite.py)\n\nSprites are part of a texture and can have a separate alpha-image as well.\nUnlike most other extractors (including AssetStudio), UnityPy merges those two images by itself.\n\n-   `.m_Name`\n-   `.image` - converts the merged texture part into a `PIL.Image`\n-   `.m_Width` - sprite width (int)\n-   `.m_Height` - sprite height (int)\n\n**Export**\n\n```python\nfor obj in env.objects:\n    if obj.type.name == \"Sprite\":\n        data = obj.read()\n        path = os.path.join(export_dir, f\"{data.m_Name}.png\")\n        data.image.save(path)\n```\n\n### [TextAsset](UnityPy/classes/TextAsset.py)\n\nTextAssets are usually normal text files.\n\n-   `.m_Name`\n-   `.m_Script` - str\n\nSome games save binary data as TextFile, so to convert the ``str`` back to bytes correctly ``m_Script.encode(\"utf-8\", \"surrogateescape\")`` has to be used.\n\n**Export**\n\n```python\nfor obj in env.objects:\n    if obj.type.name == \"TextAsset\":\n        # export asset\n        data = obj.read()\n        path = os.path.join(export_dir, f\"{data.m_Name}.txt\")\n        with open(path, \"wb\") as f:\n            f.write(data.m_Script.encode(\"utf-8\", \"surrogateescape\"))\n        # edit asset\n        fp = os.path.join(replace_dir, f\"{data.m_Name}.txt\")\n        with open(fp, \"rb\") as f:\n            data.m_Script = f.read().decode(\"utf-8\", \"surrogateescape\"))\n        data.save()\n```\n\n### [MonoBehaviour](UnityPy/classes/MonoBehaviour.py)\n\nMonoBehaviour assets are usually used to save the class instances with their values.\nThe structure/typetree for these classes might not be contained in the asset files.\nIn such cases see the 2nd example (TypeTreeGenerator) below.\n\n-   `.m_Name`\n-   `.m_Script`\n\n**Export**\n\n```python\nimport json\n\nfor obj in env.objects:\n    if obj.type.name == \"MonoBehaviour\":\n        # export\n        if obj.serialized_type.node:\n            # save decoded data\n            tree = obj.read_typetree()\n            fp = os.path.join(extract_dir, f\"{tree['m_Name']}.json\")\n            with open(fp, \"wt\", encoding = \"utf8\") as f:\n                json.dump(tree, f, ensure_ascii = False, indent = 4)\n\n        # edit\n        if obj.serialized_type.node:\n            tree = obj.read_typetree()\n            # apply modifications to the data within the tree\n            obj.save_typetree(tree)\n        else:\n            data = obj.read(check_read=False)\n            with open(os.path.join(replace_dir, data.m_Name)) as f:\n                data.save(raw_data = f.read())\n```\n\n**TypeTreeGenerator**\n\nUnityPy can generate the typetrees of MonoBehaviours from the game assemblies using an optional package, ``TypeTreeGeneratorAPI``, which has to be installed via pip.\nUnityPy will automatically try to generate the typetree of MonoBehaviours if the typetree is missing in the assets and ``env.typetree_generator`` is set.\n\n```py\nimport UnityPy\nfrom UnityPy.helpers.TypeTreeGenerator import TypeTreeGenerator\n\n# create generator\nGAME_ROOT_DIR: str\n# e.g. r\"D:\\Program Files (x86)\\Steam\\steamapps\\common\\Aethermancer Demo\"\nGAME_UNITY_VERSION: str\n# you can get the version via an object\n# e.g. objects[0].assets_file.unity_version\n\ngenerator = TypeTreeGenerator(GAME_UNITY_VERSION)\ngenerator.load_local_game(GAME_ROOT_DIR)\n# generator.load_local_game(root_dir: str) - for a Windows game\n# generator.load_dll_folder(dll_dir: str) - for mono / non-il2cpp or generated dummies\n# generator.load_dll(dll: bytes)\n# generator.load_il2cpp(il2cpp: bytes, metadata: bytes)\n\nenv = UnityPy.load(fp)\n# assign generator to env\nenv.typetree_generator = generator\nfor obj in objects:\n    if obj.type.name == \"MonoBehaviour\":\n        # automatically tries to use the generator in the background if necessary\n        x = obj.read()\n```\n\n\n### [AudioClip](UnityPy/classes/AudioClip.py)\n\n-   `.samples` - `{sample-name : sample-data}`\n\nThe samples are converted into the .wav format.\nThe sample data is a .wav file in bytes.\n\n```python\nclip : AudioClip\nfor name, data in clip.samples.items():\n    with open(name, \"wb\") as f:\n        f.write(data)\n```\n\n### [Font](UnityPy/classes/Font.py)\n\n```python\nif obj.type.name == \"Font\":\n    font : Font = obj.read()\n    if font.m_FontData:\n        extension = \".ttf\"\n        if font.m_FontData[0:4] == b\"OTTO\":\n            extension = \".otf\"\n\n    with open(os.path.join(path, font.m_Name+extension), \"wb\") as f:\n        f.write(font.m_FontData)\n```\n\n### [Mesh](UnityPy/classes/Mesh.py)\n\n-   `.export()` - mesh exported as .obj (str)\n\nThe mesh will be converted to the Wavefront .obj file format.\n\n```python\nmesh : Mesh\nwith open(f\"{mesh.m_Name}.obj\", \"wt\", newline = \"\") as f:\n    # newline = \"\" is important\n    f.write(mesh.export())\n```\n\n### Renderer, MeshRenderer, SkinnedMeshRenderer\n\nALPHA-VERSION\n\n-   `.export(export_dir)` - exports the associated mesh, materials, and textures into the given directory\n\nThe mesh and materials will be in the Wavefront formats.\n\n```python\nmesh_renderer : Renderer\nexport_dir: str\n\nif mesh_renderer.m_GameObject:\n    # get the name of the model\n    game_object = mesh_renderer.m_GameObject.read()\n    export_dir = os.path.join(export_dir, game_object.m_Name)\nmesh_renderer.export(export_dir)\n```\n\n### [Texture2DArray](UnityPy/classes/Texture2DArray.py)\n\nWARNING - not well tested\n\n-   `.m_Name`\n-   `.image` converts the texture2darray into a `PIL.Image`\n-   `.m_Width` - texture width (int)\n-   `.m_Height` - texture height (int)\n\n**Export**\n\n```python\nimport os\nfrom PIL import Image\nfor obj in env.objects:\n    if obj.type.name == \"Texture2DArray\":\n        # export texture\n        data = obj.read()\n        for i, image in enumerate(data.images):\n            image.save(os.path.join(path, f\"{data.m_Name}_{i}.png\"))\n        # editing isn't supported yet!\n```\n\n## Custom-Filesystem\n\nUnityPy uses [fsspec](https://github.com/fsspec/filesystem_spec) under the hood to manage all filesystem interactions.\nThis allows using various different types of filesystems without having to change UnityPy's code.\nIt also means that you can use your own custom filesystem to e.g. handle indirection via catalog files, load assets on demand from a server, or decrypt files.\n\nFollowing methods of the filesystem have to be implemented for using it in UnityPy.\n\n-   sep (not a function, just the seperator as character)\n-   isfile(self, path: str) -\u003e bool\n-   isdir(self, path: str) -\u003e bool\n-   exists(self, path: str, \\*\\*kwargs) -\u003e bool\n-   walk(self, path: str, \\*\\*kwargs) -\u003e Iterable[List[str], List[str], List[str]]\n-   open(self, path: str, mode: str = \"rb\", \\*\\*kwargs) -\u003e file (\"rb\" mode required, \"wt\" required for ModelExporter)\n-   makedirs(self, path: str, exist_ok: bool = False) -\u003e bool\n\n## Credits\n\nFirst of all,\nthanks a lot to all contributors of UnityPy and all of its users.\n\nAlso,\nmany thanks to:\n\n-   [Perfare](https://github.com/Perfare) for creating and maintaining and every contributor of [AssetStudio](https://github.com/Perfare/AssetStudio)\n-   [ds5678](https://github.com/ds5678) for the [TypeTreeDumps](https://github.com/AssetRipper/TypeTreeDumps) and the [custom minimal Tpk format](https://github.com/AssetRipper/Tpk)\n-   [Razmoth](https://github.com/Razmoth) for figuring out and sharing Unity CN's AssetBundle decryption ([src](https://github.com/Razmoth/PGRStudio)).\n-   [nesrak1](https://github.com/nesrak1) for figuring out the [Switch texture swizzling](https://github.com/nesrak1/UABEA/blob/master/TexturePlugin/Texture2DSwitchDeswizzler.cs)\n-   xiop_13690 (discord) for figuring out unsolved issues of the ManagedReferencesRegistry","funding_links":["https://github.com/sponsors/K0lb3"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk0lb3%2Funitypy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk0lb3%2Funitypy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk0lb3%2Funitypy/lists"}