[FAQ] Wagic's Folder structure - how to add cards, images...

Need help installing/playing Wagic? Post here
Site Admin
Posts: 3727
Joined: Wed Oct 15, 2008 12:42 am
Location: Japan

[FAQ] Wagic's Folder structure - how to add cards, images...

Post by wololo »

Starting with Wagic 0.17, the folders of Wagic are changing.

A bit of history to explain this change:
Initially all files in Wagic where in a subfolder called "Res". This caused 3 types of issues:
- The amount of files to install wagic was huge, and took a long time on poor USB devices
- The amount of files to install was so huge that it caused massive lags in recent PSP firmwares. Because of that, at some point we moved the Resource files of Wagic in a folder called psp/wagic_res, which caused other types of troubles
- People who modded Wagic and made the game crash had no easy way to revert their changes and had to entirely reinstall the game

New since 0.17
In order to address all the issues above , we came up with a new folders structure:
Wagic now has access to 2 resource folders, the system folder, and the user folder.
On PSP and on Windows, the system folder is called Res, and the user folder is called User
on iOS (TODO)
On other platforms, these two folders are actually one single folder (On Android, for now these two folders are common, in /sdcard/Wagic/Res)

In addition to this dual folder system, Wagic now supports its resources to be zipped. In Wagic 0.17, the default resources for the game are found in the system folder (Res) and are called core_017.zip. We expect further versions of the game to keep a similar naming convention.

Both these 2 things (the dual folder and zip support) constitute the new Wagic folder structure. This system offers features and limitations that you will need to understand if you want to mod the game, add images, cards, etc...

Things mentioning the User and the System folders only apply to systems which use both these folders. Some systems such as Android only use one folder instead, in that case just ignore the comments comparing User and Res folder.

1. Zipping is not compulsory, and you can get back to the old system if you prefer
First of all, zipping is not compulsory, and basically Wagic is still compatible with the old "not zipped" file structure. If you were a user of Wagic 0.16 or older versions and want to "get back on your feet", you can do the following:
- unzip core_017.zip into the User folder (for systems where there is only one folder - see above - the User folder is actually the Res folder) , then delete core_017.zip
- that's it, you should basically feel at home now, except that for PSP and Windows you work in the User folder instead of the Res folder

However I do not recommend to do this as you will lose some of the benefits of the zip system (consistency of the install file so less risk of losing stuff, and Res/User separation allows you to quickly erase your mods if you want to get back to a vanilla install)

2. Priorities
- (for systems that have two folders) The User folder takes precedence over the System (Res) folder. This means that if you have two files with the same name (and full path) in the User folder and in the Res folder, the one from the User folder will be used. Additionally, Wagic will always save files and create new files in the User folder.
- Real files have priority over zipped files. If you have a file in a zip archive (ex: Res/core_017.zip/sets/primitives/mtg.txt) and the same file outside of a zip archive (ex: Res/sets/primitives/mtg.txt), the "real" file will be used by wagic instead of the zipped one.
- With the two rules above, the User folder always has precedence (for systems where there is a dual folder mechanism), and therefore if you have a file in a zip inside the User folder, it will take precedence over a real file in the Res folder
- zip files are read in alphabetical order, and the "greatest" file takes precedence. For example, if you have the same file in two zip archives, for example in the Res folder, (ex: Res/core_017.zip/sets/primitives/mtg.txt and Res/core_018.zip/sets/primitives/mtg.txt), the latest one will "win" (in my example, Res/core_018.zip/sets/primitives/mtg.txt).

Summary of priorities (highest priority on top)
User folder's real files
User folder's zipped files(reverse alphabetical order, e.g. b.zip has more priority than a.zip)
Res folder's real files
Res folder's zipped files (reverse alphabetical order, e.g. b.zip has more priority than a.zip)

Wagic always writes/saves content in the user folder

3. How to mod/add content to Wagic
The rule of thumb is that you should never add any content in the System (Res) folder, but always in the User folder (except for systems that have no "User" folder of course)

As explained in 1. you can extract all wagic's files from core_017.zip into the User folder, and start modding in there. I personally however recommend to only extract the files you want to mod, or even create new ones when it makes sense. For example if you want to add a set named "WOLOLO", just create a folder "sets/WOLOLO" in the User folder, and add your _cards.dat file in there.
If you want to add your set images, the same is true. technically you could add them to the System(Res) folder, but it is recommended to add them in the User folder.

