# SC FILE
Utility and Library for decoding and converting stalcraft asset files, such as models and textures, into popular formats.
Designed for artworks creation.
For answers to common questions, please refer to [FAQ section](FAQ.md).
You can download executable from [Releases page](https://github.com/onejeuu/sc-file/releases).
> [!WARNING]
> Do not use game assets directly. \
> Any changes in game client can be detected.
## 📁 Formats
| Type | Source | Output |
| ------- | ------------- | ---------------------- |
| Model | .mcsa / .mcvd | .obj, .dae, 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 supported partially: Cubemaps (HDRI)
- Formats unsupported: RGBA32F
- Some normal map textures can be inverted
## 💻 CLI Utility
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. Only one directory can be specified.
### Options
- `-F`, `--formats`: **Preferred format for models**. To specify multiple formats, **option** must be used multiple times.
- `-O`, `--output`: **One path to output directory**. If not specified, file will be saved in same directory with a new suffix.
### Flags
- `--subdir`: Recreates input subdirectories to output directory.
- `--no-overwrite`: Do not overwrite output file if already exists.
- `--silent`: Suppress all console prints.
### Examples
1. Convert model with specified formats
```bash
scfile model.mcsa -F obj -F dae
```
_Will be saved in same location with a new suffix._
2. Convert multiple files to a specified directory:
```bash
scfile model1.mcsa model2.mcsa -O path/to/output
```
3. Convert all `.mcsa` files in current directory:
```bash
scfile *.mcsa
```
_Will be saved in same location. Subdirectories are not included._
4. Convert all `.mcsa` files with subdirectories to a specified directory:
```bash
scfile path/to/files/**/*.mcsa -O path/to/output --subdir
```
## 📚 Library
### Install
```bash
pip install sc-file -U
```
### Usage
#### Simple Method
```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 Examples
- Default usage
```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 decoder
obj = ObjEncoder(data)
obj.encode().save("model.obj") # ? Buffer closes after save
```
- Use encoded content bytes
```python
obj = ObjEncoder(data) # ? data - ModelData from McsaDecoder
obj.encode() # ? Write bytes into buffer
with open("model.obj", "wb") as fp:
fp.write(obj.content) # ? obj.content - Encoder buffer bytes
obj.close() # ? Necessary to close encoder
```
- Use convert methods
> [!IMPORTANT]
> Unclosed buffer can cause memory leaks. \
> When using `convert_to` or `to_xxx` methods, encoder buffer remains open. \
> `close()` or `save()` or another context (`with`) **is necessary**.
```python
mcsa = McsaDecoder("model.mcsa")
mcsa.convert_to(ObjEncoder).save("model.obj") # ? Encoder buffer closes after save
mcsa.close() # ? Necessary to close decoder
```
```python
mcsa = McsaDecoder("model.mcsa")
mcsa.to_obj().save("model.obj") # ? Encoder buffer closes after save
mcsa.close() # ? Necessary to close decoder
```
- Use context manager (`with`)
```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() # ? Necessary to close encoder
```
or
```python
with McsaDecoder("model.mcsa") as mcsa:
mcsa.to_obj().save("model.obj") # ? Encoder buffer closes after save
```
- Save multiple copies
```python
with McsaDecoder("model.mcsa") as mcsa:
with mcsa.to_obj() as obj:
obj.save_as("model_1.obj") # ? Encoder buffer remains open after save_as
obj.save_as("model_2.obj")
# ? Encoder buffer closes after end of context (with)
```
## 🛠️ Build
1. Download project
```bash
git clone https://github.com/onejeuu/sc-file.git
```
```bash
cd sc-file
```
2. Recommended to create virtual environment
```bash
python -m venv .venv
```
```bash
.venv\Scripts\activate
```
3. Install dependencies
via poetry
```bash
poetry install
```
or via pip
```bash
pip install -r requirements.txt
```
4. Run script to compile
```bash
python scripts/build.py
```
Executable file `scfile.exe` will be created in `/dist` directory.
Raw data
{
"_id": null,
"home_page": "https://github.com/onejeuu/sc-file",
"name": "sc-file",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": null,
"author": "onejeuu",
"author_email": "mail@66rk.ru",
"download_url": "https://files.pythonhosted.org/packages/d0/f3/be9c088d3c23ab2aa1e76642339d86fa91127ee3db5fd8b0f31ef54b8039/sc_file-3.6.1.tar.gz",
"platform": null,
"description": "# SC FILE\n\nUtility and Library for decoding and converting stalcraft asset files, such as models and textures, into popular formats.\n\nDesigned for artworks creation.\n\nFor answers to common questions, please refer to [FAQ section](FAQ.md).\n\nYou can download executable from [Releases page](https://github.com/onejeuu/sc-file/releases).\n\n\n\n> [!WARNING]\n> Do not use game assets directly. \\\n> Any changes in game client can be detected.\n\n## \ud83d\udcc1 Formats\n\n| Type | Source | Output |\n| ------- | ------------- | ---------------------- |\n| Model | .mcsa / .mcvd | .obj, .dae, ms3d, .txt |\n| Texture | .ol | .dds |\n| Image | .mic | .png |\n\n### Models\n\n- Versions supported: 7.0, 8.0, 10.0, 11.0\n- Skeleton and Animations currently unsupported\n\n### Textures\n\n- Formats supported: DXT1, DXT3, DXT5, RGBA8, BGRA8, DXN_XY\n- Formats supported partially: Cubemaps (HDRI)\n- Formats unsupported: RGBA32F\n- Some normal map textures can be inverted\n\n## \ud83d\udcbb CLI Utility\n\nFrom bash:\n\n```bash\nscfile [FILES]... [OPTIONS]\n```\n\n> [!TIP]\n> You can just drag and drop one or multiple files onto `scfile.exe`.\n\n### Arguments\n\n- `FILES`: **List of file paths to be converted**. Multiple files should be separated by **spaces**. Accepts both full and relative paths. Only one directory can be specified.\n\n### Options\n\n- `-F`, `--formats`: **Preferred format for models**. To specify multiple formats, **option** must be used multiple times.\n- `-O`, `--output`: **One path to output directory**. If not specified, file will be saved in same directory with a new suffix.\n\n### Flags\n\n- `--subdir`: Recreates input subdirectories to output directory.\n- `--no-overwrite`: Do not overwrite output file if already exists.\n- `--silent`: Suppress all console prints.\n\n### Examples\n\n1. Convert model with specified formats\n\n ```bash\n scfile model.mcsa -F obj -F dae\n ```\n\n _Will be saved in same location with a new suffix._\n\n2. Convert multiple files to a specified directory:\n\n ```bash\n scfile model1.mcsa model2.mcsa -O path/to/output\n ```\n\n3. Convert all `.mcsa` files in current directory:\n\n ```bash\n scfile *.mcsa\n ```\n\n _Will be saved in same location. Subdirectories are not included._\n\n4. Convert all `.mcsa` files with subdirectories to a specified directory:\n\n ```bash\n scfile path/to/files/**/*.mcsa -O path/to/output --subdir\n ```\n\n## \ud83d\udcda Library\n\n### Install\n\n```bash\npip install sc-file -U\n```\n\n### Usage\n\n#### Simple Method\n\n```python\nfrom scfile import convert\n\n# Output path is optional.\n# Defaults to source path with new suffix.\nconvert.mcsa_to_obj(\"path/to/model.mcsa\", \"path/to/model.obj\")\nconvert.ol_to_dds(\"path/to/texture.ol\", \"path/to/texture.dds\")\nconvert.mic_to_png(\"path/to/image.mic\", \"path/to/image.png\")\n\n# Skeleton support via MilkShape3D\nconvert.mcsa_to_ms3d(\"path/to/model.mcsa\", \"path/to/model.ms3d\")\nconvert.mcsa_to_ms3d_ascii(\"path/to/model.mcsa\", \"path/to/model.txt\")\n\n# Or determinate it automatically\nconvert.auto(\"path/to/model.mcsa\")\n```\n\n#### Advanced Examples\n\n- Default usage\n\n```python\nfrom scfile.file.data import ModelData\nfrom scfile.file import McsaDecoder, ObjEncoder\n\nmcsa = McsaDecoder(\"model.mcsa\")\ndata: ModelData = mcsa.decode()\nmcsa.close() # ? Necessary to close decoder\n\nobj = ObjEncoder(data)\nobj.encode().save(\"model.obj\") # ? Buffer closes after save\n```\n\n- Use encoded content bytes\n\n```python\nobj = ObjEncoder(data) # ? data - ModelData from McsaDecoder\nobj.encode() # ? Write bytes into buffer\n\nwith open(\"model.obj\", \"wb\") as fp:\n fp.write(obj.content) # ? obj.content - Encoder buffer bytes\n\nobj.close() # ? Necessary to close encoder\n```\n\n- Use convert methods\n\n> [!IMPORTANT]\n> Unclosed buffer can cause memory leaks. \\\n> When using `convert_to` or `to_xxx` methods, encoder buffer remains open. \\\n> `close()` or `save()` or another context (`with`) **is necessary**.\n\n```python\nmcsa = McsaDecoder(\"model.mcsa\")\nmcsa.convert_to(ObjEncoder).save(\"model.obj\") # ? Encoder buffer closes after save\nmcsa.close() # ? Necessary to close decoder\n```\n\n```python\nmcsa = McsaDecoder(\"model.mcsa\")\nmcsa.to_obj().save(\"model.obj\") # ? Encoder buffer closes after save\nmcsa.close() # ? Necessary to close decoder\n```\n\n- Use context manager (`with`)\n\n```python\nwith McsaDecoder(\"model.mcsa\") as mcsa:\n data: ModelData = mcsa.decode()\n\nwith ObjEncoder(data) as obj:\n obj.encode().save(\"model.obj\")\n```\n\n- Use context manager + convert methods\n\n```python\nwith McsaDecoder(\"model.mcsa\") as mcsa:\n obj = mcsa.convert_to(ObjEncoder)\n obj.close() # ? Necessary to close encoder\n```\n\nor\n\n```python\nwith McsaDecoder(\"model.mcsa\") as mcsa:\n mcsa.to_obj().save(\"model.obj\") # ? Encoder buffer closes after save\n```\n\n- Save multiple copies\n\n```python\nwith McsaDecoder(\"model.mcsa\") as mcsa:\n with mcsa.to_obj() as obj:\n obj.save_as(\"model_1.obj\") # ? Encoder buffer remains open after save_as\n obj.save_as(\"model_2.obj\")\n # ? Encoder buffer closes after end of context (with)\n```\n\n## \ud83d\udee0\ufe0f Build\n\n1. Download project\n\n ```bash\n git clone https://github.com/onejeuu/sc-file.git\n ```\n\n ```bash\n cd sc-file\n ```\n\n2. Recommended to create virtual environment\n\n ```bash\n python -m venv .venv\n ```\n\n ```bash\n .venv\\Scripts\\activate\n ```\n\n3. Install dependencies\n\n via poetry\n\n ```bash\n poetry install\n ```\n\n or via pip\n\n ```bash\n pip install -r requirements.txt\n ```\n\n4. Run script to compile\n\n ```bash\n python scripts/build.py\n ```\n\n Executable file `scfile.exe` will be created in `/dist` directory.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Utility & Library for decoding stalcraft assets",
"version": "3.6.1",
"project_urls": {
"Documentation": "https://github.com/onejeuu/sc-file/?tab=readme-ov-file#usage",
"Homepage": "https://github.com/onejeuu/sc-file",
"Repository": "https://github.com/onejeuu/sc-file"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2709ef0bf3a1ce1959c8c2e387eb7bb7c47f953951ad63c721c38d79af4797ac",
"md5": "8cb039ddae3aa6588751b60ab9c801ed",
"sha256": "2928b310010df3967b5fd21283b94207ef55b1dbc7961addb831136a2c0b4ad1"
},
"downloads": -1,
"filename": "sc_file-3.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8cb039ddae3aa6588751b60ab9c801ed",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 39929,
"upload_time": "2024-12-18T02:39:45",
"upload_time_iso_8601": "2024-12-18T02:39:45.953165Z",
"url": "https://files.pythonhosted.org/packages/27/09/ef0bf3a1ce1959c8c2e387eb7bb7c47f953951ad63c721c38d79af4797ac/sc_file-3.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d0f3be9c088d3c23ab2aa1e76642339d86fa91127ee3db5fd8b0f31ef54b8039",
"md5": "86df8331745fae25a4bc94cc97153ab5",
"sha256": "3e2005c6d94fe46c08ffba443a168e3ba7a1547554b8345b650088fbe0b3ce1e"
},
"downloads": -1,
"filename": "sc_file-3.6.1.tar.gz",
"has_sig": false,
"md5_digest": "86df8331745fae25a4bc94cc97153ab5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 26251,
"upload_time": "2024-12-18T02:39:47",
"upload_time_iso_8601": "2024-12-18T02:39:47.254084Z",
"url": "https://files.pythonhosted.org/packages/d0/f3/be9c088d3c23ab2aa1e76642339d86fa91127ee3db5fd8b0f31ef54b8039/sc_file-3.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 02:39:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "onejeuu",
"github_project": "sc-file",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "lz4",
"specs": [
[
"==",
"4.3.3"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.1.7"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"2.1.3"
]
]
},
{
"name": "rich",
"specs": [
[
"==",
"13.9.4"
]
]
},
{
"name": "pyinstaller",
"specs": [
[
"==",
"6.11.1"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"8.1.1"
]
]
}
],
"lcname": "sc-file"
}
JSON
