🚀 Usage
==================================================

.. include:: _links.rst

.. toctree::
   :maxdepth: 1
   :glob:

   *


----------------------------------------
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.

  .. code-block:: bash

    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.

  :doc:`Full API Reference </api/index>`

  .. code-block:: python
    :caption: 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.

    .. code-block:: bash

      scfile --version


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

    .. code-block:: bash

      scfile --updates


.. _cli-convert:

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.

  .. code-block:: bash
    :caption: 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.

  .. code-block:: bash
    :caption: 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``.

  .. code-block:: bash
    :caption: Example

    scfile convert "model.mcsb" -F glb


``-I, --include``
  Process only the specified source formats. May be repeated.

  .. code-block:: bash
    :caption: Example

    scfile convert "C:/assets" --include mcsb
    scfile convert "C:/assets" -I mcsb -I ol


``--skeleton``
  | Export model skeleton (armature).
  | Supported by: ``glb``, ``fbx``.

  .. code-block:: bash
    :caption: 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``.

  .. code-block:: bash
    :caption: 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.

  .. code-block:: bash
    :caption: 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 → <layout_>`_

  .. code-block:: bash
    :caption: 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.

  .. code-block:: bash
    :caption: Example

    scfile convert "C:/assets" --workers 4


``-v, --verbose``
  Show the result of every processed file.


.. _layout:

Output Structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Examples of how ``--layout`` changes output layout.

.. code-block:: text
  :caption: Source structure

  ./assets/
  ├── armor/albatros.mcsb
  └── items/vodka.ol


``rooted`` (default)
  .. code-block:: bash

    scfile convert "./assets" --output "./output"

  .. code-block:: text
    :caption: Output

    ./output/
    ├── assets/armor/albatros.obj
    └── assets/items/vodka.dds


``relative``
  .. code-block:: bash

    scfile convert "./assets" --output "./output" --layout relative

  .. code-block:: text
    :caption: Output

    ./output/
    ├── armor/albatros.obj
    └── items/vodka.dds


``dump``
  .. code-block:: bash

    scfile convert "./assets" --output "./output" --layout dump

  .. code-block:: text
    :caption: Output

    ./output/
    ├── albatros.obj
    └── vodka.dds


.. _cli-animate:

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.
| :doc:`Usage guide → <animate>`

``arms ANIMATION MODEL [HANDS]``
  Apply a first-person ``.mcvd`` animation to a weapon ``.mcsb`` model. Add an optional hands model.

  .. code-block:: bash
    :caption: 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.

  .. code-block:: bash
    :caption: 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.

  .. code-block:: bash
    :caption: Example

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


.. _cli-mapcache:

mapcache
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

| Merges ``.mdat`` region caches into ``.mca`` region files.
| Run with explicit command or use a path containing ``map_cache`` to auto-detect.
| :doc:`Usage guide → <mapcache>`

``SOURCE``
  Directory containing ``.mdat`` files.

  .. code-block:: bash
    :caption: 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.

  .. code-block:: bash
    :caption: 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.

  .. code-block:: bash
    :caption: 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.

  .. code-block:: bash
    :caption: 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.


.. _cli-maptiles:

maptiles
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

| Assembles flat ``r.<x>.<z>.ol`` map tiles into one JPEG or PNG image.
| :doc:`Usage guide → <maptiles>`

``SOURCE OUTPUT``
  | Assemble tiles directly from one flat folder.
  | ``OUTPUT`` must be an image file ending in ``.jpg``, ``.jpeg``, or ``.png``.

  .. code-block:: bash
    :caption: 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.

  .. code-block:: bash
    :caption: 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``.