******************************************
* AutoGive (with Unit/Resource Donation) *
* by falcontx                            *
******************************************

Summary
-------
AutoGive is a UI-mod that provides two different functions. The primary function 
is that it detects when a game is started with the Assassination victory 
condition and automatically begins monitoring the commander's health. As your 
commander loses health, you will be notified. Then, upon death, all assets are 
automatically transferred to the surviving ally with the highest score (not
including commander kill bonuses). You can also assign AutoGive to the ally
of your choice (details below). The secondary function is that it allows you
to easily give resources or units to an ally at any point during the game.

AutoGive was inspired by One Key Unit Donation (OKD) by Jiver and LazyShare by 
SvartfaR. Each of these mods provide the ability to give resources/units to 
allies during the game. I used what I considered to be the best features from 
each one during the development of this mod, with permission, of course. Also, 
since I used the ally-to-key mapping method from OKD, I worked with SvartfaR to 
include compatibility with LazyShare, for those that prefer his way of mapping 
allies to keys.


Compatibility
-------------
* One Key Unit Donation: INCOMPATIBLE
      The unit and resource donation functionality provided by this mod is very
      similar to what is provided by One Key Unit Donation. Running both would
      be redundant, so One Key Unit Donation is considered incompatible.
* LazyShare: COMPATIBLE
      The way that allies are identified by LazyShare is unique in that players 
      are assigned an identifier that is indicated on the scoreboard. Since some
      users may prefer this over the static user assignments that this script
      uses, this mod has been made compatible with LazyShare.

At the time of release, AutoGive is not known to be incompatible with any other 
major UI-mod.


Installation
------------
If you got it from the Vault, it's already installed, so you just need to enable 
it via the Mod Manager. Otherwise, you need to place the AutoGive folder in your 
mods directory, and then enable it via the Mod Manager.

Once enabled, start a game or replay and bring up the Key Bindings menu 
(normally by pressing F1). You will be asked if you would like to set the 
AutoGive default keys. Choose "Yes". You'll find the defaults listed below. You 
may reassign them if you'd prefer something else.


Usage (without LazyShare)
-------------------------
If LazyShare is not installed, the following default keys are assigned:
[Shift-Fx]       donates 50% of stored mass to ally x
[Ctrl-Fx]        donates 50% of stored energy to ally x
[Ctrl+Shift-Fx]  donates selected units to ally x
[Ctrl+Alt-Fx]    establishes AutoGive to ally x

So, what is x? x is a number from 1-6 that is used to identify which ally you 
are choosing. The ally numbers are determined from the order that your allies 
are listed on the Diplomacy Menu (normally accessed by pressing F4 in game). So, 
for example, if you want to give 50% of your stored mass to the 2nd ally listed 
on the Diplomacy Menu, you would press [Shift-F2], or, if you want to give all 
of your assets to the 3rd person listed on the Diplomacy Menu when your 
commander dies, you would press [Ctrl+Alt+F3].


Usage (with LazyShare)
----------------------
If LazyShare is installed, the following default keys are assigned:
[Ctrl+Alt-Numpad1]    establishes AutoGive to ally 1
[Ctrl+Alt-Numpad2]    establishes AutoGive to ally 2
[Ctrl+Alt-Numpad3]    establishes AutoGive to ally 3

If LazyShare is installed, the key assignments for donating resources and units 
are controlled by LazyShare. This mod simply adds the AutoGive functionality. If 
you are using LazyShare version 1, this script will always AutoGive to ally #1, 
as assigned by LazyShare. However, if you use the latest version of LazyShare, 
you may choose which ally you would like to AutoGive to using the key 
assignments above. These key assignments correspond to the ally IDs assigned by 
LazyShare.


AutoGive Notes
--------------
If you're playing an assassination game, AutoGive is automatically enabled, and 
you will see a message at the beginning of the game indicating this. As such, if 
your commander dies, all of your units/resources will be donated to the the
surviving ally with the highest score (not including commander kill bonuses),
automatically. However, if you would like to AutoGive to a specific ally, you
may press the corresponding key assignment any time before you die to reassign
AutoGive. Once AutoGive has been manually reassigned, the key assignment becomes
a toggle, so pressing it a second time will disable AutoGive. It should also be
noted that if your chosen ally is already dead, AutoGive will automatically
revert to using the surviving ally with the highest score. AutoGive can not be
used in non-Assassination games and it is disabled by default during Phantom
games.


Version History
---------------
v1.4 (July 23, 2009)
- AutoGive now uses score to determine which ally to give to automatically

v1.3 (June 11, 2009)
- fixed bug that caused AutoGive to fail under certain circumstances

v1.2 (June 4, 2009)
- fixed a few bugs related to giving resources [identified by Moritz]
- AutoGive disabled by default when using Phantom mod [suggested by -Shinzok]

v1.0 (May 28, 2009)
- initial release


Miscellaneous
-------------
This mod remaps some of the user debug keys in order to make room for it's 
standard default keymapping. If you use the debug features in FA, take a look at 
hook\lua\keymap\defaultKeyMap.lua to identify the changes.

This is a UI only mod, which means that you may use it in multiplayer games 
regardless of whether anyone else has the mod or not.

If you wish to include any part of this mod in your own release, please ask
permission from falcontx, first. Sending a PM on the gaspowered forums is the
best way to reach me.

Bug reports welcome.

http://forums.gaspowered.com/viewtopic.php?t=37082

Enjoy!
falcontx