BHv5 Rescripted Documentation

--[[

-- [Blackhole v5 Alpha Release Documentation/Manual RESCRIPTED] Mar 16, 2025 --

[UPDATE!] Complete revamp of the entire code. Though this isnt a full full release, just a demo. This model no longer uses the old template of v5 and v4 lite
The most complicated blackhole model in Roblox. a lot of controls that does something with each other, but uses simple maths.
If you have complaints with the blackhole, please leave a comment on the model page. and please, dont go nerdy on me, I barely know general and special relativities.

Self-explanatory components are not included cuz i expect you to know how they work

----------------
-- I PHYSICAL --
----------------

    IMPORTANT: Note that the blackhole is a MeshPart, resize the blackhole by holding `alt` to preserve proportions!
        If you want to use a regular sphere, copy and paste every child of the blackhole onto the new sphere.
        Can also be a cube, or custom MeshParts, but gravitational attraction is still spherical.

    `toggleMicroGravity` (quickly disable gravity) can be turned off or on if you dont want to go into the game settings manually.

    Change blackhole properties like `EventHorizon` (pitch black effect), color, transparency, mass, custom physical properties and more to your liking.

----------------
-- II GRAVITY --
----------------

    Blackhole v5 Alpha runs on various constraint gravities: LinearVelocity, LineForce, VectorForce, & AlignPosition.
    The old BodyVelocity and BodyForce-based gravities are preserved as legacy, but in my descretion, you may still use them.

    `gravity` is the base strength of the blackhole's overall gravity. setting it to negatives will push objects away.
        Gravity can be chosen using "1.1", "1.2", "2", "3", & "4" but you can also choose "linear1", "linear2", "line", "vector", & "align" with `gravityEngine`.
        Legacy gravities can be chosen with "5", "6" or "force", "speed", or "bodyforce", "bodyvelocity".
        `gravitationMode` can be chosen between "universal" to attract every object and "selective" to only attract objects with the `attractionTag` ("attractable").
        Setting `gravity` to a negative value will trigger something cool, trust

    `alignSpeed` is an alternate to gravity when using AlignPosition. higher number means faster speeds.
    `range` is the area in studs where objects are pulled in, anything outside that is not affected. default is 500 studs.
    `forceCap` sets the maximum force/velocities on objects while moving within range, higher caps mean laggier simulations. default is 2000.
    `centerOfMassBased` applies constraint gravities at the center of masses of objects. it already does this, but this is for when the mass DOES change.
    `realisticGravity` uses inverse square law. basically the closer objects are, the stronger the gravity. its recommended you use BodyVelocity!
    `realGravDamping` dampens gravity when `realisticGravity` is enabled. higher values means faster gravity, lower means slower (cannot be 0)
    `microGravity` directly disables workspace gravity for better simulations. though you can do this via settings.

    If you want more freedom with the gravity, you can use BodyVelocity or BodyForce as its purely mathematical. break it if you want. i dare you, i double dare you.

----------------------------------
-- III ABSORPTION & PERFORMANCE --
----------------------------------

    Objects are absorbed only when `absorption` is enabled, else everything within Absoription does not apply:

    `growth` allows the blackhole to grow by absorbing objects, including other blackholes (v5+ only) while `growthDamping` sets the speed the blackhole can grow at.
        `merging` allows blackholes to combine into bigger blackholes. though this may not work every time, so keep in mind that there will be bugs.
        You can also set `growthDamping` to a negative to shrink the blackhole.

    `fading` allows objects to slowly fade out of existence, where `fadeDuration` will set how long objects will take to full fade out. fading also synergizes with
    `colorShift` where the objects will shift to a color picked with RGB `color` and objects will shift to that color as its fading within `fadingDuration`.
    `rocheFactor` is the range (in multiples of the blackhole's size) where objects' joints are removed including: Welds, Motors, Hinges, Ropes, and Springs.
        This does not affect constraint gravities.

    Things to note: setting `fadeDuration` too high will cause performance issues, as well as larger `rocheFactors` if you have any models with joints nearby.
    Also note that having too many blackholes will start to cause lag as they're calculating tons of calculations even for one.

------------------------
-- IV SPECIAL EFFECTS --
------------------------

    Special effects set the blackhole's appearance when running the simulation ONLY.

    `lensing` allows "gravitational lensing" to occur, bending light around the blackhole with a radius `lensingFactor` multiplies to the blackhole's size.
        `lensingStrength` will set the intensity of the gravitational lensing; lower for less warping. do not set it too high or it will break the effect!
        The value of `lensingFactor` becomes insignificant below 15, so it automatically sets it to 1 because it also means the least warping, which is none.

    `cameraDistortion` allows the FOV (only for editor/server mode) to be warped within range - closer means higher FOVs, furthest is default FOV.
    `distortThreshold` sets the minimum range for FOV to reach the maximum (120) in percentages. default is 1 for 1% the blackhole's size
    `blackHoleSound` toggles the blackhole's sound using the rainbow periastron blackhole sound. this sound is only heard within range.
    `distortSound` is a feature that changes the pitch whenever its around other v5+ blackholes. this feature is still beta.
    `glintSizeMultiplier` is the factor of propotionality for the `Glint` ParticleEmitter within `FX`. if you want to change it, go ahead. but it will unsync its size.

----------------------------------------
-- V EXPERIMENTALS | AKA THE TEMPLATE --
----------------------------------------

    Automatically disables other BH scripts to prevent conflicts.
    For `Constraint-based gravity`: `gravitationalStrength` = `gravitationalConstant`, `absorption`, `toggleMicroGravity`, `constraintMode` = `gravityEngine`, and
    `detectionRange` = `rangeFactor` are the same as their main script counterparts EXCEPT:

        `dampingFactor` is the elasticity of constraints, 0 means no bouncy and 1 is bouncy. `damping` is reversed in logic.
        `innerEventHorizon` is similar to `infinityHandler` but the range is in studs in which constraints stop applying forces. more on `infinityHandler` next section.
        `visibleConstraints` simply allows you to see active constraints on objects for testing. this does not affect performance.
        `centerOfMassBased` sets if forces are applied at the center of MASS. force attachments are placed at the center of GEOMETRY.
        `forceCap` sets the maximum force for objects when using linear and realistic LineForce. this prevents infinite speed at singularity.
        `cameraDistortion` is a toggleable parameter that allows the camera to warp for realism (Warning! May be nausea-inducing. This only works with Run)
        `distortThreshold` is the factor (x100 for percentage) of `detectionRange` where the maximum FOV is achieved (min: 70 [default], max: 120 [absolute])
        `alignSpeed` adjusts how fast objects will act to align or race toward the blackhole; small for smooth, high for fast.
        `blackHoleSound` toggles the ambient sound the blackhole will make with a range exact to `detectionRange` to indicate whether you are in the range or not.
        `gravitationMode` toggles between universal and selective gravitation for specifc objects. requires tags in desired objects with the same value as `attractionTag`
        `attractionTag` is the specific id for the blackhole to pick out and apply gravity while leaving anything without the tag alone.

        Constraint modes:
        `spring` or `1` - pretty self-explanatory, uses elasticity to reel in objects, causing them to get jiggy with it.
        `rope` or `2` - just like spring, but with less jiggy, but both can have their jiggy-ness controlled with `dampingFactor`.
        `line` or `3` - a "constraint", but a force like BodyForce. this version may replace bodyforce-based gravity entirely, but I'll still keep the legacy mode.
        `vector` or `4` - similar to lineforces, but uses xyz distribution to apply gravity. generally how bodyforce-based gravity works.
        `linear1` or `5.1` - line-based linear velocity. the old velocity-based gravity and mat replace it, but it can also be accessed. THIS HAS MODEL SUPPORT! RAAAAAH
        `linear2` or `5.2` - vector-based linear velocity. does not support orbits and boring in my opinion.
        `align` or `6` - simple & efficient homing-based constraint that does not simulate orbits, rather useful for clusters of objects.

    Experimentals will continue to be a part of the blackhole for newer features before firectly integrating them into the main script

-----------------
-- VI ADVANCED --
-----------------

    If you know how to code, you can edit the script to your liking.

    You can modify the master formula: (gravity * blackHole:GetMass() * object:GetMass()) / ((effDist / realGravDamping) ^ 2)
        Context, this is the Newtonian formula for gravity, tweaked to match robloxian environments. original formula is G(m1)(m2)/r^2
        Also works with [something].Size.X or, an average of Size.XYZ dimensions

    This is just here in case i need it or found a fix
    -- Disable other gravitational scripts to avoid conflicts
    local scriptConflict = false
    if script.Enabled then
        if not blackHole["Constraint-based_grav"] then blackHole["Constraint-based_grav"].Enabled = false scriptConflict = true end
        if not script.v5A_Deprecated then script.v5A_Deprecated.Enabled = false scriptConflict = true end
    end

    `gravitationMode` and `attractionTag` are relatively easy to use if you know how tags work. why did I make it advanced? I wanted to make cool demoes.

    Modifying the minimum FOV:
        ...
        if distance >= detectionRange then
            newFOV = 70 -- Default FOV, but feel free to change it
        elseif distance <= detectionRange * distortThreshold then
            newFOV = 120 -- Maximum FOV, roblox does not allow higher
        else
            local t = (detectionRange - distance) / (detectionRange - distortThreshold)
            newFOV = 70 + t * (120 - 70)
        end

]]