Poggy AnimTool

Overview#

AnimTool is a tool for script makers and staff. It opens a timeline editor inside the game where you build an animation scene on your own character, then export it as a Lua table that any of your scripts can play.

• Chain animations back to back on an animation track, trim them, or hold the last frame.
• Attach props to your character, choose the bone, parent prop and scale, and keyframe their position and rotation, with in and out times.
• Preview everything live on your own ped.
• Search or browse the game's animation dictionaries and object models, with favourites.
• Save projects, undo and redo, share projects as JSON.
• Export a Lua scene table plus the playback runtime, scene_player.lua, which you may ship inside your own resources.

It has no settings: access is one ACE permission.

Requirements#

No database tables, no items and no config file.

Installation#

1. Download poggy_animtool from your Cfx portal and put the folder in your server's resources folder.
2. In server.cfg, start it after poggy_core:

   ensure poggy_core
   ensure poggy_animtool

3. Give your staff the permission (see Permissions).
4. Restart the server.

Configuration#

AnimTool has no settings. Its card in /poggy shows the command and two help pages: Giving staff access and Playing an exported scene.

Commands#

Editor shortcuts

Press ? in the editor for the full list.

Permissions#

/animtool only opens for players with the ACE command.animtool. Set it in server.cfg:

# a whole group
add_ace group.admin command.animtool allow

# or one player, through a group of their own
add_principal identifier.license:<their licence> group.animators
add_ace group.animators command.animtool allow

Many servers already give group.admin the ACE command (every command), which includes command.animtool, so admins may already have access.

Restart the server after editing server.cfg, or type the same lines in the server console to apply them at once.

Using it in game#

Type /animtool. The editor has three parts:

• Library (left): search or browse animation dictionaries. Click a clip to preview it on your ped. Double-click, press +, or drag it onto the timeline to add it. ★ saves favourites.
• Timeline (bottom): clips play back to back. Drag a clip to reorder it and drag its edges to trim. Drag the right edge past the clip's own length to hold its last frame. Each prop gets its own lane: drag the bar ends for in and out points; diamonds are keyframes.
• Inspector (right): add props, choose the bone, parent prop and scale, and pose them with sliders. When a prop has keyframes, the sliders edit the keyframe under the playhead. With Auto-key on, a keyframe is made wherever you pose. K keys the current pose.

Projects

Save and Open keep projects on the player's own PC, not on the server. To move a project to another PC or share it, use Export → Project JSON and Import. Unsaved work is kept and offered for restore next time you open the tool.

Exporting a scene

1. Click Export.
2. On the Scene (Lua) tab, click Copy to clipboard.
3. On the Runtime · scene_player.lua tab, copy scene_player.lua too. You need it once per resource.

Clips shown as skipped failed to load or were disabled, and are left out of the export.

For developers#

Save the runtime as scene_player.lua in your own resource and load it before the script that plays the scene. It is readable source, and you may ship it inside your own resources.

-- fxmanifest.lua
client_scripts {
    'scene_player.lua',
    'my_script.lua',
}

-- my_script.lua
local scene = { ... }   -- pasted from AnimTool

-- Play once. Props are cleaned up when it ends.
ScenePlayer.playOnce(PlayerPedId(), scene)

-- Or with control:
local player = ScenePlayer.new(PlayerPedId())
player:load(scene)
player:play()
player.onFinish = function() player:destroy() end

The scene plays on the client, on whatever ped you pass in.

Troubleshooting#

/animtool does nothing

You do not have the ACE command.animtool. Add it (see Permissions) and restart, or type the add_ace line in the server console.

A clip shows as failed or skipped

Its animation dictionary did not load. Pick another clip or check the name. Skipped clips are left out of the export.

My projects are gone on another PC

Projects are stored on the PC you saved them on. Use Export → Project JSON and Import to move them.

A prop does not appear

The model name may be wrong. The editor shows an error for props that fail to spawn. A prop from a streamed pack needs that pack running.

Updating#

poggy_core's updater keeps it up to date: see Updates. Saved projects live on each player's PC and are not touched by an update. If you shipped scene_player.lua inside your own resources, those copies stay as they are; copy the new runtime from the export dialog when you want its fixes.