FLASHWORLD II
Designed and Developed by David Millington aka Tann San 2004
Flash 3D Matrix Code written by Chad Corbin and taken from
http://www.macromedia.com/devnet/mx/flash/articles/flash_3d.html

-------------------------------------------------------------------

Initial public release 11/06/2004

FlashWorld II is a level developer for HomeWorld II.  It is solely written in Flash MX.
At this time it is still very much under production.  This first release is what I call a "rush release".
I planned the first release to be a fully functional application however I've taken on
some more paid work which takes precedence over any free projects I'm working on.
If the new project goes well then I should be able to continue two weeks after the initial release date.
I've decided to release it in it's current form so that I may receive suggestions for improvement in the meantime.
I will try and keep an eye on the relic forums thread.  This is being released under the LGPL and as such you 
should have a read of the notice and license files included with this document.  :)

-------------------------------------------------------------------

FEATURES
Flash MX based
3D development environment
Keyboard keys can be modified via the flashworld2.xml file
Uses Flash Shared Objects for data storage
Open for future usage of mods for example you can enter any name for a unit type so you can use custom units.

-------------------------------------------------------------------

USAGE
Load hw2.swf into a browser window or the flash player to view and use the system.  I've included an index.php file that 
I use for testing purposes here.  Instructions on usage on can be seen via the help panel.  Heres the default key list:

Numpad End - Tile Scene Left
Numpad PgDn - Tilt Scene Right
Numpad Left - Rotate Scene Left
Numpad Right - Rotate Scene Right
Numpad Up - Rotate Scene Up
Numpad Down - Rotate Scene Down
Numpad 4 - Move Crosshair on x axis
Numpad 6 - Move Crosshair on x axis
Numpad 8 - Move Crosshair on y axis
Numpad 2 - Move Crosshair on y axis
Numpad 1 - Move Crosshair on z axis
Numpad 3 - Move Crosshair on z axis	
Numpad 5 - Create Object

These can be configured via the supplied xml file.  The idea with the default set is that you use the num pad.
You can then easily switch between cross hair movement and scene rotation by toggling the num lock on and off. 
I set it up so you can enter your own keys via the xml doc as I understand that some keyboards either don't 
have a num pad or they are just a pain to use.

-------------------------------------------------------------------

FAQ

How do I change the type of object to be placed?
Hold the mouse button down on the "New Type" combo box.  It will expand to show you all the available objects you can place. 
Select one by dragging the mouse down to it.  You can then place objects of that type within the level.

How do I add an object to the level?
Move the crosshairs to the desired location for the new object then press numpad 5 to place it.  Numpad 5 is the default key, 
you should use whatever you have set as the create key.  You should now see a new object in the level.

How do I edit an objects properties?
If you have the xml config "Set new as selected" turned on then when you place a new object it will automatically become 
the selected object.  The editor panel will enable and disable properties depending on what each object can do.  To alter 
a different object left click on it.

How do I delete an object?
hehe..well you cant for now.  That's quite high on the list of things todo, sorry about that :)

How do I change the color for objects such as Nebula?
Click the color button to open the color mixer panel.  You can change the red, blue, green and alpha values using the sliders 
or by typing the value in the text box next to each slider.  When your done click accept to update the value.  If you just 
want to close the color mixer without setting the value click the X button in the top right.

Why doesnt the color change on the accept button when using the color mixer?
Thats probably because you havent turned the alpha value up.  This is 0 as default.

How come I can see an object that is behind another one as if it was in front of it?
Well that's probably due to the depth sorting function.  I havent touched this section, its straight from Chads demo.  
He acknowledges that it isnt perfect and gives excellent reasons why.  He does say you can write your own improved 
version although I dont really see the need.

I made one or more objects inside an other object such as a dust cloud and cannot select them, what should I do?
Well I was going to build a tick box option to make things clickable and unclickable but I decided it was to much trouble for now.  
I have had to do this myself a few times and the easiest way is to simply move the surrounding object, alter the one inside and then 
move the outer object back to where it was.  You only have to remember a single positional value to do this quickly and easily.  
I might just leave this as the solution.

Whats the deal with the interactive tick box?
Theres two highly important areas of a level file.  

DetermChunk() - interactive ticked
This is for things the player can interact with such as salvage.

NonDetermChunk() - interactive cleared
This is for things the player can't interact with such as pebbles.

Theres a thread in the Tanis Shipyards where someone (tell me who you are and where it was!) said you could place almost 
anything in either function.  Having not tried this out I dont know how if this will work with everything.  I thought 
about building a warning window that will warn the user of things that are potentially ticked incorrectly.

How do I add more object types to fw2?
This is now a fairly straightforward process.  Two steps are involved to setup your own objects.

Step 1
Add a new object type to the file "flashworld.xml".  If you take a look you will see that I have commented the Asteroid object to show what each element does.
The rest of the options mostly explain themselves.  I will write a list of what property does what for easy reference later on.

Step 2
In Flash, open the Level Output movie clip.  View the actionscript in keyframe 1.  You will see a big switch statement with the 
output format lines for each object.  All you have to do now is add your own case statement using your new objects properties.

It should be noted that further modifications will be required if you wish to add your own properties.

