0
# UnityPy
1

2
A comprehensive Python library for extracting, editing, and manipulating Unity game assets. Built on AssetStudio, UnityPy provides programmatic access to Unity asset files, enabling developers to extract textures, sprites, audio clips, meshes, and other game resources. The library supports both extraction and modification of Unity assets through their native typetree structures.
3

4
## Package Information
5

6
- **Package Name**: UnityPy
7
- **Language**: Python  
8
- **Installation**: `pip install UnityPy`
9
- **Python Version**: >= 3.8
10
- **License**: MIT
11

12
## Core Imports
13

14
```python
15
import UnityPy
16
```
17

18
Common aliases:
19
```python
20
# Main Environment class for loading assets
21
from UnityPy import Environment
22
# Alternative load function (same as Environment)
23
env = UnityPy.load("path/to/assets")
24
```
25

26
For asset decryption:
27
```python
28
from UnityPy import set_assetbundle_decrypt_key
29
```
30

31
For configuration:
32
```python
33
import UnityPy.config
34
```
35

36
## Basic Usage
37

38
```python
39
import UnityPy
40

41
# Load Unity asset files or directories
42
env = UnityPy.load("path/to/unity/assets")
43

44
# Alternative methods
45
env = UnityPy.Environment("path/to/asset.bundle")
46
env = UnityPy.load("path/to/folder/", "specific_file.assets")
47

48
# Iterate through all objects in loaded files
49
for obj in env.objects:
50
    # Check object type
51
    if obj.type.name == "Texture2D":
52
        # Read the object as a Texture2D
53
        texture = obj.read()
54
        
55
        # Access properties
56
        print(f"Texture: {texture.m_Name}")
57
        print(f"Format: {texture.m_TextureFormat}")
58
        print(f"Size: {texture.m_Width}x{texture.m_Height}")
59
        
60
        # Export to standard format
61
        texture.image.save("exported_texture.png")
62
        
63
    elif obj.type.name == "AudioClip":
64
        # Read and export audio
65
        audio = obj.read()
66
        for name, data in audio.samples.items():
67
            with open(f"exported_{name}.wav", "wb") as f:
68
                f.write(data)
69

70
# Save modified assets
71
env.save()
72
```
73

74
Asset modification example:
75
```python
76
import UnityPy
77

78
env = UnityPy.load("path/to/assets")
79

80
for obj in env.objects:
81
    if obj.type.name == "Texture2D":
82
        texture = obj.read()
83
        
84
        # Method 1: Modify via parsed class
85
        texture.m_Name = "modified_texture"
86
        texture.save()  # Save changes to object
87
        
88
        # Method 2: Modify via raw dictionary
89
        raw_data = obj.read_typetree()
90
        raw_data["m_Name"] = "modified_via_dict"
91
        obj.save_typetree(raw_data)
92

93
# Save changes
94
env.save(pack="lz4", out_path="modified_assets/")
95
```
96

97
## Architecture
98

99
UnityPy follows Unity's internal asset structure and provides multiple layers of abstraction:
100

101
- **Environment**: Top-level container that manages multiple asset files and provides unified access to objects
102
- **Files**: Represent different Unity file formats (SerializedFile, BundleFile, WebFile) with their specific loading and compression handling
103
- **Objects**: Individual Unity assets (Texture2D, AudioClip, Mesh, etc.) that can be read, modified, and saved
104
- **TypeTree System**: Unity's reflection system that enables reading/writing any Unity object type, even unknown ones
105

106
The library supports both high-level parsed object access and low-level typetree manipulation, providing flexibility for different use cases from simple asset extraction to complex asset modification workflows.
107

108
## Capabilities
109

110
### Asset Loading and Environment Management
111

112
Core functionality for loading Unity asset files, directories, and compressed bundles. The Environment class serves as the primary interface for managing multiple asset files and provides unified access to all contained objects.
113

114
```python { .api }
115
class Environment:
116
    def __init__(self, *args, fs=None, path=None): ...
117
    def load_file(self, file, parent=None, name=None, is_dependency=False): ...
118
    def load_folder(self, path: str): ...
119
    def load_files(self, files: List[str]): ...
120
    def save(self, pack="none", out_path="output"): ...
121
    @property
122
    def objects(self) -> List[ObjectReader]: ...
123
    @property
124
    def container(self): ...
125

126
def load(*args, **kwargs) -> Environment: ...
127
def set_assetbundle_decrypt_key(key): ...
128
```
129

130
[Asset Loading](./asset-loading.md)
131

132
### Unity Asset Classes and Objects
133

134
Complete collection of Unity asset types including textures, audio, meshes, shaders, and game objects. Each class provides typed access to Unity's native data structures with methods for reading, modifying, and exporting assets.
135

