Skip to content

Commit 9232cdd

Browse files
authored
Support Encryption of CN Builds (K0lb3#157)
* implement CN Encryption for BundlePackages * Improve Decrypion and BundleFile handling * Update README.md * Update README.md
1 parent a4b2f06 commit 9232cdd

9 files changed

Lines changed: 285 additions & 93 deletions

File tree

‎README.md‎

Lines changed: 51 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# UnityPy
2+
23
[![Discord server invite](https://discordapp.com/api/guilds/603359898507673630/embed.png)](https://discord.gg/C6txv7M)
34
[![PyPI supported Python versions](https://img.shields.io/pypi/pyversions/UnityPy.svg)](https://pypi.python.org/pypi/UnityPy)
45
[![Win/Mac/Linux](https://img.shields.io/badge/platform-windows%20%7C%20macos%20%7C%20linux-informational)]()
@@ -9,31 +10,29 @@ A Unity asset extractor for Python based on [AssetStudio](https://github.com/Per
910

1011
Next to extraction, it also supports editing Unity assets.
1112
So far following obj types can be edited:
12-
- Texture2D
13-
- Sprite(indirectly via linked Texture2D)
14-
- TextAsset
15-
- MonoBehaviour (and all other types that you have the typetree of)
13+
14+
- Texture2D
15+
- Sprite(indirectly via linked Texture2D)
16+
- TextAsset
17+
- MonoBehaviour (and all other types that you have the typetree of)
1618

1719
If you need advice or if you want to talk about (game) data-mining,
1820
feel free to join the [UnityPy Discord](https://discord.gg/C6txv7M).
1921

20-
2122
If you're using UnityPy a commercial project,
2223
a donation to a charitable cause or a sponsorship of this project is expected.
2324

24-
2525
**As UnityPy is still in active development breaking changes can happen.**
2626
Those changes are usually limited to minor versions (x.y) and not to patch versions (x.y.z).
2727
So in case that you don't want to actively maintain your project,
2828
make sure to make a note of the used UnityPy version in your README or add a check in your code.
2929
e.g.
30+
3031
```python
3132
if UnityPy.__version__ != '1.9.6':
3233
raise ImportError("Invalid UnityPy version detected. Please use version 1.9.6")
3334
```
3435

35-
36-
3736
1. [Installation](#installation)
3837
2. [Example](#example)
3938
3. [Important Classes](#important-classes)
@@ -78,7 +77,6 @@ TypeTreeHelper.read_typetree_c = False
7877

7978
The following is a simple example.
8079

81-
8280
```python
8381
import os
8482
import UnityPy
@@ -130,6 +128,10 @@ and [Important Object Types](#important-object-types) to understand how it works
130128
People with slightly advanced python skills should look at [UnityPy/tools/extractor.py](UnityPy/tools/extractor.py) for a more advanced example.
131129
It can also be used as a general template or as an importable tool.
132130

131+
### Setting the decryption key for Unity CN's AssetBundle encryption
132+
133+
The 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.
134+
To 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`.
133135

134136
## Important Classes
135137

@@ -138,16 +140,16 @@ It can also be used as a general template or as an importable tool.
138140
Environment loads and parses the given files.
139141
It can be initialized via:
140142

141-
* a file path - apk files can be loaded as well
142-
* a folder path - loads all files in that folder (bad idea for folders with a lot of files)
143-
* a stream - e.g., io.BytesIO, file stream,...
144-
* a bytes object - will be loaded into a stream
143+
- a file path - apk files can be loaded as well
144+
- a folder path - loads all files in that folder (bad idea for folders with a lot of files)
145+
- a stream - e.g., io.BytesIO, file stream,...
146+
- a bytes object - will be loaded into a stream
145147

146148
UnityPy can detect if the file is a WebFile, BundleFile, Asset, or APK.
147149

148-
The unpacked assets will be loaded into ``.files``, a dict consisting of ``asset-name : asset``.
150+
The unpacked assets will be loaded into `.files`, a dict consisting of `asset-name : asset`.
149151

150-
All objects of the loaded assets can be easily accessed via ``.objects``,
152+
All objects of the loaded assets can be easily accessed via `.objects`,
151153
which itself is a simple recursive iterator.
152154

153155
```python
@@ -177,28 +179,29 @@ with open(dst, "wb") as f:
177179
Assets are a container that contains multiple objects.
178180
One of these objects can be an AssetBundle, which contains a file path for some of the objects in the same asset.
179181

180-
All objects can be found in the ``.objects`` dict - ``{ID : object}``.
182+
All objects can be found in the `.objects` dict - `{ID : object}`.
181183

182-
The objects with a file path can be found in the ``.container`` dict - ``{path : object}``.
184+
The objects with a file path can be found in the `.container` dict - `{path : object}`.
183185

184186
### [Object](UnityPy/files/ObjectReader.py)
185187

186-
Objects contain the *actual* files, e.g., textures, text files, meshes, settings, ...
188+
Objects contain the _actual_ files, e.g., textures, text files, meshes, settings, ...
187189

188-
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. Serialized objects can be set with raw data using ``.set_raw_data(data)`` or modified with ``.save()`` function, if supported.
190+
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. Serialized objects can be set with raw data using `.set_raw_data(data)` or modified with `.save()` function, if supported.
189191

190192
## Important Object Types
191193

192194
All object types can be found in [UnityPy/classes](UnityPy/classes/).
193195

194196
### [Texture2D](UnityPy/classes/Texture2D.py)
195197

196-
* ``.name``
197-
* ``.image`` converts the texture into a ``PIL.Image``
198-
* ``.m_Width`` - texture width (int)
199-
* ``.m_Height`` - texture height (int)
198+
- `.name`
199+
- `.image` converts the texture into a `PIL.Image`
200+
- `.m_Width` - texture width (int)
201+
- `.m_Height` - texture height (int)
202+
203+
**Export**
200204

201-
__Export__
202205
```python
203206
from PIL import Image
204207
for obj in env.objects:
@@ -218,12 +221,13 @@ for obj in env.objects:
218221
Sprites are part of a texture and can have a separate alpha-image as well.
219222
Unlike most other extractors (including AssetStudio), UnityPy merges those two images by itself.
220223

221-
* ``.name``
222-
* ``.image`` - converts the merged texture part into a ``PIL.Image``
223-
* ``.m_Width`` - sprite width (int)
224-
* ``.m_Height`` - sprite height (int)
224+
- `.name`
225+
- `.image` - converts the merged texture part into a `PIL.Image`
226+
- `.m_Width` - sprite width (int)
227+
- `.m_Height` - sprite height (int)
228+
229+
**Export**
225230

226-
__Export__
227231
```python
228232
for obj in env.objects:
229233
if obj.type.name == "Sprite":
@@ -235,13 +239,14 @@ for obj in env.objects:
235239

236240
TextAssets are usually normal text files.
237241

238-
* ``.name``
239-
* ``.script`` - binary data (bytes)
240-
* ``.text`` - script decoded via UTF8 (str)
242+
- `.name`
243+
- `.script` - binary data (bytes)
244+
- `.text` - script decoded via UTF8 (str)
245+
246+
Some games save binary data as TextFile, so it's usually better to use `.script`.
241247

242-
Some games save binary data as TextFile, so it's usually better to use ``.script``.
248+
**Export**
243249

244-
__Export__
245250
```python
246251
for obj in env.objects:
247252
if obj.type.name == "TextAsset":
@@ -263,11 +268,12 @@ If a type tree exists, it can be used to read the whole data,
263268
but if it doesn't exist, then it is usually necessary to investigate the class that loads the specific MonoBehaviour to extract the data.
264269
([example](examples/CustomMonoBehaviour/get_scriptable_texture.py))
265270

266-
* ``.name``
267-
* ``.script``
268-
* ``.raw_data`` - data after the basic initialisation
271+
- `.name`
272+
- `.script`
273+
- `.raw_data` - data after the basic initialisation
274+
275+
**Export**
269276

270-
__Export__
271277
```python
272278
import json
273279

@@ -300,7 +306,7 @@ for obj in env.objects:
300306

301307
### [AudioClip](UnityPy/classes/AudioClip.py)
302308

303-
* ``.samples`` - ``{sample-name : sample-data}``
309+
- `.samples` - `{sample-name : sample-data}`
304310

305311
The samples are converted into the .wav format.
306312
The sample data is a .wav file in bytes.
@@ -326,10 +332,9 @@ if obj.type.name == "Font":
326332
f.write(font.m_FontData)
327333
```
328334

329-
330335
### [Mesh](UnityPy/classes/Mesh.py)
331336

332-
* ``.export()`` - mesh exported as .obj (str)
337+
- `.export()` - mesh exported as .obj (str)
333338

334339
The mesh will be converted to the Wavefront .obj file format.
335340

@@ -341,9 +346,10 @@ with open(f"{mesh.name}.obj", "wt", newline = "") as f:
341346
```
342347

343348
### Renderer, MeshRenderer, SkinnedMeshRenderer
349+
344350
ALPHA-VERSION
345351

346-
* ``.export(export_dir)`` - exports the associated mesh, materials, and textures into the given directory
352+
- `.export(export_dir)` - exports the associated mesh, materials, and textures into the given directory
347353

348354
The mesh and materials will be in the Wavefront formats.
349355

@@ -366,5 +372,6 @@ thanks a lot to all contributors of UnityPy and all of its users.
366372
Also,
367373
many thanks to:
368374

369-
- [Perfare](https://github.com/Perfare) for creating and maintaining and every contributor of [AssetStudio](https://github.com/Perfare/AssetStudio)
370-
- [ds5678](https://github.com/ds5678) for the [TypeTreeDumps](https://github.com/AssetRipper/TypeTreeDumps) and the [custom minimal Tpk format](https://github.com/AssetRipper/Tpk)
375+
- [Perfare](https://github.com/Perfare) for creating and maintaining and every contributor of [AssetStudio](https://github.com/Perfare/AssetStudio)
376+
- [ds5678](https://github.com/ds5678) for the [TypeTreeDumps](https://github.com/AssetRipper/TypeTreeDumps) and the [custom minimal Tpk format](https://github.com/AssetRipper/Tpk)
377+
- [Razmoth](https://github.com/Razmoth) for figuring out and sharing Unity CN's AssetBundle decryption ([src](https://github.com/Razmoth/PGRStudio)).

‎UnityPy/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
__version__ = "1.9.20"
22

33
from .environment import Environment
4+
from .helpers.ArchiveStorageManager import set_assetbundle_decrypt_key
45

56

67
def load(*args):

‎UnityPy/config.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,7 @@
22
FALLBACK_UNITY_VERSION = "2.5.0f5"
33
# determines if the typetree structures for the Object types will be parsed
44
# disabling this will reduce the load time by a lot (half of the time is spend on parsing the typetrees)
5-
# but it will also prevent saving an edited file
5+
# but it will also prevent saving an edited file
66
SERIALIZED_FILE_PARSE_TYPETREE = True
7+
# enable for chinese version with AssetBundle encryption
8+
USE_CN_ENCRYPTION = False

‎UnityPy/enums/BundleFile.py‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
from enum import IntFlag
2+
3+
4+
class CompressionFlags(IntFlag):
5+
NONE = 0
6+
LZMA = 1
7+
LZ4 = 2
8+
LZ4HC = 3
9+
LZHAM = 4
10+
11+
12+
class ArchiveFlagsOld(IntFlag):
13+
CompressionTypeMask = 0x3F
14+
BlocksAndDirectoryInfoCombined = 0x40
15+
BlocksInfoAtTheEnd = 0x80
16+
OldWebPluginCompatibility = 0x100
17+
UsesAssetBundleEncryption = 0x200
18+
19+
20+
class ArchiveFlags(IntFlag):
21+
CompressionTypeMask = 0x3F
22+
BlocksAndDirectoryInfoCombined = 0x40
23+
BlocksInfoAtTheEnd = 0x80
24+
OldWebPluginCompatibility = 0x100
25+
BlockInfoNeedPaddingAtStart = 0x200
26+
UsesAssetBundleEncryption = 0x400

‎UnityPy/enums/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
from .Audio import AudioType, AudioCompressionFormat, AUDIO_TYPE_EXTEMSION
22
from .BuildTarget import BuildTarget
3+
from .BundleFile import ArchiveFlags, ArchiveFlagsOld, CompressionFlags
34
from .ClassIDType import ClassIDType
45
from .FileType import FileType
56
from .TextureFormat import TextureFormat

0 commit comments

Comments
 (0)