> For the complete documentation index, see [llms.txt](https://maindab.gitbook.io/meta/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://maindab.gitbook.io/meta/black-magic-ii-2019/development/class-framework/framework-functions.md).

# Framework Functions

## Short description

This page lists out functions in the Framework.

## **Setting up the framework**

#### Calling the framework

```lua
Reviewlocal f = require(game.ServerStorage.ClassesFramework)
local Framework = f()
```

## **Initial character stats, conditions**

#### Framework.StartHitboxes()

{% hint style="info" %}
**This function is not used commonly in classes**\
It is used within the framework scripts but is not called directly ouside of that.
{% endhint %}

This function continuously loops to check for hits.

```lua
Framework.StartHitboxes()
```

#### Framework.UpdateCondition()

Changing a condition in the player's Condition folder and a value to go along with it

```lua
Framework.UpdateCondition(Condition, Value)
-- Example usage
Framework.UpdateCondition("ClassCanSprint", true)
```

#### Framework.ToggleSuperArmor()

```lua
Framework.ToggleSuperArmor(Value, Level)
```

#### Framework.UpdateColors()

{% hint style="info" %}
**Used within SkinHandler only**\
Additionally, some of the color usage may seem a bit weird
{% endhint %}

Updates Framework.Character.Colors (character display colours) from a set of colours. A Color3Value is created for each color listed.

```lua
Framework.UpdateColors(
    unpack(
        {
            Color3.fromRGB(109, 25, 255),
            Color3.fromRGB(-450, -320, -1326),
            Color3.fromRGB(255, 255, 255),
            Color3.fromRGB(-1300, -1300, -1300),
            Color3.fromRGB(0, 0, 0),
            Color3.fromRGB(159, 161, 172),
            Color3.fromRGB(17, 17, 17),
            Color3.fromRGB(120, 81, 255),
            Color3.fromRGB(142, 12, 255)
        }
    )
)
```

#### Framework.UpdateStats()

Updates a player's stats.

```lua
Framework.UpdateStats(MaxHealth, WalkSpeed, SprintSpeed, JumpPower)
-- Example usage
Framework.UpdateStats(100, 80, 120, 81.25)
```

## Cooldown Functions

#### Framework.FakeCooldown()

The FakeCooldown function is there for visual representation, aka for the HUD.

```lua
Framework.FakeCooldown(CooldownType, Percent)
-- Example usage
Framework.FakeCooldown("Guardbreak")
```

#### Framework.Cooldown()

This is the actual cooldown function for a move.

```lua
Framework.Cooldown(CooldownType, Percent)
-- Example usage
Framework.Cooldown("1") -- cooldown for SP1
```

#### Framework.OnCooldown()

Checks if a move is currently on cooldown.

```lua
Framework.OnCooldown(CooldownType) 
-- Example usage for a move.
-- Moves require certain conditions to be met before running.
-- Cooldown is one of them.
if Framework.JumpCancelled == true then
    return true
elseif Framework.OnCooldown("2") or Framework.LocalConditions.InAir.Value == false then
    return false
end
```

#### Framework.IsKeyHeld()

Checks if a key is being held.

```lua
Framework.IsKeyHeld(Key)
-- Example usage, we know Assailant SP5 can be mod
local Mod1 = Framework.IsKeyHeld("Mod1")
local Mod2 = Framework.IsKeyHeld("Mod2")
if Mod1 == false and Mod2 == false then
    -- Mod key not held
else
    -- Mod key held
end
```

## FPS and yield functions

#### Some things to note

* FPS fluctuates, in this case things like animation speed are affected.
* The yield/wait functions are used for timing events and intervals throughout the framework.
* **If the yield waits were not adjusted for FPS, they could end up waiting too long or too short depending on the current framerate.**
* `Framework.DefaultFPS()` sets a baseline expected FPS, like 60.
* `Framework.GetFPS()` gets the actual current FPS of the character
* `Framework.GetFPSFactor()` calculates the ratio of actual to default 
  * For example, at 30 FPS the factor would be 0.5 (30/60)
  * When yielding, if `AffectedByFPS` is `true`, it will divide the wait time by this factor At 30 FPS, a 1 second wait would adjust to 2 seconds (1/0.5)

#### Framework.GetFPS()

{% hint style="info" %}
**Not used within classes**\
You are likely looking for GetFPSFactor().
{% endhint %}

Get FPS of character.

```lua
Framework.GetFPS(Character)
```

#### Framework.GetFPSFactor()

Factor to adjust for FPS. If the  FPS was 30 but the default FPS was 60, the factor returned would be 0.5 (30/60 = 0.5).

```lua
Framework.GetFPSFactor()
-- Factor to adjust for FPS
function Framework.GetFPSFactor()
    -- Example: if FPS was 30 but the default FPS was 60, the factor
    -- returned would be 0.5 (30/60 = 0.5)
    return (Framework.GetFPS() / Framework.DefaultFPS)
end
-- Example usage
Framework.Animation.ChangeCurrentAnimSpeed(1.4 * Framework.GetFPSFactor())
```

#### Framework.Yield()

Wait function that converts time to yield to frames.

```lua
Framework.Yield(TimeToYield, AffectedByFPS)
-- Example usage, wait for 0.05 seconds
Framework.Yield(0.05)
```

#### Framework.YieldFrames()

Input: YieldFrames(10, false) \
Output: Waiting for 10 frames, return 0.167s at 60FPS

Input: YieldFrames(10, false) FPS Factor = 0.5 (given that the FPS is 30) \
Output: Frames adjusted to 20 (10/0.5 = 20). Wait 20 frames, return 0.333s at 30FPS

```lua
Framework.YieldFrames(FramesToYield, AffectedByFPS)
-- Example usage
Framework.YieldFrames(3)
```

## Tables & Some Angles

####  Framework.GetTableAmount()

{% hint style="info" %}
**Framework utility function**\
This function is not really used outside of the framework script itself.
{% endhint %}

Count number of elements in a table.

```lua
Framework.GetTableAmount(Array)
```

#### Framework.RandomFromTable()

{% hint style="info" %}
**Framework utility function**\
This function is not really used outside of the framework script itself.
{% endhint %}

Pick random element from a table.

```lua
Framework.RandomFromTable(Array)
```

#### Framework.RandomAngle()

{% hint style="info" %}
**Framework utility function**\
This function is not really used outside of the framework script itself.
{% endhint %}

Pick a random angle.

```lua
Framework.RandomAngle(Min, Max)
```

#### Framework.CreateRegion3FromLocAndSize()

{% hint style="info" %}
**Framework utility function**\
This function is not really used outside of the framework script itself.
{% endhint %}

Create Region3 from center position and size.

```lua
Framework.CreateRegion3FromLocAndSize(Position, Size)
```

#### Framework.CopyArray()

{% hint style="info" %}
**Framework utility function**\
This function is not really used outside of the framework script itself.
{% endhint %}

Deep copy a table.

```lua
Framework.CopyArray(original)
```

## Humanoid conditions checker

#### Framework.ToggleHumanoidCollision()

Toggle collision groups for character parts.

```lua
Framework.ToggleHumanoidCollision(Bool)
-- Example usage
Framework.ToggleHumanoidCollision(true)
```

#### Framework.GetHumanoidFromPart()

{% hint style="info" %}
**Framework utility function**\
This function is not really used outside of the framework script itself.
{% endhint %}

Get humanoid from part's parent model.

```lua
Framework.GetHumanoidFromPart(Part)
```

#### Framework.IsInTeam()

Check if target is in same team.

```lua
Framework.IsInTeam(Target)
-- Example usage
Hitbox.AddHitFunc(
    function(Noob)
        -- Do not damage target if in same team
        if Framework.IsInTeam(Noob) then return end
        ...
    end
)
```

#### Framework.CheckGrab()

Check if a target can be grabbed. Used for grabs like Assailant SP6.

```lua
Framework.CheckGrab(Target, GrabProperties)
-- Example usage
Hitbox.AddHitFunc(
    function(Noob)
        ...
        if Grabbed == false then
            if Framework.CheckGrab(Noob, {}) == true then
                ...
            end
        end
    end
)
```

## Combat Functions - Damaging

#### Framework.Parry()

Play parry effects and stun attacker.

```lua
Framework.Parry(User, ParryPart)
```

#### Framework.Stun()

Apply stun state.

```lua
Framework.Stun(Target, User, Settings)
-- Example usage
local s = {Type = "Knockdown1"; Duration = 2, V2 = true}
Framework.Stun(ExecuteTarget, Character, s)
```

#### Framework.ScaleDamage()

Scale combo damage falloff. Very rarely used within classes themselves.

```lua
Framework.ScaleDamage(OGdmg, Mini) 
```

#### Framework.CheckComboTimeLimit()

{% hint style="danger" %}
**Non-standard function**\
Combo time limits do not exist in the actual BM2. This is a new addition that is yet to be fully implemented within the place.
{% endhint %}

Function to check combo time.

```lua
Framework.CheckComboTimeLimit()
```

#### Framework.ApplyDamage()

Apply damage and effects.

```lua
Framework.ApplyDamage(Target, Settings, Stuns, StunData, Attack)
-- Example usage
local s = {Starter = "B";Damage = 20;Type = "Grab";BreakGuard = true, Parry = false;Sound = "Grapple",ParryPart=Hitbox.Part}
local s2 = {Type = "LowHit";Duration = 1;IgnoreSuperArmor=true,SuperArmorPriority = 3}			
Framework.ApplyDamage(Noob, s, true, s2, ActionR)
```

#### Framework.NApplyDamage()

{% hint style="danger" %}
**Non-standard function**\
Only used by old Kar98k tool (Viethin modification). Do not use the NApplyDamage function in actual classes.
{% endhint %}

```lua
Framework.NApplyDamage(Target, Damage)
```

## Combat Functions - Finished Combos

#### Framework.ComboEnded()

```lua
Framework.ComboEnded()
```

#### Framework.CleanMovers()

```lua
Framework.CleanMovers(Part)
```

#### Framework.ClientControlVel()

```lua
Framework.ClientControlVel(Velocity, Part, Direction, Sign)
```

## Combat Functions - Knockback

#### Framework.Knockback()

```lua
Framework.Knockback(Target, Velocity, Time, Ignore, Force, AffectedFPS)
```

#### Framework.MoveTo()

```lua
Framework.MoveTo(Target, Position, Force, Time) 
```

#### Framework.PushCharacter()

```lua
Framework.PushCharacter(Velocity, Duration)
```

#### Framework.Root()

```lua
Framework.Root(Target, Duration, CanBeBroken, Type, ...)
```

## Combat Functions - Hitboxes

#### Some things to note

**Framework.GetHumanoidFromPart(part) \[This somewhat still counts]**

* This takes a BasePart and tries to find a Model parent with a Humanoid and Conditions child.
* Checks if the model Health > 0 and Iframes = false Returns the model if found, nil otherwise.

**Hitbox.Detect(scale, customCFrame) \[in Framework.CreateHitbox]**

* Casts a RotatedRegion3 from the hitbox Part's CFrame and scale.
* Loops through results and calls GetHumanoidFromPart on each part.
* Stores any found humanoids in a table and returns it.

**Hitbox.Part.Touched Event \[in Framework.CreateHitbox]**

* Connects to the Touched event on the hitbox Part.
* Gets the touched part's Model parent.
* Calls OnTouch and passes the model if found via GetHumanoidFromPart.

**Hitbox.Fire() \[in Framework.CreateHitbox]**

* Calls Detect() to get humanoids in the current hitbox bounds.
* Loops through and calls OnTouch on each one.

**Hitbox.Remote Event \[in Framework.CreateHitbox]**

* RemoteEvent created on the server.
* OnServerEvent connects to call OnTouch on synced model.

#### Framework.CreateHitbox()

```lua
Framework.CreateHitbox(Debounce, Size, Point, Offset)
```

## Combat Functions - Raycasts

#### Linear interpolation

* With the BM2 framework this is used to smoothly transition between two values over time.
* It calculates an "interpolated" value based on a factor t between 0-1.
* When t=0 it returns the first value. When t=1 it returns the second value. 
* For values in between, it calculates a weighted average of the two values based on t.
* For example, to linearly interpolate between value a and b:
  * When t=0, return a
  * When t=1, return b
  * For t between 0-1, 
    * return a \* (1-t) + b \* t (search it up if unsure) 
    * This gives a straight linear transition between the two values.

#### Bezier curve

* A Bezier curve is defined by n+1 "control points", imagine: P0, P1, ..., Pn.
* For a quadratic we have 3 points (n=2), cubic uses 4 points (n=3).
* It uses polynomial equations to calculate curve points. This allows for smooth curved paths compared to linear interpolation
* Quadratic Beziers:
  * The curve is calculated as: B(t) = (1-t)2P0 + 2(1-t)tP1 + t2P2.
  * Where t varies from 0 to 1, 
    * B(0) = P0, B(1) = P2
    * B(t) gives the point on the curve for that value of t
* Cubic Beziers:
* Now we have segments...
* Let's make 2 of these segments, these are calculated as
  * B1(t) = (1-t)3P0 + 3(1-t)2tP1 + 3(1-t)t2P2 + t3P3
  * B2(t) = (1-t)3P1 + 3(1-t)2tP2 + 3(1-t)t2P3 + t3P4
  * B1 calculates points between P0-P1, B2 between P1-P2
  * The overall curve is: B(t) = B1(t)(1-t) + B2(t)t

#### Framework.RelativeCF()

```lua
Framework.RelativeCF(CFrame, CFrameFrom)
```

#### Framework.NumberLerp()

```lua
Framework.NumberLerp(a, b, time)
```

#### Framework.Lerp()

```lua
Framework.Lerp(a, b, time)
```

#### Framework.QuadBezier()

```lua
Framework.QuadBezier(Part0, Part1, Part2, Time)
```

#### Framework.CubicBezier()

```lua
Framework.CubicBezier(Part0, Part1, Part2, Part3, Time)
```

#### Framework.RayCast()

```lua
Framework.RayCast(Position, Direction, Range, Ignore)
```

#### Framework.RayCastWhiteList()

```lua
Framework.RayCastWhiteList(Position, Direction, Range, WhiteList)
```

## Combat Functions - Moves

#### Framework.UpdateWalkSpeed()

```lua
Framework.UpdateWalkSpeed(Speed)
```

#### Framework.D\_Moves()

```lua
Framework.D_Moves(Bool, Move, StopMovement, ...)
```

## Combat Functions - Core Class Functions

#### Framework.DoMove()

```lua
Framework.DoMove(Action, ...)
```

#### Framework.CastAction()

```lua
Framework.CastAction(Action, ...)
```

#### Framework.RunEvents()

```lua
Framework.RunEvents()
-- Within Framework.RunEvents()
Framework.AttemptJumpCancel()
```