Skip to content

Commit 4f80733

Browse files
committed
1.2.6.2
1 parent ec22ac1 commit 4f80733

39 files changed

Lines changed: 1288 additions & 610 deletions

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2019 K0lb3
3+
Copyright (c) 2019-2020 K0lb3
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md‎

Lines changed: 157 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,26 @@
11
# UnityPy
2-
A Unity asset extractor based on [AssetStudio](https://github.com/Perfare/AssetStudio).
2+
[![Discord server invite](https://discordapp.com/api/guilds/603359898507673630/embed.png)](https://discord.gg/C6txv7M)
3+
[![PyPI supported Python versions](https://img.shields.io/pypi/pyversions/UnityPy.svg)](https://pypi.python.org/pypi/UnityPy)
4+
[![Win/Mac/Linux](https://img.shields.io/badge/platform-windows%20%7C%20macos%20%7C%20linux-informational)]()
5+
[![MIT](https://img.shields.io/pypi/l/UnityPy.svg)](https://github.com/K0lb3/UnityPy/blob/master/LICENSE)
6+
7+
A Unity asset extractor for Python based on [AssetStudio](https://github.com/Perfare/AssetStudio).
8+
9+
1. [Installation](https://github.com/K0lb3/UnityPy#installation)
10+
2. [Example](https://github.com/K0lb3/UnityPy#example)
11+
3. [Important Classes](https://github.com/K0lb3/UnityPy#important-classes)
12+
4. [Important Object Types](https://github.com/K0lb3/UnityPy#important-object-types)
13+
5. [Goals](https://github.com/K0lb3/UnityPy#goals)
14+
6. [Motivation](https://github.com/K0lb3/UnityPy#motivation)
15+
7. [Community](https://github.com/K0lb3/UnityPy#community)
316

417
## Installation
518

19+
**Python 3.6.0 or higher is required**
20+
621
## UnityPy
722

8-
### main module
23+
### core package
924
```cmd
1025
pip install UnityPy
1126
```
@@ -16,58 +31,168 @@ python setup.py install
1631
```
1732

1833
### optional modules
19-
It's highly recommended to install following modules to enjoy the full power of UnityPy.
20-
21-
All texture modules use [Cython](https://cython.org/), so they won't work on some systems.
2234

23-
Windows users have to install [Microsoft Visual C++ 14.0 Build Tools Only](http://go.microsoft.com/fwlink/?LinkId=691126&fixForIE=.exe) to be able to use Cython.
24-
25-
* [python-fsb5](https://github.com/HearthSim/python-fsb5) - FSB Audio Sample Support
35+
* [python-fsb5](https://github.com/HearthSim/python-fsb5) - required to extract samples from AudioClips
2636
```cmd
2737
pip install fsb5
2838
```
2939

40+
**Cython required**
41+
42+
All of the following packages decompress specific texture formats and require [Cython](https://cython.org/).
43+
44+
It's highly recommended to install the following modules to enjoy the full power of UnityPy.
45+
46+
Windows users have to install [Microsoft Visual C++ 14.0 Build Tools Only](http://go.microsoft.com/fwlink/?LinkId=691126&fixForIE=.exe) to be able to use Cython.
47+
48+
49+
3050
* [decrunch](https://github.com/HearthSim/decrunch) - crunch texture support
31-
```cmd
32-
pip install decrunch
33-
```
3451
* [etcpack](https://github.com/K0lb3/etcpack) - ETC texture support
35-
```cmd
36-
pip install etcpack
37-
```
3852
* [pvrtc_decoder](https://github.com/K0lb3/pvrtc_decoder) - PVRTC Texture Support
39-
```cmd
40-
pip install pvrtc_decoder
41-
```
4253
* [astc_decomp](https://github.com/K0lb3/astc_decomp) - ASTC Texture Support
54+
4355
```cmd
56+
pip install decrunch
57+
pip install etcpac
58+
pip install pvrtc_decoder
4459
pip install astc_decomp
4560
```
4661

47-
## Usage
62+
## Example
63+
64+
The following is a simple example.
65+
4866
```python
67+
import os
4968
from UnityPy import AssetsManager
5069

51-
am = AssetsManager()
70+
def unpack_all_assets(source_folder : str, destination_folder : str):
71+
# iterate over all files in source folder
72+
for root, dirs, files in os.walk(source_folder):
73+
for file_name in files:
74+
# generate file_path
75+
file_path = os.path.join(root, file_name)
76+
# load that file via AssetsManager
77+
am = AssetsManager(file_path)
78+
79+
# iterate over all assets and named objects
80+
for asset in am.assets.values():
81+
for obj in asset.objects.values():
82+
# only process specific object types
83+
if obj.type in ["Texture2D", "Sprite"]:
84+
# parse the object data
85+
data = obj.read()
86+
87+
# create destination path
88+
dest = os.path.join(destination_folder, data.name)
89+
90+
# make sure that the extension is correct
91+
# you probably only want to do so with images/textures
92+
dest, ext = os.path.splitext(dest)
93+
dest = dest + ".png"
94+
95+
img = data.image
96+
img.save(dest)
97+
```
98+
99+
You probably have to read [Important Classes](https://github.com/K0lb3/UnityPy#important-classes)
100+
and [Important Object Types](https://github.com/K0lb3/UnityPy#important-object-types) to understand how it works.
101+
102+
People who have slightly advanced python skills should take a look at [AssetBatchConverter.py](https://github.com/K0lb3/UnityPy/blob/master/AssetBatchConverter.py) for a more advanced example.
103+
104+
105+
## Important Classes
106+
107+
### [AssetsManager](https://github.com/K0lb3/UnityPy/blob/master/UnityPy/AssetsManager.py)
52108

53-
# Load file via file path
54-
am.load_file(fp)
55-
# Load all files in a folder
56-
am.load_folder(fp)
109+
AssetsManager loads and parses the files that are given to it.
110+
It can be initialized via:
111+
* a file path - apk files can be loaded as well
112+
* a folder path - loads all files in that folder (bad idea for folders with a lot of files)
113+
* a stream - e.g. io.BytesIO, filestream,...
114+
* a bytes object - will be loaded into a stream
57115

58-
for name, asset in am.assets.items():
59-
for id, obj in asset.objects.items():
60-
data = obj.read()
61-
````
116+
UnityPy can detect itself if the file is a WebFile, BundleFile, Asset or APK itself.
117+
118+
The unpacked assets will be loaded into ``.assets``, which is a dict consisting of ``asset-name : asset``.
119+
120+
```python
121+
from UnityPy import AssetsManager
122+
am = AssetsManager(src)
123+
124+
for asset_name, asset in am.assets.items():
125+
pass
126+
```
127+
128+
### [Asset]((https://github.com/K0lb3/UnityPy/blob/master/UnityPy/files/SerializedFile.py))
129+
130+
Assets are a container that contains multiple objects.
131+
One of these objects can be an AssetBundle, which contains a file path for some of the objects in the same asset.
132+
133+
All objects can be found in the ``.objects`` dict - ``{ID : object}``.
134+
135+
The objects which have a file path can be found in the ``.container`` dict - ``{path : object}``.
136+
137+
### [Object]((https://github.com/K0lb3/UnityPy/blob/master/UnityPy/ObjectReader.py))
138+
139+
Objects contain the *actual* files which, e.g. textures, text files, meshes, settings, ...
140+
141+
To 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.
142+
143+
## Important Object Types
144+
145+
All object types can be found in [UnityPy/classes](https://github.com/K0lb3/UnityPy/tree/master/UnityPy/classes).
146+
147+
### [Texture2D](https://github.com/K0lb3/UnityPy/blob/master/UnityPy/classes/Texture2D.py)
148+
149+
* ``.name``
150+
* ``.image`` converts the texture into a ``PIL.Image``
151+
* ``.m_Width`` - texture width (int)
152+
* ``.m_Height`` - texture height (int)
153+
154+
### [Sprite](https://github.com/K0lb3/UnityPy/blob/master/UnityPy/classes/Sprite.py)
155+
156+
Sprites are part of a texture and can have a separate alpha-image as well.
157+
Unlike most other extractors (including AssetStudio) UnityPy merges those two images by itself.
158+
159+
* ``.name``
160+
* ``.image`` - converts the merged texture part into a ``PIL.Image``
161+
* ``.m_Width`` - sprite width (int)
162+
* ``.m_Height`` - sprite height (int)
163+
164+
### [TextAsset](https://github.com/K0lb3/UnityPy/blob/master/UnityPy/classes/TextAsset.py)
165+
166+
TextAssets are usually normal text files.
167+
168+
* ``.name``
169+
* ``.script`` - binary data (bytes)
170+
* ``.text`` - script decoded via UTF8 (str)
171+
172+
Some games save binary data as TextFile, so it's usually better to use ``.script``.
173+
174+
### [MonoBehaviour](https://github.com/K0lb3/UnityPy/blob/master/UnityPy/classes/MonoBehaviour.py)
175+
176+
MonoBehaviour assets are usually binary data that has to be decoded.
177+
e.g. via msgpack, protobuf
178+
179+
* ``.name``
180+
* ``.script``- binary data (bytes)
181+
182+
### [AudioClip](https://github.com/K0lb3/UnityPy/blob/master/UnityPy/classes/AudioClip.py)
183+
184+
* ``.samples`` - ``{sample-name : sample-data}`` dict
62185

63186
## Goals
64-
### near future
65-
* adding a documentation
66187

67-
### far future
68-
* ability to edit assets (like in UABE)
69-
* broader object type support
188+
### WIP
189+
* a documentation
190+
* the ability to edit assets (like in UABE)
191+
192+
### planned
193+
* support for more object types
70194
* code optimization
195+
* speed-ups via C-extensions
71196
* multiprocessing
72197

73198
## Motivation
@@ -76,8 +201,5 @@ The problem in unitypack isn't that easy to fix and the undocumented code is a b
76201
That's why I tried other tools like UABE and AssetStudio. Sadly none of these tools can be used like unitypack.
77202
That's why I started this project.
78203

79-
## License
80-
UnityPy is licensed under the terms of the MIT license. The full license text is available in the LICENSE file.
81-
82204
## Community
83205
[Discord](https://discord.gg/C6txv7M)

0 commit comments

Comments
 (0)