@rbxts/gravity-controller 1.0.6 → 1.0.7

package/GravityController.rbxmx

@@ -1744,7 +1744,7 @@ local defaultUpdateMouseBehavior = BaseCamera.UpdateMouseBehavior
 
 function BaseCamera:UpdateMouseBehavior()
 	defaultUpdateMouseBehavior(self)
-	if UserGameSettings.RotationType == Enum.RotationType.CameraRelative then
+	if _G._gravityControllerActive and UserGameSettings.RotationType == Enum.RotationType.CameraRelative then
 		UserGameSettings.RotationType = Enum.RotationType.MovementRelative
 	end
 end
@@ -2662,6 +2662,7 @@ function init(self)
 		self._characterMass = getModelMass(self.Character)
 	end))
 
+	_G._gravityControllerActive = true
 	self.Humanoid.PlatformStand = true
 	self.Maid:Mark(self.Humanoid:GetPropertyChangedSignal("Jump"):Connect(function()
 		if self.Humanoid.Jump then
@@ -2719,6 +2720,7 @@ function GravityControllerClass:Destroy()
 	RunService:UnbindFromRenderStep("GravityStep")
 	self.Maid:Sweep()
 	self.Humanoid.PlatformStand = false
+	_G._gravityControllerActive = false
 end
 
 --

package/README.md

@@ -1,11 +1,273 @@
 # @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)
+TypeScript bindings for [EgoMoose's Rbx-Gravity-Controller](https://github.com/EgoMoose/Rbx-Gravity-Controller) with
+ground-normal-based wall walking by [EmilyBendsSpace](https://x.com/EmilyBendsSpace).
 
-## Flamework setup
+Players can walk on walls, ceilings, and any arbitrary surface with smooth gravity transitions.
 
-1. Add `installGravityControllerClass` to the `onInit` of some `@Service`
+## Installation
+
+```bash
+npm install @rbxts/gravity-controller
+```
+
+The package ships a `GravityController.rbxmx` model that contains the Lua runtime (camera, collider, state tracker, animations, and character sounds). The TypeScript wrapper in `src/index.ts` handles deploying those scripts at runtime and provides typed access to the controller.
+
+## How it works
+
+### Architecture
+
+```
+Server (onInit)                         Client (onStart)
+─────────────────                       ──────────────────
+installGravityControllerClass()         installGravityControllerClass()
+  ├─ Copies Client/PlayerScriptsLoader    └─ require("GravityController")
+  │  → StarterPlayerScripts                     from ReplicatedStorage
+  ├─ Copies Client/RbxCharacterSounds           ↓
+  │  → StarterPlayerScripts             new GravityControllerClass(player)
+  ├─ Copies Client/Animate                ├─ Camera  (custom camera module)
+  │  → StarterCharacterScripts            ├─ Control (input → move vector)
+  └─ Moves GravityController module       ├─ Collider (physics body movers)
+     → ReplicatedStorage                  └─ StateTracker (humanoid states)
+```
+
+`installGravityControllerClass()` must be called on **both** the server and the client. On the server it deploys the bundled scripts into `StarterPlayerScripts`, `StarterCharacterScripts`, and `ReplicatedStorage`. On the client it `require`s the `GravityController` ModuleScript from `ReplicatedStorage` and returns the class.
+
+### Permanent runtime modifications
+
+The server-side `installGravityControllerClass()` **replaces** scripts in StarterPlayerScripts / StarterCharacterScripts:
+
+- **PlayerScriptsLoader** — modified version that monkey-patches `BaseCamera`, `CameraUtils`, `Poppercam`, and the `CameraModule.Update` loop to support arbitrary gravity up-vectors
+- **Animate** — custom version that works with `PlatformStand = true`
+- **RbxCharacterSounds** — custom version driven by the gravity controller's `StateTracker` rather than native `Humanoid` state
+
+These replacements are **permanent for the session** — they survive `GravityController:Destroy()`.
+
+### Key monkey-patch: `BaseCamera:UpdateMouseBehavior()`
+
+The modified PlayerScriptsLoader overrides `BaseCamera:UpdateMouseBehavior()` to force `UserGameSettings.RotationType` from `CameraRelative` to `MovementRelative`. This is necessary while the gravity controller is active because `CameraRelative` rotation conflicts with the custom `BodyGyro`-driven character orientation.
+
+This override is guarded by `_G._gravityControllerActive` so it only applies while a gravity controller instance is alive. Without this guard, any first-person camera system that depends on `CameraRelative` (such as Character-Realism's `FpsCamera`) will break permanently after gravity controller destruction.
+
+### What a GravityController instance does (per-player, temporary)
+
+- Sets `Humanoid.PlatformStand = true` (disables the default humanoid physics)
+- Creates collision proxy parts (Sphere, FloorDetector, JumpDetector) welded to HRP
+- Adds `VectorForce`, `BodyGyro`, `BodyPosition` to HRP
+- Binds `"GravityStep"` RenderStep at priority `Camera - 1` (199)
+- Sets `_G._gravityControllerActive = true`
+
+### What `GravityController:Destroy()` does
+
+- Unbinds `"GravityStep"` from RenderStep
+- `Maid:Sweep()` — destroys all proxy parts, body movers, disconnects events
+- Sets `Humanoid.PlatformStand = false`
+- Sets `_G._gravityControllerActive = false`
+
+It does **not** restore the Animate script or the PlayerScriptsLoader — those persist.
+
+### Gravity step (per frame)
+
+Each render frame the controller runs `onGravityStep`:
+
+1. **Query gravity direction** — calls `GetGravityUp(oldGravity)` which you can override. By default it returns the previous gravity (no change). Assign `getGravityControllerUp` to enable surface-following wall walk.
+2. **Lerp transition** — spherically interpolates from the old gravity direction toward the new one, controlled by `Transition` (default `0.15`).
+3. **Compute world move vector** — projects the camera-relative input onto the plane perpendicular to gravity so the character always moves along the surface.
+4. **Compute forces** — calculates a counter-gravity force (`gForce`) and a walk force (`walkForce`) that accelerates the character toward target velocity.
+5. **Optional horizontal lock** — when `UseBodyPositionLock` is enabled and the character is standing still on an aligned surface, a `BodyPosition` prevents micro-sliding.
+6. **Update collider and state** — applies the combined force to the character's body movers and updates the state tracker (running, jumping, freefall, etc.).
+
+### Interaction with first-person camera systems
+
+If you use a first-person camera module (e.g. Character-Realism's `FpsCamera`) that depends on `UserGameSettings.RotationType` being `CameraRelative`:
+
+- While the gravity controller is **active**, `onGravityStep` handles character rotation via `BodyGyro`. The `_G._gravityControllerActive` flag ensures the monkey-patch forces `MovementRelative` only during this time.
+- After `Destroy()`, the flag clears and the monkey-patch becomes a no-op, allowing your first-person system to set `AutoRotate = false` and take over character rotation normally.
+
+### Ground normal detection (`getGroundNormal`)
+
+The exported `getGroundNormal` function determines which direction is "up" by casting rays from the character's root part:
+
+| Ray group | Count | Purpose |
+|---|---|---|
+| Center ray | 1 | Single downward ray (length 25) to find the surface directly below |
+| Down rays | 24 | Radial ring of rays angled slightly inward/outward, with alternating even/odd radii, to sample the surrounding surface normals |
+| Feeler rays | 9 | Shorter rays (length 2) fanning outward and downward to detect walls and edges the character is approaching |
+
+All hit normals are weighted (front-facing rays weighted more heavily, feelers weighted 8x) and summed. The final unit vector becomes the new "up" direction. If no rays hit anything, the previous gravity direction is preserved.
+
+### `GravityController.rbxmx` file manifest
+
+The `.rbxmx` model bundles all the Lua scripts needed at runtime. During `installGravityControllerClass()` these are deployed to the correct locations in the Roblox data model.
+
+```
+GravityController (Script) ← server entry point; deploys children at runtime
+├── Client (Folder) ← scripts that get copied into StarterPlayer
+│   ├── Animate (LocalScript) → StarterCharacterScripts
+│   │   ├── Controller (ModuleScript) — bootstraps R6/R15 animation sets
+│   │   ├── Loaded (BoolValue) — signals when animations are ready
+│   │   ├── PlayEmote (BindableFunction) — emote playback hook
+│   │   ├── R15 (ModuleScript) — full R15 animation state machine
+│   │   ├── R6 (ModuleScript) — full R6 animation state machine
+│   │   ├── ReplicatedHumanoid (ObjectValue) — humanoid reference for replication
+│   │   └── VerifyAnims (ModuleScript) — validates animation assets on the character
+│   ├── PlayerScriptsLoader (LocalScript) → StarterPlayerScripts
+│   │   ├── CameraInjector (ModuleScript) — monkey-patches PlayerModule's CameraModule
+│   │   │   to expose a public GetUpVector API for gravity-aware camera rotation
+│   │   └── FakeUserSettings (ModuleScript) — shims UserSettings() to override feature
+│   │       flags (e.g. disables UserRemoveTheCameraApi) during camera injection
+│   └── RbxCharacterSounds (LocalScript) → StarterPlayerScripts
+│       └── AnimationState (ModuleScript) — maps animation track names to
+│           HumanoidStateTypes so footstep/jump/fall sounds play correctly
+│           under custom gravity
+└── GravityController (ModuleScript) → ReplicatedStorage
+    ├── CharacterModules (Folder)
+    │   ├── Camera (ModuleScript) — hooks into PlayerModule cameras to override
+    │   │   GetUpVector, making the camera orbit around the custom gravity axis
+    │   └── Control (ModuleScript) — wraps PlayerModule controls to read the
+    │       move vector from keyboard/gamepad/touch input
+    ├── Collider (ModuleScript) — creates an invisible Ball Part welded below
+    │   the HRP for ground detection, plus VectorForce (gravity + walk),
+    │   BodyGyro (orientation), and BodyPosition (optional anti-slide lock)
+    ├── StateTracker (ModuleScript) — replaces Humanoid state detection with
+    │   velocity-based Running/Jumping/Freefall tracking and fires the
+    │   Animate script's callbacks (onRunning, onJumping, onFreeFall, etc.)
+    └── Utility (Folder)
+        ├── Maid (ModuleScript) — connection/instance cleanup utility
+        └── Signal (ModuleScript) — lightweight event/signal implementation
+```
+
+**Where each piece ends up at runtime:**
+
+| Script | Deployed to | Role |
+|---|---|---|
+| `Client/PlayerScriptsLoader` | `StarterPlayerScripts` | Replaces the default PlayerScriptsLoader to inject gravity-aware camera and control overrides into the stock `PlayerModule` |
+| `Client/RbxCharacterSounds` | `StarterPlayerScripts` | Replaces default character sounds so audio triggers are driven by the custom `StateTracker` instead of the native `Humanoid` state |
+| `Client/Animate` | `StarterCharacterScripts` | Replaces default Animate script; plays R6/R15 animations driven by `StateTracker.Changed` events rather than native humanoid states |
+| `GravityController` | `ReplicatedStorage` | The core module — `require`d by both the TypeScript wrapper and the PlayerScriptsLoader at runtime |
+
+## API
+
+### `installGravityControllerClass(config?)`
+
+Initializes the gravity system. Call on both server and client. Returns the `GravityControllerClass` constructor. Idempotent — calling it again returns the same class (and optionally applies new config).
+
+### `GravityControllerClass`
+
+| Member | Type | Description |
+|---|---|---|
+| `new(player)` | constructor | Creates a controller for the given player's current character |
+| `SetConstants(config)` | static method | Updates physics constants globally (see Configuration below) |
+
+### `GravityController` (instance)
+
+| Member | Type | Description |
+|---|---|---|
+| `Player` | `Player` | The owning player |
+| `Character` | `Model` | The player's character model |
+| `Humanoid` | `Humanoid` | The character's humanoid |
+| `HRP` | `BasePart` | `HumanoidRootPart` |
+| `Maid` | `{ Mark }` | Cleanup helper — tracks connections for automatic teardown |
+| `GetGravityUp(oldGravity)` | method | Override this to control gravity direction each frame. Default returns `oldGravity` (no change). |
+| `ResetGravity(direction)` | method | Instantly sets the gravity-up vector and resets the fall tracker |
+| `GetFallHeight()` | method | Returns the signed distance fallen along the gravity axis while in freefall; `0` otherwise |
+| `Destroy()` | method | Unbinds the render step, sweeps all connections, and restores `PlatformStand` |
+
+### `GravityManager`
+
+A plain TypeScript class (no framework dependencies) that manages the full lifecycle of a `GravityController` instance — waiting for the character and Animate script, constructing the controller, handling timeouts and retries, and tearing down cleanly.
+
+```typescript
+const cls = installGravityControllerClass(config)
+const manager = new GravityManager(cls, logger)
+
+manager.enable(getGravityControllerUp)  // async 4-phase construction
+manager.disable()                       // teardown + reset GravityUp attribute
+manager.getController()                 // live instance or undefined
+manager.getIsEnabling()                 // true while construction is in-flight
+```
+
+**Constructor:** `new GravityManager(gravityControllerClass, logger?)`
+
+- `gravityControllerClass` — the class returned by `installGravityControllerClass()`
+- `logger` — optional `GravityLogger` (see below). If omitted, logging is silently skipped.
+
+**`enable(getGravityUp)`** — starts a 4-phase async construction:
+
+1. Waits for `Players.LocalPlayer.Character` to exist
+2. Waits for the `Animate` script and its `Controller` child (with timeout)
+3. Waits for the `Animate` module to finish loading (`Loaded.Value = true`)
+4. Constructs the `GravityController` instance and assigns `GetGravityUp`
+
+Each call stores the requested `getGravityUp` function. If `enable()` is called again while construction is in-flight, the new function is saved and will be used when the current construction completes or on retry.
+
+A generation counter invalidates stale constructions — if `disable()` is called while construction is running, the in-flight thread is cancelled and any completed-but-stale controller is destroyed immediately.
+
+A watchdog fires after the timeout period and hard-cancels stuck construction threads, cleans up partial state (`GravityStep` RenderStep binding, `PlatformStand`), and triggers a retry.
+
+**`disable()`** — tears down the active controller:
+
+- Increments the generation counter (invalidating any in-flight construction)
+- Cancels the construction thread if running
+- Calls `Destroy()` on the live controller
+- Sets the HRP `GravityUp` attribute to `(0, 1, 0)`
+
+**`getController()`** — returns the live `GravityController` instance or `undefined`.
+
+**`getIsEnabling()`** — returns `true` while construction is in-flight.
+
+### `GravityLogger`
+
+Minimal logging interface so the package doesn't depend on any specific logging library. Any object with `Info`, `Warn`, and `Error` string methods satisfies it — including `@rbxts/log`'s `Logger`.
+
+```typescript
+interface GravityLogger {
+  Info(message: string): void
+  Warn(message: string): void
+  Error(message: string): void
+}
+```
+
+### `wrapGravityUpSaveAttribute(getGravityUp)`
+
+Higher-order function that wraps a `GetGravityUp` function to persist the current gravity direction as an HRP attribute (`GravityUp`). Only writes when the direction actually changes (magnitude delta > 0.001).
+
+```typescript
+manager.enable(wrapGravityUpSaveAttribute(getGravityControllerUp))
+```
+
+### `GetGravityUp` (type)
+
+```typescript
+type GetGravityUp = (self: GravityController, oldGravityUp: Vector3) => Vector3
+```
+
+The signature for gravity direction functions. Passed to `GravityManager.enable()` or assigned to `controller.GetGravityUp`.
+
+### `getGravityControllerUp(controller, oldGravityUp)`
+
+Convenience wrapper that calls `getGroundNormal` using the controller's `HRP.CFrame` with a rig-type-aware origin offset. Assign this to `controller.GetGravityUp` to enable wall walking.
+
+### `getGroundNormal(cframe, originOffset, oldGravityUp)`
+
+Low-level raycast function that returns a unit `Vector3` representing the surface normal beneath and around `cframe`. Useful if you want to build your own gravity logic.
+
+## Configuration
+
+Pass a config table to `installGravityControllerClass()` or call `SetConstants()` at any time:
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `Transition` | `number` | `0.15` | Lerp alpha per frame for gravity direction changes. Lower = slower, smoother transitions. |
+| `WalkForce` | `number` | `66.67` | Horizontal acceleration multiplier. Increase for snappier movement. |
+| `JumpModifier` | `number` | `1.2` | Multiplier on `Humanoid.JumpPower` when jumping along the custom gravity axis. |
+| `UseBodyPositionLock` | `boolean` | `false` | When `true`, locks the character's horizontal position with a `BodyPosition` while idle on an aligned surface to prevent sliding. |
+
+## Usage
+
+### With GravityManager (recommended)
+
+**Server** — install in a `@Service`:
 
 ```typescript
 import { OnInit, Service } from '@flamework/core'
@@ -14,52 +276,86 @@ 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`
+**Client** — use `GravityManager` to handle the full enable/disable lifecycle:
 
 ```typescript
 import { Controller, OnStart } from '@flamework/core'
 import {
   getGravityControllerUp,
-  GravityController,
-  GravityControllerClass,
+  GravityManager,
   installGravityControllerClass,
+  wrapGravityUpSaveAttribute,
 } from '@rbxts/gravity-controller'
-import { Players } from '@rbxts/services'
+import { Logger } from '@rbxts/log'
 
 @Controller({})
 export class PlayerGravityController implements OnStart {
-  gravityControllerClass: GravityControllerClass | undefined
-  gravityController: GravityController | undefined
+  private gravityManager: GravityManager | undefined
+
+  constructor(private logger: Logger) {}
 
   onStart() {
-    this.gravityControllerClass = installGravityControllerClass()
-    Players.LocalPlayer.CharacterAdded.Connect((_character) => {
-      this.disableGravityController()
-      this.enableGravityController()
-    })
-    if (Players.LocalPlayer.Character) this.enableGravityController()
+    const cls = installGravityControllerClass()
+    this.gravityManager = new GravityManager(cls, this.logger)
+
+    // Enable gravity with surface-following wall walk
+    this.gravityManager.enable(
+      wrapGravityUpSaveAttribute(getGravityControllerUp),
+    )
   }
 
-  disableGravityController() {
-    this.gravityController?.Destroy()
-    this.gravityController = undefined
+  disable() {
+    this.gravityManager?.disable()
   }
+}
+```
 
-  enableGravityController() {
-    if (this.gravityController || !this.gravityControllerClass) return
-    const gravityController = new this.gravityControllerClass(Players.LocalPlayer)
+### Manual lifecycle (without GravityManager)
 
-    // Use EmilyBendsSpace's getGroundNormal() to walk up walls
-    gravityController.GetGravityUp = getGravityControllerUp
+If you need full control over construction timing:
 
-    this.gravityController = gravityController
-  }
-}
+```typescript
+import {
+  installGravityControllerClass,
+  getGravityControllerUp,
+} from '@rbxts/gravity-controller'
+import { Players } from '@rbxts/services'
+
+const GravityControllerClass = installGravityControllerClass()
 
+Players.LocalPlayer.CharacterAdded.Connect(() => {
+  const gc = new GravityControllerClass(Players.LocalPlayer)
+  gc.GetGravityUp = getGravityControllerUp
+})
 ```
+
+### Custom gravity direction
+
+If you don't want surface-following wall walk, you can point gravity in any fixed direction:
+
+```typescript
+const gc = new GravityControllerClass(Players.LocalPlayer)
+
+// Gravity pulls toward -X (sideways)
+gc.GetGravityUp = () => new Vector3(1, 0, 0)
+```
+
+Or reset gravity imperatively:
+
+```typescript
+gc.ResetGravity(new Vector3(0, -1, 0)) // flip upside down
+```
+
+## Credits
+
+- [EgoMoose](https://github.com/EgoMoose) — original [Rbx-Gravity-Controller](https://github.com/EgoMoose/Rbx-Gravity-Controller) Lua implementation
+- [EmilyBendsSpace](https://x.com/EmilyBendsSpace) — improved ground normal raycasting for smooth wall walking ([DevForum post](https://devforum.roblox.com/t/example-source-smooth-wall-walking-gravity-controller-from-club-raven/440229))
+
+## License
+
+MIT

package/out/index.d.ts

@@ -28,7 +28,31 @@ export interface GravityControllerConfig {
     JumpModifier?: number;
     UseBodyPositionLock?: boolean;
 }
+export interface GravityLogger {
+    Info(message: string): void;
+    Warn(message: string): void;
+    Error(message: string): void;
+}
+export type GetGravityUp = (self: GravityController, oldGravityUp: Vector3) => Vector3;
 export declare let gravityControllerClass: GravityControllerClass;
 export declare function installGravityControllerClass(config?: GravityControllerConfig): GravityControllerClass;
+export declare function wrapGravityUpSaveAttribute(getGravityUp: GetGravityUp): (gravityController: GravityController, oldGravityUp: Vector3) => Vector3;
+export declare class GravityManager {
+    private _controller;
+    private _enabling;
+    private enablingStartedAt;
+    private generation;
+    private retryCount;
+    private constructionThread;
+    private pendingGetGravityUp;
+    private readonly gravityControllerClass;
+    private readonly logger;
+    constructor(gravityControllerClass: GravityControllerClass, logger?: GravityLogger);
+    getController(): GravityController | undefined;
+    getIsEnabling(): boolean;
+    disable(): void;
+    enable(getGravityUp: GetGravityUp): void;
+    private retryEnable;
+}
 export declare function getGroundNormal(cframe: CFrame, originOffset: Vector3, oldGravityUp: Vector3): Vector3;
 export declare function getGravityControllerUp(gravityController: GravityController, oldGravityUp: Vector3): Vector3;

package/out/init.lua

@@ -6,6 +6,7 @@ local Players = _services.Players
 local ReplicatedStorage = _services.ReplicatedStorage
 local RunService = _services.RunService
 local StarterPlayer = _services.StarterPlayer
+local Workspace = _services.Workspace
 local function installGravityControllerClass(config)
 	if exports.gravityControllerClass then
 		if config then
@@ -44,6 +45,228 @@ local function installGravityControllerClass(config)
 	end
 	return exports.gravityControllerClass
 end
+-- ── Utility ──────────────────────────────────────────────────────────
+local function wrapGravityUpSaveAttribute(getGravityUp)
+	return function(gravityController, oldGravityUp)
+		local up = getGravityUp(gravityController, oldGravityUp)
+		local _oldGravityUp = oldGravityUp
+		if (up - _oldGravityUp).Magnitude > 0.001 then
+			gravityController.HRP:SetAttribute("GravityUp", up)
+		end
+		return up
+	end
+end
+-- ── GravityManager ───────────────────────────────────────────────────
+local ENABLING_STALE_SEC = 5
+local MAX_GRAVITY_RETRIES = 3
+local RETRY_BACKOFF_SEC = 2
+local noopLogger = {
+	Info = function(self) end,
+	Warn = function(self) end,
+	Error = function(self) end,
+}
+local GravityManager
+do
+	GravityManager = setmetatable({}, {
+		__tostring = function()
+			return "GravityManager"
+		end,
+	})
+	GravityManager.__index = GravityManager
+	function GravityManager.new(...)
+		local self = setmetatable({}, GravityManager)
+		return self:constructor(...) or self
+	end
+	function GravityManager:constructor(gravityControllerClass, logger)
+		self._enabling = false
+		self.enablingStartedAt = 0
+		self.generation = 0
+		self.retryCount = 0
+		self.gravityControllerClass = gravityControllerClass
+		self.logger = logger or noopLogger
+	end
+	function GravityManager:getController()
+		return self._controller
+	end
+	function GravityManager:getIsEnabling()
+		return self._enabling
+	end
+	function GravityManager:disable()
+		local wasActive = self._controller ~= nil
+		local wasEnabling = self._enabling
+		if not wasActive and not wasEnabling then
+			return nil
+		end
+		local prevGen = self.generation
+		self.generation += 1
+		self._enabling = false
+		self.pendingGetGravityUp = nil
+		self.retryCount = 0
+		if self.constructionThread then
+			pcall(function()
+				return task.cancel(self.constructionThread)
+			end)
+			self.constructionThread = nil
+		end
+		self.logger:Info(`Disabling gravity controller: wasActive={wasActive}, wasEnabling={wasEnabling}` .. `, gen={prevGen}->{self.generation}`)
+		local _result = self._controller
+		if _result ~= nil then
+			_result:Destroy()
+		end
+		self._controller = nil
+		local _result_1 = Players.LocalPlayer.Character
+		if _result_1 ~= nil then
+			_result_1 = _result_1:FindFirstChild("HumanoidRootPart")
+		end
+		local hrp = _result_1
+		local _result_2 = hrp
+		if _result_2 ~= nil then
+			_result_2:SetAttribute("GravityUp", Vector3.new(0, 1, 0))
+		end
+	end
+	function GravityManager:enable(getGravityUp)
+		self.pendingGetGravityUp = getGravityUp
+		if self._controller then
+			return nil
+		end
+		local now = Workspace:GetServerTimeNow()
+		if self._enabling and now - self.enablingStartedAt < ENABLING_STALE_SEC then
+			return nil
+		end
+		self._enabling = true
+		self.enablingStartedAt = now
+		local generation = self.generation
+		local timeout = ENABLING_STALE_SEC + self.retryCount * RETRY_BACKOFF_SEC
+		self.logger:Info(`Enabling gravity controller (gen {generation}, timeout {timeout}s)`)
+		self.constructionThread = task.spawn(function()
+			-- Phase 1: wait for character
+			if not Players.LocalPlayer.Character then
+				Players.LocalPlayer.CharacterAdded:Wait()
+			end
+			local character = Players.LocalPlayer.Character
+			if generation ~= self.generation then
+				self._enabling = false
+				local pending = self.pendingGetGravityUp
+				if pending then
+					self:enable(pending)
+				end
+				return nil
+			end
+			-- Phase 2: wait for Animate script + Controller instance
+			local animate = character:WaitForChild("Animate", timeout)
+			if not animate then
+				self:retryEnable(generation, `Animate not found after {timeout}s`)
+				return nil
+			end
+			local animController = animate:WaitForChild("Controller", timeout)
+			if not animController then
+				self:retryEnable(generation, `Animate.Controller not found after {timeout}s`)
+				return nil
+			end
+			-- Phase 3: wait for Animate module to finish executing
+			local loaded = animate:FindFirstChild("Loaded")
+			if loaded and not loaded.Value then
+				self.logger:Info(`Waiting for Animate to finish loading (gen {generation})`)
+				local loadStart = os.clock()
+				while not loaded.Value and os.clock() - loadStart < timeout and generation == self.generation do
+					task.wait(0.1)
+				end
+				if not loaded.Value then
+					self:retryEnable(generation, `Animate not fully loaded after {timeout}s`)
+					return nil
+				end
+			end
+			if generation ~= self.generation then
+				self._enabling = false
+				local pending = self.pendingGetGravityUp
+				if pending then
+					self:enable(pending)
+				end
+				return nil
+			end
+			-- Phase 4: construct
+			self.logger:Info(`Constructing gravity controller (gen {generation})`)
+			local ok, result = pcall(function()
+				local gc = self.gravityControllerClass.new(Players.LocalPlayer)
+				gc.GetGravityUp = getGravityUp
+				return gc
+			end)
+			self._enabling = false
+			if generation ~= self.generation then
+				self.logger:Info(`Gravity controller construction completed but generation is stale ({generation} vs {self.generation}), destroying`)
+				if ok and result then
+					result:Destroy()
+				end
+				local pending = self.pendingGetGravityUp
+				if pending then
+					self:enable(pending)
+				end
+				return nil
+			end
+			if ok and result then
+				self._controller = result
+				self.pendingGetGravityUp = nil
+				self.retryCount = 0
+				self.logger:Info(`Gravity controller enabled (gen {generation})`)
+			else
+				local _result
+				if type(result) == "string" then
+					_result = result
+				else
+					local _condition = result
+					if _condition == nil then
+						_condition = "Unknown error"
+					end
+					_result = tostring(_condition)
+				end
+				local err = _result
+				self.logger:Error(`Error enabling gravity controller: {err}`)
+			end
+		end)
+		-- Watchdog: hard-cancel + cleanup + retry
+		task.delay(timeout, function()
+			if not self._enabling or self.generation ~= generation then
+				return nil
+			end
+			if self.constructionThread then
+				pcall(function()
+					return task.cancel(self.constructionThread)
+				end)
+				self.constructionThread = nil
+			end
+			pcall(function()
+				return RunService:UnbindFromRenderStep("GravityStep")
+			end)
+			local _humanoid = Players.LocalPlayer.Character
+			if _humanoid ~= nil then
+				_humanoid = _humanoid:FindFirstChildOfClass("Humanoid")
+			end
+			local humanoid = _humanoid
+			if humanoid then
+				humanoid.PlatformStand = false
+			end
+			self:retryEnable(generation, `construction timed out after {timeout}s`)
+		end)
+	end
+	function GravityManager:retryEnable(generation, reason)
+		if generation ~= self.generation then
+			return nil
+		end
+		self._enabling = false
+		self.retryCount += 1
+		if self.retryCount > MAX_GRAVITY_RETRIES then
+			self.logger:Error(`Gravity controller failed after {self.retryCount} attempts ({reason}), giving up (gen {generation})`)
+			return nil
+		end
+		self.logger:Warn(`Gravity controller: {reason} (gen {generation}), retrying (attempt {self.retryCount}/{MAX_GRAVITY_RETRIES})`)
+		self.generation += 1
+		local pending = self.pendingGetGravityUp
+		if pending then
+			self:enable(pending)
+		end
+	end
+end
+-- ── GetGravityUp implementations ─────────────────────────────────────
 local PI2 = math.pi * 2
 local ZERO = Vector3.new(0, 0, 0)
 local LOWER_RADIUS_OFFSET = 3
@@ -175,6 +398,8 @@ 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.wrapGravityUpSaveAttribute = wrapGravityUpSaveAttribute
 exports.getGroundNormal = getGroundNormal
 exports.getGravityControllerUp = getGravityControllerUp
+exports.GravityManager = GravityManager
 return exports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/gravity-controller",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "main": "out/init.lua",
   "keywords": [
     "gravity",