User:Dcurd/ConfigXP

This tutorial covers converting an existing configurable avatar to using ConfigXP.

Prerequisites

 * 1) An avatar using the normal config method or decent knowledge of configurable avatar creation
 * 2) The ConfigXP files source files are located here: [[Media:ConfigXP.zip|ConfigXP]] and you can obtain the example avatar here: [[Media:FATConfigXP.zip|FATConfigXP]]. Extract the .as files to your whirled/examples/uravatar/src directory so that they will be accessible to any of your avatars.

Getting Started
If you learn well by example, make sure to check out the example avatar linked above.

Open up both the avatar you would like to convert and FATConfigXP.fla.

Transferring Symbols
On your avatar select the symbols pane and click the button to open a new library panel.

On this new library panel select FATConfigXP from the dropdown.

Drag the config folder from FATConfigXP's library to your library. When prompted by "One or more library items already exist" select "Don't replace existing items."

Your config folder should now have a new folder labeled ConfigXP that has all the new components inside. If you want to restyle these components, start with config/configXP/popup_master. This symbol contains all the symbols that are used in your config panel.

Grouping Scenes to MovieClips
All your scenes are needed to be placed in movieclips in main scene.

Don't forget to export them all for ActionScript, if you won't, your avatar will be invisible. You export them for ActionScript by going to advanced on the symbols properties or when your creating the new symbol press advanced then tick "Export for ActionScript".

Notice, that lower layer movieclips are higher in state list, that's why some of your states can trigger earlier than Default state.



Symbol name and class name must be same.

You can't use random states, because ":" is not supported.

After you finish converting scenes into movieclips you can go next step.

Editing the Config Panels
The symbol popup_master contains all the symbols you would need to edit to theme the config panel to fit your avatar.

All elements can be re-sized/re-colored/edited without problem so long as any instance names are preserved. All of the buttons have a common background symbol so re-coloring/re-shaping them should be painless :)

There are three symbols in popup_master that represent the three different panels that are displayed when the buttons at the top are pressed:
 * popup_config : This should be the same symbol you previously used in your config. You can optionally drag an instance of one of your avatars states/actions and give it the instance name "thumb". ConfigXP will automatically change the colors on this symbol to match the current config.
 * popup_save : This symbol controls saving/loading of config settings. This panel automatically grabbed your state_Default symbol which may need to be repositioned to properly fit within the saveslot box. You can put any symbol you like in place of state_Default so long as it retains the instance name of "thumb". ConfigXP will re-color this symbol for you based on your config settings.
 * popup_share : This symbol controls displaying and loading of share codes. There isn't anything that needs to be edited unless you want to re-style it.

Workaround a Flash Bug
There is a bug in Flash that will sometimes cause your config panel to fail to be created after idling in Whirled for a while. The exact reasons why haven't been pinpointed but you can prevent it by making sure there are no symbols that have "Export for Actionscript" set in the popup_master symbol. There should be only three places that have linked symbols:


 * 1) popup_config : If you are working with a previous config avatar, this symbol has its linkage properties set. Right click on the symbol in the library, select linkage, and uncheck the box that says "Export for Actionscript". Press OK.
 * 2) saveSlot : In the ConfigXP/saveSlot symbol is one of your avatars states or actions. This likely has linkage properties set. We cannot unset those properties since that will make the state or action stop working in your avatar. Instead right click on the "thumb" symbol inside saveslots and select "duplicate symbol". Give this new symbol a name and select OK. This makes a new copy that does not have linkage properties set.
 * 3) popup_config : If you are using an avatar preview here, it may have a linkage property set as well. You can either use the duplicate method like the previous step, or you can swap the symbol for the symbol you created in step 2.

OMG C0de
In your main scene replace any instance of ConfigBody with ConfigXPBody. There are likely only two places this needs to be done.

ConfigXP does not need you to edit any of the .as files (REJOICE! :D), instead you can supply all the information ConfigXP needs in your main scene.

Registering Config Options
You can register both color and image options through the registerOption function:

Color Config
_body.registerOption(optionName, optionType, default)
 * optionName is a string representing the name of the option and also the instance name of the color picker on popup_config
 * optionType can be ConfigXPBody.OPTION_COLOR_SKIN for skin color picker or ConfigXPBody.OPTION_COLOR_ALL for general color picker
 * default will be the default color used in hexadecimal

For example if the color picker on your popup_config had an instance name of "skin_color" you could do this: _body.registerOption("skin_color", ConfigXPBody.OPTION_COLOR_SKIN, 0xEB933B);

Image Config
_body.registerOption(optionName, optionType, default, options)
 * optionName is a string representing the name of the option and also the instance name of the dropdown on popup_config
 * optionType for image configs will always be ConfigXPBody.OPTION_DROPDOWN
 * default is a number representing which dropdown option is the default 1 would make the first option default, 3 would make the third, etc.
 * options is an array of the names of the different options

For example if the dropdown in your popup_config had an instance name of "hat_choice" you could do this: _body.registerOption("hat_choice", ConfigXPBody.OPTION_DROPDOWN, 1, [ "No Hat", "Baseball Cap", "Propeller Beanie" ]); In this example, No Hat would be the default

Setting Config Frames
Now we need to let ConfigXP know what symbols on our avatar to edit. This is similar, but more compact, then editing selectCurConfigFrames and applyCurConfigFilters in ConfigBody.as.

Setting Recolorable Frames
We need to tell ConfigXP where to apply the re-colors, we do that with: _body.setRecolorFrames(optionName, ...paths);
 * optionName is one of the color option names you registered earlier
 * paths is an array representing the instance name path to be the symbol to be re-colored. This is the same format as you used in applyCurConfigFilters if you used the old Config method. You can add as many paths as necessary by separating them with a comma.

Here is an example: _body.setRecolorFrames("skin_color",     [ "body", "skin", "color"],      ["leftArm", "skin", "color"],      ["rightArm", "skin", "color"]);

Remember, the instance names are not same as movieclip names! In the image below, the instance name is highlighted with yellow, the movieclip name is highlighted in red!



Displaying Dropdown Selections
Now we need to tell ConfigXP where to apply the dropdown selections, we do that with: _body.setImageConfigFrames(optionName, ...paths)
 * optionName is one of the dropdown options you registered earlier
 * paths is an array representing the instance name path to be the symbol to be re-colored. This is the same format as you used in selectCurConfigFrames if you used the old Config method. You can add as many paths as necessary by separating them with a comma.

Here is an example: _body.setImageConfigFrames("hat_choice", [ "head", "hatContainer", "hat" ]);

Finish Config
We need to let ConfigXP know when we are finished setting the options, do this by putting _body.completeConfig at the end. This is crucial as your config options won't be applied until you call this function.

Finished!
That's it :) Make sure to compile and test your avatar and pay attention to the output dialog. ConfigXP will try and find anything amiss and give error warnings in the cases of common mistakes (typos in option names, having an option name that doesn't match something in popup_config). Unlike config, ConfigXP will let you know about errors in the config panel without having to test it in Whirled :)

Attribution
If you use ConfigXP, attribute your listings to one of the following:
 * ConfigXP Base Coins
 * ConfigXP Base Bars
 * ConfigXP Backdrop Base (coins)
 * ConfigXP Backdrop Base (bars)
 * ConfigXP Furniture Base (coins)
 * ConfigXP Furniture Base (bars)
 * ConfigXP Toy Base (coins)
 * ConfigXP Toy Base (bars)

If you cannot attribute to ConfigXP due to using another base, or any other reason, please ask TheCosmicCheese for permission first before listing.