136
```python { .api }
137
class ObjectReader:
138
    @property
139
    def type(self) -> ClassIDType: ...
140
    @property
141
    def path_id(self) -> int: ...
142
    @property
143
    def class_id(self) -> int: ...
144
    def read(self, check_read: bool = True) -> T: ...
145
    def read_typetree(self, nodes: Optional[NodeInput] = None, wrap: bool = False, check_read: bool = True) -> Union[dict, T]: ...
146
    def save_typetree(self, tree: Union[dict, T], nodes: Optional[NodeInput] = None, writer: Optional[EndianBinaryWriter] = None): ...
147
    def get_raw_data(self) -> bytes: ...
148
    def set_raw_data(self, data: bytes): ...
149

150
class Texture2D(Object):
151
    m_Name: str
152
    m_Width: int
153
    m_Height: int
154
    m_TextureFormat: int
155
    image_data: bytes
156
    @property
157
    def image(self) -> Image.Image: ...
158
    @image.setter
159
    def image(self, img: Union[Image.Image, str, BinaryIO]): ...
160
    
161
class AudioClip(Object):
162
    m_Name: str
163
    m_CompressionFormat: int
164
    @property
165
    def samples(self) -> Dict[str, bytes]: ...
166
    @property
167
    def extension(self) -> str: ...
168

169
class Mesh(Object):
170
    m_Name: str
171
    @property
172
    def vertices(self) -> List[Vector3f]: ...
173
    @property
174
    def triangles(self) -> List[int]: ...
175
    def export(self) -> str: ...
176
    
177
class Sprite(Object):
178
    m_Name: str
179
    @property
180
    def image(self) -> Image.Image: ...
181
    @property
182
    def texture(self) -> PPtr[Texture2D]: ...
183
```
184

185
[Unity Asset Classes](./asset-classes.md)
186

187
### File Format Handling
188

189
Support for Unity's various file formats including serialized assets, compressed bundles, and web-optimized files. Each file type provides specialized loading, parsing, and compression handling.
190

191
```python { .api }
192
class SerializedFile:
193
    @property
194
    def objects(self): ...
195
    def save(self, packer="none"): ...
196

197
class BundleFile:
198
    @property
199
    def files(self): ...
200
    def save(self): ...
201

202
class WebFile:
203
    @property
204
    def files(self): ...
205
    def save(self): ...
206
```
207

208
[File Formats](./file-formats.md)
209

210
### Asset Export and Conversion
211

212
Comprehensive export capabilities for converting Unity assets to standard formats. Includes format conversion, compression options, and platform-specific optimizations for textures, audio, meshes, and other asset types.
213

214
```python { .api }
215
class Texture2DConverter:
216
    def export_PIL(texture): ...
217
    def export_bytes(texture, format): ...
218

219
class AudioClipConverter:
220
    def export_wav(audio_clip): ...
221
    def export_ogg(audio_clip): ...
222

223
class MeshExporter:
224
    def export_obj(mesh): ...
225
    def export_ply(mesh): ...
226

227
class SpriteHelper:
228
    def export_sprite(sprite): ...
229
```
230

231
[Asset Export](./asset-export.md)
232

233
### Enumerations and Constants
234

235
Complete set of Unity enumerations and constants including texture formats, audio types, build targets, and other Unity-specific identifiers used throughout the asset system.
236

237
```python { .api }
238
class TextureFormat(Enum): ...
239
class AudioType(Enum): ...
240
class ClassIDType(Enum): ...
241
class BuildTarget(Enum): ...
242
class GraphicsFormat(Enum): ...
243
```
244

245
[Enumerations](./enumerations.md)
246

247
### Binary Data Handling
248

249
Low-level binary data reading and writing with endianness support, enabling direct manipulation of Unity's binary asset formats and custom data structures.
250

251
```python { .api }
252
class EndianBinaryReader:
253
    def read_int(self): ...
254
    def read_string(self): ...
255
    def read_bytes(self, count): ...
256

257
class EndianBinaryWriter:
258
    def write_int(self, value): ...
259
    def write_string(self, value): ...
260
    def write_bytes(self, data): ...
261
```
262

263
[Binary Data](./binary-data.md)
264

265
### Configuration and Global Settings
266

267
Global configuration options for controlling UnityPy behavior including Unity version fallbacks and performance optimizations.
268

269
```python { .api }
270
# Configuration variables
271
FALLBACK_UNITY_VERSION: Optional[str]  # Default Unity version when not specified
272
SERIALIZED_FILE_PARSE_TYPETREE: bool   # Control typetree parsing for performance
273

274
def get_fallback_version() -> str: ...  # Get configured fallback version with validation
275
```
276

277
Access via `UnityPy.config` module for advanced performance tuning and Unity version handling.