Exacto: How to copy scenes between Stencyl files
Warning: This has only been successfully tested in one specific case and it could potentially leave Stencyl files unusable. Only use it after backing up the Stencyl projects involved.
So this is a tool with a pretty narrow application, but, I made a thing. If you’re familiar with the (generally pretty nice) game-making tool Stencyl, you may be aware of a curious limitation it has: It is not possible to copy a scene between two Stencyl files. You can import and export assets, or scripts; but not entire scenes. My friend Liz wound up getting stuck on this hard when she was making her game Problem Attic (it’s really good, you should play it); she had split her project file into two, and was experimentally making levels in each. Then she went back to merge them and found out Stencyl won’t let you do this.
To unstick Liz, I wound up making a Python script that just goes behind Stencyl’s back and copies scene data between games. You can find the script, named Exacto, here; click “Download”, or look under “source” (it’s the only file). From our testing, the script appears to work— it was used to make the final version of Problem Attic.
Caveats
The script copies all the data related to a Stencyl scene that I am aware of. There are two problems here though. First off, it’s possible there’s some data I’m not aware of, and which the script therefore misses. Second off, the script does not even try to copy things which are global to the game— such as actors, or assets like tilemaps. So if you want this script to work, you will need to copy those things over first. You will need to separately load all the assets used in game A, into game B.
There’s one more, even more awkward thing though. Remember I said above our test programs were two versions of the same game? Well, all the assets have “ID numbers”. You can’t see them while you’re making the game, but they’re in the game files. I’m not sure, but it’s possible that if you copied between two *very* different games, and you used a lot of assets in the scene you copied, and both games contained the same assets *but* the “ID numbers” were different, then my script might get the ID numbers confused and cause Stencyl to use the wrong actors or the wrong assets or tilemaps after you copy the scene. I’m not sure; I haven’t had a chance to try this. Because Liz again was just working off two versions of one game file, I expect the ID numbers would be the same in both for her anyway.
I’m going into all this technical detail for a simple reason: Stencyl does not deal well when it sees something it doesn’t expect in the game file. Stencyl expects it will only see game files it made and that people like me won’t be mucking around behind its back. So if you copy something into a game file that Stencyl doesn’t understand, it might just crash, or freeze, or maybe you’ll think the copy worked but afterward you’ll find certain windows in the interface just refuse to open. (This is why I am making such a big deal about backing up your files.) So I’m wanting to warn about places where my script might confuse Stencyl, and the assets/asset ID thing is the biggest danger point I know of.
By the way though— if you *do* find a case where running this script left Stencyl unable to work on your game file, I’d be curious to talk to you. If I had more examples to work with, I’d be able to make the script more resistant to bugs.
Usage
Download the exacto.py script from the above URL. If you are using Windows, you’re also going to need to install something called “Python”. Go here and download the “Python 2.7 Windows Installer” or “Python 2.7.5 Windows installer”— it doesn’t much matter which you pick as long as it has “2.7” in the name and not “3.0”. (If you are on a Mac, you already have Python.) Run that installer.
Close Stencyl, and open up a command line window— on Windows this is “Command prompt” in the start menu, on the Mac this is Applications->Utilities->Terminal, but if you don’t already know how to use the command line this next part might not make much sense to you anyway. Cd to the directory you downloaded exacto.py to. Here’s a few examples of using Exacto– things you can type into the command line:
python exacto.py --help
This has Exacto print out exactly how to use it. There’s a couple small features it lists in the –help but which I don’t document in this blog post.
python exacto.py -i ~/stencylworks/games/gameFROM list
This prints out a list of all the scenes, and their “Scene ID” numbers. By the way, where I say “gameFROM”, put the name of your game.
python exacto.py -i ~/stencylworks/games/gameFROM -o ~/stencylworks/games/gameTO copy "scene one" "scene two" "scene three"
This is what you actually want to do to copy scenes. You’ll want to put the name of the game you want to pull from instead of gameFROM after the -i, the name of the game you want to write into instead of gameTO after the -o, and at the end instead of “scene one” “scene two” put the names of the scenes you want to copy (in quotation marks). Once you’ve run this command, you can open up Stencyl again and see if it worked.
By the way– maybe you run “list” and realize the names are kinda complicated or messy to type? You could also just use numbers. Say you ran the “list” command and you saw the scenes you want to copy have scene IDs 6 and 8. You could say:
python exacto.py -i ~/stencylworks/games/gameFROM -o ~/stencylworks/games/gameTO copy --raw-id 6 8
Notice all these examples are for the Mac command line. If you run on Windows, you want to write it a little different. Instead of saying “python” you want to say “C:\Python27\python.exe”, and everywhere I wrote “~/stencylworks/games/” above you’ll want to say “%APPDATA%\Stencyl\stencylworks\games\”. (The point with this “stencylworks/games” folder is that you need to find the place where stencylworks stores your game’s *directory*– the thing containing the game.xml. The script doesn’t work on .stencylworks files.)
TODO
I’m not sure if I intend to do any more work on this— it depends on how much interest there is. But some things I think would be worth exploring in a future version of this script:
- It’s probably pretty easy to make a Windows GUI so you don’t have to do all this downloading-Python/command line junk. cx_Freeze or something.
- Fix for the “ID numbers” thing I’m worried about above?
- It’s probably possible to copy assets and actors and stuff! I just haven’t looked into it. At least, it’s probably pretty easy to *check* if the assets are present in the destination file, and if they aren’t, complain and refuse to copy, instead of just going ahead and breaking stuff.
- It would be pretty easy to be able to operate on .stencylworks files, or even make new .stencylworks files. They’re just zips.
Anyway
Anyway, good luck, and if you try this script out, I’d be curious to hear how it went (whether it works or not!).