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

This file explains the buff field class like the changed regeneration field enhancement for the Seraphim ACU in
this mod. Modders can use this to create a buff field for their own enhancements or units.
Basically the field adds a buff to a unit within a certain distance to the unit with the field. If the unit is to
far away it loses the buff again.

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

HOW TO USE:

1.  The file \lua\BuffFieldDefinitions.lua contains the blueprints for the buff fields. I had to improvise this
    a bit but you'll manage. If you add a new one just copy-paste an existing blueprint definition and change it.
    Find a buff field that you like and remember it's name (or copy-paste it).

    Here's an example of a buff field blueprint + explanation for each setting.

        BuffFieldBlueprint( {
            Name = 'SeraphimACURegenBuffField',           # used to refer to this buff field
            AffectsUnitCategories = 'ALLUNITS',           # unit categories affected by this buff field
            AffectsAllies = false,                        # does the buff field affect units owned by allied players
            AffectsVisibleEnemies = false,                # does the buff field affect units owned by enemy players
            AffectsOwnUnits = true,                       # does the buff field affect units owned by the owning player
            AffectsSelf = true,                           # does the buff field affect the unit that has the buff field
            DisableInTransport = true,                    # does the field turn off during transport
            InitiallyEnabled = false,                     # does the field turn on as soon as the unit is created
            MaintenanceConsumptionPerSecondEnergy = 0,    # energy cost per second
            Radius = 15,                                  # range of the field. higher number = bigger field
            Buffs = {                                     # list of buffs that will be applied to all units affected by the field
                'SeraphimACURegenAura',
            },
        })

2.  Open up the units blueprint file and add a BuffField table, like this one:

        BuffFields = {
            RegenField = 'SeraphimACURegenBuffField',
        },

    In this example "SeraphimACURegenBuffField" is the name of a BuffField. Change this value to the buff field
    name you copy-pasted in step 1. Also edit "RegenField" to something appropriate. Remember what you change it
    to (or copy-paste).

3.  Open up the script file of your unit. Under the Weapons section (if there is any) add a BuffField table:

        BuffFields = {
            RegenField = Class(SeraphimBuffField) { },
        },

    Here "RegenField" should be what you copy-pasted in step 2. "SeraphimBuffField" should be the buff field class
    for the faction of the unit you're editing, in my case that's Seraphim. Remember what class you're using, you
    need this in steps 4 and 5.

4.  Go to the top of the unit script file. Define the "SeraphimBuffField" class mentioned in step 3, like this:

        local SeraphimBuffField = SWeapons.SeraphimBuffField

    Reminder: this is faction dependant. In this example "SWeapons" points to file "/lua/seraphimweapons.lua".
    Open this file for step 5.

5.  Open the faction weapons file for the unit you're editing, in this example thats "/lua/seraphimweapons.lua".
    Make sure that the weapons file contains the forementioned class (step 3). Also make sure it inherits from
    the default buff field class:
   
        SeraphimBuffField = Class(DefaultBuffField) { }

6.  Go to the top of the faction weapons file and make sure "SeraphimBuffField" is defined like this:

        local DefaultBuffField = import('/lua/defaultbufffield.lua').DefaultBuffField

7.  Save all changed files if you haven't yet. You can now use the buff field. If the buff field is not set to 
    be enabled initially then you need to call Enable() before the field shows any effect. Use Disable() to
    turn of the buff field.

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

HOW IT WORKS:

1.  A unit is created. The unit class is modified so it checks whether it has a BuffFields table. If no then
    nothing else happens. If yes then a seperate instance of each field is created.

2.  The field is created by the game using the specified buff field blueprint. If so set the field will enable
    automatically. If it doesn't auto-start then you'll need to call Enable() in the code to start the field.
    Use Disable() to disable the field again.

3.  Once the field is enabled a thread is started that periodically finds all eligible units in range. It 
    then goes through all units and adds a buff thread to each unit that doesn't have one yet.

4.  The unit buff thread adds the specified buffs and then repeatedly checks the distance between itself and the 
    field emitting unit. If the distance between the field emitting unit and itself, or if the field is 
    disabled, or if the field emitting unit is killed, or if the unit itself is killed then the thread removes 
    the buffs it applied earlier. The thread then stops working and is destroyed.

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

ADDITIONAL NOTES:

- There are a couple of events you can use to enhance the field or whatever. If you use a buff that increases the
  max. HP of affected units you can use this to keep the HP : max. HP ratio the same (among other things).
- Buff fields that share the same blueprint (same buff field name actually) don't stack. Only fields with 
  different names stack.
- Buff durations should be -1 (unlimited) because the buff is set once and then the script waits until the unit
  has gone out of reach before the buff is removed again. If the buff has a limited duration then it will not be
  re-applied when it has expired unless the unit leaves and then re-enters the field.
- The variable "FieldVisualEmitter" can be used to use graphics for the field.
- Check the Restoration enhancement on the Seraphim ACU for an example on how to use this class.
- Some changes were made in v3 of the buff field scripts. The buff field is now an entity. Also the functions
  Create() is now obsolete. Blueprint value "EnableOnCreate" is renamed to "InitiallyEnabled". You'll get log
  warnings if you use any of these.

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

FILES AND CODE:

- \lua\BuffField.lua
- \lua\BuffFieldDefinitions.lua
- \lua\DefaultBuffField.lua
- \lua\sim\Unit.lua -> InitBuffFields(), CreateBuffField() and GetBuffFieldByName()

Also uses the code that allows paths to be softcoded.

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