Animations, effects and sounds
Play the game's own clips, write animations as keys in Lua for anything, and add particles, lights, trails, shakes and sounds.
Three names work together here. game.Animations moves things: bones of a character or a creature, or a thing
as a whole. game.Effects adds what is seen around it, and game.Sounds what is heard. None of them needs the
Unreal editor or a pak.
local wave = game.Animations:Define("Wave", {
length = 1.2,
tracks = {
RightShoulder = { { 0, {} }, { 0.4, { Pitch = 60 } }, { 0.8, { Pitch = 60, Yaw = 30 } }, { 1.2, {} } },
},
})
local window = ui.Window({ title = "Wave", width = 260, height = 110 })
window:Button("Wave", function()
if game.Me.Exists then wave:Play(game.Me) end
end)An animation written as keys
game.Animations:Define(name, spec) makes an animation. It is plain Lua until it plays.
- A track says what moves. It is named by a bone, or
Selffor the thing as a whole. - A track is a list of keys: a time in seconds, then what is added at that time.
- A turn is about the character's own directions, whichever way the bone points:
Yawabout up (positive turns right),Pitchabout the character's right (negative leans forward),Rollabout forward. - What a key adds is an offset:
Pitch,Yaw,Rollin degrees,X,Y,Z, andScale. A key of{}means "as the game has it". So an animation that starts and ends with{}blends in and out by itself. - Between two keys the values are eased.
easeis"smooth"when omitted. The others are"linear","in","out"and"snap". A key can name its own as its third entry.
| In the spec | What it is |
|---|---|
tracks | What moves, by name. |
third | Tracks for the player's body in third person, when they should differ from tracks. |
reach | Where a hand or a foot goes. See below. |
reach_from | "hand" or "shoulder": what a reach key is measured from. |
length | How long it runs. The time of the last key when omitted. |
loop | true starts it again when it ends. |
ease | How keys are eased when a key does not say. |
events | { { seconds, function } }: functions that run when the animation passes a time. |
Bones
A bone is added to, not replaced: the game goes on animating, and your offsets come on top. So a swing you write works while the character walks, and a creature keeps breathing under it.
These names fit the player's arms in first person and the body in third:
RightClavicle, RightShoulder, RightElbow, RightWrist, RightHand, and the same with Left. On the
body there are also Head, Neck, Chest, Spine, Waist, Hips, RightThigh, LeftThigh, RightKnee,
LeftKnee, RightFoot and LeftFoot.
Any other bone goes by the name its skeleton gives it. game.Animations:GetBones(target) lists them, and a
name the skeleton does not have raises an error that suggests the nearest.
Reaching: a hand or a foot goes somewhere
Turning a shoulder and an elbow by hand until the hand is where you want it is slow work. A reach says
where the end of a limb goes, and Wax bends the two bones above it to get it there. The limbs are RightHand,
LeftHand, RightFoot and LeftFoot. X is forward, Y to the right and Z up, as the character stands.
local salute = game.Animations:Define("Salute", {
length = 1.6,
reach_from = "shoulder",
reach = {
RightHand = { { 0, { X = 25, Y = 5, Z = 22 } }, { 1.6, { X = 25, Y = 5, Z = 22 } } },
},
third = { Head = { { 0, {} }, { 0.4, { Yaw = 30 } }, { 1.6, {} } } },
})
local window = ui.Window({ title = "Salute", width = 260, height = 110 })
window:Button("Salute", function()
if game.Me.Exists then salute:Play(game.Me, { view = "third" }) end
end)reach_from = "hand", when omitted: a key adds to where the hand is in the game's own pose.reach_from = "shoulder": a key says where the hand is, measured from the shoulder (for a foot, from the hip). The reach comes in from the game's pose over the first moments and goes back at the end, so the keys need no{}at the ends. An arm is about 60 long and a leg about 90. A place further off is reached as far as the limb goes.- To turn the hand as well, give the limb a table:
RightHand = { turn = true, keys = { ... } }. With"shoulder", thePitch,YawandRollof a key are then how the thing in the hand is turned, as the character stands: all three 0 points it the way the character faces. - The elbow or the knee stays on the side it is on in the game's pose.
- One limb can differ from the rest:
LeftHand = { from = "hand", keys = { ... } }adds to the game's pose while the other limbs of the animation are placed from the shoulder. reach_blendis how long a reach from the shoulder takes to come in and to go back:0.2, or{ 0.1, 0.4 }.
When these were tried on the player's body, the hand, the foot and the turn of the held thing each came out where they were asked for, to the unit and to the degree.
Look at it before you use it
A model view can play your animation on a mesh in a window, where you can turn it and see it
from every side. view:Play(animation, options) takes the same options as animation:Play.
local wave = game.Animations:Define("PreviewWave", {
length = 1.5,
reach_from = "shoulder",
reach = { RightHand = { { 0, { X = 20, Y = 25, Z = 25 } }, { 1.5, { X = 20, Y = 25, Z = 25 } } } },
})
local window = ui.Window({ title = "Preview", width = 340, height = 420 })
local view = window:Model({
size = 300, spin = false, facing = 0, animation = "idle",
mesh = "/Game/ASS/CHA/Human/3RD/CHA_Suit_Variation/SK_CHA_3RD_MAL_V5",
idle = "/Game/ASS/CHA/Human/3RD/Animations/3RD_CHA_MAL_1HWeaponIdle",
})
window:Button("Play", function()
if view:IsLoaded() then view:Play(wave, { rate = 0.5 }) end
end)facing = 0says the mesh faces along its own X, as the player's body does. Left out, a look faces the way the game's creatures do.rate = 0.2plays it in slow motion, which is the easy way to see where a limb goes.view:Attach(shape, { socket = "R_prop_00", at = , turn = , material = })puts a shape of your own in the model's hand, so a tool is seen through the swing. With no turn, find out which way it points first.view = "third"in the options plays the tracks underthird, as the player's body does.
A movement that looks alive
A hand that follows a path while the rest stands still looks like a puppet. When a swing for the player's body was first made here that way, it was plainly wrong. What made it read as a swing:
- Key poses, not a path. A wind-up, the cut, the follow-through and a settle, each a whole pose.
- The body leads. Hips, waist and chest turn through the cut, each a little more than the one below. The head turns the other way, so the eyes stay on what is hit.
- The other arm moves against it, and a step or a sinking of the hips goes with a heavy blow.
- Uneven timing. Slow into the wind-up (
"out"), fast through the cut ("in"), slow to settle. - The tool leads with its edge. Give the hand a turn at every key, so the blade is ahead of the handle the whole way.
Hold one pose at a time in a model view, look from the front, the side and above, and only then join them.
Play it
animation:Play(target, options) plays it and gives you the play.
| Target | What moves |
|---|---|
game.Me | The arms in first person and the body in third. It follows when the player changes view. |
| A creature or another character | Its body. |
| A thing of a blueprint, or a part | The thing as a whole, by its Self track. |
| Option | What it does |
|---|---|
rate | How fast it runs. 1 when omitted. |
loop | Overrides the animation's own. |
weight | How much of the movement is added. 0.5 is half. |
keep | true leaves a thing where its Self track put it. |
done | A function that runs when it has run to its end. |
view | "first" or "third": on the player, the one view it shows in. |
A play has Stop(), IsPlaying(), GetTime() and SetRate(rate).
local spin = game.Animations:Define("Spin", {
length = 2,
loop = true,
ease = "linear",
tracks = { Self = { { 0, { Yaw = 0 } }, { 2, { Yaw = 360 } } } },
})
local cube = game.Blueprints:Define("SpinCube", {
parts = { Body = { mesh = "/Engine/BasicShapes/Cube.Cube", root = true, scale = 0.4, collision = "none" } },
})
local window = ui.Window({ title = "Cube", width = 260, height = 110 })
window:Button("Spawn a spinning cube", function()
if not game.IsHost or not game.Me.Exists then return end
local me = game.Me.Position
spin:Play(cube:Spawn({ X = me.X + 250, Y = me.Y, Z = me.Z + 40 }))
end)How bones are moved
The game gives no way to set a bone of a mesh it animates. So while an animation plays, Wax shows a copy of the mesh that it can pose: the copy takes the game's own pose every frame, your keys are added, and the real mesh is hidden. What hangs on the mesh, such as a held tool or clothing, is moved over to the copy and back. When nothing has played for ten seconds the copy is taken away. While nothing plays, it costs nothing.
The game's own clips
game.Animations:Play(target, clip, options) plays one of the game's montages or sequences.
game.Animations:Play(game.Me, {
first = "/Game/ASS/CHA/1ST/1ST_NewRig/1ST_CHA_Sledge_Hit_Montage",
third = "/Game/ASS/CHA/Human/3RD/Animations/3RD_CHA_SledgeHit_Montage",
})- The player's arms and body are two skeletons with clips of their own, so give
firstandthird. For a creature give one path. - Options:
rate,blend(seconds in and out),start, and for a single sequenceslotandloops. partplays one named part of a montage, such as"Action_0", or{ first = name, third = name }.- With both
firstandthird, the body's clip is paced to last as long as the arms'.match = falselets each run at its own length. game.Animations:Find("1st sledge montage")gives the paths that hold every word. The game has 4,091.- A clip only moves a skeleton it was made for.
Effects
Everything here hangs on something: on is a character, a creature, a thing or a part, and game.Me when
omitted. socket names a bone or socket of it, and at is measured from there.
local window = ui.Window({ title = "Effects", width = 260, height = 190 })
window:Button("Sparks", function()
game.Effects:Particles("/Game/ASS/VFX/FRE/NS_Sparks_AnvilT4", { on = game.Me, seconds = 2 })
end)
window:Button("Red light", function()
game.Effects:Light({ on = game.Me, color = "Red", intensity = 20000, radius = 600, seconds = 2, fade = 1 })
end)
window:Button("Shake", function()
game.Effects:Shake(1.5)
end)| Function | What it does |
|---|---|
game.Effects:Particles(path, options) | Starts one of the game's particle effects. seconds is how long it stays, 3 when omitted, false for until Stop. set gives parameters of the effect. |
game.Effects:Light(options) | A point light: color, intensity, radius, seconds, fade. |
game.Effects:Trail(on, options) | A glowing ribbon behind an edge that moves: from and to are the ends of the edge, seconds how long the ribbon is in time, life how long it runs. |
game.Effects:Shake(scale, path) | Shakes the player's view with one of the game's camera shakes. |
game.Effects:Find(text) | Paths of the game's 554 particle effects. FindShakes does the same for its 78 shakes. |
- What
Particles,LightandTrailgive hasStop()andIsAlive(). Particles haveSet(name, value), a lightSetColorandSetIntensity. - Everything your mod started is taken away when the mod unloads.
- At most 64 effects are alive at once for all mods. A new one past that takes the oldest away.
A slash off a blade
A trail is laid on a curve through the places the edge was at, so a fast swing leaves an arc, not corners. It
keeps the edge's outer end (to) and closes in on it toward its old end, which gives a crescent.
-- thing is a blade your mod spawned with game.Blueprints; the edge runs along its tip
game.Effects:Trail(thing, {
from = { -16, 0, 38 }, to = { 5, 0, 52 },
color = "Orange",
delay = 0.36, -- the swing winds up first: start with the cut
life = 0.3,
seconds = 0.14,
embers = 110, -- small glowing bits that come off the edge, a second
})| Option | What it does |
|---|---|
delay | Starts this many seconds from now. A trail that also runs during the wind-up doubles back on itself. life counts from the start. |
embers | Small glowing bits that come off the edge while it moves, drift, rise and shrink: how many a second, or { rate, size, life, speed, rise }. A trail has 60 at a time at most. |
width | Makes it a streak this wide along the middle of the edge, always turned to face the view. Without it a cut that comes straight at the view shows the ribbon from its side, as a line. |
with_view | true keeps the trail with the view, as the arms of first person are, instead of leaving it behind in the world. For something held in first person. |
material | A material of your own from game.Assets:Material in place of the plain glowing one. |
In first person
The game draws what is held in first person bent toward the screen, and it does that in the item's material
(the number PaniniScale, 1 in first person and 0 in third). A trail with the plain glowing material is drawn
where the blade really is, which is a little off where the blade shows. So give it a material of the game's
item kind with that number set, and with_view = true:
local glow = game.Assets:Material("/Game/ASS/ORB/ICARUS_STATION/MI_ORB_Light", {
textures = { ["Albedo [ITM]"] = game.Assets:Texture("black.png"), ["Emissive [ITM]"] = game.Assets:Texture("orange.png") },
numbers = { PaniniScale = 1, ["Emissive Intensity"] = 2 },
})
game.Effects:Trail(thing, { to = { 5, 0, 52 }, with_view = true, material = glow })MI_ORB_Light is one of the game's item materials that glow. The plain item material
(/Game/ASS/MAT/MA_ITM) takes the same textures and stays dark whatever Emissive Intensity says.
At an intensity of 14 orange turns yellow; 2 to 4 keeps the colour of the picture.
Sounds
game.Sounds:Play("/Game/FMOD/Events/SFX/Creatures/Movement/SFX_CRE_BEAR_WHOOSH")- With nothing else it is heard everywhere. With
onit comes from that thing:{ on = creature }. game.Sounds:Find("whoosh bear")gives the paths that hold every word. The game has 5,515 sounds.- Only the game's own sounds can be played. A sound file of your own is not possible yet.
- A sound cannot be stopped once it plays.
What has been seen
All of it was run on the host of a prospect: a sound, a shake, sparks and a light on the player's hand, a clip of the game, an animation of keys on the arms and on the body with the clothing following, and a spawned cube turning with a trail behind it. These have not been looked at yet:
- An animation of keys on a creature.
- A reach on the arms seen in first person. On the body it was measured.
- Particle effects of the older kind (
ParticleSystem), andSeton any effect. - A sound that comes from a thing.
- What other players of a session see. Expect them to see none of it: it is made on your PC.
Every function is listed in the Animations reference and the Effects reference.