Skip to content

Commit 345ea09

Browse files
committed
docs: README - fix typo and update legacy content
1 parent b811a29 commit 345ea09

File tree

1 file changed

+43
-41
lines changed

1 file changed

+43
-41
lines changed

README.md

Lines changed: 43 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,9 @@
99
A Unity asset extractor for Python based on [AssetStudio](https://github.com/Perfare/AssetStudio).
1010

1111
Next to extraction, UnityPy also supports editing Unity assets.
12-
Via the typetree structure all objects types can be edited.
13-
```py
12+
Via the typetree structure all object types can be edited.
13+
14+
```python
1415
# modification via dict:
1516
raw_dict = obj.read_typetree()
1617
# modify raw dict
@@ -24,11 +25,11 @@ Via the typetree structure all objects types can be edited.
2425
If you need advice or if you want to talk about (game) data-mining,
2526
feel free to join the [UnityPy Discord](https://discord.gg/C6txv7M).
2627

27-
If you're using UnityPy a commercial project,
28+
If you're using UnityPy for a commercial project,
2829
a donation to a charitable cause or a sponsorship of this project is expected.
2930

30-
**As UnityPy is still in active development breaking changes can happen.**
31-
Those changes are usually limited to minor versions (x.y) and not to patch versions (x.y.z).
31+
**As UnityPy is still in active development, breaking changes can happen.**
32+
These changes are usually limited to minor versions (x.y) and not to patch versions (x.y.z).
3233
So in case that you don't want to actively maintain your project,
3334
make sure to make a note of the used UnityPy version in your README or add a check in your code.
3435
e.g.
@@ -42,22 +43,22 @@ if UnityPy.__version__ != '1.9.6':
4243
2. [Example](#example)
4344
3. [Important Classes](#important-classes)
4445
4. [Important Object Types](#important-object-types)
45-
5. [Custom Fileystem](#custom-filesystem)
46+
5. [Custom Filesystem](#custom-filesystem)
4647
6. [Credits](#credits)
4748

4849
## Installation
4950

50-
**Python 3.7.0 or higher is required**
51+
**Python 3.7.0 or higher is required.**
5152

52-
via pypi
53+
Install via PyPI:
5354

54-
```cmd
55+
```bash
5556
pip install UnityPy
5657
```
5758

58-
from source
59+
Install from source code:
5960

60-
```cmd
61+
```bash
6162
git clone https://github.com/K0lb3/UnityPy.git
6263
cd UnityPy
6364
python -m pip install .
@@ -70,11 +71,11 @@ python -m pip install .
7071
Visual C++ Redistributable is required for the brotli dependency.
7172
In case a new(ish) Python version is used, it can happen that the C-dependencies of UnityPy might not be precompiled for this version.
7273
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.
73-
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.
74+
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.
7475

7576
### Crash without warning/error
7677

77-
The C-implementation of the typetree reader can directly crash python.
78+
The C-implementation of the typetree reader can directly crash Python.
7879
In case this happens, the usage of the C-typetree reader can be disabled by adding these two lines to your main file.
7980

8081
```python
@@ -90,7 +91,7 @@ The following is a simple example.
9091
import os
9192
import UnityPy
9293

93-
def unpack_all_assets(source_folder : str, destination_folder : str):
94+
def unpack_all_assets(source_folder: str, destination_folder: str):
9495
# iterate over all files in source folder
9596
for root, dirs, files in os.walk(source_folder):
9697
for file_name in files:
@@ -134,24 +135,24 @@ def unpack_all_assets(source_folder : str, destination_folder : str):
134135
You probably have to read [Important Classes](#important-classes)
135136
and [Important Object Types](#important-object-types) to understand how it works.
136137

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

140141
### Setting the decryption key for Unity CN's AssetBundle encryption
141142

142-
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.
143-
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`.
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`.
144145

145146
## Important Classes
146147

147-
### [Environment](UnityPy/environment.py)
148+
### Environment
148149

149-
Environment loads and parses the given files.
150+
[Environment](UnityPy/environment.py) loads and parses the given files.
150151
It can be initialized via:
151152

152153
- a file path - apk files can be loaded as well
153154
- a folder path - loads all files in that folder (bad idea for folders with a lot of files)
154-
- a stream - e.g., io.BytesIO, file stream,...
155+
- a stream - e.g., `io.BytesIO`, file stream,...
155156
- a bytes object - will be loaded into a stream
156157

157158
UnityPy can detect if the file is a WebFile, BundleFile, Asset, or APK.
@@ -183,26 +184,26 @@ with open(dst, "wb") as f:
183184
f.write(env.file.save())
184185
```
185186

186-
### [Asset](UnityPy/files/SerializedFile.py)
187+
### Asset
187188

188-
Assets are a container that contains multiple objects.
189+
Assets \([SerializedFile class](UnityPy/files/SerializedFile.py)\) are a container that contains multiple objects.
189190
One of these objects can be an AssetBundle, which contains a file path for some of the objects in the same asset.
190191

191192
All objects can be found in the `.objects` dict - `{ID : object}`.
192193

193194
The objects with a file path can be found in the `.container` dict - `{path : object}`.
194195

195-
### [Object](UnityPy/files/ObjectReader.py)
196+
### Object
196197

197-
Objects contain the _actual_ files, e.g., textures, text files, meshes, settings, ...
198+
Objects \([ObjectReader class](UnityPy/files/ObjectReader.py)\) contain the _actual_ files, e.g., textures, text files, meshes, settings, ...
198199

199200
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.
200201

201202
## Important Object Types
202203

203-
All object types can be found in [UnityPy/classes](UnityPy/classes/).
204+
Now UnityPy uses [auto generated classes](UnityPy/classes/generated.py). You can search for a specific classes in the module `UnityPy.classes`.
204205

205-
### [Texture2D](UnityPy/classes/Texture2D.py)
206+
### Texture2D
206207

207208
- `.m_Name`
208209
- `.image` converts the texture into a `PIL.Image`
@@ -226,7 +227,7 @@ for obj in env.objects:
226227
data.save()
227228
```
228229

229-
### [Sprite](UnityPy/classes/Sprite.py)
230+
### Sprite
230231

231232
Sprites are part of a texture and can have a separate alpha-image as well.
232233
Unlike most other extractors (including AssetStudio), UnityPy merges those two images by itself.
@@ -246,7 +247,7 @@ for obj in env.objects:
246247
data.image.save(path)
247248
```
248249

249-
### [TextAsset](UnityPy/classes/TextAsset.py)
250+
### TextAsset
250251

251252
TextAssets are usually normal text files.
252253

@@ -272,7 +273,7 @@ for obj in env.objects:
272273
data.save()
273274
```
274275

275-
### [MonoBehaviour](UnityPy/classes/MonoBehaviour.py)
276+
### MonoBehaviour
276277

277278
MonoBehaviour assets are usually used to save the class instances with their values.
278279
The structure/typetree for these classes might not be contained in the asset files.
@@ -312,7 +313,7 @@ for obj in env.objects:
312313
UnityPy can generate the typetrees of MonoBehaviours from the game assemblies using an optional package, ``TypeTreeGeneratorAPI``, which has to be installed via pip.
313314
UnityPy will automatically try to generate the typetree of MonoBehaviours if the typetree is missing in the assets and ``env.typetree_generator`` is set.
314315

315-
```py
316+
```python
316317
import UnityPy
317318
from UnityPy.helpers.TypeTreeGenerator import TypeTreeGenerator
318319

@@ -340,7 +341,7 @@ for obj in objects:
340341
```
341342

342343

343-
### [AudioClip](UnityPy/classes/AudioClip.py)
344+
### AudioClip
344345

345346
- `.samples` - `{sample-name : sample-data}`
346347

@@ -354,7 +355,9 @@ for name, data in clip.samples.items():
354355
f.write(data)
355356
```
356357

357-
### [Font](UnityPy/classes/Font.py)
358+
### Font
359+
360+
**Export**
358361

359362
```python
360363
if obj.type.name == "Font":
@@ -368,14 +371,14 @@ if obj.type.name == "Font":
368371
f.write(font.m_FontData)
369372
```
370373

371-
### [Mesh](UnityPy/classes/Mesh.py)
374+
### Mesh
372375

373376
- `.export()` - mesh exported as .obj (str)
374377

375378
The mesh will be converted to the Wavefront .obj file format.
376379

377380
```python
378-
mesh : Mesh
381+
mesh: Mesh
379382
with open(f"{mesh.m_Name}.obj", "wt", newline = "") as f:
380383
# newline = "" is important
381384
f.write(mesh.export())
@@ -390,7 +393,7 @@ ALPHA-VERSION
390393
The mesh and materials will be in the Wavefront formats.
391394

392395
```python
393-
mesh_renderer : Renderer
396+
mesh_renderer: Renderer
394397
export_dir: str
395398

396399
if mesh_renderer.m_GameObject:
@@ -400,7 +403,7 @@ if mesh_renderer.m_GameObject:
400403
mesh_renderer.export(export_dir)
401404
```
402405

403-
### [Texture2DArray](UnityPy/classes/Texture2DArray.py)
406+
### Texture2DArray
404407

405408
WARNING - not well tested
406409

@@ -423,15 +426,15 @@ for obj in env.objects:
423426
# editing isn't supported yet!
424427
```
425428

426-
## Custom-Filesystem
429+
## Custom Filesystem
427430

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

432435
Following methods of the filesystem have to be implemented for using it in UnityPy.
433436

434-
- sep (not a function, just the seperator as character)
437+
- sep (not a function, just the separator as character)
435438
- isfile(self, path: str) -> bool
436439
- isdir(self, path: str) -> bool
437440
- exists(self, path: str, \*\*kwargs) -> bool
@@ -444,11 +447,10 @@ Following methods of the filesystem have to be implemented for using it in Unity
444447
First of all,
445448
thanks a lot to all contributors of UnityPy and all of its users.
446449

447-
Also,
448-
many thanks to:
450+
Also, many thanks to:
449451

450452
- [Perfare](https://github.com/Perfare) for creating and maintaining and every contributor of [AssetStudio](https://github.com/Perfare/AssetStudio)
451453
- [ds5678](https://github.com/ds5678) for the [TypeTreeDumps](https://github.com/AssetRipper/TypeTreeDumps) and the [custom minimal Tpk format](https://github.com/AssetRipper/Tpk)
452454
- [Razmoth](https://github.com/Razmoth) for figuring out and sharing Unity CN's AssetBundle decryption ([src](https://github.com/Razmoth/PGRStudio)).
453455
- [nesrak1](https://github.com/nesrak1) for figuring out the [Switch texture swizzling](https://github.com/nesrak1/UABEA/blob/master/TexturePlugin/Texture2DSwitchDeswizzler.cs)
454-
- xiop_13690 (discord) for figuring out unsolved issues of the ManagedReferencesRegistry
456+
- xiop_13690 (discord) for figuring out unsolved issues of the ManagedReferencesRegistry

0 commit comments

Comments
 (0)