or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

asset-classes.md asset-export.md asset-loading.md binary-data.md enumerations.md file-formats.md index.md

tile.json

tessl/pypi-unitypy

A Unity asset extractor for Python based on AssetStudio that supports extraction, editing, and manipulation of Unity game assets.

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:pypi/unitypy@1.23.x

To install, run

npx @tessl/cli install tessl/pypi-unitypy@1.23.0

UnityPy

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.

Package Information

Package Name: UnityPy
Language: Python
Installation: pip install UnityPy
Python Version: >= 3.8
License: MIT

Core Imports

import UnityPy

Common aliases:

# Main Environment class for loading assets
from UnityPy import Environment
# Alternative load function (same as Environment)
env = UnityPy.load("path/to/assets")

For asset decryption:

from UnityPy import set_assetbundle_decrypt_key

For configuration:

import UnityPy.config

Basic Usage

import UnityPy

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

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

# Iterate through all objects in loaded files
for obj in env.objects:
    # Check object type
    if obj.type.name == "Texture2D":
        # Read the object as a Texture2D
        texture = obj.read()
        
        # Access properties
        print(f"Texture: {texture.m_Name}")
        print(f"Format: {texture.m_TextureFormat}")
        print(f"Size: {texture.m_Width}x{texture.m_Height}")
        
        # Export to standard format
        texture.image.save("exported_texture.png")
        
    elif obj.type.name == "AudioClip":
        # Read and export audio
        audio = obj.read()
        for name, data in audio.samples.items():
            with open(f"exported_{name}.wav", "wb") as f:
                f.write(data)

# Save modified assets
env.save()

Asset modification example:

import UnityPy

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

for obj in env.objects:
    if obj.type.name == "Texture2D":
        texture = obj.read()
        
        # Method 1: Modify via parsed class
        texture.m_Name = "modified_texture"
        texture.save()  # Save changes to object
        
        # Method 2: Modify via raw dictionary
        raw_data = obj.read_typetree()
        raw_data["m_Name"] = "modified_via_dict"
        obj.save_typetree(raw_data)

# Save changes
env.save(pack="lz4", out_path="modified_assets/")

Architecture

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

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

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.

Capabilities

Asset Loading and Environment Management

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.

class Environment:
    def __init__(self, *args, fs=None, path=None): ...
    def load_file(self, file, parent=None, name=None, is_dependency=False): ...
    def load_folder(self, path: str): ...
    def load_files(self, files: List[str]): ...
    def save(self, pack="none", out_path="output"): ...
    @property
    def objects(self) -> List[ObjectReader]: ...
    @property
    def container(self): ...

def load(*args, **kwargs) -> Environment: ...
def set_assetbundle_decrypt_key(key): ...

Asset Loading

Unity Asset Classes and Objects

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.

class ObjectReader:
    @property
    def type(self) -> ClassIDType: ...
    @property
    def path_id(self) -> int: ...
    @property
    def class_id(self) -> int: ...
    def read(self, check_read: bool = True) -> T: ...
    def read_typetree(self, nodes: Optional[NodeInput] = None, wrap: bool = False, check_read: bool = True) -> Union[dict, T]: ...
    def save_typetree(self, tree: Union[dict, T], nodes: Optional[NodeInput] = None, writer: Optional[EndianBinaryWriter] = None): ...
    def get_raw_data(self) -> bytes: ...
    def set_raw_data(self, data: bytes): ...

class Texture2D(Object):
    m_Name: str
    m_Width: int
    m_Height: int
    m_TextureFormat: int
    image_data: bytes
    @property
    def image(self) -> Image.Image: ...
    @image.setter
    def image(self, img: Union[Image.Image, str, BinaryIO]): ...
    
class AudioClip(Object):
    m_Name: str
    m_CompressionFormat: int
    @property
    def samples(self) -> Dict[str, bytes]: ...
    @property
    def extension(self) -> str: ...

class Mesh(Object):
    m_Name: str
    @property
    def vertices(self) -> List[Vector3f]: ...
    @property
    def triangles(self) -> List[int]: ...
    def export(self) -> str: ...
    
class Sprite(Object):
    m_Name: str
    @property
    def image(self) -> Image.Image: ...
    @property
    def texture(self) -> PPtr[Texture2D]: ...

Unity Asset Classes

File Format Handling

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.

class SerializedFile:
    @property
    def objects(self): ...
    def save(self, packer="none"): ...

class BundleFile:
    @property
    def files(self): ...
    def save(self): ...

class WebFile:
    @property
    def files(self): ...
    def save(self): ...

File Formats

Asset Export and Conversion

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.

class Texture2DConverter:
    def export_PIL(texture): ...
    def export_bytes(texture, format): ...

class AudioClipConverter:
    def export_wav(audio_clip): ...
    def export_ogg(audio_clip): ...

class MeshExporter:
    def export_obj(mesh): ...
    def export_ply(mesh): ...

class SpriteHelper:
    def export_sprite(sprite): ...

Asset Export

Enumerations and Constants

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

class TextureFormat(Enum): ...
class AudioType(Enum): ...
class ClassIDType(Enum): ...
class BuildTarget(Enum): ...
class GraphicsFormat(Enum): ...

Enumerations

Binary Data Handling

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

class EndianBinaryReader:
    def read_int(self): ...
    def read_string(self): ...
    def read_bytes(self, count): ...

class EndianBinaryWriter:
    def write_int(self, value): ...
    def write_string(self, value): ...
    def write_bytes(self, data): ...

Binary Data

Configuration and Global Settings

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

# Configuration variables
FALLBACK_UNITY_VERSION: Optional[str]  # Default Unity version when not specified
SERIALIZED_FILE_PARSE_TYPETREE: bool   # Control typetree parsing for performance

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

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