== medFlag210 ============
== a mutator by ==========
==========================
 _   _       _
| | | | ___ | | ___ _ __  
| |_| |/ _ \| |/ _ \ '_ \ 
|  _  |  __/| |  __/ | | |
|_| |_|\___||_|\___|_| |_|
                          
==========================
== Version 210 ===========
== www.birdieman.com/forum
== 2010.07 ===============


==========================
	| About |
==========================

This mutator lets you put flags into maps, with textures
of your making, without having to recompile the map.


=================================
	| Requirements |
=================================

You are going to need an image editor, like photoshop, or paint shop pro, or something.
It doesn't have to be a fancy version. I for example use Paint Shop Pro 5, which is a 
very old version. I'm sure there's something out there that's free these days that would
do just a good a job.

You will also need a local install of UnrealTournament on your computer. This is because
you need to use some UT tools to set stuff up before you host this mutator on your server.
AND, it is important that the version of your local UT install is 436, and not higher.
This is because higher versions screw up the UnrealEd.

If you don't know how to navigate with the mouse in UnrealEd, you need to learn. I have
provided a link to a tutorial further down to help you with this.


=================================
	| Prep |
=================================

This is where the files go, whether you are putting it on your server, or if you are 
testing it locally on your machine (which you are going to do, right? Of course!)

Put these 3 files into your UnrealTournament/System directory:
	medFlag210.int
	medFlag210.u
	medFlag.ini

Put this file into your UnrealTournament/Textures directory:
	myFlags.utx


====================================
	| Making a Flag |
====================================

Open your image editor.
I have provided two flag template files, called JpflagBTEMPLATEBLANK.pcx and
JpflagRTEMPLATEBLANK.pcx. One is red and one is blue.

Open the JpflagBTEMPLATEBLANK.pcx in your editor.
Immediately do a Save As... because you don't wan't to screw up this template.
I will do a Save As....  myBlue1.pcx for reference.

RULE1 - the size of a UT pcx file must be a multiple of 2. The size of our templates
is 256 x 256, so do not change their size. This is the original size of the texture
when I exported it from UT.

RULE2 - The amount of colors must 256 or less.

-- Rule 2 kind of blows because you can't get a real smoking image in there, but we can
-- do not too bad. Just follow these steps.

In your editor, increase the color depth of myBlue1 to 16 million colors.
Ok now you are ready to paste in some picture. Obviously the size of your picture
should be such that it fits into the the blue square bit of myBlue1. This area is
roughly 210 pixels wide and 140 pixels tall. 

-- The amount of blue you take up is up to you. It depends on what you want to paste in too.
-- If I have a nice small or medium image, I like leaving about 15 pixels of blue around the
-- edges, because they have those wrinkles, which makes the flag look more real. Or if I have
-- a bigger image, it is more important to me to get as much of the image in as possible, so
-- I go right to the edge of the blue.
-- But there is no point in going BEYOND the blue, because it just won't be shown.

-- Also I don't think the TYPE of image matters, what I mean is you don't have to paste a .pcx 
-- into your myBlue1.pcx. I have always pasted in .jpg images with no problem. 

Once you have your image ready, paste it in. If you don't like the result, try pressing CTRL + Z,
it might reverse it for you. Anyway, play around until you get it how you want.

When you are happy with how it looks, you now need to DECREASE the amount of colors in myBlue.pcx
back down to 256. 

-- Be prepared to be a LITTLE disappointed  :-)

Decreasing colors is a little more involved. It is just a matter of choosing the method that retains
as much of your image as possible. Ok, when I tell my editor I now want to decrease my color depth
back to 256, it is showing me some options. The options I choose are:
	- Optimized Octree
	- Nearest Color
You may or may not have similar choices. Just trying choosing different ones until you find the choices
that do the LEAST amount of visual change to your image (obviously).

Save your myBlue1.pcx. It is now ready to put into a texture file.


=============================================================
	| importing your flags into a texture file |
=============================================================

Find the myFlags.utx I supplied in the package. Copy that file into your UnrealTournament/Textures
directory. Now open up UnrealEd. (This should be at UnrealTournament/System/UnrealEd.exe).
Once that is started, you need to open the Texture Browser. Hover over the icons in the toolbar until
you find the one with the tooltip that says "Texture Browser". Click this.

Now in the texture browser window, click File | Open.
Find the myFlags.utx and open it.
Now again in the texture browse window, select File | Import...
Find where you saved myBlue1.pcx, select it and open it.

You are now looking at a dialog where it has these three fields and values:
Package: myFlags
Group:	 Flag
Name:	 myBlue1

