Animation Studio runtime

Wally-пакет alqw/animation-studio@0.1.0 для воспроизведения клипов Animation Studio: свойства объектов, UI, пространственные пути, камеры, звук, события и готовые Animation ID. Работает на клиенте и сервере. Не имеет внешних зависимостей.

Редактор Animation Studio создаёт библиотеку клипов формата 1. Пакет содержит игровой проигрыватель и общий вычислитель кривых. Клипы, камеры и объекты вашей игры в публичный пакет не входят.

Установка в игру

После публикации пакета добавьте в секцию [dependencies] игрового wally.toml:

AnimationStudio = "alqw/animation-studio@0.1.0"

Выполните wally install. В Rojo-проекте игры должно быть сопоставление:

"ReplicatedStorage": {
  "Packages": { "$path": "Packages" }
}

В _template это сопоставление уже есть. Для его исходников используйте require("@pkg/AnimationStudio"): существующий darklua преобразует импорт. В обычном Studio используйте require(ReplicatedStorage.Packages.AnimationStudio).

Wally-пакет всё равно становится ModuleScript внутри ReplicatedStorage.Packages; теперь его версией и обновлениями управляет Wally. Кнопка установки отдельного runtime из плагина для этого варианта не нужна.

Подготовка клипа

1. В Animation Studio создайте клип, дорожки и ключи. Запомните точное имя клипа.
2. Сохраните place. В нём должны оставаться ReplicatedStorage.AnimationStudioLibrary и анимируемые объекты. Для камер также сохраните Workspace.AnimationStudioCameras.
3. Для камеры/UI выберите Context Client, для общих объектов Server. Both разрешает дорожку в обоих контекстах; избегайте одновременной записи одного свойства клиентом и сервером.
4. При работе с Rojo сохраните редакторские данные вне дерева кода: разрешите неизвестные экземпляры на нужных корнях либо добавьте явные сохраняемые корни. В шаблоне SyncBack по умолчанию не экспортирует AnimationStudioLibrary и AnimationStudioCameras. Пример настроек — в examples/template/README.md проекта пакета.

Клиент: камера, UI и личная катсцена

LocalScript в StarterPlayerScripts:

local RS = game:GetService("ReplicatedStorage")
local AnimationStudio = require(RS:WaitForChild("Packages"):WaitForChild("AnimationStudio"))
local player = AnimationStudio.new(RS:WaitForChild("AnimationStudioLibrary"), nil, {
    Context = "Client",
})
player.Error:Connect(warn)
player:Play("My Animation")

В _template замените require на require("@pkg/AnimationStudio"). Пример контроллера для его Loader находится в examples/template/AnimationController.luau. Игровой код вызывает controller:Play("My Animation") по кнопке или событию; контроллер не запускает клип при загрузке.

Сервер: общая дверь, платформа или свет

В обычном Script в ServerScriptService используйте такой же код с { Context = "Server" }. У нужных дорожек выберите Server или Both. Для преобразований закрепите кинематические Parts через Anchored. Камеры проигрываются на клиенте.

examples/PlayAnimation.server.luau и examples/PlayAnimation.client.luau показывают простой запуск. examples/Cutscene.server.luau и .client.luau показывают согласованный запуск клиента и сервера через RemoteEvent и workspace:GetServerTimeNow(); они используют клип Demo Cutscene из редакторской демосцены.

Привязки и динамические объекты

По умолчанию проигрыватель читает ObjectValue из AnimationStudioLibrary.Bindings. Имена объектов можно менять. При переносе в другой place проверьте поля Value и замените потерянные цели. Для созданных во время игры объектов передайте переопределения:

local player = AnimationStudio.new(library, {
    Door = workspace:WaitForChild("AnotherDoor"), -- Door — имя привязки из Bindings
}, { Context = "Server" })
player:Play("Door Open")

Вместо Folder с данными можно передать массив таблиц клипов формата 1. Тогда все привязки передаются явно. GUI-привязки из StarterGui разрешаются в PlayerGui; дождитесь создания нужного GUI перед запуском.

API

local player = AnimationStudio.new(library, bindings, { Context = "Client" })
player:Play("My Animation", { Loop = false, Speed = 1 })
player:Pause()
player:Seek(1.5)       -- Секунды; маркеры не вызываются.
player:Resume()
player:SetSpeed(0.5)
player:Stop()          -- Восстановить исходные свойства и камеру.
player:Destroy()       -- Остановить и отключить соединения.

Play принимает Loop, Speed, Time, Paused, RestoreOnFinish, StartServerTime, ManualStep. Последний параметр позволяет обновлять время через player:Step(deltaSeconds) вместо подключения к RunService. По умолчанию контекст определяется средой запуска.

События: MarkerReached(name, payload, trackId), Finished(clipName), Error(message). При естественном завершении итоговые свойства сохраняются, камера возвращается игроку, собственные звук и AnimationTrack очищаются. RestoreOnFinish = true восстанавливает также свойства. Stop({ Restore = false }) сохраняет текущие свойства объектов. Один экземпляр player воспроизводит один клип; независимым одновременным клипам нужны отдельные player.

Клипы объектов и камер используют формат Animation Studio. Экспорта в Animation ID, FBX или видео здесь нет.

Разработка и публикация

Node.js нужен только для локальных проверок с ограничением потоков и времени. В игре Node.js не используется.

rokit install
node scripts/run-tool.cjs lune run scripts/check.luau

Проверки выполняются последовательно: формат, численные тесты кривых, модельные тесты runtime, сборка Rojo, упаковка Wally и проверка содержимого архива. Studio, фоновые серверы и PowerShell не запускаются. dist/AnimationStudioRuntime.rbxmx — дополнительная сборка модуля; dist/animation-studio-0.1.0.zip — проверенный архив Wally.

Для первой публикации из папки с этим wally.toml:

wally login
wally publish

Публикующий аккаунт должен иметь права на scope alqw. Перед последующими публикациями увеличьте package.version в wally.toml и снова выполните проверки. Здесь ничего автоматически не публикуется.

Проект подготовлен из runtime редактора Animation Studio. При экспорте исходники семи модулей копируются без изменений; версия формата библиотеки и API сохраняются. Ссылки: Wally manifest, Rojo.