Custom locomotion

Build walking and running styles from authored animations, then assign them to players with server Lua. Open77 blends the selected graph on remote player bodies and the local third-person body, including male and female puppets.

Use client and server 2.31.21+op77.141 or later for the API and transition behavior described here. You also need a locomotion resource exported by Gta2CPPuppet Studio. Animation packages are supplied by the resource author; choosing a style ID does not download a built-in animation bank.

Build and install a package#

1. In Studio, import GTA clips or GLB animations authored on the exported Cyberpunk rig.
2. Create states, transition conditions and blends. Use a one-dimensional blend for speed or a two-dimensional blend for movement direction.
3. Preview the graph on both Cyberpunk puppets. Check idle, starting, stopping, turning, walking and running; tune stride timing as described below.
4. Choose Export Open77 and copy the entire exported resource into the server's resource directory.
5. Enable the resource in the server configuration. Declare it as a dependency of the resource that assigns styles.
6. Connect through the launcher so it installs the preload archive before starting Cyberpunk.

An export has this structure; archive filenames depend on the package:

open77_locomotion_my_walk/
  open77.lua
  register.lua
  package.json
  graph.locomotion.json
  dist/
    <exported-archive>.zip

The generated manifest declares the shared registration script, graph files, preload_mod archive and locomotion.register permission. Keep the metadata, graph and archive together as one export. Re-export after editing animations or the graph so their revision and native bindings remain consistent.

Adding or changing the native archive requires a game restart for clients already running. Restarting the Lua resource alone cannot mount the new native assets. See Mods and custom assets for preload distribution and Server resources for configuration.

Assign a style#

The package's resource name and style ID are different. In this example, the resource is open77_locomotion_my_walk and the exported style ID is my_walk. Replace both with your own export's names.

-- open77.lua: the gameplay resource that selects player styles.
resource 'my_walk_controller'
server_script 'server.lua'
dependency 'open77_locomotion_my_walk'
permissions { 'locomotion.control', 'locomotion.read' }

-- server.lua: call from your validated gameplay handler after the player is ready.
local function applyWalkStyle(playerId)
    local ok, revisionOrReason = Open77.locomotion.set(playerId, 'my_walk', {
        durationMs = 60000,
        resetOnDeath = true,
    })
    if not ok then return nil, revisionOrReason end
    return revisionOrReason
end

local function readWalkStyle(playerId)
    local selected, reason = Open77.locomotion.get(playerId)
    if reason then return nil, reason end
    return selected -- nil means this player has no custom style assigned.
end

local function clearWalkStyle(playerId)
    return Open77.locomotion.reset(playerId)
end

The player must be authenticated, ready and alive when calling set. Validate the gameplay action on the server before assigning a style. Clients register package assets; they cannot assign or reset player styles.

Lua API#

Registration#

The exported register.lua runs on both runtimes:

local style, reason = Open77.locomotion.register('package.json')
assert(style, 'Locomotion package registration failed: ' .. tostring(reason))

Paths are relative to the registering resource. The server catalogs the package identity; the client validates the complete graph, clip selectors, durations, four native variants and mounted resources. Registration does not assign the style to anyone.

Style IDs are unique across resources. Generations of the same resource can register identical package content; conflicting content under the same revision is rejected by the client.

Assignment options#

Unknown options and incorrect types are rejected. Setting the same style, package revision and death policy again renews the duration while keeping the assignment revision and presentation body.

get returns player, style, packageRevision, revision and resetOnDeath, plus remainingMs when the assignment expires. packageRevision identifies the exported package; revision identifies the server assignment. This result describes server state, not successful rendering on every client.

Ownership and change events#

The resource generation that calls set owns the assignment. Another resource cannot replace or reset it. Stopping the assigning resource, disconnecting the player or removing the package's last registration releases the assignment. Death removes it when resetOnDeath is enabled.

Updates follow routing buckets. Clients joining the session receive the current selections, including their package and assignment revisions.

Listen for changes locally on the server:

AddEventHandler('onPlayerLocomotionChanged', function(playerId, style, packageRevision, revision, reason)
    print(('Player %s locomotion: %s (%s), revision %s'):format(
        tostring(playerId), style or 'native', reason, tostring(revision)))
end)

style is nil on reset. Reasons are set, reset, expired, died, disconnected, resource_stopped and package_stopped.

Graph inputs and native animation#

The runtime supplies these parameters when they exist in the authored graph:

Direction uses the rendered body's heading. Extra parameters retain their authored defaults; package version 1 has no general Lua API for setting parameters or firing triggers.

The layer changes animation presentation. First-person camera motion, appearance, collision, movement speed and network movement keep their existing behavior. NPC model projections use their own graphs and take precedence over custom player locomotion.

Vehicles, workspots, airborne movement, traversal, swimming and combat suppress the custom layer. A graph's native state also returns control to the native pose. Observations older than 750 ms release the layer; drawing more frames does not refresh an old movement observation.

Smooth transitions and stride timing#

Give ordinary movement transitions a positive duration to use an eased crossfade. A zero-duration edge is an immediate cut. When a transition is interrupted, its complete outgoing mixture remains visible and its clips keep playing, preserving continuity through the next fade.

Speed and direction are damped for animation blending. State conditions still receive observed speed immediately, so starting and stopping need not wait for the blend filter. Returning from native animation fades the custom layer in over 0.20 seconds; an actual jump releases it immediately.

For looping clips, select the clip in Studio and set:

Count the strides in each source recording, then align the leading foot between walk and run. Synchronized transitions preserve a shared cadence throughout the fade. Non-looping states play their full clip and ignore these two fields.

Tune transition durations for your clips and movement speeds. The runtime does not generate missing start/stop animations or foot locking, so crossfades alone cannot correct mismatched stride lengths or an unsuitable animation.

Graph limits#

An interrupted transition waits if the outgoing mixture plus the new state would exceed eight samples. The 2D blend uses the four nearest points with normalized inverse-square distance weights; its interpolation differs from Unity's blend trees.

Errors and troubleshooting#

Keep the returned reason in logs; these are common failures, not an exhaustive list.

Verify your animation in game#

Check both male and female bodies, the local third-person view and a second client's view. Exercise idle-to-walk, walk-to-run, turns, stops, rapid transition reversals, jump/land, vehicles and workspots. Verify reset, resource stop and late join with the package installed.

The debug runtime self-view report exposes customStyle, customState, customWeight, customTime, customSamples, customFrom, customMix and customBlend (clip index, time and weight). Remote movement reports expose the corresponding evaluator state. These values help explain blending; inspect the rendered body as well.

Studio checks rigs, cooked graph/entity roundtrips and packed resources during export. Its receipt leaves runtimeValidated=false because an offline export cannot validate rendering in the running game.

For gestures, held items and stationary actions alongside movement, see Role-play animations.