<commit_before>#**BMD's Lua Advanced Projectiles Library**
--------------------------------

####**How to install:**
- Drop projectiles.lua in with your vscripts
- Add require( 'projectiles' ) somewhere in your lua instantiation path

####**How to use:**
- The projectiles library can be used to generate projectiles which are a combination of mathematical simulation and particle control.
- Projectiles.lua projectiles do not use a unit or entity as part of the projectile simulation, and as such are lighter weight than unit-based projectiles.
- Due to not using a unit, the projectile simulation can potentially get out of synch with the particle representation if there a large number of high-velocity changes.  Because of this, a projectile which needs highly complex motion is better off implemented as a Physics:Unit().
- Projectiles.lua projectiles have more advanced capabilities than default LinearProjectiles, including the ability to dynamically change direction/speed, operate in 3 dimentions, bounce off of walls/ground, be tracked easily by instance, affect trees, etc.


**Projectiles Library Functions**
=============================
####**Projectiles:CreateProjectile(projectile)**
  This function is used to create ane release the projectile defined by the projectile table passed to the function.  The function returns an updated reference to the projectile table on which the Proejctile Table Functions can be called.  See the Projectiles Table Format section for more detail on what properties can be used with the projectile table.


####**Projectiles:CalcSlope(pos, unit, dir)**
  This function can be used to get the estimated slope of the ground in the given Vector direction 'dir' at the world point Vector 'pos'.  The 'unit' parameter is used to specify what unit should be used with GetGroundPosition() in order to handle the ground collision sizing.  This function can return odd values when used around sheer vertical edges.

####**Projectiles:CalcNormal(pos, unit, scale)**
  This function can be used to get the estimated normal Vector of the ground at the world point Vector 'pos'.  The 'unit' parameter is used to specify what unit should be used with GetGroundPosition() in order to handle the ground collision sizing.  This function can return odd values when used around sheer vertical edges.


**Projectile Table Functions**
=============================
A projectile table which has been fed to CreateProjectile will have the following functions:

####**projectile:GetVelocity()**
  This function can be called to get the current velocity vector of this projectile.

####**projectile:Destroy()**
  This function can be called to immediately destroy this projectile, triggering its OnFinish callback function if present.

####**projectile:SetVelocity(newVel[, newPos])**
  This function can be called to adjust the current velocity of the projectile, as well as the current simulated position of the unit (if specified).  The projectile simulation and particle will only update if the projectile is within its nMaxChanges velocity change limit.


**Projectiles Table Format**
=============================
Projectiles are effectively a formatted lua table which is registered with the Projectiles API for processing and action.  All projectiles tables can have the following properties and functions:

| Property  | Default | Description |
| :------------ | :--------| :-----|
| bProvidesVision | false | If set to true, this projectile will provide vision around it as it travels. |
| bCutTrees | false | If set to true, this projectile will cut any trees that it comes in contact with. |
| bFlyingVision | true | If set to true and, this projectile will provide flying vision as it travels (if bProvidesVision is enabled) |
| bGroundLock | false | If set to true, the simulation will lock its height to the ground position + fGroundOffset.  This setting is useful for simulating Dota-like LinearProjectiles that effectively operate in 2D. |<commit_msg>add documentation to ProjectilesReadme<commit_after>#**BMD's Lua Advanced Projectiles Library**
--------------------------------

####**How to install:**
- Drop projectiles.lua in with your vscripts
- Add require( 'projectiles' ) somewhere in your lua instantiation path

####**How to use:**
- The projectiles library can be used to generate projectiles which are a combination of mathematical simulation and particle control.
- Projectiles.lua projectiles do not use a unit or entity as part of the projectile simulation, and as such are lighter weight than unit-based projectiles.
- Due to not using a unit, the projectile simulation can potentially get out of synch with the particle representation if there a large number of high-velocity changes.  Because of this, a projectile which needs highly complex motion is better off implemented as a Physics:Unit().
- Projectiles.lua projectiles have more advanced capabilities than default LinearProjectiles, including the ability to dynamically change direction/speed, operate in 3 dimentions, bounce off of walls/ground, be tracked easily by instance, affect trees, etc.


**Projectiles Library Functions**
=============================
####**Projectiles:CreateProjectile(projectile)**
  This function is used to create ane release the projectile defined by the projectile table passed to the function.  The function returns an updated reference to the projectile table on which the Proejctile Table Functions can be called.  See the Projectiles Table Format section for more detail on what properties can be used with the projectile table.


####**Projectiles:CalcSlope(pos, unit, dir)**
  This function can be used to get the estimated slope of the ground in the given Vector direction 'dir' at the world point Vector 'pos'.  The 'unit' parameter is used to specify what unit should be used with GetGroundPosition() in order to handle the ground collision sizing.  This function can return odd values when used around sheer vertical edges.

####**Projectiles:CalcNormal(pos, unit, scale)**
  This function can be used to get the estimated normal Vector of the ground at the world point Vector 'pos'.  The 'unit' parameter is used to specify what unit should be used with GetGroundPosition() in order to handle the ground collision sizing.  This function can return odd values when used around sheer vertical edges.

####**Projectiles:DefaultUnitTest(unit)**
  This is the default UnitTest function used if none is provided. This test will use the iUnitTargetTeam, iUnitTargetType, and iUnitTargetFlags keys on the projectile, if they're specified. Otherwise, it inherits targeting rules from the ability referenced by the ability key on the projectile. If none of these keys are available, the test will simply always fail.
  

**Projectile Table Functions**
=============================
A projectile table which has been fed to CreateProjectile will have the following functions:

####**projectile:GetVelocity()**
  This function can be called to get the current velocity vector of this projectile.

####**projectile:Destroy()**
  This function can be called to immediately destroy this projectile, triggering its OnFinish callback function if present.

####**projectile:SetVelocity(newVel[, newPos])**
  This function can be called to adjust the current velocity of the projectile, as well as the current simulated position of the unit (if specified).  The projectile simulation and particle will only update if the projectile is within its nMaxChanges velocity change limit.


**Projectiles Table Format**
=============================
Projectiles are effectively a formatted lua table which is registered with the Projectiles API for processing and action.  All projectiles tables can have the following properties and functions:

| Property  | Default | Description |
| :------------ | :--------| :-----|
| bProvidesVision | false | If set to true, this projectile will provide vision around it as it travels. |
| bCutTrees | false | If set to true, this projectile will cut any trees that it comes in contact with. |
| bFlyingVision | true | If set to true and, this projectile will provide flying vision as it travels (if bProvidesVision is enabled) |
| bGroundLock | false | If set to true, the simulation will lock its height to the ground position + fGroundOffset.  This setting is useful for simulating Dota-like LinearProjectiles that effectively operate in 2D. |
{'fraction_non_alphanumeric': 0.0886962716694372, 'fraction_numerical': 0.0004749465685110425, 'mean_word_length': 4.683535762483131, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '192632', 'n_tokens_mistral': 1949, 'n_tokens_neox': 1890, 'n_words': 1136}