Installing

Goal: get CrystalWorkshop and its command-line tool crystalw running on Windows or Linux.

Prerequisites

• The Steam release of the game(s) you want to mod. The Microsoft Store version of XIII-2 is experimental; see Compatibility.

• Windows: 64-bit Windows 10 or 11 with Direct3D 12 or Vulkan drivers.

• Linux: x86_64 with a Vulkan driver (or OpenGL via WGPU_BACKEND=gl).

• An up-to-date GPU driver with Vulkan 1.3 support. 3D previews (models, effects, scenes) draw with the game’s own D3D9 shaders through DXVK, and DXVK needs a Vulkan 1.3-capable GPU and driver. Otherwise DXVK reports “Vulkan 1.3 capable setup is required”.

  • Windows: nothing to download. The package includes DXVK 3.1.1 (dxvk\d3d9.dll next to crystalworkshop.exe).
  • Linux: the package does not include DXVK. Install DXVK-native (libdxvk_d3d9.so) and SDL3 or SDL2 from your system:
    • Arch: the libdxvk package;
    • other distributions: the dxvk-native package, or a DXVK-native release from https://github.com/doitsujin/dxvk/releases.

  CrystalWorkshop looks for DXVK in this order:

  1. the path under Settings › 3D model viewer (DXVK D3D9 library);
  2. the FF13_STUDIO_D3D9 environment variable;
  3. next to the executable: dxvk\d3d9.dll, then d3d9.dll (Windows), or dxvk/libdxvk_d3d9.so, then libdxvk_d3d9.so (Linux);
  4. Linux only: the system’s libdxvk_d3d9.so.

  It only ever loads a DXVK build, never Windows’ own d3d9.dll. Without DXVK, the model preview falls back to a simpler renderer without the game shaders. The scene View, scene renders and MCP renders have no fallback.

• Scripts: a JDK 17 or newer (java and javac; a Java runtime alone is not enough). Script decompile, compile and export need it. No JDK is bundled:

  • Windows: install the Eclipse Temurin JDK 17 (or 21) MSI from adoptium.net. In the installer, turn on Set JAVA_HOME variable and Add to PATH.
  • Linux: install your distribution’s JDK package, for example Arch jdk17-openjdk or jdk21-openjdk, Debian/Ubuntu openjdk-17-jdk, Fedora java-17-openjdk-devel (the -jdk / -devel package has javac).

  CrystalWorkshop uses the java and javac paths set under Settings › Scripts toolchain. While those are unset, it looks in JAVA_HOME’s bin folder, then on PATH; Detect toolchain checks again. The Vineflower 1.12.0 decompiler is included in both packages. If its jar is missing, CrystalWorkshop downloads the same jar once from Maven Central and checks it by SHA-1, or you can choose a jar under Settings › Scripts toolchain.

• Testing mods in game: PulseDepot and Crux. On Linux the game runs through Proton.

Steps

Windows

1. Extract crystalworkshop-0.1.0-alpha-windows-x86_64.zip to a folder you can write to.
2. Start crystalworkshop.exe. The build is not code-signed. If SmartScreen says “Windows protected your PC”, choose More info › Run anyway.
3. Optional: in a terminal, crystalw.exe --version prints crystalw 0.1.0-alpha (CrystalWorkshop ALPHA).

Linux

1. Extract crystalworkshop-0.1.0-alpha-linux-x86_64.zip with unzip crystalworkshop-0.1.0-alpha-linux-x86_64.zip (or any archive manager that keeps file permissions), for example to ~/Apps/CrystalWorkshop. If the program won’t start, run chmod +x crystalworkshop crystalw pulsedepot in the extracted folder.
2. Run ./crystalworkshop (add --game ff13, --game xiii2 or --game lr to open a game right away).
3. ./crystalw --version checks the command-line tool.

The package also contains pulsedepot. PulseDepot’s own package adds the Crux DLLs that installing mods needs; get it for testing in game.

Result

The window title reads CrystalWorkshop 0.1.0-alpha. Settings › About shows the version and the ALPHA channel.

Undo / remove

Delete the folder. CrystalWorkshop keeps its settings in these places:

• Settings: ~/.local/share/ff13-studio on Linux, or the app-data folder on Windows.
• Author key: $XDG_CONFIG_HOME/ff13-studio/author.
• Caches: ff13-studio in the cache folder.
• Per-game work: ff13_studio/ inside each game folder.

Delete those as well to remove everything.

Related

First Run and Game Setup · FAQ and Troubleshooting · Enabling MCP