{"id":"v6fire/animatebootstrapper","name":"animatebootstrapper","scope":"v6fire","platform":"roblox","description":"Run Roblox's stock Animate LocalScript without forking it.","version":"0.1.3","latest":"0.1.3","versions":["0.1.0","0.1.1","0.1.2","0.1.3"],"license":"MIT","licenseRating":"safe","licenseCaveats":["License identified from the packaged LICENSE file; the manifest declared none."],"licenseVerified":true,"dependencies":{},"integrity":"a1e788d2515405251e000f6e6b87849868f21adfc50335f3c6811ae5c91ff3d1","likes":0,"downloads":0,"install":"forest install v6fire/animatebootstrapper","url":"https://forest.dev/p/roblox/v6fire/animatebootstrapper","files":"https://api.forest.dev/ai/package/roblox/v6fire/animatebootstrapper/files","readme":"# AnimateBootstrapper\n\nRun Roblox's stock **Animate** `LocalScript` on client-owned characters (NPCs from `CreateHumanoidModelFromDescriptionAsync`, custom client models, etc.) **without forking Animate**.\n\n`LocalScript`s only run under `PlayerScripts`, `PlayerGui`, `Backpack`, or the local player's `Character`. An NPC sitting in `workspace` does not qualify, so its Animate script never runs. This package works around that by briefly parenting the model into a valid container, starting stock Animate, then parking the script under `PlayerScripts` while the model lives wherever you need it.\n\n**Client-only.** Requires stock R6/R15 Animate behavior.\n\n## Installation\n\n```toml\n# wally.toml\n[dependencies]\nanimatebootstrapper = \"v6fire/animatebootstrapper@0.1.3\"\n```\n\n```bash\nwally install\n```\n\n```luau\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\nlocal AnimateBootstrapper = require(ReplicatedStorage.Packages.AnimateBootstrapper)\n```\n\nAdjust the require path to match your Rojo `Packages` layout.\n\n## Server setup (required)\n\nThe Animate `LocalScript` you clone **must be created on the server and replicated to the client**. A `LocalScript` bundled with a client-created model from `CreateHumanoidModelFromDescriptionAsync` will misbehave in live games (works in Studio, fails in Live).\n\nThis package does not create or name those templates for you. Your game is responsible for:\n\n1. Creating stock Animate `LocalScript`s on the **server** (one per rig type you need).\n2. Replicating them to the client (e.g. `ReplicatedStorage`, a folder, or another container you already use for assets).\n3. Passing the appropriate template into `BootstrapAnimate` from client code.\n\nSee [`examples/server`](examples/server) for one demo approach — the instance names there (`BaseAnimateR6`, `BaseAnimateR15`) are **example-place conventions**, not part of this library's API.\n\nFor background on the replication issue, see the [DevForum thread](https://devforum.roblox.com/t/studio-vs-live-server-discrepancy-failure-with-animate-script-generated-by-createhumanoidmodelfromdescriptionasync/4685167).\n\n## Usage\n\nBootstrap **before** parenting the character into `workspace` (or anywhere visible) to avoid a brief flash while the model is reparented during setup.\n\n```luau\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\nlocal AnimateBootstrapper = require(ReplicatedStorage.Packages.AnimateBootstrapper)\n\n-- A server-replicated stock Animate LocalScript from your game's setup (see above).\nlocal animateTemplate: LocalScript = ...\n\nlocal character: Model = ... -- Humanoid + Animator; not yet parented to workspace\n\nAnimateBootstrapper.BootstrapAnimate(character, animateTemplate)\n\ncharacter.Parent = workspace\n```\n\n### Custom animation children\n\nPass a third argument to copy animation children onto the cloned Animate script (each child is `:Clone()`'d; sources are untouched):\n\n```luau\nAnimateBootstrapper.BootstrapAnimate(character, animateTemplate, sourceAnimate:GetChildren())\n```\n\nA common pattern when using `CreateHumanoidModelFromDescriptionAsync` is to read children from the client-bundled Animate, destroy that script, then pass the child list while cloning a server-replicated template for the script itself.\n\n## API\n\n### `AnimateBootstrapper.BootstrapAnimate(character, animateScript, replacementChildren?)`\n\n| Parameter | Description |\n|-----------|-------------|\n| `character` | `Model` with a `Humanoid` and `Animator` |\n| `animateScript` | Server-replicated stock Animate `LocalScript` to clone |\n| `replacementChildren` | Optional `{ Instance }` — cloned onto the bootstrapped Animate (`ClearAllChildren()` first) |\n\n**Returns:** The bootstrapped Animate `LocalScript`. Destroyed automatically when `character` is destroyed.\n\n**Yields** until stock Animate plays its first idle animation (up to 3 seconds).\n\n**Errors if:**\n\n- Called on the server\n- `Humanoid` or `Animator` is missing\n- Animate does not start within the timeout (usually a replication or setup issue)\n\n## Gotchas\n\n- **Client-only** — do not require or call from server scripts.\n- **Server-replicated Animate** — the package does not verify replication; that is your responsibility.\n- **Bootstrap before showing** — reparenting during bootstrap can cause a visible flash.\n- **Other LocalScripts on the character** — any `LocalScript` descendant of the model may also run during bootstrap.\n- **Stock Animate coupling** — after idle starts, the script is moved to `PlayerScripts` because stock Animate caches `Humanoid`/`Animator` at startup. This relies on unmodified Roblox Animate behavior.\n- **Rebootstrap** — `BootstrapAnimate` stops existing locomotion tracks on the target `Animator` before starting a new Animate instance. Pass animation children via the third argument; each is cloned so a parked or onboard source can be destroyed after bootstrap.\n- **R6 and R15** — tested against default Roblox Animate scripts for both rig types.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md).\n\n## Examples\n\nThis repo includes a demo place for local testing:\n\n```bash\nrojo serve examples.project.json\n```\n\n| Path | Purpose |\n|------|---------|\n| [`examples/server`](examples/server) | Demo server setup that extracts stock Animate scripts and replicates them |\n| [`examples/client`](examples/client) | Demo client that spawns NPCs, bootstraps Animate, and parents to `workspace` |\n\nThe examples include extra scaffolding (template naming, a `VerifyReplication` remote, NPC spawning) that illustrates one end-to-end workflow. Copy the patterns that fit your game; you do not need to match the demo names or remotes to use the package.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","readmeTruncated":false}