slimming down the distributable

[myk]

Ok, here's what I'm thinking for skins:

1. package format - I think a .zip file would be the best since it is easy for people to create and other parts of our code are packaged the same way (e.g. cardsfolder.zip)
   
   • skin.txt - a metadata file with the following fields:
     
     • display name
     • author name
     • skin description
     • others?
   • sprite_foils.png - card foil overlays
   • sprite_icons.png - interface image sprites
   • default_font.ttf - UI font
   • splash* - one random image that matches this filename pattern will be returned whenever the splash image is requested (from here on down, images can be in any format that ImageIO can load; they don't have to be .png)
   • texture* - one random image that matches this filename pattern will be returned whenever the texture image is requested
   • match* - images that match this pattern are analyzed when the skin is loaded and grouped by aspect ratio. one random image in the group whose aspect ratio most closely matches the current window aspect ratio will be returned whenever the match background image is requested.
   • preview* - all images that match this filename pattern will be returned when preview images are requested. these images are displayed on the UI when the user is selecting a skin to apply
   • (default skin only) sprite_avatars.png - avatars
   • in the future, we can also add in default layout files for certain skins (e.g. for a tablet-themed skin) and prompt to reset layouts to their new defaults when a skin is chosen if default layouts are defined for that skin. this would be a backward compatible change and will not affect existing skins
2. document skin location change and package format in CHANGES.txt (move to README.txt for the following release)
3. create packages for all current skins and upload them to the server; repackage default skin in new format and put it in the res/defaults directory
4. create list file and corresponding download button on Content Downloaders screen for skins (perhaps combine all downloaders into a single dialog - there are getting to be quite a few of these buttons, and soon the sounds downloader will join them); download skins to cacheDir/skins
5. users can also create or download "unofficial" skins and put them in userDir/skins and forge will load and use them
6. on preferences submenu, load skins in old format from old location and in new format from {cacheDir,userDir}/skins. if the same skin exists in multiple locations, the priority goes: userDir, cacheDir, old res/skins location. In each location, if a skin is expanded into a directory, it has priority over the same skin in its zip packaging.
7. when a skin is selected in the preferences submenu, display the metadata in a panel to the right. cycle through the found preview images while the skin is selected, perhaps zooming the image on mouse hover (if I can figure out how to do that)
8. restart still required to apply skin (I think changing this would be too much work, at least for now)
9. after the next release, remove res/skins directory and code related to the old skin package format. people will have a full release cycle to click the 'download skins' button and get the new skin packages. when they update to the following release, their skin selections will continue to work and no manual transition steps will be required. people who did not download the skins by that time will have their skin reverted to the default and a popup message will come up explaining that their chosen skin has disappeared and instructs how to download skins.

Did I miss anything? Overall, I expect this to be a relatively localized and low-impact change to the codebase. In particular, it shouldn't affect anything close to what Max is currently working on with the input subsystem.

[Chris H.]

I am considering keeping the user data instructions in the CHANGES.txt file for a few betas. I doubt that everyone updates on a regular basis and there may be a number of people who only update once every month or two.

We can add in additional info to this section as the skins and sounds get moved to the cardforge site.

[myk]

That's absolutely fine too -- we can delay step 9 for as long as is appropriate.

[myk]

How long should we wait for SVN users to get their data migrated before we clean up pics_product and the old user data directories?

a week or two?

I'll go ahead and remove the old user data directories from svn on Tuesday, 26 March. Everyone who is updating via svn: please migrate your data out of the following directories by that date or your svn client will unceremoniously delete it all:

• res/decks/
• res/gauntlet/
• res/layouts/
• res/pics/
• res/pics_product/
• res/preferences/
• res/quest/data/

After migration, all these folders will be empty of user data (pics_product will have old copies, but nothing to worry about). To migrate, update your code from svn, build, and run. The migration dialog will fire up and help you from there. If it is already past the 26th, copy your data to another directory before you update, then use the Import Data dialog to re-import it from where ever you copied it to.
This warning and procedure is only for those who update via SVN. If you install releases or snapshots downloaded from cardforge.org, there is nothing you need to do. The automatic migration process will walk you through all steps you need to take when you upgrade, no matter what the date.

Old directories are now removed. SVN updaters: heed the quote!

[moomarc]

That's absolutely fine too -- we can delay step 9 for as long as is appropriate.

I'm not sure whether it's necessary to hold off on step 9 seeing as it falls back to the default skin anyway and will have instructions on how to get the other skins again.

As for the metadata, perhaps a tag for Contributers? Quite often I'll use icons from other skins and I would just add the original artist under this tag. But then again, maybe it would just be easier to add a 'thank you' line to the end of the skin description.

The rest of the implementation looks perfect! Looking forward to it, and hopefully the lure of easily sharing skins with others will make some more users contribute some themes.

[myk]

As for the metadata, perhaps a tag for Contributers? Quite often I'll use icons from other skins and I would just add the original artist under this tag. But then again, maybe it would just be easier to add a 'thank you' line to the end of the skin description.

Unless this is really common, I'd think just tacking on some thank you text to the description would suffice. We can always add this field later, too, if we do find it is useful.

and hopefully the lure of easily sharing skins with others will make some more users contribute some themes.

This reminded me that themes that are downloaded outside of the in-program downloader should not go in with the "official" skins. I updated the plan to allow for unofficial skins in userDir/skins. This directory can also be used for in-progress skins. I can keep the code that reads files from directories as well as add the new zip file reader so skins can be tested and changed without having to re-zip them every time.

[moomarc]

One more thing to consider if you haven't already is that the new code should still allow the default icons to be used when a skin's sprite sheet has a blank (I think there's an exception to this for the colour swatches so that certain elements can have 100% transparency).

[myk]

absolutely -- all current fallback behavior will be preserved. Btw, should I list you as the author for the current skins? Also, could you perhaps write a one-line (or whatever) description for each of the current skins?

You just gave me another idea, though. I remember a short discussion a while ago about a theme needing a different background image for monitors with different aspect ratios. Would it be convenient to have the fallback theme defined in skin.txt? For example, a theme can reuse sprites from another theme, and just provide new background images. There would always be an implicit fallback to the default theme if a fallback theme is not defined or the defined one is not found.

[moomarc]

absolutely -- all current fallback behavior will be preserved. Btw, should I list you as the author for the current skins? Also, could you perhaps write a one-line (or whatever) description for each of the current skins?

You just gave me another idea, though. I remember a short discussion a while ago about a theme needing a different background image for monitors with different aspect ratios. Would it be convenient to have the fallback theme defined in skin.txt? For example, a theme can reuse sprites from another theme, and just provide new background images. There would always be an implicit fallback to the default theme if a fallback theme is not defined or the defined one is not found.

I did the default, Dark Ascension, Simpsons and Rebel themes; WompWomp made the Firebloom theme; and DoubleStrike designed the Marble Blue and Smith skins. I'll write descriptions for mine and send Doublestrike and Womp Womp a PM asking them to write something for their's. If there's no response from them I'll just draft something for them.

For the aspect ratio, I think your suggestion sounds good, and it has the advantage of allowing users to make some small tweaks easily by pointing to other skins. If resolution can be detected from within a java app, an alternate solution is to have an optional field that lets you stipulate a second background image that would be used, depending on whether your screen resolution is closer to 16:9 or 4:3. So you might have the following in skin.txt:

Code: Select all

background(default):background.jpg
background(wide):background2.jpg

The advantage of this method is that the user doesn't need to do anything extra and the skin can be packaged as one download. It also allows (at some later date) listing a few background images that could rotate between matches:

Code: Select all

background(default):background.jpg,bg2.jpg,my_extra_bg.jpg

[myk]

I think your idea has more potential for usefulness. When I started going through the use cases, I found non-default fallbacks fraught with fragility (e.g. a missing parent theme would severely impact the display. what is expected behavior when multiple background images are defined in both child and parent themes? additive vs. overwrite. etc. messy messy).

I don't know if I can get full screen resolution, but I can get window size, which is likely more relevant anyway. I can probably get away with not being explicit about which pictures are default and which are wide, though. All background images (bg_match*) will be loaded and analyzed when the skin is loaded, and when a background is requested, one can be chosen at random from the ones which are closest in aspect ratio to the current window size. If we have this, do we /need/ explicit lines in skin.txt? We can always add optional directives to skin.txt later, but do you think this would suffice as a default behavior?

Do you happen to know why bg_match and bg_texture are .jpg files but bg_splash is .png? I can see why the sprites are required to be .png, but do the others matter? Can I make the code just match basenames and not care about file extensions?

[moomarc]

I suspect that bg_splash was originally a png to allow transparency in the color swatches similar to how the swatches are treated in the main sprite sheet. I don't think the alpha reading was ever implemented though and I can't see any reason to use a png otherwise.

And your implementation sounds perfect. Might even allow for adding other non-standard resolutions for those that want it without having to add extra code.

[myk]

In working with FSkin, I've noticed that the way we load avatars might not be compatible with the way they are used. Currently, every avatar gets a numeric index, starting at 0. If a skin defines avatars, they are added to the avatars list first, then the avatars from the default skin are added. Each opponent stores an index to the avatar that should be displayed. Are these stored avatar indices expected to resolve to a particular avatar? If not, there isn't really a problem. If they are expected to resolve consistently, however, there are a few things we can potentially do:

1. load default avatars first and skin avatars second. this makes the skin avatars only useful for the Human avatar, though, since they will never be used by AI decks (unless we start randomizing avatar selection instead of deterministically assigning them)
2. don't allow skins to define new avatars. currently only the simpsons skin defines new avatars.
3. keep as it is and let avatar choices be shifted when the current skin defines avatars

Thoughts?

[friarsol]

myk, is all-prices supposed to be in the svn still? I see it's in the profile now, but it's also still in res/quest/

[moomarc]

I thought we were already applying random AI avatars in constructed since multiplayer modes were introduced, and that the ai avatar selection just wasn't removed. I guess I wasn't paying enough attention. Regardless, I think that the skin specific avatars can be removed. I was the only one who had an interest in it originally anyway and I haven't felt the need to use it again since making the Simpsons skin.

[myk]

myk, is all-prices supposed to be in the svn still? I see it's in the profile now, but it's also still in res/quest/

I hadn't gotten around to ensuring our code worked if that file was missing and the cacheDir one hadn't been downloaded yet. I just checked, though, and everything works fine. File deleted.

I thought we were already applying random AI avatars in constructed since multiplayer modes were introduced, and that the ai avatar selection just wasn't removed. I guess I wasn't paying enough attention.

No, you're right -- I just hadn't followed the code path far enough back. a random choice is being selected for the AI. The avatar shifting would only happen for the human player.

Regardless, I think that the skin specific avatars can be removed. I was the only one who had an interest in it originally anyway and I haven't felt the need to use it again since making the Simpsons skin.

Yeah, even with the randomization, I still agree -- there just isn't enough opportunity to /use/ skin-specific avatars to make it worth the effort.

one more question too: can grid_icons.png be deleted? I see no reference to it in the code. What use was intended for it/did it once have?