3. Zip format
You can zip files as you want, create as many zip files as you want, and put whatever you want in them. This is very convenient for modders as you can create your mod, zip it, and tell users to just put the zip file in their "User" folder. There are only 2 rules:
- One very important thing is that the only supported zip format is "Store" (no compression). All zip utilities I know have this option, so be sure to use that. If you use a compressed zip in Wagic, the behavior is undocumented. Most likely the system won't find your files, but potentially the game could crash.
- Secondly, the insides of your zip files need to follow the Wagic folders structure (ex: if you want to add sets, your zip needs to contain a folder set, and then subfolders for each set...). It's difficult to explain, bu just by looking at core_017.zip you should grasp the idea

Historically Wagic supported zip files for images. As an exception, Wagic now supports zips inside zips (all of them need to use the "store" compression!) for images only. This is very convenient as you can now put all your images in one single file! Here's what it should look like:
Just one file: User/images.zip
inside, you will have a subfolder sets, then a subfolder for each set, and then the card images zip file. It looks like this:
Remember that all zip files should use the store compression method, even the zips inside the zip.

You can also have the following structure, which involves only one zip file, instead. This technique is NOT recommended on the PSP because it lacks Ram, and building the zip index for thousands of files would take time and space:
and so on...

I messed up my mods, and wagic stopped working, what do I do?
Assuming you did all your changes in the User folder and never touched the core_017.zip file, you can easily get back to a working version of Wagic by deleting your User folder. If you're on a system that doesn't have a User folder and/or changed some stuff in the Res folder, delete everything except the core zip file (core_017.zip). Always do a backup of your files somewhere before deleting them, you might then want to put them back progressively in order to get your achievements, decks, etc... back
Posts: 229
Joined: Thu Apr 29, 2010 4:13 pm

Re: [FAQ] Wagic's Folder structure - how to add cards, image

Post by mnguyen »

for the iOS port:
everything will reside in the Documents folder of the app accessible through iTunes. The folder structure will correspond with the "Res" vs "User" structure. Due to the nature of iOS, you can only supply files to the Documents folder. Thus, you can not add files to "Res" or "User" directly, nor modify them. The application will therefore handle zip files placed in the Documents folder and place them into the "User" and "Res" folders. All "core_" files will be placed into the "Res" folder, all other zip files will be put into the "User" folder.

At this time, there's no way to modify the files except to wipe out the Documents folder and restart the app/downloads. Unless of course if your iDevice is jailbroken and you have full access to the file system. But that is self explanatory.

If you have suggestions on how things can be done to make it a little easier to manage the files let me or the dev group know. I'm working on some things to improve the experience but input can always help. I'll probably add a mechanic that will automatically copy your collection.dat and deck*.txt from the Documents directory to the appropriate place in the User folder. That way you can be sure to have the latest versions of your decks/collection load. I'll do that later today and post an update to the build later as well.

Posts: 1
Joined: Sat Dec 31, 2011 5:08 pm

Re: [FAQ] Wagic's Folder structure - how to add cards, image

Post by tagus »

android version:
Using Sony Ericsson Xperia Play, rooted (if that matters), and using stock firmware. Not the PSP, but its close relative! :)

Installed the apk without any problem. At startup it starts downloading the file and at some point near the 100% mark the screen went black. Not sure if it was the screen lock or the app itself, but later things didn't work so well.
Whenever I started Wagic again the download progress bar was always visible with the language selection on the background.

The only way to get around it was to delete the application data on the app system details, and after that the progress bar finally went away.

Now for the user experience (attention: I didn't follow the other threads regarding this so I'll just mention whatever comes to mind)
On the options page sometimes the section title (settings, game, etc) remained selected (visually) after changing to another section.

On the key bindings section, I was unable to assign hardware keys: very hard and frustrating to use at the moment. If i pressed a line it would immediately scroll up or down and expect me to press a key even if the message "press a key..." wasn't visible. I ended up "up" on many of the options...

On the key part, it responds to up, down, left and right keys (even in the menus but that should be expected), but not to the playstation keys (cross, etc).. how great it would be if it did :)
note: the circle button usually does the same thing as the back button.

I'll get back after getting some time to play around with it.

By the way: love the zip file feature... now instead of thousands of files on the sdcard it will be only one!

Thanks for the effort. On a side note even though I am a developer I never worked on Android.
Posts: 30
Joined: Sun Jun 14, 2009 9:34 am

Re: [FAQ] Wagic's Folder structure - how to add cards, image

Post by belux »

