FAQ and Troubleshooting

FAQ

Does CrystalWorkshop change my game files or saves? No:

• It reads the archives.
• It keeps its own work in <game>/ff13_studio/.
• It writes into the game only when you export loose files, and then only to mod_data (with backups).
• It never touches saves.

Shards are separate files in ff13_studio/exports/.

Which games are supported? FINAL FANTASY XIII is the most complete. XIII-2 and LIGHTNING RETURNS open and edit too, but more of their features are Experimental and their exports are not verified in game. See the table on Home.

Do players need CrystalWorkshop to use my mod? No. They need PulseDepot. PulseDepot installs Crux, the mod host.

Do I or my players need Java?

• You need a JDK 17 or newer (java and javac, not just a Java runtime) to decompile, compile and export scripts. See Installing.
• Players need one only for mods that change game scripts. Your shard stores script edits as Java source patches, and PulseDepot cannot apply those without a JDK: its review stops and asks the player to install one. With a JDK, PulseDepot merges script changes from several mods class by class.
• The Vineflower decompiler is included in both CrystalWorkshop and PulseDepot.

Can I open a shard someone else made? PulseDepot installs any shard. CrystalWorkshop reopens a shard as an editable project only for its author, because the project is encrypted to the author key.

I lost my author key. Your existing shards still install and work. You cannot reopen them as projects. Keep a backup of ~/.config/ff13-studio/author/.

Where are my settings?

• Settings: the ff13-studio data folder.
• Author key: ff13-studio/author in the config folder.
• Caches: ff13-studio in the cache folder.
• Per-game work: <game>/ff13_studio/.

What is CrystalWorkshop’s licence? Who owns the mods I make? CrystalWorkshop is freeware: free to download and use, all rights reserved. Don’t re-upload it outside the official download pages, modify, reverse engineer or sell it. It comes as is, without warranty; the full terms are in LICENSE in the program folder. Mods and other content you create with it belong to you, subject to the game’s own terms. Bundled third-party components keep their own licences, listed in THIRD-PARTY-NOTICES.txt. FINAL FANTASY is a trademark of Square Enix. CrystalWorkshop is an unofficial fan tool, not affiliated with or endorsed by Square Enix.

What does ALPHA mean here? Features can change, and some fail on some files. Pages and ALPHA.md mark Experimental areas. Keep backups, and expect to re-export your mods with later versions.

Troubleshooting

Problem	What to do
“no game open” / nothing found	Use Browse… on the Welcome page, or set FF13_GAME_DIR / FF13_2_GAME_DIR / LR_GAME_DIR.
The window does not open (wgpu error)	Start with WGPU_BACKEND=vulkan (or gl).
Models draw flat or the renderer says Fallback	DXVK did not load. Update your GPU driver: DXVK needs Vulkan 1.3 (“Vulkan 1.3 capable setup is required”). Windows: keep the package’s dxvk\d3d9.dll next to crystalworkshop.exe (extract the zip again if it is missing). Linux: install DXVK-native (libdxvk_d3d9.so; Arch: libdxvk) and SDL3/SDL2. Or set the path under Settings › 3D model viewer. Restart after changing it.
Scene View is black	Check DXVK and that your GPU driver supports Vulkan 1.3 (see the row above). Scene renders have no fallback renderer.
“JDK tool javac not found on JAVA_HOME or PATH…”	Install a JDK 17 or newer (Windows: the Eclipse Temurin JDK MSI with Set JAVA_HOME variable on; Linux: your distribution’s OpenJDK 17+ package; see Installing), or set the java and javac paths under Settings › Scripts toolchain. Then choose Detect toolchain.
Scripts: “Decompile failed”	Check that a JDK 17+ is found (row above) and that Settings › Scripts toolchain shows the Vineflower jar. If the jar is missing, extract the package again, or download it there. “unknown script … SELECT id FROM scripts first” means the script list was still loading. Open Open Scripts once and try again.
SQL: no column "x"	The message suggests close names (for example buy_price, sell_price). The SOURCES list shows every table’s columns.
Export: rows marked Unverified	That route is not proven in game. Tick allow to include it, at your own risk.
Export blocked (Crystarium)	Fix the Crystarium validation errors first.
The mod has no effect in game	That is a PulseDepot/Crux question. Check the Crux.jsonl log beside the game executable (addons). See PulseDepot’s guide.
MCP client sees no tools / 401	Headless: check the path to crystalw and the --game value. HTTP: tick Allow AI clients, and use the current bearer token.
The AI keeps calling call_tool	That is expected in progressive mode. Use enable_tool_group to list a group’s tools, or --tools full.

Bug reports help most with:

• the version (crystalw --version);
• the game and archive variant;
• BUILD-INFO.json from the package;
• the Log panel output (bottom right);
• the steps that led to the problem.

Related

Installing · First Run and Game Setup · Glossary