Leave Package and Group alone. Also leave the checkboxes alone. The one thing we can change is the Name.

-- Note, after I enter a name, UT tends to make it uppercase on me, so now I just enter them as uppercase.
-- (hey, if that's what UT wants, fine).
-- ALSO, not mandatory, but a lot of texture names have eight letters or less, so that is another informal
-- rule I follow.

Chose a name that describes your flag. For this example I'll use "COOL" (without the quotes).
Click Ok on the dialog.
There! Now it's in the texture package. Last thing is to save the package. Make sure to use the save button
that is on the Texture Browser window.
Now, when you hit Save, it kind of treats it as a "Save As..." which is weird. So what you do is...
- click the Save button.
- It then opens a file dialog, as if you wanted to save it under a different name, but you don't, so just...
- click the save button on the file dialog
- It then says "myFlags.utx already exists, do you want to replace it?". Click Yes.

(You are done, but don't close UnrealEd yet)


==============================================
	| determining flag positions |
==============================================

The next task is to find out WHERE we want the flags to appear in maps. So pick a map that you want a flag 
to appear in. For this example, I will use DM-Agony. 
From the main menu, select File | Open, navigate to DM-Agony, and open it.

-- !! NOTE !! Never ever press SAVE when you have this map open. Do NOT save any changes to the map!
-- Our actions will be to find locations only, we do NOT need to save these changes to the map!

Ok now we need to open the Actor Class Browser. You can do this by going to the main menu and selecting
View | Actor Class Browser.

Now from the menu on the Actor Class browse, select File | Open Package.
Find the medFlag210.u (which you should have put in your UnrealTournament/System folder) and open it.
Now in the tree, expand the Actor node, then expand the Decoration node, then scroll down a bit until you
find something called medFlagDecoration. Click this once so that it is highlighted.

-- Now you need to navigate in the map to a spot where you want to add a flag. If you do not know how to 
-- use the mouse to move around the map in UnrealEd, that is a whole tutorial itself. In the files I have
-- provided is a UnrealEdMouseControl.htm, open this up and learn how to move around the map! P.S. I got
-- this file from here: http://wiki.beyondunreal.com/Legacy:Mouse_Control#Mouse_control
-- so if that link is still up, use that instead.

So now you are at a spot in the map where you want to add a flag. Right-click on the spot. One of the choices
should be "Add medFlagDecoration here". Click on that choice.

-- At this point you see the flag. It always gets added too low, so here is my next automatic step:

Click once on the flag that has been added.
Now right-click on the flag, the first choice should be "medFlagDecoration properties", choose that one.
In the properties window, expand the Movement node, then expand the Location node.
For the Z value, add 60 to the current value, and press Enter.
	Examples: If the current value is 16, then the new value should be 76.
		  If the current value is -240 (yes negative), then the new value should be -180.

-- Now the flag has a good up/down value (actually a perfect value). It might look like it is a little out of the
-- ground but in fact it is not. In fact it cannot be too deep into the ground or the entire thing won't be drawn.

Now you can tweak its position more. If you want to move it left/right, tweak the X value. 
If you want to move it forwards/backwards, tweak the Y value.

Now you may want to change the direction the flag is facing. So still under the Movement node, find the Rotation
node and expand it. We are going to play with the Yaw value. Here are the basic values you can try that will
make it spin 90 degrees at a time.
	 0
	 16000
	 32000
	-16000
You can of course enter values in between these numbers, these are just suggestions.

When you are happy with where it is, write down what the values are for X, Y, Z, and Yaw.

(we are done with unrealEd, but you can leave it open if you want. Just DON'T save the map).


================================================
	| setting up medFlag.ini |
================================================

Open up medFlag.ini that was provided. Find these 2 lines:

mTex[0]=myFlags.Flag.COOL
mTex[1]=myFlags.Flag.MFM

This is where you list all the textures you have available. Right now you have 2 available in your texture
package, so we have two listings here. Later if you want to add more textures to the texture package, you
can add up to 256.

Notice that the name of the first texture is COOL. If that is not what you named yours, then update this line.

Ok now we are going to enter a line that indicates what map to put a flag in, and WHERE. So now we are going 
to use the x, y, z, and yaw you wrote down. As I was doing this readme, I was doing the steps as well, so here
is what my line would look like for that flag we added to DM-Agony. (even though this particular position is dumb).

mMap[0]=DM-Agony,x=-672,y=260,z=-180,yaw=-16000

Just a few notes about this line.
- The map name must always be first.
- Anything else in the line can be in any order.
- The values for x, y, and z are REQUIRED
- yaw is NOT required.
- A value of ZERO is invalid for x, y, and z. (Just use 1 instead).

- You can have up to 256 of these lines.
- you can specify the same map more than once, this allows you to have more than one flag in the same map.


================================================
	| assigning a texture to a flag |
================================================

So now the mutator know what textures to use, and what maps and where to put the flag. So what textures get put
on what flag? Let's look at one of the settings in the ini:

mRotate=true

Setting this to true is the easy way to do it. This means that whenever the mutator has stuck in a flag at the 
position you want, it will then cycle through the available textures and always use the next one. And related
to this is this setting

mRandomRotation=false

If this is true, the mutator will randomly choose one of your textures, instead of cycling through them in order.

Ok, maybe you don't want to rotate the textures. First you need this of course:

mRotate=false

But you are also going to have to indicate what texture needs to go on what flag. Here's how. On the mMap line,
we are going to add an "index" setting, like this for example:

mMap[0]=DM-Agony,x=-672,y=260,z=-180,yaw=-16000,index=0

So at the end we have specified index=0. This means it will use the texture in the mTex list at the zero index.
So in this case that would be the myFlags.Flag.COOL texture.

If you have mRotate=false, and you do not specify an index, it will default to zero.


You can combine the use of mRotate and index. Let's say you are ok with most of the textures being rotated. But
for one or two flags, you want them to always use a particular texture. So what you do is:
- have mRotate=true
- for most mMap lines, don't specify an index
- for the few lines where you want to "pin" a texture to a flag all the time, just specify an index.


a final setting to do with rotating the textures. If you are pinning certain textures to certain maps/flag positions,
then it may be that you don't want this texture to be included in the rotation. For example you might have a texture
that has the name of a map, so you sure wouldn't that to be rotated in other maps. So you tell the texture that it is
"pinned". This will exclude it from the rotation. Here are our current 2 texture lines, and in this example we tell
the COOL texture to be excluded from the rotation.

mTex[0]=myFlags.Flag.COOL,pin=true
mTex[1]=myFlags.Flag.MFM


Finally let's look at the remaining settings.

mHideFlagIfSkinFailsToLoad=true

	Rarely, the mutator fails to load the texture for the flag. This means you are left with the flag, but it has
	the normal CTF texture. By setting this to true, the flag will be hidden too if the texture fails to load.
NOTE: 	When you are first setting up this mutator, maybe set this to false. Then you can at least see if the flag is
	appearing. The texture may not be loading because you misspelled something. When you have it running good,
	set this to false.

mShowInCTF=false

	Do you want your flags to show up in a CTF game?

mLogInfo=false
mLogErrors=false

	If these are true, they spit out a lot of information to the log. I would set these to true when you are first
	setting up, to help you with any issues. Once you are running good, set these to false.

mNextRotateIndex=0

	This is more for the mutator's use than your use. This is how it keeps track of what texture it is supposed
	to load when you have mRotate=true. But, if you have a lot of textures, and you really want it to start 
	further down the texture list, feel free to specify the texture index.


================================================
	| running it on the server |
================================================

Ready to test? Test locally first!

You already know where to put the files.
Open your UnrealTournament.ini and add these lines to the [Engine.GameEngine] section:

ServerPackages=myFlags
ServerPackages=medFlag210

(The myFlags is the name of the texture file. Yes, you must add this so it gets sent to the client).


==========================================================
	| adding more textures at a later time |
==========================================================

- IMPORTANT - 
You probably know this but I'll reiterate. Once you have uploaded a file to your server, then you can't make changes
to it and upload it again. This causes version mismatches. So if you want to add more textures to myFlags.utx, just
make a copy of it so it has a new name, like myFlagsII.utx

Then in the medFlag.ini, you just change the reference path in the mTex lines, so these:

mTex[0]=myFlags.Flag.COOL
mTex[1]=myFlags.Flag.MFM

might become these:

mTex[0]=myFlagsII.Flag.COOL
mTex[1]=myFlagsII.Flag.MFM
mTex[2]=myFlagsII.Flag.NEWPIC


==========================================================
	| just a couple more things you can set |
==========================================================

Here, for example, are ALL the settings you can specify for a flag position:

mMap[0]=DM-Agony,x=-672,y=260,z=-180,pitch=4000,roll=2000,yaw=-16000,index=0,unlit=true

So here are the items I haven't covered yet.
"pitch" and "roll": 	these are very similar to yaw. You will see them in the UnrealEd right above "Yaw". You can play
			with these numbers to make the flag tilt.
"unlit":		By default the flag will use the lighting that is in the area where you put it. But in the cases
			where it is too dark and you can't see it to well, then just add unlit=true, and then the flag
			will be bright.



=======================
	| fin |
=======================