Android Version
I'm also a Xperia Play owner, this is my considerations so far:
- the trophy room is not working correctly, it let me enter and see only the spoilerof the 10ED, it's impossible to enter the spoiler of the other sets, every time I try the response is simply moving the selection of the set among them (obviously I've unlocked them all);
- ok, no support for hardware key buttons, but don't despair! During play I suggest to reverse "left and right triggers", so that the swipe up would let you permit to see your hand, not to change the game phase, which can be done simply by pressing the game phase icon on the middle left of the screen. The swipe down it's the X button for the interructions. In this way is fully playable;
- in shop I don't know how to obatain new cards, alias the square button function;
- I can't do the story mode: whenever I try to enter in "where all it begins" the apps crashes and exits to android;
- the same when I lose a battle, the apps crashes and exits to android;
- Which is better for the ANDROID ram menagement system? (the xperia play is not very powerful)
a) only one huge zipped file with all the images inside;
b) a zip file for every set;
c) no zip, but the raw images;
which option do you suggest?

PSP version
- Mounting the images make the game very very slow 97% of times. Not playable.
Ok, I don't use cropped images, I don't like them! Again, Which is better for the PSP ram menagement system?
a) only one huge zipped file with all the images inside;
b) a zip file for every set;
c) no zip, but the raw images;
which option do you suggest?

Windows version
It's ok. No peculiar matters.

Thanks to you all and I've to say: great job guys!
Posts: 2
Joined: Thu Feb 24, 2011 6:47 pm

Re: [FAQ] Wagic's Folder structure - how to add cards, image

Post by dbax1969 »

I seem to be having problems displaying card images since the transition from Wagic v16 to Version 17.1. My zipped card sets are in the User folder but for some strange reason the images won't display in the shop or during a duel, etc. Any help in this matter would be appreciated greatly, as I have been playing since version 0.9.0 and love the game. I am playing on a PC using HQ scans 480x680 for cards and 200x285 for thumbnails. Just can't seem to figure this out.
Last edited by dbax1969 on Tue Mar 05, 2013 6:31 am, edited 1 time in total.
Site Admin
Posts: 3727
Joined: Wed Oct 15, 2008 12:42 am
Location: Japan

Re: [FAQ] Wagic's Folder structure - how to add cards, image

Post by wololo »

Unzip your sets, and rezip them using the "store" compression level
Posts: 2
Joined: Thu Feb 24, 2011 6:47 pm

Re: [FAQ] Wagic's Folder structure - how to add cards, image

Post by dbax1969 »

Dear Wololo,
Thank you for your quick response to my dilemma but alas I tried re-zipping 5ED with no compression and this set still did not display any images in the store. I think I'm just going to stay with Wagic v16 at this point since it makes no sense to go on. This is too bad because I'm dying to play with the Jester's Cap, one of my favorite cards from Ice Age. Maybe if I mess around with the SVN I can solve my problem. Thank you again. My deepest regards and admiration to you.

Update: I got the images to display once I set up a player profile! Hooray! Thanks a million, Wololo!!! :lol:
JuDicus MaXimus
Posts: 62
Joined: Sat Aug 06, 2011 8:18 am
Location: Northern Ireland

Re: [FAQ] Wagic's Folder structure - how to add cards, image

Post by JuDicus MaXimus »

I'm just a bit confused but want to get going, I'm using psp and when i install it theres no user folder just Res so do I unzip and add content to core_17? :?

Wait never mind I got it! :)
Posts: 15
Joined: Tue Nov 17, 2009 3:28 pm

Re: [FAQ] Wagic's Folder structure - how to add cards, image

Post by Pablohc86 »

i've just installed 0.171 version on my psp fat...
i have correctly imported all my data from 0.16 : decks, sets, statistic, options and credits to new user folder..
All less than image.. i have put my full image included in the zip in the folder with the sets..

when i start the game all works perfetcly.. but the system never charge image..
in 0.17 does image have changed format? i need to download the android version present on this forum?
reading here some user says that psp ram lack when try to load it.. so i know my psp is the first model, if there is the crop picture and works perfectly 4 me is not problem.
make me know where can i download the version for 0.17

i support wagic since long time and it's my favourite psp game :) i support the team also with a donation! i wanna this project grow up!!!
Site Admin
Posts: 3727
Joined: Wed Oct 15, 2008 12:42 am
Location: Japan

Re: [FAQ] Wagic's Folder structure - how to add cards, image

Post by wololo »

- make sure that your zips are using the "store" compression

Can you send me a screenshot of your folders to see what might be the problem?
Post Reply