API Reference

Modules

• 🛠️ Core
  • BaseFile
  • Content
  • Decoder
  • Encoder
  • Options
  • StructIO
• 🔄 Convert
  • Detect
  • Formats
  • Convert
  • Factory
• 🧩 Formats
  • Modules
• 🗃️ Structures
  • 🧊 Models
  • 🧱 Textures
  • 🗺 Regions
• 🧰 Utils
  • Files
  • Updates
  • Versions

Constants

SUPPORTED_FORMATS: set[FileFormat] = {FileFormat.EFKMODEL, FileFormat.MCSA, FileFormat.MCSB, FileFormat.MCVD, FileFormat.MDAT, FileFormat.MIC, FileFormat.NBT, FileFormat.OL, FileFormat.TEXARR}

Formats available for conversion.

SUPPORTED_SUFFIXES: set[str] = {'.efkmodel', '.mcsa', '.mcsb', '.mcvd', '.mdat', '.mic', '.nbt', '.ol', '.texarr'}

Formats suffixes available for conversion.

SUPPORTED_NBT: set[str] = {'common', 'itemnames.dat', 'prefs', 'sd0', 'sd1', 'sd2', 'sd3', 'sd4'}

NBT filenames available for conversion.

ALLOWED_SUFFIXES: set[str] = {'.efkmodel', '.mcsa', '.mcsb', '.mcvd', '.mdat', '.mic', '.nbt', '.ol', '.texarr', 'common', 'itemnames.dat', 'prefs', 'sd0', 'sd1', 'sd2', 'sd3', 'sd4'}

All path suffixes available for conversion.

class FileSignature

Format magic bytes.

MCSA = b'MCSA'

MCAL = b'MCAL'

MIC = b'\x89MIC'

OL = b'\n\x95#\xfd'

DDS = b'DDS '

PNG = b'\x89PNG'

GLTF = b'glTF'

MS3D = b'MS3D000000'

class CLI

Command line interface constants.

NON_SKELETAL_FORMATS: Sequence[FileFormat] = (FileFormat.OBJ, FileFormat.FBX)

NON_ANIMATION_FORMATS: Sequence[FileFormat] = (FileFormat.OBJ, FileFormat.FBX, FileFormat.DAE, FileFormat.MS3D)

class OutputFormats

Supported output formats for file data types.

MODELS: Sequence[FileFormat] = (FileFormat.OBJ, FileFormat.GLB, FileFormat.FBX, FileFormat.DAE, FileFormat.MS3D)

TEXTURES: Sequence[FileFormat] = (FileFormat.DDS,)

IMAGES: Sequence[FileFormat] = (FileFormat.PNG,)

REGIONS: Sequence[FileFormat] = (FileFormat.MCA,)

TEXARR: Sequence[FileFormat] = (FileFormat.ZIP,)

NBT: Sequence[FileFormat] = (FileFormat.JSON,)

class DefaultModelFormats

Default model formats for unset options.

STANDARD: Sequence[FileFormat] = (FileFormat.OBJ,)

ON_SKELETON: Sequence[FileFormat] = (FileFormat.GLB,)

class Factor

Integer range limits.

I8 = 127

U8 = 255

I16 = 32767

U16 = 65535

I32 = 2147483647

U32 = 4294967295

class CubemapFaces

DDS cubemap faces.

FACES = {'+x', '+y', '+z', '-x', '-y', '-z'}

COUNT = 6

class ModelDefaults

Model default constants.

DECIMALS = 6

ROOT_BONE_ID = -1

GEOMETRY_LIMIT = 1000000

Safety limit to prevent memory overflow on corrupted files.

class Text

Shared text constants.

FORMATS = "Supported Formats: ['.efkmodel', '.mcsa', '.mcsb', '.mcvd', '.mdat', '.mic', '.nbt', '.ol', '.texarr']"

NBT = "Supported NBTs: ['common', 'itemnames.dat', 'prefs', 'sd0', 'sd1', 'sd2', 'sd3', 'sd4']"

EXCEPTION = '[b yellow]Input file appears to be corrupted or invalid.[/]'

Enums

class FileFormat(value)

Bases: StrEnum

File extension without dot.

NONE = ''

DAE = 'dae'

DDS = 'dds'

EFKMODEL = 'efkmodel'

FBX = 'fbx'

GLB = 'glb'

JSON = 'json'

MCA = 'mca'

MCAL = 'mcal'

MCSA = 'mcsa'

MCSB = 'mcsb'

MCVD = 'mcvd'

MDAT = 'mdat'

MIC = 'mic'

MS3D = 'ms3d'

NBT = 'nbt'

OBJ = 'obj'

OL = 'ol'

PNG = 'png'

TEXARR = 'texarr'

ZIP = 'zip'

property suffix

class FileType(value)

Bases: StrEnum

File content kind.

NONE = 'none'

MODEL = 'model'

TEXTURE = 'texture'

IMAGE = 'image'

TEXARR = 'texarr'

NBT = 'nbt'

REGION = 'region'

class ByteOrder(value)

Bases: StrEnum

File data byte order.

NATIVE = '@'

STANDARD = '='

LITTLE = '<'

BIG = '>'

NETWORK = '!'

class UnicodeErrors(value)

