Skip to content

Commit 3cd0160

Browse files
committed
docs: README - improve environment section, add tips for properly closing files
1 parent 2c11561 commit 3cd0160

1 file changed

Lines changed: 38 additions & 19 deletions

File tree

README.md

Lines changed: 38 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -138,39 +138,58 @@ It can also be used as a general template or as an importable tool.
138138
### Environment
139139

140140
[Environment](UnityPy/environment.py) loads and parses the given files.
141-
It can be initialized via:
142141

143-
- a file path - apk files can be loaded as well
144-
- a folder path - loads all files in that folder (bad idea for folders with a lot of files)
145-
- a stream - e.g., `io.BytesIO`, file stream,...
146-
- a bytes object - will be loaded into a stream
142+
#### Initialization
147143

148-
UnityPy can detect if the file is a WebFile, BundleFile, Asset, or APK.
144+
An Environment object can be created by providing:
149145

150-
The unpacked assets will be loaded into `.files`, a dict consisting of `asset-name : asset`.
146+
- a file path - loads a single file (typically an asset bundle file, apk file or zip file).
147+
- a folder path - loads all files in the given folder (bad idea for large folders).
148+
- a streamable object - loads the data from the given stream (it can be `io.BytesIO`, file stream returned by `open()` and any other object that extends `io.IOBase`).
149+
- a bytes object - loads the data from memory.
150+
151+
UnityPy can detect if the file is a WebFile, BundleFile, Asset, or APK.
151152

152-
All objects of the loaded assets can be easily accessed via `.objects`,
153-
which itself is a simple recursive iterator.
153+
The following code shows the different ways to create an Environment object.
154154

155155
```python
156156
import io
157157
import UnityPy
158158

159-
# all of the following would work
160-
src = "file_path"
161-
src = b"bytes"
162-
src = io.BytesIO(b"Streamable")
159+
# load from file path or folder path
160+
env = UnityPy.load("path/to/your/file")
161+
162+
# note that the best way to pass a file to UnityPy is
163+
# using with-statement to ensure the file can be properly closed
164+
with open("path/to/your/file", "rb") as f:
165+
env = UnityPy.load(f)
166+
167+
# load from bytes io stream
168+
data = io.BytesIO(b"streamable-data")
169+
env = UnityPy.load(data)
170+
171+
# load from bytes object
172+
data = b"some-bytes-data"
173+
env = UnityPy.load(data)
174+
```
175+
176+
#### Attributes
177+
178+
The unpacked assets will be loaded into `.files`, a dict consisting of `asset-name : asset`.
163179

164-
env = UnityPy.load(src)
180+
All objects of the loaded assets can be easily accessed via `.objects`, which itself is a simple recursive iterator.
181+
If you want, you can modify the objects and save the edited file later.
182+
See [Object](#object) section to learn how to apply modifications to the objects.
183+
184+
```python
185+
# assumes that you have already created an `env`
165186

166187
for obj in env.objects:
188+
# your code for processing each object
167189
...
168190

169-
# saving an edited file
170-
# apply modifications to the objects
171-
# don't forget to use data.save()
172-
...
173-
with open(dst, "wb") as f:
191+
# don't forget to save an edited file
192+
with open("path/to/save", "wb") as f:
174193
f.write(env.file.save())
175194
```
176195

0 commit comments

Comments
 (0)