Metadata-Version: 2.1
Name: sc-file
Version: 3.5.4
Summary: Utility & Library for decoding stalcraft assets
Home-page: https://github.com/onejeuu/sc-file
License: MIT
Author: onejeuu
Author-email: mail@66rk.ru
Requires-Python: >=3.11,<3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: click (>=8.1.7,<9.0.0)
Requires-Dist: lz4 (>=4.3.2,<5.0.0)
Requires-Dist: numpy (>=1.26.3,<2.0.0)
Requires-Dist: rich (>=13.0.0,<14.0.0)
Project-URL: Documentation, https://github.com/onejeuu/sc-file/?tab=readme-ov-file#usage-1
Project-URL: Repository, https://github.com/onejeuu/sc-file
Description-Content-Type: text/markdown

# SC FILE

Utility and Library for decoding and converting stalcraft assets files, such as models and textures into well-known formats.

Designed for artworks creation and the like.

> [!NOTE]
> There is not and will not be encoding back into game formats.

> [!WARNING]
> Do not use game assets directly. \
> Any changes in game client can be detected.

You can use executable program from [Releases](https://github.com/onejeuu/sc-file/releases) page.

# 📁 Formats

| Type    | Source        | Output                 |
| ------- | ------------- | ---------------------- |
| Model   | .mcsa / .mcvd | .dae, .obj, ms3d, .txt |
| Texture | .ol           | .dds                   |
| Image   | .mic          | .png                   |

### Models

- Versions supported: 7.0, 8.0, 10.0, 11.0
- Skeleton and Animations currently unsupported

### Textures

- Formats supported: DXT1, DXT3, DXT5, RGBA8, BGRA8, DXN_XY
- Formats unsupported: RGBA32F, Cubemaps

# 💻 CLI Utility

## Usage

From bash:

```bash
scfile [FILES]... [OPTIONS]
```

> [!TIP]
> You can just drag and drop one or multiple files onto `scfile.exe`.

## Arguments

- `FILES`: **List of file paths to be converted**. Multiple files should be separated by **spaces**. Accepts both full and relative paths. **Does not accept directory**.

## Options

- `-O`, `--output`: **One path to output directory**. If not specified, file will be saved in same directory with a new suffix.

## Examples

1. Convert a single file:

   ```bash
   scfile file.mcsa
   ```

   _Will be saved in same directory with a new suffix._

2. Convert multiple files to a specified directory:

   ```bash
   scfile file1.mcsa file2.mcsa --output path/to/dir
   ```

3. Convert all `.mcsa` files in current directory:

   ```bash
   scfile *.mcsa
   ```

   _Subdirectories are not included._

4. Convert all `.mcsa` files with subdirectories to a specified directory:

   ```bash
   scfile **/*.mcsa -O path/to/dir
   ```

   _With `--output` specified, directory structure is not duplicated._

# 📚 Library

## Install

### Pip

```bash
pip install sc-file -U
```

### Manual

```bash
git clone git@github.com:onejeuu/sc-file.git
```

```bash
cd sc-file
```

```bash
poetry install
```

## Usage

### Simple

```python
from scfile import convert

# Output path is optional.
# Defaults to source path with new suffix.
convert.mcsa_to_obj("path/to/model.mcsa", "path/to/model.obj")
convert.ol_to_dds("path/to/texture.ol", "path/to/texture.dds")
convert.mic_to_png("path/to/image.mic", "path/to/image.png")

# Skeleton support via MilkShape3D
convert.mcsa_to_ms3d("path/to/model.mcsa", "path/to/model.ms3d")
convert.mcsa_to_ms3d_ascii("path/to/model.mcsa", "path/to/model.txt")

# Or determinate it automatically
convert.auto("path/to/model.mcsa")
```

### Advanced

- Default

```python
from scfile.file.data import ModelData
from scfile.file import McsaDecoder, ObjEncoder

mcsa = McsaDecoder("model.mcsa")
data: ModelData = mcsa.decode()
mcsa.close() # ? Necessary to close

obj = ObjEncoder(data)
obj.encode().save("model.obj") # ? Encoder closes after saving
```

- Use encoded content bytes

```python
obj = ObjEncoder(data)
obj.encode()

with open("model.obj", "wb") as fp:
    fp.write(obj.content)

obj.close() # ? Necessary to close
```

- Use convert methods

```python
mcsa = McsaDecoder("model.mcsa")
mcsa.convert_to(ObjEncoder).save("model.obj")
mcsa.close() # ? Necessary to close
```

```python
mcsa = McsaDecoder("model.mcsa")
mcsa.to_obj().save("model.obj")
mcsa.close() # ? Necessary to close
```

- Use context manager

```python
with McsaDecoder("model.mcsa") as mcsa:
    data: ModelData = mcsa.decode()

with ObjEncoder(data) as obj:
    obj.encode().save("model.obj")
```

- Use context manager + convert methods

```python
with McsaDecoder("model.mcsa") as mcsa:
    obj = mcsa.convert_to(ObjEncoder)
    obj.close()
```

```python
with McsaDecoder("model.mcsa") as mcsa:
    mcsa.to_obj().save("model.obj")
```

> [!IMPORTANT]
> When using `convert_to` buffer remains open. \
> `close()` or `save()` or another context (`with`) is necessary.

- Save multiple copies

```python
with McsaDecoder("model.mcsa") as mcsa:
    with mcsa.to_obj() as obj:
        obj.save_as("model_1.obj")
        obj.save_as("model_2.obj")
```

# 🛠️ Build

> [!IMPORTANT]
> You will need [poetry](https://python-poetry.org) to do compilation.

> [!TIP]
> Recommended to create virtual environment.
>
> ```bash
> poetry shell
> ```

Then install dependencies:

```bash
poetry install
```

And run script to compile:

```bash
python scripts/build.py
```

Executable file will be created in `/dist` directory.

