Skip to content

Commit 738ea76

Browse files
committed
docs: README - add configuration section
1 parent 345ea09 commit 738ea76

File tree

1 file changed

+59
-24
lines changed

1 file changed

+59
-24
lines changed

README.md

Lines changed: 59 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
@@ -349,7 +339,7 @@ The samples are converted into the .wav format.
349339
The sample data is a .wav file in bytes.
350340

351341
```python
352-
clip : AudioClip
342+
clip: AudioClip
353343
for name, data in clip.samples.items():
354344
with open(name, "wb") as f:
355345
f.write(data)
@@ -361,7 +351,7 @@ for name, data in clip.samples.items():
361351

362352
```python
363353
if obj.type.name == "Font":
364-
font : Font = obj.read()
354+
font: Font = obj.read()
365355
if font.m_FontData:
366356
extension = ".ttf"
367357
if font.m_FontData[0:4] == b"OTTO":
@@ -426,21 +416,66 @@ for obj in env.objects:
426416
# editing isn't supported yet!
427417
```
428418

429-
## Custom Filesystem
419+
## Configurations
420+
421+
There're several configurations and interfaces that provide the customizability to UnityPy.
422+
423+
### Unity CN Decryption
424+
425+
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.
426+
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`.
427+
428+
```python
429+
import UnityPy
430+
UnityPy.set_assetbundle_decrypt_key(key)
431+
```
432+
433+
### Unity Fallback Version
434+
435+
In case UnityPy failed to detect the Unity version of the game assets, you can set a fallback version. e.g.
436+
437+
```python
438+
import UnityPy.config
439+
UnityPy.config.FALLBACK_UNITY_VERSION = "2.5.0f5"
440+
```
441+
442+
### Disable Typetree C-Implementation
443+
444+
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.
445+
446+
```python
447+
from UnityPy.helpers import TypeTreeHelper
448+
TypeTreeHelper.read_typetree_boost = False
449+
```
450+
451+
### Custom Block (De)compression
452+
453+
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.
454+
455+
```python
456+
from UnityPy.enums.BundleFile import CompressionFlags
457+
flag = CompressionFlags.LZHAM
458+
459+
from UnityPy.helpers import CompressionHelper
460+
CompressionHelper.COMPRESSION_MAP[flag] = some_function
461+
CompressionHelper.DECOMPRESSION_MAP[flag] = another_function
462+
```
463+
464+
### Custom Filesystem
430465

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

435470
Following methods of the filesystem have to be implemented for using it in UnityPy.
436471

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

445480
## Credits
446481

0 commit comments

Comments
 (0)