How do I add my own custom properties to an object?
If you are planning on using your custom property with your own object then you should read the above passage first.
The first step to adding your own property is to add it to the xml file for the relevant object(s).  Next open fw2 in Flash.
View the AS in keyframe 1 of the main movie.  Look in the readObjects() function.  You need to add a new case statement that will 
pass your new property to the new object type within flash.  Its really just a copy and paste job with a bit of rewriting.  Next 
you need to edit the output string via the AS in the Level Output movie.

The last step really depends on what your doing.  If it's a property that is either permanantly on or permanantly off depending on what 
type the object is then you can probably just set the variable in xml and that's enough.  If its a property you wish to configure 
on a per-object basis via the fw2 interface then you will have to add your own interface component and link it up.  This really becomes 
more of an addition or modification of fw2.

If you require assistance with this final stage then request it via the Tanis Shipyard Flashworld II thread or PM me there.

-------------------------------------------------------------------

TODO
Add some more items to the new type menu such as points
Clean up source
Remove most library items - I prefer to generate everything via AS normally so I'll swap everything over later, as I said "rush release" :)
Set the customisation features up - Going to add a new section to the xml file so you can change details of the user interface such as color scheme, panel placement, object defaults
Get permission and link in some of Mikails map functions ;) pretty please
Sort out the memory problem - yes you heard me right, the memory problem!  I'll explain this a little later on.
2D Glyphs instead of boxes, probably as an option
Delete Object
Use XML attributes instead of nodes, its faster that way.
Switch all color options to use the color panel that opens for object color.

-------------------------------------------------------------------

I was hoping that by distributing the Flash source code other people may be able to help expand the project.  Taking suggestions is
fine but I'm only one person so implementing everything everybody wants might take a while.  If some devs want to tackle a particular
problem then they should indicate in the forum that they are doing so otherwise several people may be doing the same thing.  Below is
a list of areas I'm going to work on, starting with my system spec:

Athlon XP 1800+
512MB Memory
Gainwood Geforce 4 MX 440 - NVIDIA ForceWare 61.11 drivers
Windows XP Pro SP1
Flash MX
IE 6
Flash Player 7

THE EVIL MEMORY PROBLEM
I dont know if you noticed that under features I added Shared Objects.  For those that dont know these are a type of Flash cookie.
Throughout development I've been using 50 test objects.  So my method of memory testing is this:

Close all Internet Explorer windows.
Load a new one up.
View FW2 in it.
CTRL-ALT-DEL and summon task manager.
Locate the IE window process. - on my system this is about 23MB to start off.
As you add objects to the scene you will see the amount of memory used slowly increase.
This varies from 100-250k depending on what version of FW2 your using.
So as you can imagine 50 objects comes to around 12-13 meg.

So whats the deal with the Shared Objects?
Well I'm glad you asked that, in one of my attempts to lower the memory usage 
I started storing all the object data into a single Shared Object (SO).  It didnt help 
in the end but I left it setup like this for future extensions.  FW2 isnt really meant for online usage, 
at one point I was going to run it as a web page but I decided against it as it's up to each person 
on how they want to use it.  So at some future point I might use the SO for more than object data, otherwise 
I'll remove the code relating to it.

So do you even know what's causing the memory usage?
Another very good question :) I think I've tracked it down mostly.  I think it's to do with how Flash
renders the objects.  I thought all the alpha effects might be taking up a lot of mem but even turned off 
it didn't help.  I really believe it's just Flash struggling to render all the objects.  You'll notice that 
the objects all disappear except the one you have selected.  That is so that you can rotate etc without 
suffering the same slowdown you would if everything was visible.  Either edit it and see for yourself 
or just take my word for it.

In trying to reduce the amount of memory each object uses I stumbled across a curious thing with Flash. 
I linked the delete object button to delete all scene objects.  Now you would expect the memory used to drop 
back to 23mb (my initial IE mem size).  Well it doesnt.  I spent quite a while looking for people with similar 
problems.  The closest I came to finding anything was a thread about Flash and XML.  Someone said that 
even when they cleared some huge amount of XML from their flash movie it still used the same (large) amount 
of memory.  The explanation for this was that Flash keeps the memory allocated to it and only frees 
it when its built in garbage collection is activated.  The explanation also went on to say something like this:

load IE - 23mb
load massive xml doc - 50mb
clear massive xml doc - 50mb
load an xml doc half the size of massive one - 50mb
clear that one as well - 50mb
now load stonkingly huge xml doc - 60mb

the mem sizes are total used and not individual.  The point is that flash keeps hold of the memory and reuses it. 
So that sounds good right.  Now it sounds like we:

create 50 objects, memory increases to 34mb.
Delete 50 objects, memory sticks at 34mb.
Create 10 objects, memory sticks at 34mb.

Now that last stage is where it gets a little odd.  In my tests it only took something like 2-4 objects before the 
memory started increasing beyond 34mb.

So to sum up what I want to do with the memory issue:

reduce the size of each object
free up memory after object deletion

MAP FUNCTIONS
I've been using the Karos Graveyard HW2 Wiki:

http://hw2.tproc.org/wiki/ScopeLevel

as well as peeking in some .level files.  The wiki is somewhat incomplete and some function arguments are 
not described.  It would be cool if someone could fill in the blanks.  You'll see that in the level output window 
some functions have ??? as args.  Those are areas where there is no explanation.
