🚀 Usage

🚀 Usage#

Quick Start#

🖥️ GUI

Launch scfile.exe without arguments to open the graphical interface. Use Converter for standalone assets, Animation for model and animation pairs, Map cache for region caches, and 2D Map for map tiles.

📥 Drag & Drop

Drag files or folders directly onto scfile.exe in File Explorer. Supported files are converted to default formats and saved alongside the source file.

🖱️ Open With

Set scfile.exe as the default program for opening supported file types. Double-clicking any such file in Explorer will convert it and save output alongside the source file.

To set up: right-click a file → Open With → choose scfile.exe and check Always use this app.

📟 Command Line

Run scfile.exe --help to see all available arguments and options. Paths are routed automatically to commands by context.

scfile.exe model.mcsb -F fbx --skeleton # convert to fbx with skeleton
scfile.exe clips.mcvd model.mcsb # convert animation clips
scfile.exe path/to/map_cache/5.0 # convert map cache
📖 Python Library
Install the package from PyPI: pip install sc-file -U.
Use scfile package from your Python scripts.

Full API Reference

Example#
from scfile import Options, convert

convert.mcsb_to_glb("model.mcsb", options=Options(skeleton=True))

Command Line Interface#

General#

COMMAND
Available commands: convert, animate, mapcache, and maptiles.
When paths are supplied without a command, the CLI selects one from their names and formats.
--version

Show the program version and exit.

scfile --version
--updates

Check for available updates on GitHub Releases and exit. Requires internet connection.

scfile --updates

convert#

Default command. Converts game assets to standard formats.

PATHS

One or more files or directories. Accepts absolute and relative paths. Only supported files are processed.

Example#
scfile convert "model.mcsb"
scfile convert "model.mcsb" "texture.ol"
scfile convert "C:/assets"
-O, --output

Output directory for converted files. If not specified, output files are saved alongside the source file.

Example#
scfile convert "model.mcsb" --output "D:/output"
-F, --model-format
Preferred output format for models.
Accepted values: obj, glb, fbx.
Default is obj.
When --skeleton or --animation is used, default is glb.
Example#
scfile convert "model.mcsb" -F glb
-I, --include

Process only the specified source formats. May be repeated.

Example#
scfile convert "C:/assets" --include mcsb
scfile convert "C:/assets" -I mcsb -I ol
--skeleton
Export model skeleton (armature).
Supported by: glb, fbx.
Example#
scfile convert "model.mcsb" --skeleton
scfile convert "model.mcsb" -F glb --skeleton
scfile convert "model.mcsb" -F fbx --skeleton
--animation
Export embedded animation clips. Implies --skeleton.
Supported by: glb, fbx.
Example#
scfile convert "model.mcsb" --animation
scfile convert "model.mcsb" -F glb --animation
--on-conflict
What to do when an output file already exists in output directory.
Accepted values: replace, rename, skip.
Default is replace.

  • replace: Replace existing file.

  • rename: Add numeric suffix: model (1).obj, model (2).obj.

  • skip: Keep existing file.

Example#
scfile convert "C:/assets/model.mcsb" "C:/assets/sub/model.mcsb" --on-conflict rename
--layout
Output layout inside --output. Defaults to rooted.
Accepted values: rooted, relative, dump. Examples →
Example#
scfile convert "C:/assets" --output "D:/output" --layout relative
-W, --workers
Number of worker threads. Default: CPU count.
Set to 0 for sequential execution.
Example#
scfile convert "C:/assets" --workers 4
-v, --verbose

Show the result of every processed file.

Output Structure#

Examples of how --layout changes output layout.

Source structure#
./assets/
├── armor/albatros.mcsb
└── items/vodka.ol
rooted (default)
scfile convert "./assets" --output "./output"
Output#
./output/
├── assets/armor/albatros.obj
└── assets/items/vodka.dds
relative
scfile convert "./assets" --output "./output" --layout relative
Output#
./output/
├── armor/albatros.obj
└── items/vodka.dds
dump
scfile convert "./assets" --output "./output" --layout dump
Output#
./output/
├── albatros.obj
└── vodka.dds

animate#

Applies external animation data to one or more .mcsb models and exports a .glb file. Each subcommand accepts -O, --output for a GLB file or directory. Without it, the GLB is saved next to the animation source.
Usage guide →
arms ANIMATION MODEL [HANDS]

Apply a first-person .mcvd animation to a weapon .mcsb model. Add an optional hands model.

Example#
scfile animate arms "wpn_fp_akm.mcvd" "akm.mcsb" "hands.mcsb"
scfile animate arms "wpn_fp_akm.mcvd" "akm.mcsb"
scfile animate arms "wpn_fp_walkcycles.mcvd" "hands.mcsb"
face ANIMATION MODEL

Apply a facial .mcvd animation to a head .mcsb model.

Example#
scfile animate face "shaman.mcvd" "unique_shaman.mcsb"
body ANIMATION MODEL

Apply an .mcal skeletal animation library to an .mcsb model.

--raw

Keep technical and duplicate clips.

Example#
scfile animate body "pack.mcal" "origin.mcsb"
scfile animate body "pack.mcal" "origin.mcsb" --raw

mapcache#

Merges .mdat region caches into .mca region files.
Run with explicit command or use a path containing map_cache to auto-detect.
Usage guide →
SOURCE

Directory containing .mdat files.

Example#
scfile "C:/map_cache/5.0"
scfile mapcache "C:/map_cache/5.0"
-O, --output

Output directory for .mca files. If not specified, creates a folder alongside SOURCE with _mca suffix.

Example#
scfile mapcache "C:/map_cache/5.0" --output "D:/output"
-W, --workers
Number of worker threads. Default: CPU count.
Set to 0 for sequential execution.
Example#
scfile mapcache "C:/map_cache/5.0" --workers 4
--biomes / --no-biomes

Export biome data. Enabled by default. Use --no-biomes to omit it.

Example#
scfile mapcache "C:/map_cache/5.0" --no-biomes
--backup / --no-backup

Keep the first original .mca region as .mca.bck before replacement. Enabled by default. Existing backups are kept unchanged.

-v, --verbose

Show the result of every processed region.

maptiles#

Assembles flat r.<x>.<z>.ol map tiles into one JPEG or PNG image.
Usage guide →
SOURCE OUTPUT
Assemble tiles directly from one flat folder.
OUTPUT must be an image file ending in .jpg, .jpeg, or .png.
Example#
scfile maptiles "C:/tiles" "D:/zone.jpg"
SOURCE TARGET OUTPUT
Assemble a named map from game asset layers.
--region optionally selects localization region. Otherwise system language is preferred.
Example#
scfile maptiles "C:/Steam/steamapps/common/STALCRAFT" "global_map" "D:/global.jpg" --region ru
--jpeg-quality
JPEG quality from 0 through 100.
Default: 92.
--png-compression
PNG compression level from 0 through 9.
Default: 6.