# 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()
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://maindab.gitbook.io/meta/black-magic-ii-2019/development/class-framework/framework-functions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.