User:Dcurd/ConfigXPEntities

This tutorial covers using ConfigXP to create a configurable toy, furni, or backdrop using Flash CS3.

Requirements

 * 1) A toy, furniture, or backdrop that only exists in one scene.
 * 2) The ConfigXP files source files located here: [[Media:ConfigXP.zip|ConfigXP]] and you can obtain the example backdrop here: [[Media:ConfigXP Backdrop.zip‎ |ConfigXP Backdrop]].

Getting Started
Create a symbol with the name of "thumb". This symbol will be used by ConfigXP to show a snapshot of what your item looks like with certain configurations applied. For simpler items, you can place the contents of the stage into the thumb symbol. For more complicated items if performance is an issue you could create a non-animated simpler version of the item inside the thumb for configuring.

Transferring Symbols
Open up both your items file and the ConfigXP Backdrop.fla example file.

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

On this new library panel select ConfigXP Backdrop from the dropdown.

Drag the config folder from ConfigXP Backdrop 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.

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 symbol will require the most editing as you will need to populate the panel with your configuration options.
 * popup_save : This symbol controls saving/loading of config settings. This panel automatically grabbed your thumb symbol which may need to be repositioned and resized to properly fit within the saveslot box. 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.

Editing popup_config
Unless your item was previously a config item, this panel should have all the options from the backdrop example, unless your item has the exact same options as the backdrop (unlikely :P), you will need to add or remove dropdowns and change the instance names to match what configurable options there are (TODO: Rewrite this section so it would make sense to someone who hasn't created a config panel before)

OMG C0de
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.

In your main scene, your code will be different based on what type of item you are creating.

Backdrop: import com.whirled.BackdropControl;

var _ctrl:BackdropControl = new BackdropControl(this);

Furniture: import com.whirled.FurniControl;

var _ctrl:FurniControl = new FurniControl(this);

Toy: import com.whirled.ToyControl;

var _ctrl:ToyControl = new ToyControl(this);

After that, the code is the same regardless of what type of item you are creating.

First lets create our config class: var config:ConfigXPEntity = new ConfigXPEntity(_ctrl, this);

Now we just need to use config to register our color options, dropdown options, and tell config where those options are on the stage :)

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

Color Config
config.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: config.registerOption("skin_color", ConfigXPBody.OPTION_COLOR_SKIN, 0xEB933B);

Image Config
config.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: config.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: config.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: config.setRecolorFrames("skin_color",     [ "body", "skin", "color"],      ["leftArm", "skin", "color"],      ["rightArm", "skin", "color"]);

Displaying Dropdown Selections
Now we need to tell ConfigXP where to apply the dropdown selections, we do that with:

config.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: config.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 config.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.