BH v5 Alpha Documentation

--[[

-- [Blackhole v5 Alpha Release Documentation/Manual] Mar. 1, 2025 --

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.

----------
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 Prototype runs on BodyForce-based gravity. Blackhole v4.0+ runs on Velocity-based gravity, v4 Betas are hybrid-based (force or velocity).

    `gravitationalConstant` is the base strength of the blackhole's overall gravity, which are manipulated by `damping` (suppresses violent simulation between 0 & 1),
    and `rangeFactor` (area in studs where objects are pulled in, anything outside that is not affected. gravity is amplified for bigger values).

    When switching between BodyForce and Velocity gravity, note that gravitational constant is fixed, but the two behave differently. velocity-based is violent!
        BodyForce gravity: Stable, less accurate, customizable range. overall a mode to play around with!
        Velocity gravity: Violent, accurate, unlimited range. overall a mode to simulate blackholes with! (tweaked to synchronize with BodyForce)

    Since there's so many knobs to turn, you can break the blackhole. break it, I dare you. I double dare you. just kidding, just dont break the laws of math!
----------

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

    Objects are absorbed if `absorption` is enabled, which will follow `transparencySteps` (fading effect between 1 & 0 invisibilities)
    in a span of `dematerializeDuration` (time to progress each transparency step) while `partMaterialTransform` (material absorbed objects turn into) and
    `partColor` (color absorbed objects turn into) lead the object into deletion, causing `growth` to make the blackhole bigger and stronger with
    `sizeProportion` (how fast the blackhole grows, bigger means slower growth) and `rangeProportion` (how fast rangeFactor grows, bigger means faster growth).
        `sizeProportion` CANNOT be 0 as it divides, only non-zeroes. Positive = grow, negative = shrink, asymptote to 0 = max size of 2048 studs.

        Sizing: maximum is 2048 xyz, minimum is 0.001. not recommended to have micro blackholes as it causes issues, as well as infinity for range-related variables.

        Gravity: negative `damping` == repel objects like negative `gravitationalConstant`. also not recommended setting values to large numbers.

    `killPlayers` (kills absorbed players) can be turned on or off when simulating with a player. Please disable when doing rapid blackhole merging!
        An error will say {attempt to index nil with 'FindFirstChild'} because it cannot identify any humanoids fast enough.

    `fixedPosition` (anchor absorbed objects) can help with performance, along with `collision` (make objects pass through eachother while being absorbed), and
    `updateInterval` (value in seconds to update gravitational forces. lower values are accurate but slower, higher values are inaccurate but faster).

    If `absorption` is disabled, everything above within ABSORPTION is excluded EXCEPT `killPlayers`.
----------------------------

------------------
IV BETA PARAMETERS

    `infinityHandler` prevents objects that crosses `EventHorizon` (AKA the blackhole's volume) from accelerating into infinity at singularity (the very center)

    `paradoxHandler` prevents two blackholes from absorbing eachother when they touch.

    `mergeBlackholes` merges blackholes: bigger blackhole absorbs the smaller, equal blackholes merge into a blackhole twice as big.
        When two different sized blackholes touch eachother with this enabled, it will cause the winning blackhole to accelerate to infinity. [BUG FIXED]

    `gravityEngine` modes between BodyForce-based gravity and Velocity-based gravity. accepts "1" or "force" too, and accepts "2" or "speed" as well, respectively.
        BodyForce-based gravity ensures stable simulations, but a lower accuracy than to Velocity-based gravity, which is more violent, laggy and accurate.

    `glint` is the reference to a cosmetic the blackhole has. when changing its name and or location, you must also change the path of the variable.

    `glintProportion` not to be confused with `glintProportions`, modified value of `glintProportions` multiplied by `glintProportion` to change `glint` proportions.

    `rocheLimitFactor` is the area around the blackhole (multiple of the radius) where any joint is destroyed for realistic simulation. this feature is from v4.0+
        This can be disabled by setting it to zero!

    `gravitySync` synchronizes the gravitational prowess of velocity-based gravity with the force-based gravity without modifying `gravitationalConstant`.
        When disabled, note that velocity-based gravity is significantly more powerfull than force-based gravity, and modification to the constant is needed.
------------------

---------------
V EXPERIMENTALS

    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.
        -- ADVANCED --
        `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.

    Experimentals doesn't have much freedom for parameters, only when they're fully integrated into the main scripts. a complete revamp of `gravityEngine` is underway!
---------------

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

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

    Tips:
    In `CheckAndApplyGravity(obj)`, you can change `if not obj:IsDescendantOf(game.Workspace) or not obj:IsA("BasePart") then return end` to exclude specific objects.

    Changing `if obj == hole or obj.Parent:IsA("Player") then return end` will cause glitches. however, you may change `obj.Parent:IsA("Player")` without issues.

    Tinkering with `ApplyGravity(object)` and `onTouched(part)` can throw simulation accuracy off, modify cautiously.

    Overriding `infinityHander` code can make the blackhole have strange, but cool behavior. Be careful with your math!

    Examples of overriding the function:
        local holeRadius = hole.Size.Magnitude * 2 -- Increase the area bigger than the blackhole (twice in size). can be any value.
        ...
        if distance < holeRadius then

            force = Vector3.zero -- Removes gravity, acts like a vacuum (make into -force for something epic to happen) [DEFAULT]
            OR
            force = -force -- Inverts gravity, creating a forcefield shell around the blackhole [NEW!]

            direction = Vector3.zero -- Prevents direction inversion for velocity-based logic [KEEP]
        end

    `gravitySync` is not an exact synchronization, only an approximation. If you have a solution to make it exact, modify the following dunction in the main script:

        if engineType == "velocity" or engineType == "speed" or engineType == "2" and gravitySync then
            magnitude = magnitude / (gravitationalConstant * 0.1) -- Dampening factor for velocity-based gravity
        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.

-----------

You may be wondering, how much did I put into this?
Yes.

]]