Bases: StrEnum

Unicode error handling policy.

STRICT = 'strict'

Raise UnicodeDecodeError on invalid bytes

IGNORE = 'ignore'

Skip invalid bytes silently

REPLACE = 'replace'

Replace invalid bytes with a replacement marker (�)

BACKSLASH = 'backslashreplace'

BACKSLASHREPLACE = 'backslashreplace'

Replace with backslash-escaped sequences (xHH)

NAME = 'namereplace'

NAMEREPLACE = 'namereplace'

Replace with N{…} escape sequences

XML = 'xmlcharrefreplace'

XMLCHARREFREPLACE = 'xmlcharrefreplace'

Replace with XML/HTML numeric entities (&#…;)

SURROGATE = 'surrogateescape'

SURROGATEESCAPE = 'surrogateescape'

Preserve invalid bytes as surrogate codes

class StructFormat(value)

Bases: StrEnum

C-type struct format codes.

BOOL = '?'

BOOL 1 byte [False, True]

Type:

boolean

I8 = 'b'

BYTE 1 byte [-128, 127]

Type:

signed char

I16 = 'h'

WORD 2 bytes [-32768, 32767]

Type:

signed short

I32 = 'i'

DWORD 4 bytes [-2147483648, 2147483647]

Type:

signed int

I64 = 'q'

QWORD 8 bytes [-9223372036854775808, 9223372036854775807]

Type:

signed long long

U8 = 'B'

BYTE 1 byte [0, 255]

Type:

unsigned char

U16 = 'H'

WORD 2 bytes [0, 65535]

Type:

unsigned short

U32 = 'I'

DWORD 4 bytes [0, 4294967295]

Type:

unsigned int

U64 = 'Q'

QWORD 8 bytes [0, 18446744073709551615]

Type:

unsigned long long

F16 = 'e'

half-precision 2 bytes

Type:

float

F32 = 'f'

single-precision 4 bytes

Type:

double

F64 = 'd'

double-precision 8 bytes

Type:

double

F

StructFormat Alias.

class ConsoleLabel(value)

Bases: StrEnum

Colored console output labels.

INFO = '[b blue]INFO:[/]'

HINT = '[b cyan]HINT:[/]'

DONE = '[b green]DONE:[/]'

WARN = '[b yellow]WARN:[/]'

ABORTED = '[b yellow]ABORTED:[/]'

ERROR = '[b red]ERROR:[/]'

INVALID = '[b red]INVALID INPUT:[/]'

EXCEPTION = '[b red]UNEXPECTED ERROR:[/]'

L

ConsoleLabel Alias.

class CliCommand(value)

Bases: StrEnum

CLI command names.

CONVERT = 'convert'

MAPCACHE = 'mapcache'

class UpdateStatus(value)

Bases: StrEnum

Update check result status.

ERROR = 'error'

UPTODATE = 'uptodate'

AVAILABLE = 'available'

Types

Formats

Sequence of file formats.

alias of Sequence[FileFormat]

PathLike: TypeAlias = str | pathlib.Path | os.PathLike[str]

Path represented as string, pathlib.Path, or OS path-like object.

Output

Optional output path.

alias of Path | None

OutputLike

Optional path-like output.

alias of str | Path | PathLike[str] | None

FilesWhitelist

Iterable of file suffixes for filtering.

alias of Iterable[str]

FilesPaths

Iterable of file paths.

alias of Iterable[Path]

FilesSources

Iterable of path-like sources.

alias of Iterable[str | Path | PathLike[str]]

class FileEntry(root: str, path: str, relpath: str)

Bases: NamedTuple

File entry from directory walk.

root: str

Alias for field number 0

path: str

Alias for field number 1

relpath: str

Alias for field number 2

FilesWalk

Iterator over file entries.

alias of Iterator[FileEntry]

Exceptions

exception ScFileException

Bases: Exception

Base exception for scfile library.

exception DecodingError

Bases: ScFileException

Base exception occurring while file decoding.

exception EncodingError

Bases: ScFileException

Base exception occurring while file encoding.

exception ParsingError

Bases: ScFileException

Base exception occurring due to unexpected file structure.

exception UnsupportedError

Bases: ScFileException

Base exception occurring intentionally for unsupported formats.

exception BaseIOError

Bases: ScFileException

Base exception occurring i/o operations.

prefix

exception FileError(location)

Bases: BaseIOError

Base exception occurring file i/o operations.

location: str

exception FileNotFound(location)

Bases: FileError

Raised when file doesn’t exist.

exception EmptyFileError(location)

Bases: FileError

Raised when file is empty.

exception UnsupportedFormatError(location, suffix)

Bases: FileError

Raised when file format (by suffix) is not supported.

suffix: str

exception InvalidSignatureError(location, actual, expected)

Bases: FileError

Raised when file signature doesn’t match expected.

actual: bytes

expected: bytes

exception InvalidStructureError(location, position=None)

Bases: FileError

Raised when file structure is invalid.

position: Optional[int] = None

exception RegionError

Bases: ScFileException

Base exception for region operations.

exception RegionFileError(path)

Bases: RegionError

Raised when a region file fails to decode.

path: str

exception MergeInterrupted

Bases: RegionError

Raised when region merge is interrupted by user.