Skip to content

Commit a4a410a

Browse files
isHarryhK0lb3
authored andcommitted
docs: README - add configuration section
1 parent bcc9aab commit a4a410a

File tree

1 file changed

+62
-24
lines changed

1 file changed

+62
-24
lines changed

README.md

Lines changed: 62 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ if UnityPy.__version__ != '1.9.6':
4343
2. [Example](#example)
4444
3. [Important Classes](#important-classes)
4545
4. [Important Object Types](#important-object-types)
46-
5. [Custom Filesystem](#custom-filesystem)
46+
5. [Configurations](#configurations)
4747
6. [Credits](#credits)
4848

4949
## Installation
@@ -73,15 +73,10 @@ In case a new(ish) Python version is used, it can happen that the C-dependencies
7373
In 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.
7474
Another 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.
7575

76-
### Crash without warning/error
76+
#### Crash without warning/error
7777

7878
The C-implementation of the typetree reader can directly crash Python.
79-
In case this happens, the usage of the C-typetree reader can be disabled by adding these two lines to your main file.
80-
81-
```python
82-
from UnityPy.helpers import TypeTreeHelper
83-
TypeTreeHelper.read_typetree_boost = False
84-
```
79+
In case this happens, the usage of the C-typetree reader can be disabled. Read [this section](#disable-typetree-c-implementation) for more details.
8580

8681
## Example
8782

@@ -135,14 +130,9 @@ def unpack_all_assets(source_folder: str, destination_folder: str):
135130
You probably have to read [Important Classes](#important-classes)
136131
and [Important Object Types](#important-object-types) to understand how it works.
137132

138-
People with slightly advanced Python skills should look at [UnityPy/tools/extractor.py](UnityPy/tools/extractor.py) for a more advanced example.
133+
Users with slightly advanced Python skills should look at [UnityPy/tools/extractor.py](UnityPy/tools/extractor.py) for a more advanced example.
139134
It can also be used as a general template or as an importable tool.
140135

141-
### Setting the decryption key for Unity CN's AssetBundle encryption
142-
143-
The Chinese version of Unity has its own builtin 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.
144-
To enable encryption simply use `UnityPy.set_assetbundle_decrypt_key(key)`, with key being the value that the game that loads the bundles passes to `AssetBundle.SetAssetBundleDecryptKey`.
145-
146136
## Important Classes
147137

148138
### Environment
@@ -350,7 +340,7 @@ The samples are converted into the .wav format.
350340
The sample data is a .wav file in bytes.
351341

352342
```python
353-
clip : AudioClip
343+
clip: AudioClip
354344
for name, data in clip.samples.items():
355345
with open(name, "wb") as f:
356346
f.write(data)
@@ -362,7 +352,7 @@ for name, data in clip.samples.items():
362352

363353
```python
364354
if obj.type.name == "Font":
365-
font : Font = obj.read()
355+
font: Font = obj.read()
366356
if font.m_FontData:
367357
extension = ".ttf"
368358
if font.m_FontData[0:4] == b"OTTO":
@@ -427,21 +417,69 @@ for obj in env.objects:
427417
# editing isn't supported yet!
428418
```
429419

430-
## Custom Filesystem
420+
## Configurations
421+
422+
There're several configurations and interfaces that provide the customizability to UnityPy.
423+
424+
### Unity CN Decryption
425+
426+
The Chinese version of Unity has its own builtin 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.
427+
To enable encryption simply use the code as follow, with `key` being the value that the game that loads the bundles passes to `AssetBundle.SetAssetBundleDecryptKey`.
428+
429+
```python
430+
import UnityPy
431+
UnityPy.set_assetbundle_decrypt_key(key)
432+
```
433+
434+
### Unity Fallback Version
435+
436+
In case UnityPy failed to detect the Unity version of the game assets, you can set a fallback version. e.g.
437+
438+
```python
439+
import UnityPy.config
440+
UnityPy.config.FALLBACK_UNITY_VERSION = "2.5.0f5"
441+
```
442+
443+
### Disable Typetree C-Implementation
444+
445+
The [C-implementation](UnityPyBoost/) of typetree reader can boost the parsing of typetree by a lot. If you want to disable it and use pure Python reader, you can put the following 2 lines in your main file.
446+
447+
```python
448+
from UnityPy.helpers import TypeTreeHelper
449+
TypeTreeHelper.read_typetree_boost = False
450+
```
451+
452+
### Custom Block (De)compression
453+
454+
Some game assets have non-standard compression/decompression algorithm applied on the block data. If you wants to customize the compression/decompression function, you can modify the corresponding function mapping. e.g.
455+
456+
```python
457+
from UnityPy.enums.BundleFile import CompressionFlags
458+
flag = CompressionFlags.LZHAM
459+
460+
from UnityPy.helpers import CompressionHelper
461+
CompressionHelper.COMPRESSION_MAP[flag] = custom_compress
462+
CompressionHelper.DECOMPRESSION_MAP[flag] = custom_decompress
463+
```
464+
465+
- `custom_compress(data: bytes) -> bytes` (where bytes can also be bytearray or memoryview)
466+
- `custom_decompress(data: bytes, uncompressed_size: int) -> bytes`
467+
468+
### Custom Filesystem
431469

432470
UnityPy uses [fsspec](https://github.com/fsspec/filesystem_spec) under the hood to manage all filesystem interactions.
433471
This allows using various different types of filesystems without having to change UnityPy's code.
434472
It 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.
435473

436474
Following methods of the filesystem have to be implemented for using it in UnityPy.
437475

438-
- sep (not a function, just the separator as character)
439-
- isfile(self, path: str) -> bool
440-
- isdir(self, path: str) -> bool
441-
- exists(self, path: str, \*\*kwargs) -> bool
442-
- walk(self, path: str, \*\*kwargs) -> Iterable[List[str], List[str], List[str]]
443-
- open(self, path: str, mode: str = "rb", \*\*kwargs) -> file ("rb" mode required, "wt" required for ModelExporter)
444-
- makedirs(self, path: str, exist_ok: bool = False) -> bool
476+
- `sep` (not a function, just the separator as character)
477+
- `isfile(self, path: str) -> bool`
478+
- `isdir(self, path: str) -> bool`
479+
- `exists(self, path: str, **kwargs) -> bool`
480+
- `walk(self, path: str, **kwargs) -> Iterable[List[str], List[str], List[str]]`
481+
- `open(self, path: str, mode: str = "rb", **kwargs) -> file` ("rb" mode required, "wt" required for ModelExporter)
482+
- `makedirs(self, path: str, exist_ok: bool = False) -> bool`
445483

446484
## Credits
447485

0 commit comments

Comments
 (0)