@rbxts/gravity-controller 1.0.0

package/README.md

@@ -0,0 +1,65 @@
+# @rbxts/gravity-controller
+
+Typescript bindings for [EgoMoose's Rbx-Gravity-Controller](https://github.com/EgoMoose/Rbx-Gravity-Controller) with
+ground normal finding by [EmilyBendsSpace](https://x.com/EmilyBendsSpace)
+
+## Flamework setup
+
+1. Add `installGravityControllerClass` to the `onInit` of some `@Service`
+
+```typescript
+import { OnInit, Service } from '@flamework/core'
+import { installGravityControllerClass } from '@rbxts/gravity-controller'
+
+@Service()
+export class GravityService implements OnInit {
+  onInit() {
+    // Install EgoMoose's Rbx-Gravity-Controller https://github.com/EgoMoose/Rbx-Gravity-Controller
+    installGravityControllerClass()
+  }
+}
+```
+
+2. Setup a `GravityController` in some `@Controller`
+
+```typescript
+import { Controller, OnStart } from '@flamework/core'
+import {
+  getGravityControllerUp,
+  GravityController,
+  GravityControllerClass,
+  installGravityControllerClass,
+} from '@rbxts/gravity-controller'
+import { Players } from '@rbxts/services'
+
+@Controller({})
+export class PlayerGravityController implements OnStart {
+  gravityControllerClass: GravityControllerClass | undefined
+  gravityController: GravityController | undefined
+
+  onStart() {
+    this.gravityControllerClass = installGravityControllerClass()
+    Players.LocalPlayer.CharacterAdded.Connect((_character) => {
+      this.disableGravityController()
+      this.enableGravityController()
+    })
+    if (Players.LocalPlayer.Character) this.enableGravityController()
+  }
+
+  disableGravityController() {
+    this.gravityController?.Destroy()
+    this.gravityController = undefined
+  }
+
+  enableGravityController() {
+    if (this.gravityController || !this.gravityControllerClass) return
+    const gravityController = new this.gravityControllerClass(Players.LocalPlayer)
+
+    // Use EmilyBendsSpace's getGroundNormal() to walk up walls
+    gravityController.GetGravityUp = getGravityControllerUp
+
+    this.gravityController = gravityController
+  }
+}
+
+```

package/out/index.d.ts

@@ -0,0 +1,22 @@
+/// <reference types="@rbxts/types" />
+/// <reference types="@rbxts/types" />
+/// <reference types="@rbxts/types" />
+export interface GravityController extends Instance {
+    Player: Player;
+    Character: Model;
+    Humanoid: Humanoid;
+    HRP: BasePart;
+    Maid: {
+        Mark: (connection: RBXScriptConnection) => void;
+    };
+    GetFallHeight(): number;
+    GetGravityUp(self: GravityController, oldGravityUp: Vector3): Vector3;
+    ResetGravity(gravityDirection: Vector3): void;
+}
+export interface GravityControllerClass {
+    new (player: Player): GravityController;
+}
+export declare let gravityControllerClass: GravityControllerClass;
+export declare function installGravityControllerClass(): GravityControllerClass;
+export declare function getGroundNormal(cframe: CFrame, originOffset: Vector3, oldGravityUp: Vector3): Vector3;
+export declare function getGravityControllerUp(gravityController: GravityController, oldGravityUp: Vector3): Vector3;

package/out/init.lua

@@ -0,0 +1,174 @@
+-- Compiled with roblox-ts v2.3.0
+local TS = _G[script]
+local exports = {}
+local _services = TS.import(script, TS.getModule(script, "@rbxts", "services"))
+local Players = _services.Players
+local ReplicatedStorage = _services.ReplicatedStorage
+local RunService = _services.RunService
+local StarterPlayer = _services.StarterPlayer
+local function installGravityControllerClass()
+	if exports.gravityControllerClass then
+		return exports.gravityControllerClass
+	end
+	if RunService:IsServer() then
+		local starterPlayerScripts = StarterPlayer:WaitForChild("StarterPlayerScripts")
+		local starterCharacterScripts = StarterPlayer:WaitForChild("StarterCharacterScripts")
+		local _parent = script.Parent
+		if _parent ~= nil then
+			_parent = _parent:WaitForChild("GravityController")
+		end
+		local parent = _parent
+		if not parent then
+			error("GravityController module not found")
+		end
+		local client = parent:WaitForChild("Client")
+		local replace = function(child, parent)
+			local found = parent:FindFirstChild(child.Name)
+			local _result = found
+			if _result ~= nil then
+				_result:Destroy()
+			end
+			child.Parent = parent
+		end
+		replace(client:WaitForChild("PlayerScriptsLoader"), starterPlayerScripts)
+		replace(client:WaitForChild("RbxCharacterSounds"), starterPlayerScripts)
+		replace(client:WaitForChild("Animate"), starterCharacterScripts)
+		parent:WaitForChild("GravityController").Parent = ReplicatedStorage
+	end
+	exports.gravityControllerClass = require(ReplicatedStorage:WaitForChild("GravityController"))
+	return exports.gravityControllerClass
+end
+local PI2 = math.pi * 2
+local ZERO = Vector3.new(0, 0, 0)
+local LOWER_RADIUS_OFFSET = 3
+local NUM_DOWN_RAYS = 24
+local ODD_DOWN_RAY_START_RADIUS = 3
+local EVEN_DOWN_RAY_START_RADIUS = 2
+local ODD_DOWN_RAY_END_RADIUS = 1.66666
+local EVEN_DOWN_RAY_END_RADIUS = 1
+local NUM_FEELER_RAYS = 9
+local FEELER_LENGTH = 2
+local FEELER_START_OFFSET = 2
+local FEELER_RADIUS = 3.5
+local FEELER_APEX_OFFSET = 1
+local FEELER_WEIGHTING = 8
+-- Thanks to EmilyBendsSpace for the new get normal function!
+-- https://devforum.roblox.com/t/example-source-smooth-wall-walking-gravity-controller-from-club-raven/440229?u=egomoose
+local function getGroundNormal(cframe, originOffset, oldGravityUp)
+	local ignoreList = {}
+	for _, player in Players:GetPlayers() do
+		if player.Character then
+			local _character = player.Character
+			table.insert(ignoreList, _character)
+		end
+	end
+	local _position = cframe.Position
+	local _originOffset = originOffset
+	local origin = _position + _originOffset
+	local radialVector = if math.abs(cframe.LookVector:Dot(oldGravityUp)) < 0.999 then cframe.LookVector:Cross(oldGravityUp) else cframe.RightVector:Cross(oldGravityUp)
+	local centerRayLength = 25
+	local _oldGravityUp = oldGravityUp
+	local _arg0 = -centerRayLength
+	local centerRay = Ray.new(origin, _oldGravityUp * _arg0)
+	local centerHit, _centerHitPoint, centerHitNormal = game.Workspace:FindPartOnRayWithIgnoreList(centerRay, ignoreList)
+	local mainDownNormal = if centerHit then centerHitNormal else ZERO
+	local centerRayHitCount = 0
+	local evenRayHitCount = 0
+	local oddRayHitCount = 0
+	local downHitCount = 0
+	local downRaySum = ZERO
+	do
+		local i = 0
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				i += 1
+			else
+				_shouldIncrement = true
+			end
+			if not (i < NUM_DOWN_RAYS) then
+				break
+			end
+			local dtheta = PI2 * ((i - 1) / NUM_DOWN_RAYS)
+			local angleWeight = 0.25 + 0.75 * math.abs(math.cos(dtheta))
+			local isEvenRay = i % 2 == 0
+			local startRadius = if isEvenRay then EVEN_DOWN_RAY_START_RADIUS else ODD_DOWN_RAY_START_RADIUS
+			local endRadius = if isEvenRay then EVEN_DOWN_RAY_END_RADIUS else ODD_DOWN_RAY_END_RADIUS
+			local downRayLength = centerRayLength
+			local offset = CFrame.fromAxisAngle(oldGravityUp, dtheta) * radialVector
+			local _oldGravityUp_1 = oldGravityUp
+			local _arg0_1 = -LOWER_RADIUS_OFFSET
+			local _arg0_2 = endRadius - startRadius
+			local _arg0_3 = offset * _arg0_2
+			local dir = _oldGravityUp_1 * _arg0_1 + _arg0_3
+			local _arg0_4 = offset * startRadius
+			local ray = Ray.new(origin + _arg0_4, dir.Unit * downRayLength)
+			local hit, _hitPoint, hitNormal = game.Workspace:FindPartOnRayWithIgnoreList(ray, ignoreList)
+			if hit then
+				local _downRaySum = downRaySum
+				local _arg0_5 = hitNormal * angleWeight
+				downRaySum = _downRaySum + _arg0_5
+				downHitCount = downHitCount + 1
+				if isEvenRay then
+					evenRayHitCount = evenRayHitCount + 1
+				else
+					oddRayHitCount = oddRayHitCount + 1
+				end
+			end
+		end
+	end
+	local feelerHitCount = 0
+	local feelerNormalSum = ZERO
+	do
+		local i = 0
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				i += 1
+			else
+				_shouldIncrement = true
+			end
+			if not (i < NUM_FEELER_RAYS) then
+				break
+			end
+			local dtheta = 2 * math.pi * ((i - 1) / NUM_FEELER_RAYS)
+			local angleWeight = 0.25 + 0.75 * math.abs(math.cos(dtheta))
+			local offset = CFrame.fromAxisAngle(oldGravityUp, dtheta) * radialVector
+			local _exp = offset * FEELER_RADIUS
+			local _oldGravityUp_1 = oldGravityUp
+			local _arg0_1 = -LOWER_RADIUS_OFFSET
+			local dir = (_exp + (_oldGravityUp_1 * _arg0_1)).Unit
+			local _oldGravityUp_2 = oldGravityUp
+			local _arg0_2 = -FEELER_APEX_OFFSET
+			local _exp_1 = origin - (_oldGravityUp_2 * _arg0_2)
+			local _arg0_3 = dir * FEELER_START_OFFSET
+			local feelerOrigin = _exp_1 + _arg0_3
+			local ray = Ray.new(feelerOrigin, dir * FEELER_LENGTH)
+			local hit, _hitPoint, hitNormal = game.Workspace:FindPartOnRayWithIgnoreList(ray, ignoreList)
+			if hit then
+				local _feelerNormalSum = feelerNormalSum
+				local _arg0_4 = FEELER_WEIGHTING * angleWeight
+				local _arg0_5 = hitNormal * _arg0_4
+				feelerNormalSum = _feelerNormalSum + _arg0_5
+				feelerHitCount = feelerHitCount + 1
+			end
+		end
+	end
+	if centerRayHitCount + downHitCount + feelerHitCount > 0 then
+		local _downRaySum = downRaySum
+		local _exp = mainDownNormal + _downRaySum
+		local _feelerNormalSum = feelerNormalSum
+		local normalSum = _exp + _feelerNormalSum
+		if normalSum ~= ZERO then
+			return normalSum.Unit
+		end
+	end
+	return oldGravityUp
+end
+local function getGravityControllerUp(gravityController, oldGravityUp)
+	return getGroundNormal(gravityController.HRP.CFrame, if gravityController.Humanoid.RigType == Enum.HumanoidRigType.R15 then ZERO else oldGravityUp * 0.35, oldGravityUp)
+end
+exports.installGravityControllerClass = installGravityControllerClass
+exports.getGroundNormal = getGroundNormal
+exports.getGravityControllerUp = getGravityControllerUp
+return exports

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@rbxts/gravity-controller",
+  "version": "1.0.0",
+  "main": "out/init.lua",
+  "keywords": [
+    "gravity",
+    "rbxts"
+  ],
+  "author": "angleopera",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AngleOpera/gravity-controller.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AngleOpera/gravity-controller/issues"
+  },
+  "types": "out/index.d.ts",
+  "files": [
+    "out",
+    "GravityController.rbxmx",
+    "!**/*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rbxtsc",
+    "prepublishOnly": "rbxtsc"
+  },
+  "devDependencies": {
+    "@rbxts/compiler-types": "^2.3.0-types.0",
+    "@rbxts/types": "^1.0.760",
+    "@typescript-eslint/eslint-plugin": "^7.1.1",
+    "@typescript-eslint/parser": "^7.1.1",
+    "copyfiles": "^2.4.1",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "eslint-plugin-roblox-ts": "^0.0.36",
+    "eslint-plugin-simple-import-sort": "^12.0.0",
+    "eslint-plugin-unused-imports": "^3.1.0",
+    "prettier": "^3.2.5",
+    "roblox-ts": "^2.3.0-dev-3a89c93",
+    "typescript": "5.4.2"
+  },
+  "dependencies": {
+    "@rbxts/services": "^1.5.4"
+  }
+}