0
# File Format Handling
1
2
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.
3
4
## Capabilities
5
6
### Serialized Asset Files
7
8
Unity's primary asset storage format containing serialized object data with metadata and type information.
9
10
```python { .api }
11
class SerializedFile:
12
"""
13
Unity serialized asset file (.assets) containing object data.
14
"""
15
16
@property
17
def unity_version(self):
18
"""
19
Unity version that created this file.
20
21
Returns:
22
str: Unity version string (e.g., "2020.3.1f1")
23
"""
24
25
@property
26
def version(self):
27
"""
28
Serialized file format version.
29
30
Returns:
31
int: Format version number
32
"""
33
34
@property
35
def target_platform(self):
36
"""
37
Target build platform.
38
39
Returns:
40
BuildTarget: Platform enumeration
41
"""
42
43
@property
44
def objects(self):
45
"""
46
Dictionary of all objects in this file.
47
48
Returns:
49
Dict[int, ObjectReader]: Mapping of path_id to objects
50
"""
51
52
@property
53
def container(self):
54
"""
55
Container path mapping for assets.
56
57
Returns:
58
Dict[str, ObjectReader]: Asset path to object mapping
59
"""
60
61
def save(self, packer="none"):
62
"""
63
Serialize file data back to bytes.
64
65
Parameters:
66
- packer: Compression method ("none", "lz4")
67
68
Returns:
69
bytes: Serialized file data
70
"""
71
```
72
73
### Asset Bundle Files
74
75
Unity's bundle format for packaging multiple asset files with compression and dependency management.
76
77
```python { .api }
78
class BundleFile:
79
"""
80
Unity asset bundle file (.bundle, .unity3d) containing multiple assets.
81
"""
82
83
@property
84
def signature(self):
85
"""
86
Bundle signature string.
87
88
Returns:
89
str: Bundle format identifier
90
"""
91
92
@property
93
def version(self):
94
"""
95
Bundle format version.
96
97
Returns:
98
int: Format version number
99
"""
100
101
@property
102
def unity_version(self):
103
"""
104
Unity version that created this bundle.
105
106
Returns:
107
str: Unity version string
108
"""
109
110
@property
111
def files(self):
112
"""
113
Dictionary of files contained in this bundle.
114
115
Returns:
116
Dict[str, Union[SerializedFile, File]]: File name to file object mapping
117
"""
118
119
def save(self):
120
"""
121
Serialize bundle data back to bytes.
122
123
Returns:
124
bytes: Bundle file data
125
"""
126
```
127
128
### Web Streaming Files
129
130
Unity's web-optimized format for streaming assets with compression.
131
132
```python { .api }
133
class WebFile:
134
"""
135
Unity web file (.unityweb) for streaming deployment.
136
"""
137
138
@property
139
def files(self):
140
"""
141
Dictionary of files contained in this web archive.
142
143
Returns:
144
Dict[str, File]: File name to file object mapping
145
"""
146
147
def save(self):
148
"""
149
Serialize web file data back to bytes.
150
151
Returns:
152
bytes: Web file data
153
"""
154
```
155
156
### Object Readers
157
158
Interface for reading individual Unity objects within files.
159
160
```python { .api }
161
class ObjectReader:
162
"""
163
Reader for individual Unity objects within asset files.
164
"""
165
166
@property
167
def assets_file(self):
168
"""
169
Parent asset file containing this object.
170
171
Returns:
172
SerializedFile: Parent serialized file
173
"""
174
175
@property
176
def path_id(self):
177
"""
178
Unique identifier for this object within its file.
179
180
Returns:
181
int: Object path ID
182
"""
183
184
@property
185
def type(self):
186
"""
187
Unity class type of this object.
188
189
Returns:
190
ClassIDType: Object type enumeration
191
"""
192
193
@property
194
def type_id(self):
195
"""
196
Numeric type identifier.
197
198
Returns:
199
int: Unity class ID number
200
"""
201
202
@property
203
def serialized_type(self):
204
"""
205
Serialization type information.
206
207
Returns:
208
SerializedType: Type metadata for serialization
209
"""
210
211
def read(self):
212
"""
213
Read object as parsed Unity class instance.
214
215
Returns:
216
Object: Parsed object with typed properties
217
"""
218
219
def read_typetree(self):
220
"""
221
Read object as raw dictionary using typetree.
222
223
Returns:
224
dict: Raw object data
225
"""
226
227
def save(self, obj):
228
"""
229
Save modified parsed object.
230
231
Parameters:
232
- obj: Modified object instance
233
"""
234
235
def save_typetree(self, obj):
236
"""
237
Save modified raw object data.
238
239
Parameters:
240
- obj: Modified object dictionary
241
"""
242
```
243
244
### File Base Classes
245
246
Base classes and utilities for file handling.
247
248
```python { .api }
249
class File:
250
"""
251
Base class for Unity file objects.
252
"""
253
254
@property
255
def name(self):
256
"""
257
File name.
258
259
Returns:
260
str: File name or path
261
"""
262
263
@property
264
def parent(self):
265
"""
266
Parent container file.
267
268
Returns:
269
File: Parent file object
270
"""
271
272
class DirectoryInfo:
273
"""
274
Directory information structure for file metadata.
275
"""
276
277
@property
278
def path(self):
279
"""
280
Directory path.
281
282
Returns:
283
str: Directory path string
284
"""
285
286
@property
287
def name(self):
288
"""
289
Directory name.
290
291
Returns:
292
str: Directory name
293
"""
294
```
295
296
## Usage Examples
297
298
### Working with Serialized Files
299
300
```python
301
import UnityPy
302
303
env = UnityPy.load("game_data.assets")
304
305
# Access the serialized file directly
306
serialized_file = list(env.files.values())[0]
307
308
print(f"Unity Version: {serialized_file.unity_version}")
309
print(f"Target Platform: {serialized_file.target_platform}")
310
print(f"Objects: {len(serialized_file.objects)}")
311
312
# Access objects in the file
313
for path_id, obj_reader in serialized_file.objects.items():
314
print(f"Object {path_id}: {obj_reader.type.name}")
315
316
# Use container mapping
317
container = serialized_file.container
318
for asset_path, obj_reader in container.items():
319
print(f"Asset: {asset_path} -> {obj_reader.type.name}")
320
```
321
322
### Processing Asset Bundles
323
324
```python
325
import UnityPy
326
327
env = UnityPy.load("level1.bundle")
328
329
# Access the bundle file
330
bundle_file = list(env.files.values())[0]
331
332
print(f"Bundle Signature: {bundle_file.signature}")
333
print(f"Bundle Version: {bundle_file.version}")
334
print(f"Unity Version: {bundle_file.unity_version}")
335
336
# List files in the bundle
337
print("Files in bundle:")
338
for filename, file_obj in bundle_file.files.items():
339
print(f" {filename}: {type(file_obj).__name__}")
340
341
# If it's a serialized file, show objects
342
if hasattr(file_obj, 'objects'):
343
print(f" Objects: {len(file_obj.objects)}")
344
```
345
346
### Handling Web Files
347
348
```python
349
import UnityPy
350
351
env = UnityPy.load("webplayer.unityweb")
352
353
# Access the web file
354
web_file = list(env.files.values())[0]
355
356
print("Files in web archive:")
357
for filename, file_obj in web_file.files.items():
358
print(f" {filename}: {type(file_obj).__name__}")
359
```
360
361
### Object Reader Operations
362
363
```python
364
import UnityPy
365
366
env = UnityPy.load("assets/")
367
368
for obj_reader in env.objects:
369
print(f"Object ID: {obj_reader.path_id}")
370
print(f"Type: {obj_reader.type.name} (ID: {obj_reader.type_id})")
371
print(f"File: {obj_reader.assets_file.name}")
372
373
# Read as parsed object
374
if obj_reader.type.name == "Texture2D":
375
texture = obj_reader.read()
376
print(f"Texture Name: {texture.name}")
377
print(f"Size: {texture.m_Width}x{texture.m_Height}")
378
379
# Read as raw data
380
raw_data = obj_reader.read_typetree()
381
if "m_Name" in raw_data:
382
print(f"Raw Name: {raw_data['m_Name']}")
383
```
384
385
### Saving Modified Files
386
387
```python
388
import UnityPy
389
390
env = UnityPy.load("original.assets")
391
392
# Modify objects
393
for obj in env.objects:
394
if obj.type.name == "Texture2D":
395
texture = obj.read()
396
texture.name = f"Modified_{texture.name}"
397
obj.save(texture)
398
399
# Save individual files with compression
400
for filename, file_obj in env.files.items():
401
if hasattr(file_obj, 'save') and getattr(file_obj, 'is_changed', False):
402
# Save with LZ4 compression
403
data = file_obj.save(packer="lz4")
404
with open(f"modified_{filename}", "wb") as f:
405
f.write(data)
406
407
# Or save entire environment
408
env.save(pack="lz4", out_path="modified_assets/")
409
```
410
411
### Format Detection and Conversion
412
413
```python
414
import UnityPy
415
from UnityPy.helpers.ImportHelper import check_file_type
416
from UnityPy.enums.FileType import FileType
417
418
# Check file type before loading
419
with open("unknown_file.dat", "rb") as f:
420
file_type, reader = check_file_type(f)
421
422
if file_type == FileType.BundleFile:
423
print("This is an asset bundle")
424
elif file_type == FileType.AssetsFile:
425
print("This is a serialized assets file")
426
elif file_type == FileType.WebFile:
427
print("This is a web file")
428
429
# Load based on detected type
430
env = UnityPy.load(f)
431
```
432
433
### Working with Split Files
434
435
```python
436
import UnityPy
437
438
# UnityPy automatically handles split files
439
# If you have: large_asset.split0, large_asset.split1, large_asset.split2
440
# Just load the first one:
441
env = UnityPy.load("large_asset.split0")
442
443
# Or let UnityPy find and merge them:
444
env = UnityPy.load("directory_with_splits/")
445
446
print("Split files merged automatically")
447
for obj in env.objects:
448
print(f"Object: {obj.type.name}")
449
```